org.apache.geode.pdx (Apache Geode 1.13.0)
Date: 2020-09-07

# Package org.apache.geode.pdx

The `org.apache.geode.pdx` package provides APIs used for object serialization.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  PdxInstance | PdxInstance provides run time access to the fields of a PDX without deserializing the PDX.
  PdxInstanceFactory | PdxInstanceFactory gives you a way to create PdxInstances.
  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
  Class | Description
  --- | ---
  JSONFormatter | JSONFormatter has a static method `JSONFormatter.fromJSON(String, String...)` to convert a JSON document into a `PdxInstance` and a static method `JSONFormatter.toJSON(PdxInstance)` to convert a `PdxInstance` into a JSON Document.
  ReflectionBasedAutoSerializer | This class uses Java reflection in conjunction with `PdxSerialzer` to perform automatic serialization of domain objects.

- Enum Summary
  Enum | Description
  --- | ---
  FieldType | Every field of a pdx must have one of these types.

- Exception Summary
  Exception | Description
  --- | ---
  JSONFormatterException | This exception will be thrown, when {link @JSONFormatter} is unable to parse the JSON document or {link @PdxInstance}.
  NonPortableClassException | Thrown if "check-portability" is enabled and an attempt is made to pdx serialize a class that is not portable to non-java platforms.
  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.
  PdxRegistryMismatchException | Thrown when an attempt is made to reuse a PDX Type.
  PdxSerializationException | Thrown if a problem occurred during serialization or deserialization of a PDX.

## Package org.apache.geode.pdx Description

The `org.apache.geode.pdx` package provides APIs used for object serialization. PDX stands for Portable Data eXchange and has the following advantages over other object serialization APIs:

- The serialized form is portable between Java and C#.
- The data in a PDX serialized object can be accessed without deserializing the object. This allows data to be accessed even if the domain class is unavailable. So GemFire servers are able to do things like queries without needing to deserialize the domain objects. Being able to keep the serialized form in the server cache saves time and memory. This also allows a C# developer to only write a C# domain class without needing to also write a corresponding Java domain class.
- PDX supports class versioning. Different versions of the same PDX class are allowed in the same distributed system. So you can add a new version of your application without by just starting a new client. No need to shutdown clients using the old version of the PDX data or of restarting your servers.
- The PDX serialized form is compact because a minimal amount of type information is encoded in the serialized form. This saves memory and time.

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(org.apache.geode.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.

- `read-serialized` Set it to true if you want PDX deserialization to produce a PdxInstance instead of an instance of the domain class.
- `ignore-unread-fields` Set it to true if you do not want unread PDX fields to be preserved during deserialization. This can save you memory and is safe to use in a member that only reads data from the cache.
- `persistent` Set to true if you are using persistent regions or WAN gateways. This causes the PDX type information to be written to disk.
- `disk-store-name` If using persistence this attribute allows you to configure what disk store the PDX type data will be store in. By default the default disk store is used.
- `pdx-serializer` Allows you to configure the `PdxSerializer` for this GemFire member.
- `distributed-system-id` When using PDX with WAN gateways each distributed system must set this gemfire property to a unique value in the range 0..255 inclusive.