GemFire 6.6.1

Package com.gemstone.gemfire.pdx

The com.gemstone.gemfire.pdx package provides APIs used for object serialization.


Interface Summary
PdxInstance PdxInstance provides run time access to the fields of a PDX without deserializing the PDX.
PdxReader A PdxReader will be passed to fromData or PdxSerializer fromData by GemFire during deserialization of a PDX.
PdxSerializable When a domain class implements PdxSerializable it marks itself as a PDX.
PdxSerializer The PdxSerializer interface allows domain classes to be serialized and deserialized as PDXs without modification of the domain class.
PdxUnreadFields Marker interface for an object that GemFire creates and returns from readUnreadFields.
PdxWriter A PdxWriter will be passed to toData or PdxSerializer toData by GemFire when it is serializing the domain class.
WritablePdxInstance WritablePdxInstance is a PdxInstance that also supports field modification using the setField method.

Class Summary
ReflectionBasedAutoSerializer This class uses Java reflection in conjunction with PdxSerialzer to perform automatic serialization of domain objects.

Exception Summary
PdxConfigurationException Thrown when a configuration that is now allowed by PDX is detected.
PdxFieldAlreadyExistsException Thrown when writing a field if the named field already exists.
PdxFieldDoesNotExistException Thrown when a PDX field does not exist and the current operation requires its existence.
PdxFieldTypeMismatchException Thrown if the type of a PDX field was changed or the wrong type was used.
PdxInitializationException Thrown if the PDX system could not be successfully initialized.
PdxSerializationException Thrown if a problem occurred during serialization or deserialization of a PDX.

Package com.gemstone.gemfire.pdx Description

The com.gemstone.gemfire.pdx package provides APIs used for object serialization. PDX stands for Portable Data eXchange and has the following advantages over other object serialization APIs:

To use PDX either implement PdxSerializable on your domain class or implement a PdxSerializer. In either case you use a PdxWriter to serialize your data and a PdxReader to deserialize.

An auto serialization mechanism is also provided as an early access feature. This has the potential to obviate the need for any augmentation of domain classes to allow them to be serialized. See ReflectionBasedAutoSerializer for more details.

The PDX object model is that a PDX type has a name and an ordered list of PDX fields. A PDX field has a name and a field type. For your domain class to be serialized by PDX you must define this meta information. You do this by calling methods on PdxWriter and PdxReader that define the PDX fields. For example calling writeString("stringField", this.stringField) defines a field whose name is "stringField" and whose field type is "String". The PDX type name is the fully qualified domain class name. PDX field names are case sensitive. They do not need to match your instance variable names but this is a good convention to follow. The order in which you write your fields must be the order in which you read them.

As your PDX domain class changes you are free to add and remove fields. But you can not change the field type of a PDX field. For example you can not change from calling writeString to writeDate for the same field name. Once the domain class has changed then some of your fields will not be read during deserialization. For example if you have a PDX class with one field (lets call it version 1) and you then add a second field (lets call it version 2) then when the version 1 code deserializes data from version 2 it will only read field one. So field two will be unread. But when this object is reserialized it will preserve the unread field data and include it in the serialized form (unless you configure ignore-unread-fields to true). You can optimize the amount of memory consumed by unread fields by managing them yourself by calling PdxReader.readUnreadFields() and PdxWriter.writeUnreadFields(com.gemstone.gemfire.pdx.PdxUnreadFields).

To read the fields of a PDX without deserializing it see PdxInstance. To modify the fields of a PDX without deserializing it see WritablePdxInstance.

PDX Configuration

The GemFire Cache has a number of configuration attributes related to PDX. They can be configured using API method on CacheFactory or ClientCacheFactory. They can also be configured in a cache.xml using the pdx element. The following describes the dtd elements and attribute names but corresponding method names are also available on the cache factories.

GemFire 6.6.1

Copyright © 1997-2011 VMware, Inc. All rights reserved.