Using Coherence Portable Object Format Annotations

Purpose

Serialization, or marshalling,  is the process of encoding an object into a binary format. It is a critical component of working with Oracle Coherence.

The Portable Object Format, or POF, is a language-agnostic binary format designed to be efficient in both space and time and has become a cornerstone of Oracle Coherence. Oracle Coherence 3.7 introduced the concept of POF annotations, enabling simple objects to support POF serialization without complex coding.

Time to Complete

One of the more useful aspects of Coherence is its support for simple interoperability between various platforms.  While most of the code accessing Coherence is cluster-side and written in Java, Coherence clients can be written in Java, .NET, or C++.  There are no special constraints on the client. Instead, code is written in the language of choice, compiled against a client library, and then run. 

What makes this possible are two things: Coherence*Extend and a specialized version of serialization known as Coherence Portable Object Format (POF). POF is a platform-independent mechanism for serializing objects into and out of a binary format. An object is marshalled into binary using POF, stored in a Coherence cache, and then unmarshalled to whatever format is appropriate for the client application.

In general, you should choose POF instead of standard Java serialization because POF is:

• Language independent: POF supports Java, C#, and C++.
• Small: POF objects are often 1/5 the size of objects serialized with Java.
• Fast: POF objects can be serialized in less than 1/4 the time of their Java counterparts.
• Versionable: POF objects can evolve over time but maintain backward compatibility.
  
• Controllable: Developers can control how POF objects are serialized and deserialized.
  

When working with POF, a developer typically extends a domain object to implement the com.tangosol.io.pof.PortableObject interface. The readExternal and writeExternal methods of this interface then do the work of marshalling and unmarshalling data into and out of a POF data stream. Although it is not exceedingly complex, implementing these interfaces had a variety of advantages and disadvantages. Coherence 3.7 provides POF annotations, a new feature that can be used to simplify the POF process.

This tutorial covers the use of Coherence 3.7 POF annotations to extend and register objects that support serialization.

Hardware and Software Requirements

• Coherence 3.7.1, which can be downloaded here
  
• Coherence POF OBE sample code, which can be downloaded here
  

Prerequisites

Before starting this tutorial, you should have: 

• Basic working knowledge of Linux commands and command-line syntax
  
• Coherence 3.7.1 installed on your machine
  
• The OBE sample code downloaded and unpacked. This code is designed to run on Linux and similar operating systems but can be adapted to Windows if required.
• Oracle Java JDK version 1.6.0_26 (or later) downloaded and installed. The Oracle JDK kits and associated products can be found here.
  Note: The installation of Java is outside the scope of this OBE. For more information, see the JDK download and installation pages. 
• A working knowledge of Java annotations

Before running this tutorial, you should download and install Oracle Coherence 3.7.1 and the associated example source code. The following steps review the installation process of Coherence 3.7.1, as well as the expected installation locations. 

Note: You can skip this step if you have already installed Coherence 3.7.1.

Annotations

Coherence POF is based on the concept of an annotation. Annotations are:

• Based on "JSR 175: A Metadata Facility for the Java Programming Language" and were introduced in Java 5
  
• Added to classes to define boilerplate behavior or characteristics
• Defined via interfaces and applied to classes by using an @Characteristic class {...} syntax

package com.tangosol.io.pof.annotation;
@Target(value=TYPE)
@Retention(value=RUNTIME)
public interface Portable extends Annotation {}

package com.tangosol.io.pof.annotation;
@Target(value={FIELD,METHOD})
@Retention(value=RUNTIME)
public interface PortableProperty extends Annotation {
    public abstract int value();
    public abstract Class codec();
}

In the preceding section, we modified entity objects to support POF serialization via POF annotations. In this section, we complete the picture by configuring Coherence to use POF as a serialization mechanism. To use POF serialization, we will perform the following tasks:

• Create and populate a POF configuration file.
• Configure Coherence to use the newly crated POF configuration.
  

In this tutorial, you should have learned:

• What Portable Object Format (POF) annotations are
  
• How POF annotations are used in Java entity classes
  
• How to test classes that implement POF annotations
• How to configure Oracle Coherence to use POF for serialization
  

Resources

• The Oracle Coherence 3.7.1 documentation (click here)
  
• Various Oracle University classes on Oracle Coherence development and administration (plus advanced training) that can be found here
  
• Additional OBEs in the Oracle Learning Library
  

Credits

• Lead curriculum developer: Al Saganich
  
• Other contributors: Jason Howes, Tim Middleton, Noah Arliss, and others