com.threerings.io
Class Streamer

java.lang.Object
  com.threerings.io.Streamer

Direct Known Subclasses:

BasicStreamers.BasicStreamer, Streamer.ArrayStreamer, Streamer.ClassStreamer, Streamer.EnumStreamer

public abstract class Streamer
extends Object

Handles the streaming of Streamable instances as well as a set of basic object types (see ObjectOutputStream). An instance of Streamer.ClassStreamer is created for each distinct class that implements Streamable. The Streamer.ClassStreamer reflects on the streamed class and caches the information necessary to efficiently read and write objects of the class in question.

Nested Class Summary

protected static class	Streamer.ArrayStreamer A streamer for array types.
protected static class	Streamer.ByteEnumStreamer Streams ByteEnums, if that's what's desired.
protected static class	Streamer.ByteOrdEnumStreamer Streams enums by the byte value of their ordinal.
protected static class	Streamer.ClassStreamer A streamer that streams the fields of a class.
protected static class	Streamer.CustomClassStreamer Extends basic class streaming with support for customized streaming.
protected static class	Streamer.EnumPolicy The enum policy of this streamer, determined at start time by examining a system property.
protected static class	Streamer.EnumStreamer Base class for Enum streamers.
protected static class	Streamer.FinalArrayStreamer A streamer for arrays with a final component type.
protected static class	Streamer.IntOrdEnumStreamer Streams enums by the int value of their ordinal.
protected static class	Streamer.NameEnumStreamer Streams enums by name.
protected static class	Streamer.OrdEnumStreamer Base class for enum streamers that stream by ordinal.
protected static class	Streamer.ShortOrdEnumStreamer Streams enums by the short value of their ordinal.

Field Summary

protected static Map<Class<?>,Streamer>	_streamers Contains the mapping from class names to configured streamer instances.
protected static Streamer.EnumPolicy	ENUM_POLICY Our policy on handling enum classes.
protected static Comparator<Field>	FIELD_NAME_ORDER Compares fields by name.
protected static Predicate<Field>	IS_STREAMABLE Filters "NotStreamable" members from a field list.
protected static Predicate<Field>	IS_STREAMCLOSURE Filters "NotStreamable" members and enclosing class refs from a field list.
protected static Class<?>[]	READER_ARGS The argument list for the custom reader method.
protected static String	READER_METHOD_NAME The name of the custom reader method.
protected static boolean	SORT_FIELDS Should we sort fields in streamable classes?
protected static Class<?>[]	WRITER_ARGS The argument list for the custom writer method.
protected static String	WRITER_METHOD_NAME The name of the custom writer method.

Constructor Summary

protected

Streamer() The constructor used by the basic streamers.

Method Summary

protected static Streamer	create(Class<?> target) Create the appropriate Streamer for a newly-seen class.
abstract Object	createObject(ObjectInputStream in) Creates a blank object that can subsequently be read by this streamer.
static Class<?>	getCollectionClass(Class<?> clazz) If the specified class is not Streamable and is a Collection type, return the most specific supported Collection interface type; otherwise return null.
static Streamer	getStreamer(Class<?> target) Obtains a Streamer.ClassStreamer that can be used to read and write objects of the specified target class.
static Class<?>	getStreamerClass(Object object) Returns the class that should be used when streaming this object.
static boolean	isStreamable(Class<?> target) Returns true if the supplied target class can be streamed using a streamer.
protected static void	maybeInit() Initializes static state if necessary.
abstract void	readObject(Object object, ObjectInputStream in, boolean useReader) Reads and populates the fields of the supplied object from the specified stream.
String	toString()
protected Objects.ToStringHelper	toStringHelper() Overrideable to add more information to this class' toString() representation.
abstract void	writeObject(Object object, ObjectOutputStream out, boolean useWriter) Writes the supplied object to the specified stream.

Methods inherited from class java.lang.Object

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

Field Detail

_streamers

protected static Map<Class<?>,Streamer> _streamers

Contains the mapping from class names to configured streamer instances.

SORT_FIELDS

protected static final boolean SORT_FIELDS

Should we sort fields in streamable classes?

ENUM_POLICY

protected static final Streamer.EnumPolicy ENUM_POLICY

Our policy on handling enum classes.

FIELD_NAME_ORDER

protected static final Comparator<Field> FIELD_NAME_ORDER

Compares fields by name.

READER_METHOD_NAME

protected static final String READER_METHOD_NAME

The name of the custom reader method.

See Also:

Constant Field Values

READER_ARGS

protected static final Class<?>[] READER_ARGS

The argument list for the custom reader method.

WRITER_METHOD_NAME

protected static final String WRITER_METHOD_NAME

The name of the custom writer method.

See Also:

Constant Field Values

WRITER_ARGS

protected static final Class<?>[] WRITER_ARGS

The argument list for the custom writer method.

IS_STREAMABLE

protected static final Predicate<Field> IS_STREAMABLE

Filters "NotStreamable" members from a field list.

IS_STREAMCLOSURE

protected static final Predicate<Field> IS_STREAMCLOSURE

Filters "NotStreamable" members and enclosing class refs from a field list.

Constructor Detail

Streamer

protected Streamer()

The constructor used by the basic streamers.

Method Detail

isStreamable

public static boolean isStreamable(Class<?> target)

Returns true if the supplied target class can be streamed using a streamer.

getStreamerClass

public static Class<?> getStreamerClass(Object object)

Returns the class that should be used when streaming this object. In general that is the object's natural class, but for enum values, that might be its declaring class as enums use classes in a way that would otherwise pollute our id to class mapping space.

getCollectionClass

public static Class<?> getCollectionClass(Class<?> clazz)

If the specified class is not Streamable and is a Collection type, return the most specific supported Collection interface type; otherwise return null.

getStreamer

public static Streamer getStreamer(Class<?> target)
                            throws IOException

Obtains a Streamer.ClassStreamer that can be used to read and write objects of the specified target class. Streamer.ClassStreamer instances are shared among all ObjectInputStreams and ObjectOutputStreams.

Parameters:

target - the class that is desired to be streamed. This should be the result of a call to getStreamerClass(java.lang.Object) if the caller has an instance they wish to stream.

Throws:

IOException - when a streamer is requested for an object that does not implement Streamable and is not one of the basic object types (@see ObjectOutputStream).

writeObject

public abstract void writeObject(Object object,
                                 ObjectOutputStream out,
                                 boolean useWriter)
                          throws IOException

Writes the supplied object to the specified stream.

Parameters:

object - the instance to be written to the stream.

out - the stream to which to write the instance.

useWriter - whether or not to use the custom writeObject if one exists.

Throws:

IOException

createObject

public abstract Object createObject(ObjectInputStream in)
                             throws IOException,
                                    ClassNotFoundException

Creates a blank object that can subsequently be read by this streamer. Data may be read from the input stream as a result of this method (in the case of arrays, the length of the array must be read before creating the array).

Throws:

IOException

ClassNotFoundException

readObject

public abstract void readObject(Object object,
                                ObjectInputStream in,
                                boolean useReader)
                         throws IOException,
                                ClassNotFoundException

Reads and populates the fields of the supplied object from the specified stream.

Parameters:

object - the instance to be read from the stream.

in - the stream from which to read the instance.

useReader - whether or not to use the custom readObject if one exists.

Throws:

IOException

ClassNotFoundException

toString

public final String toString()

Overrides:

toString in class Object

toStringHelper

protected Objects.ToStringHelper toStringHelper()

Overrideable to add more information to this class' toString() representation.

create

protected static Streamer create(Class<?> target)
                          throws IOException

Create the appropriate Streamer for a newly-seen class.

Throws:

IOException

maybeInit

protected static void maybeInit()

Initializes static state if necessary.