In order to keep things simple despite the fact that we are creating a multi-platform application, we have decided to implement only a very small set of business requirements:

These requirements should be enough to make the implementation interesting without making it overly complex.

Based on the previous requirements, we can define the following domain model to use as a starting point:

The preceding model is just a rough sketch containing the most important classes in the system. As we go along we will refine it and extend it, but for the time being this should be more than enough.

An entity is an object that has an identity. The identity can be either a natural attribute of an object, such as the country code we used to identify Country objects in Chapter 2, Getting Started, or it can be a surrogate attribute that is generated by the system when the entity is first created. Regardless of the type of identity, what is important is that once an identity is assigned to an entity, it remains the same throughout its lifetime.

An aggregate is a special, composite entity type, which represents a containment relationship between an aggregate root and dependent weak entities. For example, an order contains one or more line items, and while both the order and each individual line item are entities in their own right, a single line item is only meaningful within the larger context of an order.

Entities and aggregates are the most important types of domain objects from the Coherence perspective, as they usually have one-to-one mapping to Coherence caches.

One of the most common mistakes that beginners make is to treat Coherence as an in-memory database and create caches that are too finely grained. For example, they might configure one cache for orders and a separate cache for line items.

While this makes perfect sense when using a relational database, it isn't the best approach when using Coherence. Aggregates represent units of consistency from a business perspective, and the easiest way to achieve atomicity and consistency when using Coherence is to limit the scope of mutating operations to a single cache entry. Because of this, you should almost always store whole aggregates as individual cache entries. In the previous example that we used, an order and all of its line items would be stored as a single cache entry in the orders cache.

One exception to this rule might be the case when the aggregate root contains an unbound, continuously growing collection of dependent entities, such as Account and Transaction items in our domain model. In this case, it makes sense to separate dependent entities into their own cache, in order to avoid infinite growth of the aggregate object and to allow different caching policies to be used (for example, we might decide to keep all the accounts in the cache at all times, but only the last 60 days of transactions for each account, in order to keep the amount of memory used by transactions relatively constant over time).

public interface Entity<T> {
T getId();
}

public class Account
implements Entity<Long>, Serializable {
// data members
private final Long m_id;
private final Long m_customerId;
private String m_description;
private Money m_balance;
private int m_lastTransactionId;
// dependencies
private transient CurrencyConverter m_currencyConverter;
private transient TransactionRepository m_transactionRepository;
// constructor, getters and setters omitted for brevity
...
// core logic
public Money withdraw(Money amount, String description)
throws InsufficientFundsException {
Money balance = m_balance;
if (!balance.isSameCurrency(amount)) {
CurrencyConversion conversion =
getCurrencyConverter().convert(amount, getCurrency());
amount = conversion.getConvertedAmount();
description += " (" +
conversion.getOriginalAmount() + " @ " +
conversion.getExchangeRate() + ")";
}
if (amount.greaterThan(balance)) {
throw new InsufficientFundsException(balance, amount);
}
entity, domain model building blocksimplementingm_balance = balance = balance.subtract(amount);
postTransaction(TransactionType.WITHDRAWAL, description, amount, balance);
return balance;
}
public Money deposit(Money amount, String description) {
// omitted for brevity (similar to withdraw)
}
protected void postTransaction(TransactionType type,
String description,
Money amount, Money balance) {
Transaction transaction =
Transaction.create(m_id, ++m_lastTransactionId,
type, description,
amount, balance);
getTransactionRepository().save(transaction);
}
}

public class Account
implements Entity<Long>, Serializable {
private static IdentityGenerator<Long> s_idGen =
SequenceGenerator.create("account.id", 20);
...
}

public class Account
implements Entity<Long>, Serializable {
...
private Account(Long id, Long customerId,
String description, Money balance) {
m_id = id;
m_customerId = customerId;
m_description = description;
m_balance = balance;
}
static Account create(Customer customer,
String description,
Currency currency) {
return new Account(s_idGen.generateIdentity(),
customer.getId(),
description,
new Money(0, currency));
}
...
}

public class Account
entity, domain model building blocksrelationships, managingimplements Entity<Long>, Serializable {
private final Long m_customerId;
...
public Customer getCustomer() {
return getCustomerRepository()
.getCustomer(m_customerId);
}
}

public class Customer
implements Entity<Long>, Serializable {
private Collection<Long> m_accountIds;
...
public Collection<Account> getAccounts() {
return getAccountRepository()
.getAccounts(m_accountIds);
}
}

private transient CustomerRepository m_customerRepository;
protected CustomerRepository getCustomerRepository() {
if (m_customerRepository == null) {
m_customerRepository =
RepositoryRegistry.getCustomerRepository();
}
return m_customerRepository;
}
public void setCustomerRepository(CustomerRepository customerRepository) {
m_customerRepository = customerRepository;
}

public class Transaction
implements Entity<Id>, Serializable {
...
public static class Id implements Serializable, KeyAssociation {
private Long m_accountId;
private Long m_txNumber;
public LineItemId(Long accountId, Long txNumber) {
m_accountId = accountId;
m_txNumber = txNumber;
}
public Object getAssociatedKey() {
return m_accountId;
}
public boolean equals(Object o) {
...
}
public int hashCode() {
...
}
}
}

public class TransactionAssociator implements KeyAssociator {
public void init(PartitionedService partitionedService) {
}
}

<distributed-scheme>
<!-- ... -->
</distributed-scheme>

Unlike entities, value objects are not uniquely identifiable within a system. They simply represent values from the domain, and are typically immutable (and if they are not, they probably should be). An example of a value object might be a Money object, representing monetary amount, or an Address object, representing a mailing address of a person or a company, and defined by attributes such as street, street number, city, state, postal code, and country.

The value objects are typically used as attributes of entities. That means that they won't have their own cache, but will be stored as part of an entity's serialized state, within the cache for an entity they belong to. For example, our Account entity has a balance attribute represented by the Money value object, which will be serialized and stored with the rest of the account's state.

public class Money implements Serializable {
private final BigDecimal m_amount;
private final Currency m_currency;
public Money(BigDecimal amount, Currency currency) {
m_amount = amount.setScale(
currency.getDefaultFractionDigits(),
RoundingMode.HALF_EVEN);
m_currency = currency;
}
public BigDecimal getAmount() {
return m_amount;
}
public Currency getCurrency() {
return m_currency;
}
}

public class Money implements Serializable {
...
public boolean isSameCurrency(Money money) {
return m_currency.equals(money.m_currency);
}
public Money add(Money money) {
checkCurrency(money);
return new Money(m_amount.add(money.m_amount), m_currency);
}
public Money subtract(Money money) {
checkCurrency(money);
return new Money(m_amount.subtract(money.m_amount), m_currency);
}
public boolean greaterThan(Money money) {
checkCurrency(money);
return m_amount.compareTo(money.m_amount) > 0;
}
public boolean lessThan(Money money) {
checkCurrency(money);
return m_amount.compareTo(money.m_amount) < 0;
}
}

In a rich domain model, the best places to put business logic are the domain objects that the behavior naturally belongs to, such as entities and aggregates. However, in most applications there is some behavior that doesn't clearly belong to any of the data objects. In such cases, you can define services within the domain itself that implement the necessary logic.

These domain-layer services are not the same as the course-grained services most of us got accustomed to while building applications using session EJBs. They are much lighter and much more focused, usually encapsulating only a handful of business methods, and very often only one or two.

You will typically still have a set of coarse-grained services within the orchestration layer, that are used to coordinate multiple activities within the domain layer and transform output into the most appropriate format for the presentation layer. They can also come in handy as a boundary for some of the infrastructure-level services, such as transactions and security.

However, the big difference between these orchestration-layer services and the services most of us used to implement using session beans is that session beans tended to contain most, if not all of the business logic, making domain objects dumb data holders in the process. The orchestration-layer services, on the other hand, are there purely for coordination and boundary definition purposes, while the business logic is implemented within the domain model.

public interface CurrencyConverter {
CurrencyConversion convert(Money amount,
Currency targetCurrency);
}

public class CurrencyConversion {
private final Money m_originalAmount;
private final Money m_convertedAmount;
public CurrencyConversion(Money originalAmount,
Money convertedAmount) {
m_originalAmount = originalAmount;
m_convertedAmount = convertedAmount;
}
public Money getOriginalAmount() {
return m_originalAmount;
}
public Money getConvertedAmount() {
return m_convertedAmount;
}
public BigDecimal getExchangeRate() {
BigDecimal exchangeRate =
m_convertedAmount.getAmount()
.divide(m_originalAmount.getAmount());
return exchangeRate.setScale(4, RoundingMode.HALF_EVEN);
}
}

When we discussed creation of entity instances I mentioned that I prefer a static factory method to a direct use of a constructor. In most cases, either of those two options will be all you need. However, in some cases the creational logic for an entity might be complex, in which case implementing a factory as a separate class might be the best approach.

In most cases, implementing a factory as a separate class is not very different from the static factory method approach. For example, the following factory class is functionally equivalent to the static factory method we created earlier:

public class AccountFactory {
private static IdentityGenerator<Long> s_idGen =
SequenceGenerator.create("account.id", 20);
public Account createAccount(Customer customer,
String description,
Currency currency) {
return new Account(s_idGen.generateIdentity(),
customer.getId(),
description,
new Money(0, currency));
}
}

However, the fact that the factory is now a separate class opens up some interesting possibilities. For example, we could get rid of the hardcoded SequenceGenerator dependency and use Spring to configure the factory instance:

public class AccountFactory {
private IdentityGenerator<Long> m_idGen;
public AccountFactory(IdentityGenerator<Long> idGen) {
m_idGen = idGen;
}
public Account createAccount(Customer customer,
String description,
Currency currency) {
return new Account(m_idGen.generateIdentity(),
customer.getId(),
description,
new Money(0, currency));
}
}

The following Spring configuration could then be used to wire the AccountFactory instance:

<bean id="accountFactory" class="domain.AccountFactory">
<constructor-arg>
<bean class="c.s.c.identity.sequence.SequenceGenerator">
<constructor-arg value="account.id"/>
<constructor-arg value="20"/>
</bean>
</constructor-arg>
</bean>

That way you can let Spring manage dependencies and will be able to provide a fake or mock for the identity generator within unit tests, which alone might be a good enough reason to take this extra step.

The factories are useful when we need to create new instances of domain objects, but in many cases we simply need to retrieve the existing instances. In order to accomplish that, we can use a repository.

According to Domain Driven Design, a repository can be thought of as an unlimited, memory-backed object store containing all objects of a specific type. If that definition reminds you of a Coherence cache, you are not alone—a Coherence cache is a great object repository indeed.

Ideally, the repository interface should be completely independent of the underlying infrastructure and should be expressed in terms of domain objects and their attributes only. For example, we could define AccountRepository like this:

public interface AccountRepository {
Account getAccount(Long id);
Collection<Account> getAccounts(Collection<Long> accountIds);
void save(Account account);
}

As you can see, the interface is completely Coherence agnostic, and can be implemented for pretty much any data source. A Coherence implementation might look like this:

public class CoherenceAccountRepository
implements AccountRepository {
private static final NamedCache s_accounts = CacheFactory.getCache("accounts");
public Account getAccount(Long id) {
return (Account) s_accounts.get(id);
}
public Collection<Account> getAccounts( Collection<Long> accountIds) {
return (Collection<Account>)
s_accounts.getAll(accountIds).values();
}
public void save(Account account) {
s_accounts.put(account.getId(), account);
}
}

What you will quickly notice if you start implementing repositories this way is that basic CRUD operations tend to repeat within every repository implementation, so it makes sense to pull them up into an abstract base class in order to avoid implementing them over and over again:

public abstract class AbstractCoherenceRepository<K, V extends Entity<K>> {
public abstract NamedCache getCache();
public V get(K key) {
return (V) getCache().get(key);
repository, domain model building blocksabstract base class}
public Collection<V> getAll(Collection<K> keys) {
return getCache().getAll(keys).values();
}
public void save(V value) {
getCache().putAll(
Collections.singletonMap(value.getId(), value));
}
public void saveAll(Collection<V> values) {
Map batch = new HashMap(values.size());
for (V value : values) {
batch.put(value.getId(), value);
}
getCache().putAll(batch);
}
}

This abstract base class for our repository implementations uses generics to specify the key and value type for the cache that the repository is used to access, and constrains value type to the types that implement the Entity interface we defined earlier. This allows us to implement the save and saveAll methods as mentioned earlier, because we can obtain the cache key for any entity by calling its getId method.

Our CoherenceAccountRepository implementation now simply becomes:

public class CoherenceOrderRepository
extends AbstractCoherenceRepository<Long, Account>
implements AccountRepository {
private static final NamedCache m_accounts = CacheFactory.getCache("accounts");
public NamedCache getCache() {
return m_accounts;
}
public Account getAccount(Long id) {
return super.get(id);
}
public Collection<Account> getAccounts( Collection<Long> accountIds) {
return super.getAll(accountIds);
}
}

This concludes our coverage of different types of data objects within a domain model and how to map them to Coherence caches. For the most part, you should now know enough to be able to implement your data objects and put them into the cache.

One thing you might've noticed is that, aside from the repository implementation, none of the domain classes we implemented thus far have any dependency on or knowledge of Coherence, despite the somewhat leaky repository abstraction. This is an example of what DDD calls persistence ignorance (PI) and is extremely important as it allows us to unit test our domain model objects in isolation.

For the most part, you can use the domain objects we implemented in this section without any modifications. However, there are several important considerations that we haven't discussed yet that you need to understand in order to implement your data objects (entities and aggregates) in an optimal way.

POF is an extremely compact, platform-independent binary serialization format. It can be used to serialize almost any Java, .NET, or C++ object into a POF value.

A POF value is a binary structure containing type identifier and value. The type identifier is an integer number, where numbers less than zero are used for the intrinsic types, while the numbers greater than zero can be used for custom user types.

User types are what we are interested in most, as all the domain objects we will create within an application are considered user types. The value of a user type is encoded within the POF stream as a list of indexed attributes, where each data member of a user type is encoded by specifying its index within the type. The attribute value is then encoded as a POF value, defined previously.

The fact that attribute indexes are used instead of attribute names makes POF very compact and fast, but it puts burden on the serializer implementation to ensure that attributes are written to and read from the POF stream in the same order, using the same indexes.

This decision, as well as the decision to use an integer type identifier instead of class name to represent the type of the value was made consciously, in order to make POF platform independent—Java class name is meaningless to a .NET client and vice-versa, and attribute names might be as well. The consequence is that unlike many other serialization formats, POF is not a self-describing serialization format by design, and it requires an external means of correlating platform independent user type identifiers with platform-specific classes.

A POF context provides a way to assign POF type identifiers to your custom types. There are two implementations that ship with Coherence, and you are free to implement your own if neither fits the bill, which is highly unlikely.

The first implementation is a SimplePofContext, which allows you to register user types programmatically, by calling the registerUserType method. This method takes three arguments: POF type identifier, a class of a user type, and a POF serializer to use.

The last argument, POF serializer, can be an instance of any class that implements the com.tangosol.io.pof.PofSerializer interface. You can implement the serializer yourself, or you can implement the com.tangosol.io.pof.PortableObject interface within your data objects and use the built-in PortableObjectSerializer, as in the following example:

SimplePofContext ctx = new SimplePofContext();
ctx.registerUserType(1000, Account.class,
new PortableObjectSerializer(1000));
ctx.registerUserType(1001,
Transaction.class,
new PortableObjectSerializer(1001));
ctx.registerUserType(1002,
Customer.class,
new Customer.Serializer());

Regardless of the option chosen, you will also have to implement the actual serialization code that reads and writes object's attributes from/to a POF stream. We will get to that shortly, but now let's take a look at the other implementation of a PofContext interface, a ConfigurablePofContext class.

<!DOCTYPE pof-config SYSTEM "pof-config.dtd">
<pof-config>
<user-type-list>
<include>otherPofConfig</include>
<user-type>
<type-id>typeId</type-id>
<class-name>userTypeClass</class-name>
<serializer>
<class-name>serializerClass</class-name>
<init-params>...</init-params>
</serializer>
</user-type>
...
</user-type-list>
</pof-config>

<!DOCTYPE pof-config SYSTEM "pof-config.dtd">
<pof-config>
<user-type-list>
<user-type>
<type-id>1000</type-id>
<class-name>
sample.domain.Account
</class-name>
</user-type>
<user-type>
<type-id>1001</type-id>
<class-name>
sample.domain.Transaction
</class-name>
</user-type>
<user-type>
<type-id>1002</type-id>
<class-name>
sample.domain.Customer
</class-name>
<serializer>
<class-name>
sample.domain.Customer$Serializer
</class-name>
</serializer>
</user-type>
</user-type-list>
</pof-config>

<include>coherence-pof-config.xml</include>

-Dtangosol.pof.enabled=true
-Dtangosol.pof.config=my-pof-config.xml

The easiest way to implement POF serialization is to make your objects implement the PortableObject interface.

public interface PortableObject extends Serializable {
void readExternal(PofReader pofReader)
throws IOException;
void writeExternal(PofWriter pofWriter)
throws IOException;
}

The methods defined by the PortableObject interface return no value and accept a single argument that allows us to read the indexed attributes from the POF stream, in the case of readExternal, or to write attributes into the POF stream in writeExternal. To learn how to implement these methods, let's look at the implementation of a POF-enabled Customer class:

public class Customer
implements Entity<Long>, PortableObject {
// data members
private final Long m_id;
private String m_name;
private String m_email;
private Address m_address;
private Collection<Long> m_accountIds;
public Customer() {
}
public void readExternal(PofReader pofReader)
throws IOException {
m_id = pofReader.readLong(0);
m_name = pofReader.readString(1);
m_email = pofReader.readString(2);
m_address = (Address) pofReader.readObject(3);
m_accountIds = pofReader.readCollection( 4, new ArrayList<Long>());
}
public void writeExternal(PofWriter pofWriter)
throws IOException {
pofWriter.writeLong(0, m_d);
pofWriter.writeString(1, m_name);
pofWriter.writeString(2, m_email);
pofWriter.writeObject(3, m_address);
pofWriter.writeCollection(4, m_accountIds);
}
}

As you can see, while it probably isn't the most exciting code to write, serialization code is fairly straightforward and simply uses the appropriate PofReader and PofWriter methods to read and write attribute values.

Once you implement the PortableObject interface, all you need to do is register your user type within the POF context by adding a user-type element for it into the POF configuration file, as we've done in the previous section. You can omit the serializer element, and PortableObjectSerializer will be used by default.

The second way to implement serialization logic is to create a separate serializer class that implements the PofSerializer interface:

public interface PofSerializer {
void serialize(PofWriter pofWriter, Object o)
throws IOException;
Object deserialize(PofReader pofReader)
throws IOException;
}

As you can see, the methods that need to be implemented are very similar to the ones defined by the PortableObject interface, so the logic within them will also look familiar:

public class CustomerSerializer implements PofSerializer {
public void serialize(PofWriter writer, Object obj)
throws IOException {
Customer c = (Customer) obj;
writer.writeLong(0, c.getId());
writer.writeString(1, c.getName());
writer.writeString (2, c.getEmail());
writer.writeObject(3, c.getAddress());
writer.writeCollection(4, c.getAccountIds());
writer.writeRemainder(null);
}
public Object deserialize(PofReader reader)
throws IOException {
Long id = reader.readLong(0);
String name = reader.readString(1);
String email = reader.readString (2);
Address address = (Address) reader.readObject(3);
Collection<Long> accountIds =
reader.readCollection(4, new ArrayList<Long>());
pofReader.readRemainder();
return new Customer(id, name, email, address, accountIds);
}
}

Apart from the fact that we now have to use getters to retrieve attribute values, there are only two things that are different: calls to writeReminder and readReminder methods, and the Customer creation in the deserialization method.

The read/writeReminder methods are part of the schema evolution support, which we will discuss in more detail shortly. For now, all you need to know is that you have to call them in order to properly terminate reading or writing of a user type instance from or into a POF stream. The PortableObjectSerializer does that for us, so we didn't have to worry about it when we implemented serialization within PortableObject methods, but you do need to do it in your custom implementations of PofSerializer.

The way the Customer instance is created within the deserialize method points out one of the major differences between the two possible serialization implementations: if you write a custom serializer you have complete control over the object creation. You can use a parameterized constructor, as in the previous example, or a factory that encapsulates possibly complex creational logic.

On the other hand, in order for the PortableObjectSerializer to work, your class needs to provide a public default constructor. While in many cases this isn't a problem as there are other application components that require default constructors, such as ORM tools, in some situations this might be an issue and you might want to implement external serializers in order to have complete control over the instantiations of your objects. This brings us to our next topic: How to decide on which option to use.

One of the reasons you should choose custom PofSerializer implementation is what we discussed previously—when you have complex creational logic for your objects and need to have complete control over their instantiation.

A second, very obvious reason is that you may not be able to add the necessary POF serialization code to a class. While it is usually possible to add such code to your own classes, being able to have the code in a separate PofSerializer implementation means that you can serialize other peoples' non-POF-compliant classes using POF, including classes that come with the JDK, various frameworks, application servers, and even packaged applications.

For example, we have used the java.util.Currency class within the Money implementation. In order to make Money as a whole portable, we need to ensure that Currency is portable as well. The only way to do that is by creating an external serializer:

public class CurrencySerializer implements PofSerializer {
public void serialize(PofWriter writer, Object obj)
throws IOException {
Currency currency = (Currency) obj;
writer.writeString(0, currency.getCurrencyCode());
writer.writeRemainder(null);
}
public Object deserialize(PofReader reader)
throws IOException {
String currencyCode = reader.readString(0);
pofReader.readRemainder();
return Currency.getInstance(currencyCode);
}
}

Another good reason to choose an external serializer is when you can write a single serializer that is able to handle many different types. For example, let's take a look at serialization of enum values.

In order to serialize enums in a platform-independent way, the best option is to write the name of the enum value into a POF stream. On the surface, this seems easy enough to do directly within the serialization code:

public enum TransactionType {
DEPOSIT,
WITHDRAWAL
}
public class Transaction implements PortableObject {
// data members
private TransactionType m_type;
public Transaction() {
}
public void readExternal(PofReader pofReader)
throws IOException {
m_type = Enum.valueOf(TransactionType.class,
pofReader.readString(0));
}
public void writeExternal(PofWriter pofWriter)
throws IOException {
pofWriter.writeString(0, m_type.name());
}
}

Unfortunately, there are several issues with the approach.

For one, you will have to repeat a somewhat cumbersome piece of code that is used to deserialize enums for each serializable enum field within your application. Second, if you need to serialize an instance of a collection that contains one or more enum values, you will not have a sufficient degree of control that will allow you to inject the custom deserialization logic used previously.

Because of this, it is much better solution to implement a custom PofSerializer that can be used to serialize all enum types:

public class EnumPofSerializer implements PofSerializer {{
public void serialize(PofWriter writer, Object o)
throws IOException {
if (!o.getClass().isEnum()) {
throw new IOException(
"EnumPofSerializer can only be used to " +
"serialize enum types.");
}
writer.writeString(0, ((Enum) o).name());
writer.writeRemainder(null);
}
public Object deserialize(PofReader reader)
throws IOException {
PofContext pofContext = reader.getPofContext();
Class enumType = pofContext.getClass(reader.getUserTypeId());
if (!enumType.isEnum()) {
throw new IOException(
"EnumPofSerializer can only be used to " +
"deserialize enum types.");
}
Enum enumValue = Enum.valueOf(enumType, reader.readString(0));
reader.readRemainder();
return enumValue;
}
}

Now all we have to do is register our enum types within the POF configuration, specifying EnumPofSerializer as their serializer, and use read/writeObject methods to serialize them:

public void readExternal(PofReader pofReader)
throws IOException {
m_type = (TransactionType) pofReader.readObject(0);
}
public void writeExternal(PofWriter pofWriter)
throws IOException {
pofWriter.writeObject(0, m_type);
}

This greatly simplifies enum serialization and ensures that they are serialized consistently throughout the application. Better yet, it will allow for a completely transparent serialization of enum values within various collections.

The previous examples demonstrate some great uses for external serializers, but we still haven't answered the question we started this section with—which approach to use when serializing our domain objects.

Implementing the PortableObject interface is quick and easy, and it doesn't require you to configure a serializer for each class. However, it forces you to define a public default constructor, which can be used by anyone to create instances of your domain objects that are in an invalid state.

An external serializer gives you full control over object creation, but is more cumbersome to write and configure. It also might force you to break the encapsulation, as we did earlier, by providing a getAccountIds method on the Customer class in order to allow serialization of account identifiers.

The last problem can be easily solved by implementing the external serializer as a static inner class of the class it serializes. That way, it will be able to access its private members directly, which is really what you want to do within the serializer.

In addition to that, the Coherence Tools project provides AbstractPofSerializer, an abstract base class that makes the implementation of external serializers significantly simpler by removing the need to read and write the remainder. We will actually discuss the implementation of this class shortly, but for now let's see how the customer serializer would look like if implemented as a static inner class that extends AbstractPofSerializer:

public class Customer
implements Entity<Long> {
...
public static class Serializer
extends AbstractPofSerializer<Customer> {
protected void serializeAttributes(Customer c, PofWriter writer)
throws IOException {
writer.writeLong (0, c.m_id);
writer.writeString (1, c.m_name);
writer.writeString (2, c.m_email);
writer.writeObject (3, c.m_address);
writer.writeCollection(4, c.m_accountIds);
}
protected Customer createInstance(PofReader reader)
throws IOException {
return new Customer(
reader.readLong(0),
reader.readString(1),
reader.readString(2),
(Address) reader.readObject(3),
reader.readCollection(4, new ArrayList<Long>()));
}
}
}

I believe you will agree that implementing the external serializer this way is almost as simple as implementing the PortableObject interface directly (we still need to configure the serializer explicitly), but without its downsides.

Because of this, my recommendation is to implement external serializers in the manner presented for all domain classes, and to implement the PortableObject interface directly only within the classes that are closely related to Coherence infrastructure, such as entry processors, filters, and value extractors, which will be discussed in the following chapters.

While implementation of the POF serialization code is straightforward, one subject that deserves a more detailed discussion is collection serialization.

POF does not encode collection type into the POF stream. If it did, it wouldn't be portable, as collection types are platform dependent. For example, if it encoded the type of a java.util.LinkedList into the stream, there would be no way for a .NET client to deserialize the collection as there is no built-in linked list type in .NET.

Instead, POF leaves it to the serialization code to decide which collection type to return by providing a collection template to the PofReader.readCollection method:

List myList = pofReader.readCollection(0, new LinkedList());

The situation with maps is similar:

Map myMap = pofReader.readMap(1, new TreeMap());

You can specify null in both cases, but you should never do that if you care about the type of the returned object and not just about the fact that it implements the Collection or Map interface. If you do, Coherence will return an instance of a default type, which is probably not what you want.

For example, you might've noticed that I specified a new ArrayList as a collection template whenever I was reading account ids from the POF stream in the Customer serialization examples. The reason for that is that I need the collection of account ids to be mutable after deserialization (so the customer can open a new account). If I didn't provide a template, account ids would be returned as ImmutableArrayList, one of the internal List implementations within Coherence.

To make things even worse, there is no guarantee that the default implementation will even remain the same across Coherence versions, and you might get surprised if you move from one supported platform to another (for example, the .NET Coherence client returns an object array as a default implementation). The bottom line is that you should always specify a template when reading collections and maps.

The situation with object arrays is similar: if you want the serializer to return an array of a specific type, you should provide a template for it.

myProductArray = pofReader.readObjectArray(2, new Product[0]);

If you know the number of elements ahead of time you should size the array accordingly, but more likely than not you will not have that information. In that case, you can simply create an empty array as in the previous example, and let the POF serializer resize it for you.

The only exception to this rule is if you have written the array into the stream using the PofWriter.writeObjectArray overload that writes out a uniform array, in which case the serializer will have enough information to create an array of a correct type even if you don't specify a template for it.

This brings us to the discussion about uniform versus non-uniform collection and array write methods.

If you browse the API documentation for PofWriter, you will notice that there are multiple overloaded versions of the writeCollection, writeMap, and writeObjectArray methods.

The basic ones simply take the attribute index and value as arguments and they will write the value out using a non-uniform format, which means that the element type will be encoded for each element in a collection. Obviously, this is wasteful if all elements are of the same type, so PofWriter provides methods that allow you to specify element type as well, or in the case of the writeMap method, both the key type and the value type of map entries.

If your collection, array or a map is uniform, and most are, you should always use the uniform versions of write methods and specify the element type explicitly. This can significantly reduce the size of the serialized data by allowing the POF serializer to write type information only once instead of for each element.

The first step you need to take when adding support for schema evolution to your application is to make your data objects implement the com.tangosol.io.Evolvable interface:

public interface Evolvable extends java.io.Serializable {
int getImplVersion();
int getDataVersion();
void setDataVersion(int i);
com.tangosol.util.Binary getFutureData();
void setFutureData(com.tangosol.util.Binary binary);
}

The Evolvable interface defines the attributes each object instance needs to have in order to support the schema evolution. This includes the following:

To illustrate all of this, let's return to our earlier example and see how we could add evolution support to the Customer class:

public class Customer
implements Entity<Long>, Evolvable {
// evolvable support
public static final int IMPL_VERSION = 1;
private int dataVersion;
private Binary futureData;
// data members
private Long m_id;
private String m_name;
private String m_email;
// constructors, getters and setters omitted for brevity
...
public int getImplVersion() {
return IMPL_VERSION;
}
public int getDataVersion() {
return dataVersion;
}
public void setDataVersion(int dataVersion) {
this.dataVersion = dataVersion;
}
public Binary getFutureData() {
return futureData;
}
public void setFutureData(Binary futureData) {
this.futureData = futureData;
}
}

It is immediately obvious that the implementation of this interface will be the same for all evolvable classes, so it makes sense to pull the dataVersion and futureData attributes into a base class and define the getImplVersion method as abstract. As a matter of fact, such a class already exists within coherence.jar, and is called AbstractEvolvable.

Using AbstractEvolvable as a base class greatly simplifies implementation of evolvable objects, as you only need to implement the getImplVersion method:

public class Customer
extends AbstractEvolvable
implements Entity<Long> {
// evolvable support
public static final int IMPL_VERSION = 1;
// data members
private Long m_id;
private String m_name;
private String m_email;
// constructors, getters and setters omitted for brevity
...
public int getImplVersion() {
return IMPL_VERSION;
}
}

The Evolvable interface simply defines which information class instances need to be able to provide in order for the class to support schema evolution. The rest of the work is performed by a serializer that knows how to use that information to support serialization across multiple versions of a class.

The easiest way to add schema evolution support to your application is to use an out-of-the-box serializer that implements the necessary logic. One such serializer is the PortableObjectSerializer we discussed earlier, and it makes schema evolution a breeze. You simply implement both PortableObject and Evolvable interfaces within your class (or even simpler, a convenience EvolvablePortableObject interface), and the serializer takes care of the rest.

However, if you follow my earlier advice and implement external serializers for your domain objects, you need to handle object evolution yourself.

The algorithm to implement is fairly simple. When deserializing an object, we need to:

The last item is only meaningful when we are deserializing a newer object version. In all other cases futureData will be null.

When serializing an object, we need to do the exact opposite for steps 2 and 3, but the first step is slightly different:

The reason why we need to write the greater of implementation or data version in the first step, is that we always want to have the latest possible version in the POF stream. If we deserialize a newer version of an object, we need to ensure that its version is written into the POF stream when we serialize the object again, as we'll be including its original data into the POF stream as well. On the other hand, if we deserialized an older version, we should write a new version, containing new attributes while serializing the object again.

This is actually the key element of the schema evolution strategy in Coherence that allows us to upgrade the cluster node by node, upgrading the data stored within the cluster in the process as well.

Imagine that you have a ten-node Coherence cluster that you need to upgrade. You can shut a single node down, upgrade it with new JAR files and restart it. Because the data is partitioned across the cluster and there are backup copies available, the loss of a single node is irrelevant—the cluster will repartition itself, backup copies of the data will be promoted to primary copies, and the application or applications using the cluster will be oblivious to the loss of a node.

When an upgraded node rejoins the cluster, it will become responsible for some of the data partitions. As the data it manages is deserialized, instances of new classes will be created and the new attributes will be either calculated or defaulted to their initial values. When those instances are subsequently serialized and stored in the cluster, their version is set to the latest implementation version and any node or client application using one of the older versions of the class will use the futureData attribute to preserve new attributes.

As you go through the same process with the remaining nodes, more and more data will be incrementally upgraded to the latest class version, until eventually all the data in the cluster uses the current version.

What is important to note is that client applications do not need to be simultaneously upgraded to use the new classes. They can continue to use the older versions of the classes and will simply store future data as a binary blob on reads, and include it into the POF stream on writes. As a matter of fact, you can have ten different applications, each using different versions of the data classes, and they will all continue to work just fine, as long as all classes are evolvable.

Now that we have the theory covered, let's see how we would actually implement a serializer for our Customer class to support evolution.

public class CustomerSerializer implements PofSerializer {
public void serialize(PofWriter writer, Object o)
throws IOException {
Customer c = (Customer) o;
int dataVersion = Math.max(c.getImplVersion(),
c.getDataVersion());
writer.setVersionId(dataVersion);
writer.writeLong(0, c.getId());
writer.writeString(1, c.getName());
writer.writeString (2, c.getEmail());
writer.writeObject(3, c.getAddress());
writer.writeCollection(4, c.getAccountIds());
writer.writeRemainder(c.getFutureData());
}
public Object deserialize(PofReader reader)
throws IOException {
Long id = reader.readLong(0);
String name = reader.readString(1);
String email = reader.readString (2);
Address address = (Address) reader.readObject(3);
Collection<Long> accountIds =
reader.readCollection(4, new ArrayList<Long>());
Customer c = new Customer(id, name, email, address,accountIds);
c.setDataVersion(pofReader.getVersionId());
c.setFutureData(pofReader.readRemainder());
return c;
}
}

The highlighted code is simple, but it is immediately obvious that it has nothing to do with the Customer class per se, as it only depends on the methods defined by the Evolvable interface. As such, it simply begs for refactoring into an abstract base class that we can reuse for all of our serializers:

public abstract class AbstractPofSerializer<T>
implements PofSerializer {
protected abstract void
serializeAttributes(T obj, PofWriter writer)
throws IOException;
protected abstract void
deserializeAttributes(T obj, PofReader reader)
throws IOException;
protected abstract T createInstance(PofReader reader)
throws IOException;
public void serialize(PofWriter writer, Object obj)
throws IOException {
T instance = (T) obj;
boolean isEvolvable = obj instanceof Evolvable;
Evolvable evolvable = null;
if (isEvolvable) {
evolvable = (Evolvable) obj;
int dataVersion = Math.max(
evolvable.getImplVersion(),
evolvable.getDataVersion());
writer.setVersionId(dataVersion);
}
serializeAttributes(instance, writer);
Binary futureData = isEvolvable
? evolvable.getFutureData()
: null;
writer.writeRemainder(futureData);
}
public Object deserialize(PofReader reader)
throws IOException {
T instance = createInstance(reader);
Evolvable evolvable = null;
boolean isEvolvable = instance instanceof Evolvable;
if (isEvolvable) {
evolvable = (Evolvable) instance;
evolvable.setDataVersion(
reader.getVersionId());
}
schema evolutionevolvable objects serialization, implementingdeserializeAttributes(instance, reader);
Binary futureData = reader.readRemainder();
if (isEvolvable) {
evolvable.setFutureData(futureData);
}
return instance;
}
}

The only thing worth pointing out is the fact that both the createInstance method and deserializeAttributes method read attributes from the POF stream. The difference between the two is that createInstance should only read the attributes that are necessary for instance creation, such as constructor or factory method arguments. All other object attributes should be read from the stream and set within the deserializeAttributes method.