jdeserialize

Class jdeserialize

java.lang.Object

jdeserialize.jdeserialize

public class jdeserialize
extends java.lang.Object

The main user-facing class for the jdeserialize library. Also the implementation of the command-line tool.

Library:

The jdeserialize class parses the stream (method run()). From there, call the getContent() method to get an itemized list of all items written to the stream, or getHandleMaps() to get a list of all handle->content maps generated during parsing. The objects are generally instances that implement the interface "content"; see the documentation of various implementors to get more information about the inner representations.

To enable debugging on stdout, use the enableDebug() or disableDebug() options.


Command-line tool:

The tool reads in a set of files and generates configurable output on stdout. The primary output consists of three separate stages. The first stage is a textual description of every piece of content in the stream, in the order it was written. There is generally a one-to-one mapping between ObjectOutputStream.writeXXX() calls and items printed in the first stage. The first stage may be suppressed with the -nocontent command-line option.

The second stage is a list of every class declaration serialized in the file. These are formatted as normal Java language class declarations. Several options are available to govern this stage, including -filter, -showarrays, -noclasses, and -fixnames.

The third stage is a dump of every instance embedded inside the stream, including textual descriptions of field values. This is useful for casual viewing of class data. To suppress this stage, use -noinstances.

You can also get debugging information generated during the parse phase by supplying -debug.
The data from block data objects can be extracted with the -blockdata option. Additionally, a manifest describing the size of each individual block can be generated with the -blockdatamanifest option.
References:
- Java Object Serialization Specification ch. 6 (Object Serialization Stream Protocol):
http://download.oracle.com/javase/6/docs/platform/serialization/spec/protocol.html
- "Modified UTF-8 Strings" within the JNI specification: http://download.oracle.com/javase/1.5.0/docs/guide/jni/spec/types.html#wp16542
- "Inner Classes Specification" within the JDK 1.1.8 docs: http://java.sun.com/products/archive/jdk/1.1/
- "Java Language Specification", third edition, particularly section 3: http://java.sun.com/docs/books/jls/third_edition/html/j3TOC.html

See Also:

content

Field Summary

Fields

Modifier and Type	Field and Description
static int	CODEWIDTH
private java.util.ArrayList<content>	content
private int	curhandle
private boolean	debugEnabled
private java.util.ArrayList<java.util.Map<java.lang.Integer,content>>	handlemaps
private java.util.HashMap<java.lang.Integer,content>	handles
static java.lang.String	INDENT
static java.lang.String[]	keywords
static java.util.HashSet<java.lang.String>	keywordSet
static java.lang.String	linesep
static long	serialVersionUID

Constructor Summary

Constructors

Constructor and Description
jdeserialize(byte[] input) Reads in an entire ObjectOutputStream output on the given stream, filing this object's content and handle maps with data about the objects in the stream.

Method Summary

Modifier and Type	Method and Description
void	connectMemberClasses() Connects member classes according to the rules specified by the JDK 1.1 Inner Classes Specification.
void	debug(java.lang.String message)
static void	debugerr(java.lang.String message)
static java.lang.String	decodeClassName(java.lang.String fdesc, boolean convertSlashes) Decodes a class name according to the field-descriptor format in the jvm spec, section 4.3.2.
static void	dump_ClassDesc(int indentlevel, classdesc cd, java.io.PrintStream ps, boolean fixname)
static void	dump_Instance(int indentlevel, instance inst, java.io.PrintStream ps)
void	dump(Getopt go)
static java.lang.String	fixClassName(java.lang.String name) "Fix" the given name by transforming illegal characters, such that the end result is a legal Java identifier that is not a keyword.
java.util.List<content>	getContent() Retrieves the list of content objects that were written to the stream.
java.util.List<java.util.Map<java.lang.Integer,content>>	getHandleMaps() Return a list of Maps containing every object with a handle.
classdesc	handle_classDesc(byte tc, java.io.DataInputStream dis, boolean mustBeNew)
classdesc	handle_newClassDesc(byte tc, java.io.DataInputStream dis)
static java.lang.String	hex(long value)
static java.lang.String	hexnoprefix(long value)
static java.lang.String	hexnoprefix(long value, int len)
static java.lang.String	indent(int level)
private int	newHandle()
arraycoll	read_arrayValues(java.lang.String str, java.io.DataInputStream dis)
blockdata	read_blockdata(byte tc, java.io.DataInputStream dis)
java.util.List<content>	read_classAnnotation(java.io.DataInputStream dis)
void	read_Classdata(java.io.DataInputStream dis, instance inst)
classdesc	read_classDesc(java.io.DataInputStream dis)
content	read_Content(byte tc, java.io.DataInputStream dis, boolean blockdata) Read the next object corresponding to the spec grammar rule "content", and return an object of type content.
content	read_Exception(java.io.DataInputStream dis) Read the content of a thrown exception object.
java.lang.Object	read_FieldValue(fieldtype f, java.io.DataInputStream dis)
arrayobj	read_newArray(java.io.DataInputStream dis)
classobj	read_newClass(java.io.DataInputStream dis)
classdesc	read_newClassDesc(java.io.DataInputStream dis)
enumobj	read_newEnum(java.io.DataInputStream dis)
instance	read_newObject(java.io.DataInputStream dis)
stringobj	read_newString(byte tc, java.io.DataInputStream dis)
content	read_prevObject(java.io.DataInputStream dis)
void	reset()
static java.lang.String	resolveJavaType(fieldtype type, java.lang.String classname, boolean convertSlashes, boolean fixname)
void	setHandle(int handle, content c)
static java.lang.String	unicodeEscape(java.lang.String str) Suitably escapes non-printable-ASCII characters (and doublequotes) for use in a Java string literal.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

serialVersionUID

public static final long serialVersionUID

See Also:

Constant Field Values

INDENT

public static final java.lang.String INDENT

See Also:

Constant Field Values

CODEWIDTH

public static final int CODEWIDTH

See Also:

Constant Field Values

linesep

public static final java.lang.String linesep

keywords

public static final java.lang.String[] keywords

keywordSet

public static java.util.HashSet<java.lang.String> keywordSet

handles

private java.util.HashMap<java.lang.Integer,content> handles

handlemaps

private java.util.ArrayList<java.util.Map<java.lang.Integer,content>> handlemaps

content

private java.util.ArrayList<content> content

curhandle

private int curhandle

debugEnabled

private boolean debugEnabled

Constructor Detail

jdeserialize

public jdeserialize(byte[] input)
             throws java.io.IOException

Reads in an entire ObjectOutputStream output on the given stream, filing this object's content and handle maps with data about the objects in the stream.

If shouldConnect is true, then jdeserialize will attempt to identify member classes by their names according to the details laid out in the Inner Classes Specification. If it finds one, it will set the classdesc's flag indicating that it is an member class, and it will create a reference in its enclosing class.

Parameters:

is - an open InputStream on a serialized stream of data

shouldConnect - true if jdeserialize should attempt to identify and connect member classes with their enclosing classes Also see the

connectMemberClasses

method for more information on the member-class-detection algorithm.

Throws:

java.io.IOException

Method Detail

getContent

public java.util.List<content> getContent()

Retrieves the list of content objects that were written to the stream. Each item generally corresponds to an invocation of an ObjectOutputStream writeXXX() method. A notable exception is the class exceptionstate, which represents an embedded exception that was caught during serialization.

See the various implementors of content to get information about what data is available.

Entries in the list may be null, because it's perfectly legitimate to write a null reference to the stream.

Returns:

a list of content objects

See Also:

content, exceptionstate

getHandleMaps

public java.util.List<java.util.Map<java.lang.Integer,content>> getHandleMaps()

Return a list of Maps containing every object with a handle. The keys are integers -- the handles themselves -- and the values are instances of type content.

Although there is only one map active at a given point, a stream may have multiple logical maps: when a reset happens (indicated by TC_RESET), the current map is cleared.

See the spec for details on handles.

Returns:

a list of maps

unicodeEscape

public static java.lang.String unicodeEscape(java.lang.String str)

Suitably escapes non-printable-ASCII characters (and doublequotes) for use in a Java string literal.

Parameters:

str - string to escape

Returns:

an escaped version of the string

indent

public static java.lang.String indent(int level)

read_Classdata

public void read_Classdata(java.io.DataInputStream dis,
                           instance inst)
                    throws java.io.IOException

Throws:

java.io.IOException

read_FieldValue

public java.lang.Object read_FieldValue(fieldtype f,
                                        java.io.DataInputStream dis)
                                 throws java.io.IOException

Throws:

java.io.IOException

newHandle

private int newHandle()

resolveJavaType

public static java.lang.String resolveJavaType(fieldtype type,
                                               java.lang.String classname,
                                               boolean convertSlashes,
                                               boolean fixname)
                                        throws java.io.IOException

Throws:

java.io.IOException

read_classAnnotation

public java.util.List<content> read_classAnnotation(java.io.DataInputStream dis)
                                             throws java.io.IOException

Throws:

java.io.IOException

dump_Instance

public static void dump_Instance(int indentlevel,
                                 instance inst,
                                 java.io.PrintStream ps)

fixClassName

public static java.lang.String fixClassName(java.lang.String name)

"Fix" the given name by transforming illegal characters, such that the end result is a legal Java identifier that is not a keyword. If the string is modified at all, the result will be prepended with "$__".

Parameters:

name - the name to be transformed

Returns:

the unmodified string if it is legal, otherwise a legal-identifier version

dump_ClassDesc

public static void dump_ClassDesc(int indentlevel,
                                  classdesc cd,
                                  java.io.PrintStream ps,
                                  boolean fixname)
                           throws java.io.IOException

Throws:

java.io.IOException

setHandle

public void setHandle(int handle,
                      content c)
               throws java.io.IOException

Throws:

java.io.IOException

reset

public void reset()

read_Exception

public content read_Exception(java.io.DataInputStream dis)
                       throws java.io.IOException

Read the content of a thrown exception object. According to the spec, this must be an object of type Throwable. Although the Sun JDK always appears to provide enough information about the hierarchy to reach all the way back to java.lang.Throwable, it's unclear whether this is actually a requirement. From my reading, it's possible that some other ObjectOutputStream implementations may leave some gaps in the hierarchy, forcing this app to hit the classloader. To avoid this, we merely ensure that the written object is indeed an instance; ensuring that the object is indeed a Throwable is an exercise left to the user.

Throws:

java.io.IOException

read_classDesc

public classdesc read_classDesc(java.io.DataInputStream dis)
                         throws java.io.IOException

Throws:

java.io.IOException

read_newClassDesc

public classdesc read_newClassDesc(java.io.DataInputStream dis)
                            throws java.io.IOException

Throws:

java.io.IOException

read_prevObject

public content read_prevObject(java.io.DataInputStream dis)
                        throws java.io.IOException

Throws:

java.io.IOException

handle_newClassDesc

public classdesc handle_newClassDesc(byte tc,
                                     java.io.DataInputStream dis)
                              throws java.io.IOException

Throws:

java.io.IOException

handle_classDesc

public classdesc handle_classDesc(byte tc,
                                  java.io.DataInputStream dis,
                                  boolean mustBeNew)
                           throws java.io.IOException

Throws:

java.io.IOException

read_newArray

public arrayobj read_newArray(java.io.DataInputStream dis)
                       throws java.io.IOException

Throws:

java.io.IOException

read_arrayValues

public arraycoll read_arrayValues(java.lang.String str,
                                  java.io.DataInputStream dis)
                           throws java.io.IOException

Throws:

java.io.IOException

read_newClass

public classobj read_newClass(java.io.DataInputStream dis)
                       throws java.io.IOException

Throws:

java.io.IOException

read_newEnum

public enumobj read_newEnum(java.io.DataInputStream dis)
                     throws java.io.IOException

Throws:

java.io.IOException

read_newString

public stringobj read_newString(byte tc,
                                java.io.DataInputStream dis)
                         throws java.io.IOException

Throws:

java.io.IOException

read_blockdata

public blockdata read_blockdata(byte tc,
                                java.io.DataInputStream dis)
                         throws java.io.IOException

Throws:

java.io.IOException

read_newObject

public instance read_newObject(java.io.DataInputStream dis)
                        throws java.io.IOException

Throws:

java.io.IOException

read_Content

public content read_Content(byte tc,
                            java.io.DataInputStream dis,
                            boolean blockdata)
                     throws java.io.IOException

Read the next object corresponding to the spec grammar rule "content", and return an object of type content.

Usually, there is a 1:1 mapping of content items and returned instances. The one case where this isn't true is when an exception is embedded inside another object. When this is encountered, only the serialized exception object is returned; it's up to the caller to backtrack in order to gather any data from the object that was being serialized when the exception was thrown.

Parameters:

tc - the last byte read from the stream; it must be one of the TC_* values within ObjectStreamConstants.*

dis - the DataInputStream to read from

blockdata - whether or not to read TC_BLOCKDATA (this is the difference between spec rules "object" and "content").

Returns:

an object representing the last read item from the stream

Throws:

java.io.IOException - when a validity or I/O error occurs while reading

dump

public void dump(Getopt go)
          throws java.io.IOException

Throws:

java.io.IOException

connectMemberClasses

public void connectMemberClasses()
                          throws java.io.IOException

Connects member classes according to the rules specified by the JDK 1.1 Inner Classes Specification.

 Inner classes:
 for each class C containing an object reference member R named this$N, do:
     if the name of C matches the pattern O$I
     AND the name O matches the name of an existing type T
     AND T is the exact type referred to by R, then:
         don't display the declaration of R in normal dumping,
         consider C to be an inner class of O named I

 Static member classes (after):
 for each class C matching the pattern O$I, 
 where O is the name of a class in the same package
 AND C is not an inner class according to the above algorithm:
     consider C to be an inner class of O named I
 

This functions fills in the isInnerClass value in classdesc, the isInnerClassReference value in field, the isLocalInnerClass value in classdesc, and the isStaticMemberClass value in classdesc where necessary.

A word on static classes: serializing a static member class S doesn't inherently require serialization of its parent class P. Unlike inner classes, S doesn't retain an instance of P, and therefore P's class description doesn't need to be written. In these cases, if parent classes can be found, their static member classes will be connected; but if they can't be found, the names will not be changed and no ValidityException will be thrown.

Throws:

ValidityException - if the found values don't correspond to spec

java.io.IOException

decodeClassName

public static java.lang.String decodeClassName(java.lang.String fdesc,
                                               boolean convertSlashes)
                                        throws ValidityException

Decodes a class name according to the field-descriptor format in the jvm spec, section 4.3.2.

Parameters:

fdesc - name in field-descriptor format (Lfoo/bar/baz;)

convertSlashes - true iff slashes should be replaced with periods (true for "real" field-descriptor format; false for names in classdesc)

Returns:

a fully-qualified class name

Throws:

ValidityException - if the name isn't valid

hexnoprefix

public static java.lang.String hexnoprefix(long value)

hexnoprefix

public static java.lang.String hexnoprefix(long value,
                                           int len)

hex

public static java.lang.String hex(long value)

debugerr

public static void debugerr(java.lang.String message)

debug

public void debug(java.lang.String message)