coherence-eventdistribution-pattern

Skip to end of metadata
Go to start of metadata
Deprecation Announcement
This release of the Coherence Incubator is now deprecated. For the latest supported release, help and documentation, please refer to the Coherence Incubator Project on java.net at http://cohinc.java.net.

The Event Distribution Pattern Project
Provides a mechanism to distribute application events over multiple channels. While core infrastructure for the Push Replication Pattern, this pattern may be used directly by applications for local and/or global event distribution.

Overview

The Event Distribution Pattern provides a simple mechanism distribute application defined Events via one or more Event Channels. Specifically the Event Distribution Pattern allows the definition, construction and use of Event Distributors, that of which have the responsibility of guaranteeing in-order asynchronous delivery of Events via the defined Event Channels.

There are several Event Distributor implementations, each based on different internal technologies to provide Event delivery guarantees. Levels of performance, scalability and quality of service may differ between implementations. As of writing, there are two out-of-the-box Event Distributor implementations; one based on Coherence itself, another that leverages JMS providers.

Like Event Distributors, there are many Event Channels each of which provides different capabilities and ultimate destinations for events being distributed. Ultimately it's the responsibility of an Event Channel to perform the actual distribution of Events. Commonly used Event Channel implementations include:

Event Channel Description
FileEventChannel Write Events to a File.
LocalCacheEventChannel Replays Events into a Cache with in the Cluster in which the Events have arrived.
RemoteCacheEventChannel Replays Events into a Cache over an *Extend connection to a remote Cluster.
RemoteClusterEventChannel Distributes Events to another Cluster over an *Extend connection
(where by it may be further distributed locally).
StdErrEventChannel Writes Events to stdout.

Ultimately the purpose of this pattern is to provide an extensible, high-performance, highly-available, general purpose scalable framework to distribute application events occurring in one Coherence Cluster to one or more possibly distributed Coherence Clusters, Caches or other Devices. As such, the Event Distribution Pattern is used as core infrastructure for the Push Replication Pattern.

Revision History
Version 1.2.2 (changes since 1.1.2)

Version 1.2.2 is a patch release that resolves an issue where by an application may use a large amount of CPU when nothing is happening.

Version 1.2.1 was an internal unreleased version.
Version 1.2.0 (changes since 1.1.2)

Version 1.2.0 is a patch release of the Event Distribution Pattern. Below are the highlights for this release.

Legend | = Fixed | = Breaking Change / Deprecation | = Improved | = New
  • Upgraded to use the latest Coherence Common and Coherence Messaging Projects
  • Simplified configuration of filters. You may now simply use the <filter:*> Filter Namespace from Coherence Commons directly in a <event:filtering-transformer-scheme> element.
  • Introduced the <event:entry-type-filter>INSERTED, UPDATED, REMOVED</event:type-filter> configuration element to permit filtering of event types.
  • Introduced the <event:entry-filter> configuration element to allow regular filters to be used with the actual entries being distributed, instead of the event.
  • Introduced the <event:original-entry-filter> configuration element allow regular filters to be used with the original entry being distributed.
  • Resolved a defect where DistributableEntry.extract(..) was not correctly taking Entry types into account
    (it was assuming they were Objects). This could cause some types of filters to fail, especially those that expected to filter Entries, instead of Events.
Version 1.1.2 (changes since 1.1.1)

Version 1.1.2 is a patch release of the Event Distribution Pattern. Below are the highlights for this release.

Legend | = Fixed | = Breaking Change / Deprecation | = Improved | = New
  • Upgraded to use the latest Coherence Common and Coherence Messaging Project.
  • Resolved issue where logging a DistributableEntry may cause an NPE.
  • Resolved issue where CacheStoreEventChannels and BinaryEntryStoreEventChannels may corrupt calls to the associated CacheStore and BinaryEntryStores (by reordering and/or not handling removes correctly).
Version 1.1.1 (changes since 1.1.0)

Version 1.1.1 is a patch release of the Event Distribution Pattern. Below are the highlights for this release.

Legend | = Fixed | = Breaking Change / Deprecation | = Improved | = New
  • Upgraded to use the latest Coherence Common and Coherence Messaging Project.
  • Resolved issue where it was not possible to create a custom transformer without creating a custom XML processor. This simplifies how to use
    an MutatingEventIteratorTransformer.
Version 1.1.0 (changes since 1.0.0)

Version 1.1.0 is the first upgrade release of the Event Distribution Pattern. Numerous fixes and performance related changes have been made. Below are the highlights for this release.

Legend | = Fixed | = Breaking Change / Deprecation | = Improved | = New
  • Upgraded to use the latest Coherence Common and support the up and coming release of Coherence.
  • Introduced CacheStoreEventChannels to allow regular CacheStore and BinaryCacheStore implementations to be used as EventChannels.
  • Modified the RemoteClusterEventChannel to pass the appropriate ParameterProvider so that the remote-event-channel is correctly initialized in a remote cluster with local parameters.
  • Modified the JMS Event Distributor implementation to use ByteMessages instead of ObjectMessages for serialization. This significantly reduces message size and network latency when caches are configured to use POF serializers.
  • Optimized Conflict Resolution "merges". Now only propagates a "merge" if the merged value is different from the local value.
  • Resolved the incorrect {cache-name} resolution for LocalEventChannels. It was incorrectly using the Event Channel Identifier.
  • Resolved issue where distributing an entry without an original value (when not using POF) could cause a NullPointerException.
  • Resolved JMSException that may occur when disabling an EventChannel via JMX.
  • Resolved JMX MBeans reporting incorrect distribution candidate counters.
  • Resolved NullPointerException that may occur when attempting to use EventTransformers with non-POF serializers.
  • Modified EventChannelBuilder to extend the ParameterizedBuilder. This allows regular <class-schemes> to be used to specify custom EventChannel implementations, significantly simplifying extension.
  • Introduced the requirement for EventDistributor implementations to expose and configure a SerializerBuilder that is to be used to provide appropriate serialization for event distribution.
Version 1.0.0

While this is a new project it is heavily inspired by the previous internal implementations of Push Replication. For the most part the majority of the functionality provided by Push Replication 3.x remains but it is now available to be used outside of Push Replication itself. The most significant change has been to terminology. The following table outlines the changes in terminology and concepts.

Previous Terminology
(Push Replication Pattern)
New Terminology
(Event Distribution Pattern)
Push Replication Provider Event Distributor
Publisher Event Channel
Publishing Service Event Channel Controller
Entry Operation Publishable Event
Batch Transformer Event Iterator Transformer

Release Version: Version 1.2.2.39174
Release Date: October 31, 2012
Coherence Version: 3.7.1+
Target Platforms: Java Standard Edition 6+
Dependencies: Coherence Common
Messaging Pattern (optional)
A JMS Provider (optional)
Download: coherence-eventdistributionpattern-1.2.2.39174.jar
MD5: cdae6bafe8cf0e6313793b2e44bf70b7
Source and
Java Doc:
coherence-eventdistributionpattern-1.2.2.39174-src.zip

* Previous releases are available from the attachments page

Further Documentation

Event Distribution Topologies

The following section outlines the commonly used event distribution topologies supported by the Event Distribution Pattern. These are simply some examples of what is possible. Each of these topologies may be enhanced and combined to create a range of alternative approaches.

For Cache-based Event Channels, each topology supports Conflict Resolution at the destination cluster through the specification of ConflictResolvers. The default conflict resolver (called a BruteForceConflictResolver) will simply overwrite the existing value - that is, last write wins.
We highly recommend that all clusters using the Event Distribution Pattern are uniquely identifiable. To achieve this, each cluster should be configured such that the combination of their site and cluster names are unique. To declare the name of the geographical site in which a cluster is located you can either use the Coherence system override property tangosol.coherence.site or configure the <cluster-config>. Likewise to declare the name of a cluster use either the Coherence system override property tangosol.coherence.cluster or again, configure the the <cluster-config>.
Configuring the Event Distribution Pattern

The following section outlines the xml configuration structure for the Event Distribution Pattern as they appear in a Cache Configuration.

The definition of an <event:distributor> may occur in two places, one with in a <cache-config>, another within an <cache-mapping>.

<cache-config
.. xmls:event="class://com.oracle.coherence.patterns.eventdistribution.configuration.EventDistributionNamespaceContentHandler">

.. <event:distributor>*
.... <event:distributor-name>expression</event:distributor-name>1
.... <event:distributor-external-name>expression</event:distributor-external-name>0..1

.... <event:distributor-scheme />1 ...

.... <event:distribution-channels>1

...... <event:distribution-channel>* ...
........ <event:channel-name>expression</event:channel-name>1
........ <event:channel-external-name>expression</event:channel-external-name>0..1

........ <event:channel-scheme />1 ...

........ <event:transformer-scheme />0..1 ...
...... </event:distribution-channel>

.... </event:distribution-channels>
.. </event:distributor-name>
</cache-config>

Symbol Meaning
... More detail is available
1 Exactly One
0..1 Optional
? One of
* Zero or more
+ One or more
Labels:
current current Delete
project project Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.