rice.p2p.util
Class XMLObjectOutputStream

java.lang.Object
  java.io.OutputStream
      java.io.ObjectOutputStream
          rice.p2p.util.XMLObjectOutputStream

All Implemented Interfaces:

Closeable, DataOutput, Flushable, ObjectOutput, ObjectStreamConstants

public class XMLObjectOutputStream
extends ObjectOutputStream

XMLObjectOutputStream is an extension of ObjectOutputStream which provides for serialization for arbitrary Java objects, in the same manner as the ObjectOutputStream class. This class supports all of the features of the ObjectOutputStream, including serialization support for any Java object graph implementing the Serializable interface, maintenance of references in the object graph, support for Externalizable classes, custom serialization via the writeObject() method, alternate field writing mechanisms via the putFields() and writeFields() methods, support for the writeUnshared() method, custom serializable field specification via the serialPersistentFields field, and dynamic object replacement via the writeReplace() method. The format of the XML data written does conform to the JSX XML Schema, available online at http://www.jsx.org/jsx.xsd. This class is designed to be able to write objects which can then be deserialized using JSX, however, this has not been fully tested and bugs may be encountered.

Version:

$Id: XMLObjectOutputStream.java 4654 2009-01-08 16:33:07Z jeffh $

Author:

Alan Mislove

Nested Class Summary

class

XMLObjectOutputStream.PutField This class is an implementation of PutField which is compatible with the XMLObjectOutputStream.

Field Summary

protected Stack	currentClasses The stack of classes which are currently being written to the stream
protected Stack	currentObjects The stack of objects which are currently being written to the stream
protected Stack	currentPutFields The stack of putFields which are currently being written to the stream
protected int	next A counter used to generate unique references
protected static SoftHashMap	PERSISTENT_FIELDS A cache of the persistentFields, mapping class->Field[]
protected Hashtable	references The collection of references stored in the stream so far, maps Integer(hash) -> reference name.
protected static SoftHashMap	WRITE_OBJECTS A cache of the writeObject() methods, mapping class->writeObject()
protected static SoftHashMap	WRITE_REPLACES A cache of the writeReplace() methods, mapping class->writeReplace()
protected XMLWriter	writer The underlying XML writing engine

Fields inherited from interface java.io.ObjectStreamConstants

baseWireHandle, PROTOCOL_VERSION_1, PROTOCOL_VERSION_2, SC_BLOCK_DATA, SC_ENUM, SC_EXTERNALIZABLE, SC_SERIALIZABLE, SC_WRITE_METHOD, STREAM_MAGIC, STREAM_VERSION, SUBCLASS_IMPLEMENTATION_PERMISSION, SUBSTITUTION_PERMISSION, TC_ARRAY, TC_BASE, TC_BLOCKDATA, TC_BLOCKDATALONG, TC_CLASS, TC_CLASSDESC, TC_ENDBLOCKDATA, TC_ENUM, TC_EXCEPTION, TC_LONGSTRING, TC_MAX, TC_NULL, TC_OBJECT, TC_PROXYCLASSDESC, TC_REFERENCE, TC_RESET, TC_STRING

Constructor Summary

XMLObjectOutputStream(OutputStream out)
Constructor which writes data from the given output stream in order serialize objects.

Method Summary

protected String	assignReference() Method which assigns a new unique reference.
void	close() Method which closes the underlying output stream for writing.
void	defaultWriteObject() Method which can be called by objects if they have a writeObject() method.
void	flush() Method which flushes all buffered data to the output stream.
protected Class	getComponentType(Class array) Method which returns the component type of the given array class.
protected int	getDimension(Class array) Method which returns the dimension of the given array class.
protected Field[]	getPersistentFields(Class cl) Method which returns the serializable fields of the provided class.
protected String	getReference(Object o) Method which returns a previously stored reference.
protected Field[]	getSerialPersistentFields(Class c) Method which returns the serializablePersistenFields field of the provided class.
protected Class[]	getSuperClasses(Class c) Method which returns an array of classes representing the class hierarchy of the provided class, exempting the Object class.
protected int	hash(Object o) Method which determines a unique hash value for each object.
ObjectOutputStream.PutField	putFields() Method which can be called by objects if they have a writeObject() method.
protected void	putReference(Object o, String reference) Method which adds a reference in the hashtable of references.
void	reset() Method which resets the output stream, which removes the binding of all previously stored references.
void	write(byte b) Method which writes a byte to the underlying output stream.
void	write(byte[] b) Method which writes a array of bytes to the underlying output stream.
void	write(byte[] b, int offset, int length) Method which writes a array of bytes to the underlying output stream.
protected void	writeArray(Object o, String field, boolean shared) Method which writes an array to the stream.
void	writeBoolean(boolean b) Method which writes an boolean to the stream.
void	writeByte(byte b) Method which writes an byte to the stream.
void	writeByte(int i) Method which writes an byte to the stream.
void	writeBytes(String s) Method which writes a String as a sequence of chars to the stream.
void	writeChar(char c) Method which writes an char to the stream.
void	writeChar(int i) Method which writes an char to the stream.
void	writeChars(String s) Method which writes a String as a sequence of chars to the stream.
protected void	writeClass(Object o, Class c) Method which writes the information for one class for a given object to the stream.
void	writeDouble(double d) Method which writes an double to the stream.
void	writeFields() Method which writes the current state of the PutField object to the stream as this object's fields.
protected void	writeFields(Object o, Class c) Method which initiates the default field writing mechanism for the given object's class.
void	writeFloat(float f) Method which writes an float to the stream.
void	writeInt(int i) Method which writes an int to the stream.
void	writeLong(long l) Method which writes an long to the stream.
protected void	writeNull(String field) Method which writes a null item to the stream as the provided field.
protected void	writeObject(Object o, String field) Method which writes an object to the stream as the given field name If the next object represents a reference or null, then the appropriate helper is called.
void	writeObjectOverride(Object o) Method which is called by ObjectOutputStream.writeObject(), and writes the given object to the stream.
protected void	writeObjectUnshared(Object o, String field, boolean shared) Method which writes an object to the stream.
protected void	writeOrdinaryObject(Object o, String field, boolean shared) Method which writes an ordinary object to the stream (not a String or Array).
protected void	writePrimitive(boolean b, String field) Method which writes a boolean to the stream, as the given field name.
protected void	writePrimitive(byte b, String field) Method which writes a byte to the stream, as the given field name.
protected void	writePrimitive(char c, String field) Method which writes a char to the stream, as the given field name.
protected void	writePrimitive(double d, String field) Method which writes a double to the stream, as the given field name.
protected void	writePrimitive(float f, String field) Method which writes a float to the stream, as the given field name.
protected void	writePrimitive(int i, String field) Method which writes a int to the stream, as the given field name.
protected void	writePrimitive(long l, String field) Method which writes a long to the stream, as the given field name.
protected void	writePrimitive(short s, String field) Method which writes a short to the stream, as the given field name.
protected void	writePrimitiveField(Object o, Field f) Method which writes a primitive field to the stream.
protected void	writePutFields(XMLObjectOutputStream.PutField p) Method which writes out the data from the given PutField class as the data for the given class.
protected void	writeReference(Object o, String field) Method which writes a reference to the stream, determined from the references table.
protected void	writeReset() Method which writes a reset command to the stream.
void	writeShort(int i) Method which writes an short to the stream.
void	writeShort(short s) Method which writes an short to the stream.
protected void	writeStreamHeader() Method which writes the XML header to the stream.
protected void	writeString(String s, String field, boolean shared) Method which writes a string to the stream as the provided field.
void	writeUnshared(Object o) Method which writes the given object to the stream and does not record a reference to the object.
void	writeUTF(String s) Method which writes a UTF-encoded String to the stream.

Methods inherited from class java.io.ObjectOutputStream

annotateClass, annotateProxyClass, drain, enableReplaceObject, replaceObject, useProtocolVersion, write, writeClassDescriptor, writeObject

Methods inherited from class java.lang.Object

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

Field Detail

WRITE_REPLACES

protected static SoftHashMap WRITE_REPLACES

A cache of the writeReplace() methods, mapping class->writeReplace()

WRITE_OBJECTS

protected static SoftHashMap WRITE_OBJECTS

A cache of the writeObject() methods, mapping class->writeObject()

PERSISTENT_FIELDS

protected static SoftHashMap PERSISTENT_FIELDS

A cache of the persistentFields, mapping class->Field[]

writer

protected XMLWriter writer

The underlying XML writing engine

references

protected Hashtable references

The collection of references stored in the stream so far, maps Integer(hash) -> reference name.

next

protected int next

A counter used to generate unique references

currentObjects

protected Stack currentObjects

The stack of objects which are currently being written to the stream

currentClasses

protected Stack currentClasses

The stack of classes which are currently being written to the stream

currentPutFields

protected Stack currentPutFields

The stack of putFields which are currently being written to the stream

Constructor Detail

XMLObjectOutputStream

public XMLObjectOutputStream(OutputStream out)
                      throws IOException

Constructor which writes data from the given output stream in order serialize objects. This constructor also writes the header to the stream, and throws an IOException if an error occurs while writing the header.

Parameters:

out - The output stream to write data to

Throws:

IOException - If the an error occurs

Method Detail

writeStreamHeader

protected void writeStreamHeader()
                          throws IOException

Method which writes the XML header to the stream. Usually, this is the tag, but it may include processing instructions.

Overrides:

writeStreamHeader in class ObjectOutputStream

Throws:

IOException - If an error occurs

flush

public void flush()
           throws IOException

Method which flushes all buffered data to the output stream.

Specified by:

flush in interface Flushable

Specified by:

flush in interface ObjectOutput

Overrides:

flush in class ObjectOutputStream

Throws:

IOException - if an error occurs

close

public void close()
           throws IOException

Method which closes the underlying output stream for writing. Any subsequent writes will throw an IOException.

Specified by:

close in interface Closeable

Specified by:

close in interface ObjectOutput

Overrides:

close in class ObjectOutputStream

Throws:

IOException

reset

public void reset()
           throws IOException

Method which resets the output stream, which removes the binding of all previously stored references. If the same object is written before and after a reset(), it will be written twice to the stream.

Overrides:

reset in class ObjectOutputStream

Throws:

IOException - If an error occurs, or an object is currently being written

write

public void write(byte b)
           throws IOException

Method which writes a byte to the underlying output stream. Simply calls writeByte(b)

Throws:

IOException - If an error occurs

write

public void write(byte[] b)
           throws IOException

Method which writes a array of bytes to the underlying output stream. Simply calls writeByte(b[x]) on each of the array elements.

Specified by:

write in interface DataOutput

Specified by:

write in interface ObjectOutput

Overrides:

write in class ObjectOutputStream

Throws:

IOException - If an error occurs

write

public void write(byte[] b,
                  int offset,
                  int length)
           throws IOException

Method which writes a array of bytes to the underlying output stream. Simply calls writeByte(b[x]) on each of the array elements.

Specified by:

write in interface DataOutput

Specified by:

write in interface ObjectOutput

Overrides:

write in class ObjectOutputStream

Throws:

IOException - If an error occurs

writeInt

public void writeInt(int i)
              throws IOException

Method which writes an int to the stream.

Specified by:

writeInt in interface DataOutput

Overrides:

writeInt in class ObjectOutputStream

Parameters:

i - The value to write to the stream

Throws:

IOException - If an error occurs

writeBoolean

public void writeBoolean(boolean b)
                  throws IOException

Method which writes an boolean to the stream.

Specified by:

writeBoolean in interface DataOutput

Overrides:

writeBoolean in class ObjectOutputStream

Parameters:

b - The value to write to the stream

Throws:

IOException - If an error occurs

writeByte

public void writeByte(int i)
               throws IOException

Method which writes an byte to the stream.

Specified by:

writeByte in interface DataOutput

Overrides:

writeByte in class ObjectOutputStream

Parameters:

i - The value to write to the stream, casted to a byte

Throws:

IOException - If an error occurs

writeByte

public void writeByte(byte b)
               throws IOException

Method which writes an byte to the stream.

Parameters:

b - The value to write to the stream

Throws:

IOException - If an error occurs

writeChar

public void writeChar(int i)
               throws IOException

Method which writes an char to the stream.

Specified by:

writeChar in interface DataOutput

Overrides:

writeChar in class ObjectOutputStream

Parameters:

i - The value to write to the stream, casted to an int

Throws:

IOException - If an error occurs

writeChar

public void writeChar(char c)
               throws IOException

Method which writes an char to the stream.

Parameters:

c - The value to write to the stream

Throws:

IOException - If an error occurs

writeDouble

public void writeDouble(double d)
                 throws IOException

Method which writes an double to the stream.

Specified by:

writeDouble in interface DataOutput

Overrides:

writeDouble in class ObjectOutputStream

Parameters:

d - The value to write to the stream

Throws:

IOException - If an error occurs

writeFloat

public void writeFloat(float f)
                throws IOException

Method which writes an float to the stream.

Specified by:

writeFloat in interface DataOutput

Overrides:

writeFloat in class ObjectOutputStream

Parameters:

f - The value to write to the stream

Throws:

IOException - If an error occurs

writeLong

public void writeLong(long l)
               throws IOException

Method which writes an long to the stream.

Specified by:

writeLong in interface DataOutput

Overrides:

writeLong in class ObjectOutputStream

Parameters:

l - The value to write to the stream

Throws:

IOException - If an error occurs

writeShort

public void writeShort(int i)
                throws IOException

Method which writes an short to the stream.

Specified by:

writeShort in interface DataOutput

Overrides:

writeShort in class ObjectOutputStream

Parameters:

i - The value to write to the stream, casted to a short

Throws:

IOException - If an error occurs

writeShort

public void writeShort(short s)
                throws IOException

Method which writes an short to the stream.

Parameters:

s - The value to write to the stream

Throws:

IOException - If an error occurs

writeUTF

public void writeUTF(String s)
              throws IOException

Method which writes a UTF-encoded String to the stream. This method simply calls writeObject(), as all strings are UTF encoded in XML.

Specified by:

writeUTF in interface DataOutput

Overrides:

writeUTF in class ObjectOutputStream

Throws:

IOException - If an error occurs

writeChars

public void writeChars(String s)
                throws IOException

Method which writes a String as a sequence of chars to the stream. This method is equivalent to calling s.toCharArray() and calling writeChar() on each element. Using this method is *NOT* recommended, as it is an increadible waste of space.

Specified by:

writeChars in interface DataOutput

Overrides:

writeChars in class ObjectOutputStream

Throws:

IOException - If an error occurs

writeBytes

public void writeBytes(String s)
                throws IOException

Method which writes a String as a sequence of chars to the stream. This method is equivalent to calling s.toCharArray() and calling writeChar() on each element. Using this method is *NOT* recommended, as it is an increadible waste of space.

Specified by:

writeBytes in interface DataOutput

Overrides:

writeBytes in class ObjectOutputStream

Throws:

IOException - If an error occurs

writeObjectOverride

public void writeObjectOverride(Object o)
                         throws IOException

Method which is called by ObjectOutputStream.writeObject(), and writes the given object to the stream. If the object (or any of it's descendents) has a writeReplace() method, that object is written instead of the original object.

Overrides:

writeObjectOverride in class ObjectOutputStream

Parameters:

o - The value to write to the stream

Throws:

IOException - If an error occurs

writeUnshared

public void writeUnshared(Object o)
                   throws IOException

Method which writes the given object to the stream and does not record a reference to the object. This guarantees that in future writes of this object will not reference this copy of the object.

Overrides:

writeUnshared in class ObjectOutputStream

Parameters:

o - The value to write to the stream

Throws:

IOException - If an error occurs

defaultWriteObject

public void defaultWriteObject()
                        throws IOException

Method which can be called by objects if they have a writeObject() method. This method initiates the default field serialization mechanism, and writes all of the object's fields to the stream. If this method is called, the putFields() method CANNOT be called by the same object. However, one of these two methods MUST be called in the context of a writeObject().

Overrides:

defaultWriteObject in class ObjectOutputStream

Throws:

IOException - If an error occurs

NotActiveException - If a object is not currently being written

putFields

public ObjectOutputStream.PutField putFields()
                                      throws IOException

Method which can be called by objects if they have a writeObject() method. This method returns an object which the callee can then use to specify exactly which fields and values should be written to the steam, and can specify fields which do not exist as a member of the object. If this method is called, the defaultWriteObject() method CANNOT be called by the same object. However, one of these two methods MUST be called in the context of a writeObject().

Overrides:

putFields in class ObjectOutputStream

Returns:

A PutField, a container for fields to be written

Throws:

IOException - If an error occurs

NotActiveException - If a object is not currently being read

writeFields

public void writeFields()
                 throws IOException

Method which writes the current state of the PutField object to the stream as this object's fields. If this method is called, the defaultWriteObject() method CANNOT be called by the same object. However, one of these two methods MUST be called in the context of a writeObject().

Overrides:

writeFields in class ObjectOutputStream

Throws:

IOException - If an error occurs

NotActiveException - If a object is not currently being read

getPersistentFields

protected Field[] getPersistentFields(Class cl)

Method which returns the serializable fields of the provided class. If the class has a serialPersistentFields field, then that is used to determine which fields are serializable. Otherwise, all declared non-static and non-transient fields are returned.

Parameters:

c - The class to return the fields for

getSerialPersistentFields

protected Field[] getSerialPersistentFields(Class c)

Method which returns the serializablePersistenFields field of the provided class. If no such field exists, then null is returned.

Parameters:

c - The class to return the fields for

getComponentType

protected Class getComponentType(Class array)

Method which returns the component type of the given array class. If the class is not of type array, the class itself is returned

Returns:

The component type of the array, or the class itself if not an array

getDimension

protected int getDimension(Class array)

Method which returns the dimension of the given array class. This is determines recursively by using the getCompoenetType() method on the class.

Returns:

The dimension of the corresponding array class

getSuperClasses

protected Class[] getSuperClasses(Class c)

Method which returns an array of classes representing the class hierarchy of the provided class, exempting the Object class.

Parameters:

c - The class to return the heirarchy for

Returns:

The heierarchy of the provided class

hash

protected int hash(Object o)

Method which determines a unique hash value for each object. This implementation uses the System.identityHashCode() method, which returns the memory address.

Returns:

An integer, representing a unqiue hash value

putReference

protected void putReference(Object o,
                            String reference)

Method which adds a reference in the hashtable of references. Multiple calls to this method will replace prior objects.

Parameters:

o - The object to reference

reference - The reference name to use

getReference

protected String getReference(Object o)

Method which returns a previously stored reference. If the reference cannot be found, null is returned.

Parameters:

o - The object to look up

Returns:

The reference name, or null if none is found

assignReference

protected String assignReference()

Method which assigns a new unique reference.

Returns:

A new unique reference

writeReset

protected void writeReset()
                   throws IOException

Method which writes a reset command to the stream.

Throws:

IOException - If an error occurs

writeObject

protected void writeObject(Object o,
                           String field)
                    throws IOException

Method which writes an object to the stream as the given field name If the next object represents a reference or null, then the appropriate helper is called. Otherwise, writeObjectUnshared() is called to process the object.

Parameters:

o - The object to write to the stream

field - The field name to write the object as

Throws:

IOException - If an error occurs

ClassNotFoundException - If the class cannot be found

writeObjectUnshared

protected void writeObjectUnshared(Object o,
                                   String field,
                                   boolean shared)
                            throws IOException

Method which writes an object to the stream. This method assumes that the type of object which is being read is *sharable*, even if it is not going to be shared. Thus, this method can write objects of type String, Array, or Serializable. This method first calls the object's writeReplace() method, if such a method exists, and if a different object is returned, that object is written instead.

Parameters:

o - The object to write to the stream

field - The field name to write the object as

shared - Whether or not to record a reference to this object

Throws:

IOException - If an error occurs

writeNull

protected void writeNull(String field)
                  throws IOException

Method which writes a null item to the stream as the provided field.

Parameters:

field - The field name to write the object as

Throws:

IOException - If an error occurs

writeString

protected void writeString(String s,
                           String field,
                           boolean shared)
                    throws IOException

Method which writes a string to the stream as the provided field.

Parameters:

o - The object to write to the stream

field - The field name to write the object as

shared - Whether or not to record a reference to this object

Throws:

IOException - If an error occurs

writeArray

protected void writeArray(Object o,
                          String field,
                          boolean shared)
                   throws IOException

Method which writes an array to the stream. This method writes the array header, and then recursively writes all of the objects in the array to the stream. If a non-serializable object is found, the object is replaced with null.

Parameters:

o - The object to write to the stream

field - The field name to write the object as

shared - Whether or not to record a reference to this object

Throws:

IOException - If an error occurs

writeReference

protected void writeReference(Object o,
                              String field)
                       throws IOException

Method which writes a reference to the stream, determined from the references table. This method throws an IOException if a reference is not found to the provided object.

Parameters:

o - The object to write to the stream

field - The field name to write the object as

Throws:

IOException - If an error occurs

writeOrdinaryObject

protected void writeOrdinaryObject(Object o,
                                   String field,
                                   boolean shared)
                            throws IOException

Method which writes an ordinary object to the stream (not a String or Array). This method first writes the class type, and a list of the classes' supertypes. If the object is Externalizable, the writeExternal() method is called and the method returns. Otherwise, each of the superclasses are written, from highest to lowest, using the writeClass() method. If the object is not serializable, a NotSerializableException is thrown.

Parameters:

o - The object to write to the stream

field - The field name to write the object as

shared - Whether or not to record a reference to this object

Throws:

IOException - If an error occurs

NotSerializableException - If the object is not serializable

writeClass

protected void writeClass(Object o,
                          Class c)
                   throws IOException

Method which writes the information for one class for a given object to the stream. This method first writes the class type, and if it defines a writeObject() method, it is called. Otherwise, the fields are written in a default manner. Any extra data not read in the stream is read and ignored.

Parameters:

o - The object to write to the stream

c - The class of the object to write

Throws:

IOException - If an error occurs

writeFields

protected void writeFields(Object o,
                           Class c)
                    throws IOException

Method which initiates the default field writing mechanism for the given object's class. This method only writes the non-static and non-transient fields to the stream - all others are ignored. It reads all of the fields using the writeField() method.

Parameters:

o - The object to write to the stream

c - The class of the object to write

Throws:

IOException - If an error occurs

writePutFields

protected void writePutFields(XMLObjectOutputStream.PutField p)
                       throws IOException

Method which writes out the data from the given PutField class as the data for the given class. Each item in the PutField is written as the type it was inserted as. Thus, fields can be written which do not actually exist in the class.

Parameters:

p - The fields to write to the stream

Throws:

IOException - If an error occurs

writePrimitiveField

protected void writePrimitiveField(Object o,
                                   Field f)
                            throws IOException

Method which writes a primitive field to the stream. This method determiens the type of field that needs to be written, and calls f.getX(o), wiritng it to the stream.

Parameters:

o - The object get the primitive from

f - The field representing the primitive about to be written

Throws:

IOException - If an error occurs

writePrimitive

protected void writePrimitive(int i,
                              String field)
                       throws IOException

Method which writes a int to the stream, as the given field name.

Parameters:

i - The value to write to the stream

field - The field name to use

Throws:

IOException - If an error occurs

writePrimitive

protected void writePrimitive(boolean b,
                              String field)
                       throws IOException

Method which writes a boolean to the stream, as the given field name.

Parameters:

b - The value to write to the stream

field - The field name to use

Throws:

IOException - If an error occurs

writePrimitive

protected void writePrimitive(byte b,
                              String field)
                       throws IOException

Method which writes a byte to the stream, as the given field name.

Parameters:

b - The value to write to the stream

field - The field name to use

Throws:

IOException - If an error occurs

writePrimitive

protected void writePrimitive(char c,
                              String field)
                       throws IOException

Method which writes a char to the stream, as the given field name.

Parameters:

c - The value to write to the stream

field - The field name to use

Throws:

IOException - If an error occurs

writePrimitive

protected void writePrimitive(double d,
                              String field)
                       throws IOException

Method which writes a double to the stream, as the given field name.

Parameters:

d - The value to write to the stream

field - The field name to use

Throws:

IOException - If an error occurs

writePrimitive

protected void writePrimitive(float f,
                              String field)
                       throws IOException

Method which writes a float to the stream, as the given field name.

Parameters:

f - The value to write to the stream

field - The field name to use

Throws:

IOException - If an error occurs

writePrimitive

protected void writePrimitive(long l,
                              String field)
                       throws IOException

Method which writes a long to the stream, as the given field name.

Parameters:

l - The value to write to the stream

field - The field name to use

Throws:

IOException - If an error occurs

writePrimitive

protected void writePrimitive(short s,
                              String field)
                       throws IOException

Method which writes a short to the stream, as the given field name.

Parameters:

s - The value to write to the stream

field - The field name to use

Throws:

IOException - If an error occurs