Push Replication Pattern 2.4.0

This documentation applies to the Push Replication Pattern 2.4.0. The latest Push Replication Pattern documentation is available here.

What's New?

The following changes have been made since the Push Replication Pattern 2.3.0 release.

• Upgraded to use Coherence Common 1.4.0, Command Pattern 2.4.0 and Messaging Pattern 2.4.0

• Introduced namespaces for caches. All cache names used in this project are prefixed with coherence.pushreplicationpattern.

From now on all cache names used by the Incubator patterns have a coherence.<project-name>.* prefixed to ensure uniqueness and avoid cache names clashing with end-user defined application cache names.

• Resolves issue where "draining" would not work with in the Push Replication layer PublishingSubscriptions

• Added support for asynchronous cache stores, thus enabling write-behind cache replication. Set the write-delay of the read-write-backing-map-scheme
  in either the coherence-pushreplicationpattern-cache-config or coherence-pushreplicationpattern-pof-cache-config to enable this feature.

When enabled order of replication (based on cache operations) is not guaranteed.

• Added FilteringBatchPublisherAdapter to support pre-filtering of EntryOperations prior to them being published with BatchPublishers. This allows you to filter out what gets pushed (published) to other sites, on a site-by-site basis. Additionally added the EntryOperationFilter to support use of regular Map.Entry filters used in other parts of Coherence.

• Added support for coalescing EntryOperations to be published with a BatchPublisher with the CoalescingBatchPublisherAdapter.

• Added missing default constructors for PublishingCacheStores allowing them to be used with POF implementations.

• Included examples folder that was missing from source builds.

• Refactored BatchPublishers to use Iterator<EntryOperation> instead of List<EntryOperation> when publishing.

• Renamed DefaultPushReplicationManager (as it was spelt incorrectly).

Supported Deployment Models

The following section outlines common deployment models supported by the Push Replication Pattern.

"Master/Slave" aka "Hot and Warm" aka "Active and Standby"

In the "Master/Slave" deployment model updates to data made in the active grid are are sent to the passive grid asynchronously and ordered per NamedCache.

"Hub and Spoke" aka "Master and Slaves"

In the "Hub and Spoke" deployment model updates to data made in the active grid are are sent to any number of passive grids asynchronously and ordered per NamedCache.

"Hot Hot" aka "Federated"

In the "Hot Hot" deployment model updates to data made in either of the active grids are are sent to other active grid asynchronously and ordered per NamedCache.

"Federated" aka "Multi-Master"

In the "Federated" deployment model updates to data made in any active grid are are sent all other active grids asynchronously and ordered per NamedCache.

Each model additionally supports Conflict Resolution at the destination site through the specification of ConflictResolvers. The default conflict resolver (called a BruteForceConflictResolver) will simply overwrite the existing value - that is, last write wins.

Implementation Discussion

Before you start The Push Replication Pattern makes extensive use of the Messaging Pattern as infrastructure to capture EntryOperations and deliver them in-order of occurrence to BatchPublishers. Consequently may be beneficial for you to get familiar with the Messaging Pattern (and it's implementation) to understand the implementation of this pattern.

The Push Replication Pattern is an extension of the Messaging Pattern. The implementation provides several new Coherence CacheStore implementations, namely the PublishingCacheStore (for "hub-and-spoke" push replication) and the SafePublishingCacheStore (for "multi-way" push replication), that are used to capture cache mutation operations (like insert, update and delete) on cache entries.

After such operations are captured (represented as EntryOperations) they are sent to the messaging layer (implemented using the Messaging Pattern) for distribution to specialized TopicSubscriptions called PublishingSubscriptions.

When PublishingSubscriptions receive the EntryOperations from the messaging layer, an internal event (captured by a backing-map-listener executing in the same JVM in which the PublishingSubscription is being managed by Coherence) signals to a PublishingService to commence publishing the currently queued EntryOperations with an associated BatchPublisher implementation. How the ultimate publishing occurs is entirely dependent on the implementation of the BatchPublisher.

The following diagram provides an overview of the push replication process through the various layers of the system.

Example

The following section provides an example use of the push replication pattern, including establishing publishers.

Step 1: Configuring a Cache (with a PublishingCacheStore)

As push replication occurs on a cache-by-cache basis, the first step in making use of this pattern is configuring your application cache(s) to use an appropriate PublishingCacheStore implementation. For the "hub-and-spoke" model, where one cluster is a "master" and the other clusters are "spokes", you should use a PublishingCacheStore. For multi-way push replication, your cache(s) should be configured to use a SafePublishingCacheStore.

By default, the Push Replication cache configuration (coherence-pushreplicationpattern-pof-cache-config.xml) defines a "publishing-*" mapping to a distributed-scheme that is configured to use a PublishingCacheStore. Consequently any cache name prefixed with "publishing-" will automatically support Push Replication.

When your application first accesses a "publishing-*" based scheme (which in turn creates the PublishingCacheStore), the underlying messaging infrastructure will be created to support Push Replication. This includes establishing a Topic that is named exactly the same as your cache. In this case, a Topic called "publishing-cache" will be created in the messaging layer.

From here on any operation that mutates the "publishing-cache" will have the said operation captured and sent (as an EntryOperation) to the "publishing-cache" Topic, after which the operation will be forwarded in-order to the Subscriptions on the said Topic.

Step 2: Registering a BatchPublisher to perform Push Replication

Until a BatchPublisher is registered for a cache configured with a PublishingCacheStore, no publishing will occur. To register a BatchPublisher to publish EntryOperations, you need to use a PushReplicationManager.

There are essentially two forms of publishers; those that support "batching" and those that don't. By default, the Push Replication pattern only works with BatchPublishers. Consequently to use a non-batching publisher (ie: an implementation of the Publisher interface), an adapter has been provided. The package com.oracle.coherence.pushreplication.publishers provides numerous implementations of Publishers and BatchPublishers together with adapters to convert between them (as demonstrated in the example above)

Step 3: Using a publishing- cache.*

Once you've registered one or more BatchPublishers for each cache from which you would like to publish EntryOperations, you may simply use the said cache(s) as regular caches (as they are!).

Hence the following code, registered with the above "stderr-publisher", would output the "put" operations to stderr.

Frequently Asked Questions

How can the Push Replication Publishers be monitored?

Like the Command Pattern this pattern is JMX ready. By simply enabling JMX on the Coherence Cluster, each of the PublishingServices will be presented in the JMX tree, detailing current replication state and statistics.

How do I enable Push Replication to one or more (remote) Coherence Clusters?

In order to publish to a remote cluster, you must;

1. Configure and enable one or more proxies on the remote cluster(s).
2. Ensure that the members of the remote cluster(s) have the Push Replication Pattern (and dependencies) in the class path
3. Configure and enable one or more Remote Invocation Services in the "hub" with the addresses of the remote cluster proxy members (of it you're using Coherence 3.4+, use an AddressProvider). An example scheme is defined in the coherence-pushreplicationpattern-cache-config.xml file.
4. Register appropriate RemoteInvocationPublishers for each cache (as follows).

How are conflicts resolved when replicating EntryOperations in remote clusters?

The LocalCachePublisher, SafeLocalCachePublisher and RemoteCachePublisher classes support the specification of a CachePublisher.ConflictResolver implementation during construction. By implementing a CachePublisher.ConflictResolver your application may resolve any underlying Entry conflicts in an appropriate manner. If not specified, the LocalCachePublisher.BruteForceConflictResolver is used.

References and Additional Information

• The Coherence Incubator - Messaging Pattern