PdxWriter (Apache Geode 1.15.4)

org.apache.geode.pdx

## Interface PdxWriter

-     public interface PdxWriter

  A PdxWriter will be passed to `toData` or `PdxSerializer toData` by GemFire when it is serializing the domain class. The domain class needs to serialize instance fields using this interface. This interface is implemented by GemFire.

  The order in which the fields are written must match the order in which they are read by `PdxReader`.

  Field names are case sensitive.

  All methods on this interface return itself to allow method calls to be chained together.

  Since:
    GemFire 6.6

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `PdxWriter` | `markIdentityField(String fieldName)` Indicate that the named field should be included in hashCode and equals checks of this object on a server that is accessing `PdxInstance` or when a client executes a query on a server.
    `PdxWriter` | `writeArrayOfByteArrays(String fieldName, byte[][] value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeBoolean(String fieldName, boolean value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeBooleanArray(String fieldName, boolean[] value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeByte(String fieldName, byte value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeByteArray(String fieldName, byte[] value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeChar(String fieldName, char value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeCharArray(String fieldName, char[] value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeDate(String fieldName, Date value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeDouble(String fieldName, double value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeDoubleArray(String fieldName, double[] value)` Writes the named field with the given value to the serialized form.
    `<CT,VT extends CT> PdxWriter` | `writeField(String fieldName, VT fieldValue, Class<CT> fieldType)` Writes the named field with the given value and type to the serialized form.
    `<CT,VT extends CT> PdxWriter` | `writeField(String fieldName, VT fieldValue, Class<CT> fieldType, boolean checkPortability)` Writes the named field with the given value and type to the serialized form.
    `PdxWriter` | `writeFloat(String fieldName, float value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeFloatArray(String fieldName, float[] value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeInt(String fieldName, int value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeIntArray(String fieldName, int[] value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeLong(String fieldName, long value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeLongArray(String fieldName, long[] value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeObject(String fieldName, Object value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeObject(String fieldName, Object value, boolean checkPortability)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeObjectArray(String fieldName, Object[] value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeObjectArray(String fieldName, Object[] value, boolean checkPortability)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeShort(String fieldName, short value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeShortArray(String fieldName, short[] value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeString(String fieldName, String value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeStringArray(String fieldName, String[] value)` Writes the named field with the given value to the serialized form.
    `PdxWriter` | `writeUnreadFields(PdxUnreadFields unread)` Writes the given unread fields to the serialized form.

- - ### Method Detail

    - #### writeChar

          PdxWriter writeChar(String fieldName,
                              char value)

      Writes the named field with the given value to the serialized form. The fields type is `char`.

      Java char is mapped to .NET System.Char.

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeBoolean

          PdxWriter writeBoolean(String fieldName,
                                 boolean value)

      Writes the named field with the given value to the serialized form. The fields type is `boolean`.

      Java boolean is mapped to .NET System.Boolean.

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeByte

          PdxWriter writeByte(String fieldName,
                              byte value)

      Writes the named field with the given value to the serialized form. The fields type is `byte`.

      Java byte is mapped to .NET System.SByte.

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeShort

          PdxWriter writeShort(String fieldName,
                               short value)

      Writes the named field with the given value to the serialized form. The fields type is `short`.

      Java short is mapped to .NET System.Int16.

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeInt

          PdxWriter writeInt(String fieldName,
                             int value)

      Writes the named field with the given value to the serialized form. The fields type is `int`.

      Java int is mapped to .NET System.Int32.

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeLong

          PdxWriter writeLong(String fieldName,
                              long value)

      Writes the named field with the given value to the serialized form. The fields type is `long`.

      Java long is mapped to .NET System.Int64.

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeFloat

          PdxWriter writeFloat(String fieldName,
                               float value)

      Writes the named field with the given value to the serialized form. The fields type is `float`.

      Java float is mapped to .NET System.Float.

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeDouble

          PdxWriter writeDouble(String fieldName,
                                double value)

      Writes the named field with the given value to the serialized form. The fields type is `double`.

      Java double is mapped to .NET System.Double.

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeDate

          PdxWriter writeDate(String fieldName,
                              Date value)

      Writes the named field with the given value to the serialized form. The fields type is `Date`.

      Java Date is mapped to .NET System.DateTime.

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeString

          PdxWriter writeString(String fieldName,
                                String value)

      Writes the named field with the given value to the serialized form. The fields type is `String`.

      Java String is mapped to .NET System.String.

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeObject

          PdxWriter writeObject(String fieldName,
                                Object value)

      Writes the named field with the given value to the serialized form. The fields type is `Object`.

      It is best to use one of the other writeXXX methods if your field type will always be XXX. This method allows the field value to be anything that is an instance of Object. This gives you more flexibility but more space is used to store the serialized field.

      Note that some Java objects serialized with this method may not be compatible with non-java languages. To ensure that only portable objects are serialized use `writeObject(String, Object, boolean)`.

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeObject

          PdxWriter writeObject(String fieldName,
                                Object value,
                                boolean checkPortability)

      Writes the named field with the given value to the serialized form. The fields type is `Object`.

      It is best to use one of the other writeXXX methods if your field type will always be XXX. This method allows the field value to be anything that is an instance of Object. This gives you more flexibility but more space is used to store the serialized field.

      Note that some Java objects serialized with this method may not be compatible with non-java languages. To ensure that only portable objects are serialized set the `checkPortability` parameter to true. The following is a list of the Java classes that are portable and the .NET class they are mapped to:

      - instances of `PdxSerializable`: .NET class of same name
      - instances of `PdxInstance`: .NET class of same name
      - instances serialized by a `PdxSerializer`: .NET class of same name
      - java.lang.Byte: System.SByte
      - java.lang.Boolean: System.Boolean
      - java.lang.Character: System.Char
      - java.lang.Short: System.Int16
      - java.lang.Integer: System.Int32
      - java.lang.Long: System.Int64
      - java.lang.Float: System.Float
      - java.lang.Double: System.Double
      - java.lang.String: System.String
      - java.util.Date: System.DateTime
      - byte[]: System.Byte[]
      - boolean[]: System.Boolean[]
      - char[]: System.Char[]
      - short[]: System.Int16[]
      - int[]: System.Int32[]
      - long[]: System.Int64[]
      - float[]: System.Float[]
      - double[]: System.Double[]
      - String[]: System.String[]
      - byte[][]: System.Byte[][]
      - Object[]: System.Collections.Generic.List<Object>
      - java.util.HashMap: System.Collections.Generics.IDictionary<Object, Object>
      - java.util.Hashtable: System.Collections.Hashtable
      - java.util.ArrayList: System.Collections.Generic.IList<Object>
      - java.util.Vector: System.Collections.ArrayList
      - java.util.HashSet: CacheableHashSet
      - java.util.LinkedHashSet: CacheableLinkedHashSet
      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
        `checkPortability` - if true then an exception is thrown if a non-portable object is serialized
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `NonPortableClassException` - if checkPortability is true and a non-portable object is serialized
        `PdxSerializationException` - if serialization of the field fails.
      Since:
        GemFire 6.6.2

    - #### writeBooleanArray

          PdxWriter writeBooleanArray(String fieldName,
                                      boolean[] value)

      Writes the named field with the given value to the serialized form. The fields type is `boolean[]`.

      Java boolean[] is mapped to .NET System.Boolean[].

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeCharArray

          PdxWriter writeCharArray(String fieldName,
                                   char[] value)

      Writes the named field with the given value to the serialized form. The fields type is `char[]`.

      Java char[] is mapped to .NET System.Char[].

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeByteArray

          PdxWriter writeByteArray(String fieldName,
                                   byte[] value)

      Writes the named field with the given value to the serialized form. The fields type is `byte[]`.

      Java byte[] is mapped to .NET System.Byte[].

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeShortArray

          PdxWriter writeShortArray(String fieldName,
                                    short[] value)

      Writes the named field with the given value to the serialized form. The fields type is `short[]`.

      Java short[] is mapped to .NET System.Int16[].

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeIntArray

          PdxWriter writeIntArray(String fieldName,
                                  int[] value)

      Writes the named field with the given value to the serialized form. The fields type is `int[]`.

      Java int[] is mapped to .NET System.Int32[].

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeLongArray

          PdxWriter writeLongArray(String fieldName,
                                   long[] value)

      Writes the named field with the given value to the serialized form. The fields type is `long[]`.

      Java long[] is mapped to .NET System.Int64[].

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeFloatArray

          PdxWriter writeFloatArray(String fieldName,
                                    float[] value)

      Writes the named field with the given value to the serialized form. The fields type is `float[]`.

      Java float[] is mapped to .NET System.Float[].

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeDoubleArray

          PdxWriter writeDoubleArray(String fieldName,
                                     double[] value)

      Writes the named field with the given value to the serialized form. The fields type is `double[]`.

      Java double[] is mapped to .NET System.Double[].

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeStringArray

          PdxWriter writeStringArray(String fieldName,
                                     String[] value)

      Writes the named field with the given value to the serialized form. The fields type is `String[]`.

      Java String[] is mapped to .NET System.String[].

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeObjectArray

          PdxWriter writeObjectArray(String fieldName,
                                     Object[] value)

      Writes the named field with the given value to the serialized form. The fields type is `Object[]`.

      Java Object[] is mapped to .NET `System.Collections.Generic.List<Object>`. For how each element of the array is a mapped to .NET see `writeObject`. Note that this call may serialize elements that are not compatible with non-java languages. To ensure that only portable objects are serialized use `writeObjectArray(String, Object[], boolean)`.

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeObjectArray

          PdxWriter writeObjectArray(String fieldName,
                                     Object[] value,
                                     boolean checkPortability)

      Writes the named field with the given value to the serialized form. The fields type is `Object[]`.

      Java Object[] is mapped to .NET System.Collections.Generic.List<Object>. For how each element of the array is a mapped to .NET see `writeObject`. Note that this call may serialize elements that are not compatible with non-java languages. To ensure that only portable objects are serialized use this method

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
        `checkPortability` - if true then an exception is thrown if a non-portable object is serialized
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `NonPortableClassException` - if checkPortability is true and a non-portable element is serialized
        `PdxSerializationException` - if serialization of the field fails.
      Since:
        GemFire 6.6.2

    - #### writeArrayOfByteArrays

          PdxWriter writeArrayOfByteArrays(String fieldName,
                                           byte[][] value)

      Writes the named field with the given value to the serialized form. The fields type is `byte[][]`.

      Java byte[][] is mapped to .NET System.Byte[][].

      Parameters:
        `fieldName` - the name of the field to write
        `value` - the value of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeField

          <CT,VT extends CT> PdxWriter writeField(String fieldName,
                                                  VT fieldValue,
                                                  Class<CT> fieldType)

      Writes the named field with the given value and type to the serialized form. This method uses the `fieldType` to determine which writeXXX method it should call. If it can not find a specific match to a writeXXX method it will call `writeObject`. This method may serialize objects that are not portable to non-java languages. To ensure that only objects that are portable to non-java languages are serialized use `writeField(String, Object, Class, boolean)` instead.

      The fieldTypes that map to a specific method are:

      - boolean.class: `writeBoolean(java.lang.String, boolean)`
      - byte.class: `writeByte(java.lang.String, byte)`
      - char.class: `writeChar(java.lang.String, char)`
      - short.class: `writeShort(java.lang.String, short)`
      - int.class: `writeInt(java.lang.String, int)`
      - long.class: `writeLong(java.lang.String, long)`
      - float.class: `writeFloat(java.lang.String, float)`
      - double.class: `writeDouble(java.lang.String, double)`
      - String.class: `writeString(java.lang.String, java.lang.String)`
      - Date.class: `writeDate(java.lang.String, java.util.Date)`
      - boolean[].class: `writeBooleanArray(java.lang.String, boolean[])`
      - byte[].class: `writeByteArray(java.lang.String, byte[])`
      - char[].class: `writeCharArray(java.lang.String, char[])`
      - short[].class: `writeShortArray(java.lang.String, short[])`
      - int[].class: `writeIntArray(java.lang.String, int[])`
      - long[].class: `writeLongArray(java.lang.String, long[])`
      - float[].class: `writeFloatArray(java.lang.String, float[])`
      - double[].class: `writeDoubleArray(java.lang.String, double[])`
      - String[].class: `writeStringArray(java.lang.String, java.lang.String[])`
      - byte[][].class: `writeArrayOfByteArrays(java.lang.String, byte[][])`
      - any other array class: `writeObjectArray(java.lang.String, java.lang.Object[])`
      Note that the object form of primitives, for example Integer.class and Long.class, map to `writeObject`.
      Type Parameters:
        `CT` - the type associated with the class of the field to write
        `VT` - the type associated with the value of the field to write
      Parameters:
        `fieldName` - the name of the field to write
        `fieldValue` - the value of the field to write; this parameter's class must extend the `fieldType`
        `fieldType` - the type of the field to write
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `PdxSerializationException` - if serialization of the field fails.

    - #### writeField

          <CT,VT extends CT> PdxWriter writeField(String fieldName,
                                                  VT fieldValue,
                                                  Class<CT> fieldType,
                                                  boolean checkPortability)

      Writes the named field with the given value and type to the serialized form. This method uses the `fieldType` to determine which writeXXX method it should call. If it can not find a specific match to a writeXXX method it will call `writeObject`. To ensure that only objects that are portable to non-java languages are serialized set the `checkPortability` parameter to true.

      The fieldTypes that map to a specific method are:

      - boolean.class: `writeBoolean(java.lang.String, boolean)`
      - byte.class: `writeByte(java.lang.String, byte)`
      - char.class: `writeChar(java.lang.String, char)`
      - short.class: `writeShort(java.lang.String, short)`
      - int.class: `writeInt(java.lang.String, int)`
      - long.class: `writeLong(java.lang.String, long)`
      - float.class: `writeFloat(java.lang.String, float)`
      - double.class: `writeDouble(java.lang.String, double)`
      - String.class: `writeString(java.lang.String, java.lang.String)`
      - Date.class: `writeDate(java.lang.String, java.util.Date)`
      - boolean[].class: `writeBooleanArray(java.lang.String, boolean[])`
      - byte[].class: `writeByteArray(java.lang.String, byte[])`
      - char[].class: `writeCharArray(java.lang.String, char[])`
      - short[].class: `writeShortArray(java.lang.String, short[])`
      - int[].class: `writeIntArray(java.lang.String, int[])`
      - long[].class: `writeLongArray(java.lang.String, long[])`
      - float[].class: `writeFloatArray(java.lang.String, float[])`
      - double[].class: `writeDoubleArray(java.lang.String, double[])`
      - String[].class: `writeStringArray(java.lang.String, java.lang.String[])`
      - byte[][].class: `writeArrayOfByteArrays(java.lang.String, byte[][])`
      - any other array class: `writeObjectArray(String, Object[], boolean)`
      Note that the object form of primitives, for example Integer.class and Long.class, map to `writeObject`.
      Type Parameters:
        `CT` - the type associated with the class of the field to write
        `VT` - the type associated with the value of the field to write
      Parameters:
        `fieldName` - the name of the field to write
        `fieldValue` - the value of the field to write; this parameter's class must extend the `fieldType`
        `fieldType` - the type of the field to write
        `checkPortability` - if true then an exception is thrown if a non-portable object is serialized
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if the named field has already been written
        `NonPortableClassException` - if checkPortability is true and a non-portable object is serialized
        `PdxSerializationException` - if serialization of the field fails.
      Since:
        GemFire 6.6.2

    - #### writeUnreadFields

          PdxWriter writeUnreadFields(PdxUnreadFields unread)

      Writes the given unread fields to the serialized form. The unread fields are obtained by calling `readUnreadFields`.

      This method must be called first before any of the writeXXX methods is called.

      Parameters:
        `unread` - the object that was returned from `readUnreadFields`.
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldAlreadyExistsException` - if one of the writeXXX methods has already been called.

    - #### markIdentityField

          PdxWriter markIdentityField(String fieldName)

      Indicate that the named field should be included in hashCode and equals checks of this object on a server that is accessing `PdxInstance` or when a client executes a query on a server. The fields that are marked as identity fields are used to generate the hashCode and equals methods of `PdxInstance`. Because of this, the identity fields should themselves either be primitives, or implement hashCode and equals. If no fields are set as identity fields, then all fields will be used in hashCode and equals checks. The identity fields should be marked after they are written using a write* method.
      Parameters:
        `fieldName` - the name of the field to mark as an identity field.
      Returns:
        this PdxWriter
      Throws:
        `PdxFieldDoesNotExistException` - if the named field has not already been written.