com.gemstone.gemfire
Class CanonicalInstantiator

java.lang.Object
  com.gemstone.gemfire.Instantiator
      com.gemstone.gemfire.CanonicalInstantiator

public abstract class CanonicalInstantiator
extends Instantiator

CanonicalInstantiator is much like its parent Instantiator except that instead of needing to implement newInstance() you now must implement newInstance(DataInput). The addition of the DataInput parameter allows the instance creator to optionally read data from the data input stream and use it to decide the instance to create. This allows a value that represents a canonical instance to be written by a class's DataSerializer.toData(java.lang.Object, java.io.DataOutput) and then be read by newInstance(DataInput) and map it back to a canonical instance.

In addition to supporting serialization of canonical instances another application of this class is to have newInstance(DataInput) use the data it reads to cause it to create instances of different classes. For example it could read a single byte and then, based on the bytes value, create an empty instance of up to 256 different classes. This allows you to bypass the limit of 127 instantiators.

Note that DataSerializer.fromData(java.io.DataInput) is always called on the instance returned from newInstance(DataInput).

Since:

5.1

Constructor Summary

CanonicalInstantiator(Class c, byte classId)
Creates a new CanonicalInstantiator that instantiates a given class.

Method Summary

DataSerializable	newInstance() This method is not supported and if called will throw UnsupportedOperationException.
abstract DataSerializable	newInstance(DataInput in) Creates a new "empty" instance of a DataSerializable class whose state will be filled in by invoking its fromData method.

Methods inherited from class com.gemstone.gemfire.Instantiator

getContext, getEventId, getId, getInstantiatedClass, register, setContext, setEventId

Methods inherited from class java.lang.Object

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

Constructor Detail

CanonicalInstantiator

public CanonicalInstantiator(Class c,
                             byte classId)

Creates a new CanonicalInstantiator that instantiates a given class.

Parameters:

c - The DataSerializable class to register. This class must have a static initializer that registers this Instantiator.

classId - A unique id for class c. The classId must be greater than zero.

Throws:

IllegalArgumentException - If c does not implement DataSerializable, classId is less than or equal to zero.

NullPointerException - If c is null

Method Detail

newInstance

public final DataSerializable newInstance()

This method is not supported and if called will throw UnsupportedOperationException. Use newInstance(DataInput) instead.

Specified by:

newInstance in class Instantiator

Throws:

UnsupportedOperationException - in all cases

See Also:

DataSerializer.readObject(java.io.DataInput)

newInstance

public abstract DataSerializable newInstance(DataInput in)
                                      throws IOException

Creates a new "empty" instance of a DataSerializable class whose state will be filled in by invoking its fromData method.

Parameters:

in - the data input that can be read to decide what instance to create.

Returns:

the new "empty" instance.

Throws:

IOException - if a read from in fails.

Since:

5.1