org.apache.geode.pdx

Interface PdxInstanceFactory

public interface PdxInstanceFactory

PdxInstanceFactory gives you a way to create PdxInstances. Call the write methods to populate the field data and then call create() to produce an actual instance that contains the data. To create a factory call RegionService.createPdxInstanceFactory(String). A factory can only create a single instance. To create multiple instances create multiple factories or use PdxInstance.createWriter() to create subsequent instances. Using PdxInstance.createWriter() is usually faster.

Since:

GemFire 6.6.2

Method Summary

Modifier and Type	Method and Description
PdxInstance	create() Create a PdxInstance.
PdxInstanceFactory	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.
PdxInstanceFactory	neverDeserialize() The instance created by this factory will be one that is never deserialized to a domain class.
PdxInstanceFactory	writeArrayOfByteArrays(String fieldName, byte[][] value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeBoolean(String fieldName, boolean value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeBooleanArray(String fieldName, boolean[] value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeByte(String fieldName, byte value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeByteArray(String fieldName, byte[] value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeChar(String fieldName, char value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeCharArray(String fieldName, char[] value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeDate(String fieldName, Date value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeDouble(String fieldName, double value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeDoubleArray(String fieldName, double[] value) Writes the named field with the given value to the serialized form.
<CT,VT extends CT> PdxInstanceFactory	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> PdxInstanceFactory	writeField(String fieldName, VT fieldValue, Class<CT> fieldType, boolean checkPortability) Writes the named field with the given value and type to the serialized form.
PdxInstanceFactory	writeFloat(String fieldName, float value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeFloatArray(String fieldName, float[] value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeInt(String fieldName, int value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeIntArray(String fieldName, int[] value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeLong(String fieldName, long value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeLongArray(String fieldName, long[] value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeObject(String fieldName, Object value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeObject(String fieldName, Object value, boolean checkPortability) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeObjectArray(String fieldName, Object[] value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeObjectArray(String fieldName, Object[] value, boolean checkPortability) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeShort(String fieldName, short value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeShortArray(String fieldName, short[] value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeString(String fieldName, String value) Writes the named field with the given value to the serialized form.
PdxInstanceFactory	writeStringArray(String fieldName, String[] value) Writes the named field with the given value to the serialized form.

Method Detail

create

PdxInstance create()

Create a PdxInstance. The instance will contain any data written to this factory using the write methods.

Returns:

the created instance

Throws:

IllegalStateException - if called more than once

writeChar

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeBoolean

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeByte

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeShort

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeInt

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeLong

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeFloat

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeDouble

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeDate

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeString

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeObject

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeObject

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if checkPortability is true and a non-portable object is serialized

PdxSerializationException - if serialization of the field fails.

Since:

GemFire 6.6.2

writeBooleanArray

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeCharArray

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeByteArray

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeShortArray

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeIntArray

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeLongArray

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeFloatArray

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeDoubleArray

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeStringArray

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeObjectArray

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeObjectArray

PdxInstanceFactory 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 writeObjectArray(String, Object[], boolean).

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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if checkPortability is true and a non-portable element is serialized

PdxSerializationException - if serialization of the field fails.

Since:

GemFire 6.6.2

writeArrayOfByteArrays

PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeField

<CT,VT extends CT> PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if serialization of the field fails.

writeField

<CT,VT extends CT> PdxInstanceFactory 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 PdxInstanceFactory

Throws:

PdxFieldAlreadyExistsException - if the named field has already been written

PdxSerializationException - if checkPortability is true and a non-portable object is serialized

PdxSerializationException - if serialization of the field fails.

Since:

GemFire 6.6.2

markIdentityField

PdxInstanceFactory 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 make marked after they are written using a write* method.

Parameters:

fieldName - the name of the field to mark as an identity field.

Returns:

this PdxInstanceFactory

Throws:

PdxFieldDoesNotExistException - if the named field has not already been written.

neverDeserialize

PdxInstanceFactory neverDeserialize()

The instance created by this factory will be one that is never deserialized to a domain class. It will always be a PdxInstance.

Returns:

this PdxInstanceFactory

Since:

Geode 1.9