Serializing Data

Data in your client application’s GemFire cache must be serializable to be shared with GemFire servers and other GemFire clients. GemFire provides multiple data serialization options for storage and transmittal between processes, of which GemFire Portable Data eXchange (PDX) serialization offers the best combination of versatility and ease-of-use for most applications.

To learn more about other serialization options, see the Data Serialization section in the VMware Tanzu GemFire User Guide.

Implementing a PdxSerializable Custom Class

Pdx serialization provides custom serialization to an individual class. Fields within an object can be serialized separately from the rest of the class.

The type of serialization and its implementation can be specified entirely in the client application, with no need to create corresponding code on the GemFire server.

Setup

Pdx serialization provides custom serialization to an individual class. Fields within an object can be serialized separately from the rest of the class.

Setting up a custom class for PdxSerializable treatment requires some preparatory steps:

The custom class must inherit from the .NET IPdxSerializable interface.
You must provide serialization instructions for objects of the custom class. Specifically:
- You must implement the ToData() and FromData() methods.
- You must provide a “factory method” that returns an instance of the custom object.
Your application must register your custom class with the cache, which takes care of informing the server of your serialization scheme. With registration, you provide the name of the “factory method” you created for instantiating objects of the custom class.

PdxSerializable Examples

The native client release contains examples showing how a client application can register for serialization of custom objects using the .NET IPdxSerializable interface.

The examples are located in examples\dotnet\pdxserializable.

The examples define the serializable class, Orders, including its serialization and deserialization methods and its factory method. Once these pieces are in place, execution is simple: the main routine of the example registers the serializable class then performs some put and get operations.

Execution

The example performs a sequence of operations, displaying simple log entries as they run.

To run an example, follow the instructions in the README.md file in the example directory.
Review the source code in the example directory to see exactly how it operates.
Begin by running a script that sets up the server-side environment by invoking gfsh commands to create a region, a locator, and a server.
Run the example client application, which performs the following steps:
- Connects to the server
- Registers the PdxSerializable class
- Creates orders
- Stores orders
- Retrieves orders

.NET Example

This section contains code snippets showing highlights of the .NET PdxSerializable example. They are not intended for cut-and-paste execution. For the complete source, see the example source directory.

The .NET example defines a PdxSerializable class called Order that inherits from the IPdxSerializable interface. An Order object contains three fields:

an integer order_id
a string name
a short-int quantity

From Order.cs:

  public class Order : IPdxSerializable
  {
    ...
    public long OrderId { get; set; }
    public string Name { get; set; }
    public short Quantity { get; set; }

Using the IPdxSerializable read and write methods, the Order class defines ToData() and FromData() methods that perform the serialization and deserialization operations, respectively, and the CreateDeserializable() factory method:

From Order.cs:

    public void ToData(IPdxWriter output)
    {
      output.WriteLong(ORDER_ID_KEY_, OrderId);
      output.MarkIdentityField(ORDER_ID_KEY_);

      output.WriteString(NAME_KEY_, Name);
      output.MarkIdentityField(NAME_KEY_);

      output.WriteInt(QUANTITY_KEY_, Quantity);
      output.MarkIdentityField(QUANTITY_KEY_);
    }

    public void FromData(IPdxReader input)
    {
      OrderId = input.ReadLong(ORDER_ID_KEY_);
      Name = input.ReadString(NAME_KEY_);
      Quantity = (short)input.ReadInt(QUANTITY_KEY_);
    }

    public static IPdxSerializable CreateDeserializable()
    {
      return new Order();
    }

The .NET example mainline creates a cache, then uses it to register the PdxSerializable class that was created in Orders.cs:

   var cacheFactory = new CacheFactory()
       .Set("log-level", "none");
   var cache = cacheFactory.Create();

   cache.TypeRegistry.RegisterPdxType(Order.CreateDeserializable);

The client creates a connection pool and a region named “example_orderobject”:

   var poolFactory = cache.GetPoolFactory()
       .AddLocator("localhost", 10334);
   poolFactory.Create("pool");

   var regionFactory = cache.CreateRegionFactory(RegionShortcut.PROXY)
        .SetPoolName("pool");
   var orderRegion = regionFactory.Create<int, Order>("example_orderobject");

After declaring some keys and values, the client then stores and retrieves an Order object:

    const int orderKey = 65;

    var order = new Order(orderKey, "Donuts", 12);

    Console.WriteLine("order to put is " + order);
    orderRegion.Put(orderKey, order, null);

    Console.WriteLine("Successfully put order, getting now...");
    var orderRetrieved = orderRegion.Get(orderKey, null);

    Console.WriteLine("Order key: " + orderKey + " = " + orderRetrieved);

Finally, the application closes the cache:

    cache.Close();