com.gemstone.gemfire
Class DataSerializer

Provides static helper methods for reading and writing
non-primitive data when working with a DataSerializable.
For instance, classes that implement DataSerializable
can use the DataSerializer in their
toData and fromData methods:

Instances of DataSerializer are used to data serialize
objects (such as instances of standard Java classes or third-party
classes for which the source code is not available) that do not
implement the DataSerializable interface.

The following DataSerializer data serializes instances
of Company. In order for the data serialization
framework to consult this custom serializer, it must be registered with the framework.

DUMP_SERIALIZED

public static final boolean DUMP_SERIALIZED

If the "DataSerializer.DUMP_SERIALIZED" system
property is set, the class names of the objects that are
serialized by writeObject(Object, DataOutput) using standard Java
serialization are logged to standard out.
This aids in determining which classes should implement DataSerializable (or should be special cased by a custom
DataSerializer).

DEBUG

public static final boolean DEBUG

Should verbose debugging information be dumped?

Constructor Detail

DataSerializer

public DataSerializer()

Creates a new DataSerializer. All class that
implement DataSerializer must provide a
zero-argument constructor.

writeRegion

Writes an instance of Region. A Region is serialized as just a reference
to a full path only. It will be recreated on the other end by calling
CacheFactory.getAnyInstance() and then calling
getRegion on it.
This method will handle a
null value and not throw a
NullPointerException.

readRegion

Reads an instance of Region. A Region is serialized as a reference to a
full path only. It is recreated on the other end by calling
CacheFactory.getAnyInstance() and then calling
getRegion on it.
The return value may be null.

writeDate

Writes an instance of Date to a
DataOutput. Note that even though date
may be an instance of a subclass of Date,
readDate will always return an instance of
Date, not an instance of the subclass. To
preserve the class type of date,\
writeObject(Object, DataOutput) should be used for data serialization.
This method will handle a
null value and not throw a
NullPointerException.

writeFile

Writes an instance of File to a
DataOutput. Note that even though file
may be an instance of a subclass of File,
readFile will always return an instance of
File, not an instance of the subclass. To
preserve the class type of file,
writeObject(Object, DataOutput) should be used for data serialization.
This method will handle a
null value and not throw a
NullPointerException.

writeInetAddress

Writes an instance of InetAddress to a
DataOutput. The InetAddress is data
serialized by writing its byte
representation to the DataOutput. readInetAddress(java.io.DataInput) converts the byte representation
to an instance of InetAddress using InetAddress.getAddress(). As a result, if address
is an instance of a user-defined subclass of
InetAddress (that is, not an instance of one of the
subclasses from the java.net package), its class
will not be preserved. In order to be able to read an instance
of the user-defined class, writeObject(Object, DataOutput) should be used.
This method will handle a
null value and not throw a
NullPointerException.

writeArrayList

Writes an ArrayList to a DataOutput.
Note that even though list may be an instance of a
subclass of ArrayList, readArrayList
will always return an instance of ArrayList,
not an instance of the subclass. To preserve the class
type of list, writeObject(Object, DataOutput) should be used
for data serialization.
This method will serialize a
null list and not throw a
NullPointerException.

writeVector

Writes an Vector to a DataOutput.
Note that even though list may be an instance of a
subclass of Vector, readVector
will always return an instance of Vector,
not an instance of the subclass. To preserve the class
type of list, writeObject(Object, DataOutput) should be used
for data serialization.

writeStack

Writes an Stack to a DataOutput.
Note that even though list may be an instance of a
subclass of Stack, readStack
will always return an instance of Stack,
not an instance of the subclass. To preserve the class
type of list, writeObject(Object, DataOutput) should be used
for data serialization.

writeLinkedList

Writes an LinkedList to a DataOutput.
Note that even though list may be an instance of a
subclass of LinkedList, readLinkedList
will always return an instance of LinkedList,
not an instance of the subclass. To preserve the class
type of list, writeObject(Object, DataOutput) should be used
for data serialization.
This method will serialize a
null list and not throw a
NullPointerException.

writeHashSet

Writes a HashSet to a DataOutput. Note
that even though set may be an instance of a
subclass of HashSet, readHashSet will
always return an instance of HashSet, not an
instance of the subclass. To preserve the class type of
set, writeObject(Object, DataOutput) should be used for data
serialization.
This method will serialize a
null set and not throw a
NullPointerException.

writeLinkedHashSet

Writes a LinkedHashSet to a DataOutput. Note
that even though set may be an instance of a
subclass of LinkedHashSet, readLinkedHashSet will
always return an instance of LinkedHashSet, not an
instance of the subclass. To preserve the class type of
set, writeObject(Object, DataOutput) should be used for data
serialization.

writeHashMap

Writes a HashMap to a DataOutput. Note
that even though map may be an instance of a
subclass of HashMap, readHashMap will
always return an instance of HashMap, not an
instance of the subclass. To preserve the class type of
map, writeObject(Object, DataOutput) should be used for data
serialization.
This method will serialize a
null map and not throw a
NullPointerException.

writeIdentityHashMap

Writes a IdentityHashMap to a DataOutput. Note
that even though map may be an instance of a
subclass of IdentityHashMap, readIdentityHashMap will
always return an instance of IdentityHashMap, not an
instance of the subclass. To preserve the class type of
map, writeObject(Object, DataOutput) should be used for data
serialization.

writeConcurrentHashMap

Writes a ConcurrentHashMap to a DataOutput. Note
that even though map may be an instance of a
subclass of ConcurrentHashMap, readConcurrentHashMap will
always return an instance of ConcurrentHashMap, not an
instance of the subclass. To preserve the class type of
map, writeObject(Object, DataOutput) should be used for data
serialization.

At this time if writeObject(Object, DataOutput) is called with an instance
of ConcurrentHashMap then it will be serialized with normal java.io Serialization. So
if you want the keys and values of a ConcurrentHashMap to take advantage of GemFire serialization
it must be serialized with this method.

writeHashtable

Writes a Hashtable to a DataOutput. Note
that even though map may be an instance of a
subclass of Hashtable, readHashtable will
always return an instance of Hashtable, not an
instance of the subclass. To preserve the class type of
map, writeObject(Object, DataOutput) should be used for data
serialization.

writeTreeMap

Writes a TreeMap to a DataOutput. Note
that even though map may be an instance of a
subclass of TreeMap, readTreeMap will
always return an instance of TreeMap, not an
instance of the subclass. To preserve the class type of
map, writeObject(Object, DataOutput) should be used for data
serialization.

writeTreeSet

Writes a TreeSet to a DataOutput. Note
that even though set may be an instance of a
subclass of TreeSet, readTreeSet will
always return an instance of TreeSet, not an
instance of the subclass. To preserve the class type of
set, writeObject(Object, DataOutput) should be used for data
serialization.

writeProperties

Note that even though props may be an instance of a
subclass of Properties, readProperties will
always return an instance of Properties, not an
instance of the subclass. To preserve the class type of
props, writeObject(Object, DataOutput) should be used for data
serialization.

writeObject

Writes an arbitrary object to a DataOutput. If
o is not an instance of a specially-handled
standard Java class (see the list in getSupportedClasses()),
the toData method of each
registered DataSerializer is invoked until the object
is serialized. If no registered serializer can serialize the
object and o does not implement
DataSerializable, then it is serialized to
out using standard Java serialization.
This method will serialize a
null o and not throw a
NullPointerException.

Parameters:

allowJavaSerialization - If false, then a NotSerializableException is thrown
in the case where standard Java serialization would
otherwise be used for object o or for any nested
subobject of o. This is used to prevent
Java serialization from being used when sending data
to a non-Java client

writeObject

Writes an arbitrary object to a DataOutput. If
o is not an instance of a specially-handled
standard Java class (such as Date,
Integer, or ArrayList), the toData method of each
registered DataSerializer is invoked until the object
is serialized. If no registered serializer can serialize the
object and o does not implement
DataSerializable, then it is serialized to
out using standard Java serialization.
This method will serialize a
null o and not throw a
NullPointerException.

readObject

Reads an arbitrary object from a DataInput.
Instances of classes that are not handled specially (such as
String, Class, and
DataSerializable) are read using standard Java
serialization.

Note that if an object is deserialized using standard Java
serialization, its class will be loaded using the current
thread's context class
loader before the one normally used by Java serialization is
consulted.

Throws:

IOException - A problem occured while reading from in
(may wrap another exception)

This method invokes the DataSerializer instance's
getSupportedClasses() method and keeps track of which
classes can have their instances serialized by by this data serializer.

Parameters:

c - the DataSerializer class to create and
register with the data serialization framework.

Returns:

the registered serializer instance

Throws:

IllegalArgumentException - If c does not subclass
DataSerializer, if c does not
have a zero-argument constructor,
if id is 0,
if getSupportedClasses returns null or an empty array,
if getSupportedClasses returns and array with null elements

IllegalStateException - if another serializer
instance with id id has already been registered,
if another serializer instance that supports one of this instances
classes has already been registered,
if an attempt is made to support any of the classes reserved by DataSerializer
(see getSupportedClasses() for a list).

register

getSupportedClasses

Returns the Classes whose instances are data
serialized by this DataSerializer. This method is
invoked when this serializer is registered. This method is not allowed to return null
nor an empty array.
Only instances whose class name is the same as one of the class names
in the result will be serialized by this DataSerializer.
Two DataSerializers are not allowed to support the same class.
The following classes can not be supported by user defined data serializers
since they are all supported by the predefined data serializer:

toData

Data serializes an object to a DataOutput. It is
very important that when performing the "switch" on
o's class, your code test for a subclass before it
tests for a superclass. Otherwise, the incorrect class id could
be written to the serialization stream.

getContext

writeEnum

Writes the Enum constant to DataOutput. Unlike
standard java serialization which serializes both the enum name String and
the ordinal, GemFire only serializes the ordinal byte, so for backward
compatibility new enum constants should only be added to the end of the
enum type.
Example: DataSerializer.writeEnum(DAY_OF_WEEK.SUN, out);

readEnum

Reads a Enum constant from DataInput. Unlike
standard java serialization which serializes both the enum name String and
the ordinal, GemFire only serializes the ordinal byte, so be careful about
using the correct enum class. Also, for backward compatibility new enum
constants should only be added to the end of the enum type.
Example:
DAY_OF_WEEK d = DataSerializer.readEnum(DAY_OF_WEEK.class, in);