CanonicalInstantiator (Apache Geode 2.0.2)
Description: declaration: package: org.apache.geode, class: CanonicalInstantiator

Package org.apache.geode

# Class CanonicalInstantiator

java.lang.Object
org.apache.geode.Instantiator
org.apache.geode.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.

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

Since:
  GemFire 5.1

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CanonicalInstantiator(Class<? extends DataSerializable> c, int classId)`
  Creates a new `CanonicalInstantiator` that instantiates a given class.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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 org.apache.geode.Instantiator

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

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### CanonicalInstantiator

    public CanonicalInstantiator(Class<? extends DataSerializable> c, int 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 not be zero. This has been an `int` since dsPhase1.
    Throws:
      `IllegalArgumentException` - If `c` does not implement `DataSerializable`, `classId` is less than or equal to zero.
      `NullPointerException` - If `c` is `null`

- ## Method Details

  - ### newInstance

    public DataSerializable newInstance()
    This method is not supported and if called will throw UnsupportedOperationException. Use `newInstance(DataInput)` instead.
    Specified by:
      `newInstance` in class `Instantiator`
    Returns:
      a new "empty" instance of a `DataSerializable` class
    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:
      GemFire 5.1