CanonicalInstantiator (Apache Geode 1.13.6)
Date: 2021-12-14

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 and Description
    `CanonicalInstantiator(Class<? extends DataSerializable> c, int classId)` Creates a new `CanonicalInstantiator` that instantiates a given class.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and 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 Detail

    - #### 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 Detail

    - #### 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`
      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