In fact, Portable Types provide a better and more complete evolution support than the implementation of the Evolvable interface by hand.

One of the limitations of the Evolvable interface is that it only supports the evolution of the leaf classes in the class hierarchy. Portable Types do not have this limitation, and allow you to not only evolve any class in the hierarchy, but also to evolve the class hierarchy itself, by adding new classes to any level of the class hierarchy.

Additional attribute-level annotations allow you to control certain serialization behaviors that are specific to the type of the attribute.

For example, @PortableDate allows you to control whether you want to serialize date, time, or both when serializing java.util.Date instances (by using the mode property), and whether time zone information should be included (by using the includeTimezone property).

If you are using Java 8 (or later) java.time classes, you can derive this information from the class itself by using the @Portable annotation instead. For example, LocalTime will be serialized as time only, with no time zone information, while the OffsetDateTime will be serialized as both date and time, with time zone information.

Similarly, when serializing arrays, collections and maps, POF allows you to use uniform encoding, where the element type (or key and/or value type, in case of maps) is written into the POF stream only once, instead of once for each element of the collection, resulting in a more compact serialized form.

public class MyClass
    {
    @PortableArray(elementClass = String.class)
    private String[] m_stringArray;

    @PortableSet(elementClass = String.class, clazz = LinkedHashSet.class)
    private Set<String> m_setOfStrings;

    @PortableList(elementClass = String.class)
    private List<String> m_listOfStrings;

    @PortableMap(keyClass = Integer.class, valueClass = String.class, clazz = TreeMap.class)
    private Map<Integer, String> m_uniformMap;
    }

As you can see from the examples above, these annotations also allow you to specify the concrete class that should be created during deserialization for a given attribute. If you do not specify the clazz property, HashSet will be used as the default set type, ArrayList as the default list type, and HashMap as the default map type.

Coherence is a distributed system, and there is no guarantee that every cluster member, and every client process that connects to the cluster, will have the same version of each and every class. In fact, it is certainly true for systems that use rolling upgrades to avoid any downtime.

It is also neither safe nor practical to upgrade the cluster and all the clients at the same time. Therefore, being able to tolerate different versions of the same class across cluster members and clients is not only desirable, but a necessity for many.

The issue is that when a process that has an older version of the class reads serialized data created from the newer version of the same class, it may encounter some attributes that it knows nothing about. Ideally, it should be able to ignore them and read the attributes it needs and knows about, instead of crashing, but that only solves part of the problem. If the process ignores the unknown attributes completely, when it writes the same data back by serializing an older version of the class that is only aware of some attributes, the process will lose the data it previously received but knows nothing about.

Obviously, this is not a desirable scenario for a system that is intended for long-term data storage. POF supports class evolution in a way that ensures that no data is lost, regardless of how many versions of the same class are present across the various cluster and client processes, and regardless of which of those processes read or write the data. The support for class evolution has been in POF from the very beginning, through the Evolvable interface, but Portable Types remove some of the limitations and make the whole process significantly simpler.

Both the class annotation (@PortableType) and the attribute annotations (@Portable and related annotations) provide a way to specify versioning information that is necessary for class evolution.

At the class level, whenever you modify a class by introducing a new attribute, you should increment the version property of the @PortableType annotation.

@PortableType(id = 1, version = 1)
public class Pet
    {
    @Portable
    protected String name;

    @Portable(since = 1)
    protected int age;

    // constructors, accessors, etc.
    }

@PortableType(id = 2, version = 1)
public class Dog extends Pet
    {
    @Portable
    private String breed;

    @Portable(since = 1)
    private Color color;

    // constructors, accessors, etc.
    }

Notice that both version and since properties are zero-based, which allows you to omit them completely in the initial implementation. It also means that for the first subsequent revision, they should be set to 1.

These are just the defaults. You can certainly set the class and attribute version explicitly to any value even for the initial implementation, if required. The only thing that matters is that you increment the version and set the since property to the latest version number whenever you make changes to the class in future.

@PortableType(id = 1, version = 2)
public class Pet
    {
    @Portable
    protected String name;

    @Portable(since = 1)
    protected int age;

    @Portable(since = 2)
    protected int height;

    @Portable(since = 2)
    protected int weight;

    // constructors, accessors, etc.
    }

Annotating the classes is the first step in the implementation of Portable Types, but that alone is not sufficient. To implement the necessary serialization logic, the classes also need to be instrumented at compile time.

The following options are available for instrumentation:

• Using the Maven POF Plug-In
  
• Using the Gradle POF Plug-In
  

Portable Object Format is not a self-describing serialization format. It replaces platform-specific class names with integer-based type identifiers. Therefore, it needs a way of mapping those type identifiers back to the platform-specific classes. This mapping enables portability across platforms, which is the main objective of POF.

public interface PofContext extends Serializer
    {
    PofSerializer getPofSerializer(int nTypeId);

    int getUserTypeIdentifier(Object o);
    int getUserTypeIdentifier(Class<?> clz);
    int getUserTypeIdentifier(String sClass);

    String getClassName(int nTypeId);
    Class<?> getClass(int nTypeId);

    boolean isUserType(Object o);
    boolean isUserType(Class<?> clz);
    boolean isUserType(String sClass);
    }

It is worth noting that PofContext extends the com.tangosol.io.Serializer interface, which means that you can use any PofContext implementation wherever Coherence expects a Serializer to be specified, that is, within cache services as a storage-level serializer for data classes, as a transport-level serializer between thin clients and the proxy servers, and so on. The PofContext performs the actual serialization by delegating to the appropriate PofSerializer, which is obtained through the PofContext.getPofSerializer method, based on a type identifier.

SimplePofContext ctx = new SimplePofContext();
ctx.registerUserType(1, Pet.class, new PortableTypeSerializer<>(1, Pet.class));
ctx.registerUserType(2, Dog.class, new PortableTypeSerializer<>(2, Dog.class));
ctx.registerUserType(3, Color.class, new EnumPofSerializer());

Notice that a lot of this information is somewhat repetitive and unnecessary when working with Portable Types, as all the metadata you need can be obtained from the class itself or from the @PortableType annotation.

ctx.registerPortableType(Pet.class);
ctx.registerPortableType(Dog.class);

ctx.registerPortableTypes(Pet.class, Dog.class);

While the SimplePofContext is useful for testing and quick prototyping, a PofContext implementation that is much more widely used within Coherence applications is ConfigurablePofContext.

<pof-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xmlns="http://xmlns.oracle.com/coherence/coherence-pof-config"
              xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-pof-config coherence-pof-config.xsd">

  <user-type-list>

    <user-type>
      <type-id>1</type-id>
      <class-name>petstore.Pet</class-name>
    </user-type>

    <user-type>
      <type-id>2</type-id>
      <class-name>petstore.Dog</class-name>
    </user-type>

    <user-type>
      <type-id>3</type-id>
      <class-name>petstore.Color</class-name>
      <serializer>
        <class-name>com.tangosol.io.pof.EnumPofSerializer</class-name>
      </serializer>
    </user-type>

  </user-type-list>

</pof-config>

Notice that you did not specify a serializer explicitly for the Pet and Dog classes. This is because ConfigurablePofContext has the logic to determine which of the built-in PofSerializer implementations to use depending on the interfaces implemented by, or the annotations present on the specified class. In this case, it will automatically use PortableTypeSerializer because the classes have the @PortableType annotation.

<pof-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xmlns="http://xmlns.oracle.com/coherence/coherence-pof-config"
              xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-pof-config coherence-pof-config.xsd">

  <user-type-list>

    <user-type>
      <type-id>3</type-id>
      <class-name>petstore.Color</class-name>
      <serializer>
        <class-name>com.tangosol.io.pof.EnumPofSerializer</class-name>
      </serializer>
    </user-type>

  </user-type-list>

  <enable-type-discovery>true</enable-type-discovery>

</pof-config>

<pof-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xmlns="http://xmlns.oracle.com/coherence/coherence-pof-config"
              xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-pof-config coherence-pof-config.xsd">

  <user-type-list>
    <!-- by default just include coherence POF user types -->
    <include>coherence-pof-config.xml</include>
  </user-type-list>

  <enable-type-discovery>true</enable-type-discovery>

</pof-config>

After you have annotated, instrumented, and registered the Portable Types as described in Class Versioning and Evolution, Instrumenting the Classes at Compile-Time, and Registration and Discovery, you can use them with Coherence just as easily as you would use plain Java Serializable classes, by configuring Coherence services to use pof serializer instead of the default java serializer.

However, there is still one problem. Serialization code is implemented by the pof-maven-plugin plug-in at compile-time, and only if you run the Maven build, which can make it a bit cumbersome to run unit and integration tests within the integrated development environment (IDE).

To solve this problem, Oracle has implemented IDE plug-ins for IntelliJ IDEA and Eclipse. These plug-ins can instrument your classes during incremental or full compilation performed by your IDE. This enables you to test both the serialization of your classes and the code that depends on it without having to run the Maven build or leave your IDE.