Table of Contents

AbstractMultiplexingBackingMapListener Class Listing

Backing MapListener events are returned from replicated caches in readable Java format. However, backing MapListener events returned from distributed caches are in internal Coherence format. To return readable backing MapListener events from distributed caches, implement the AbstractMultiplexingBackingMapListener class.

The class provides an onBackingMapEvent method which you can override to specify how you would like the event returned.

The followiing is a code listing of the AbstractMultiplexingBackingMapListener class.

import com.tangosol.net.BackingMapManager;
import com.tangosol.net.BackingMapManagerContext;
import com.tangosol.net.cache.CacheEvent;
import com.tangosol.util.Binary;
import com.tangosol.util.ConverterCollections;
import com.tangosol.util.MapEvent;
import com.tangosol.util.MapListener;
import com.tangosol.util.MultiplexingMapListener;

/**
 * <p>The {@link AbstractMultiplexingBackingMapListener} provides a simplified 
 * base implementation for backing {@link MapListener}s that provide real objects in a map
 * event (in normal Java representation) rather than those that use the internal 
 * Coherence format (ie: {@link Binary}s.</p>
 * 
 * <p>Backing {@link MapListener}s are embeddable {@link MapListener}s that are 
 * injected into Coherence Cache members (storage-enabled) for the purpose of
 * handling events directly in-process of the primary partitions (of distributed schemes).</p>
 * 
 * <p>They are extremely useful for performing in-process processing of events within 
 * Coherence itself.</p>
 * 
 * @author Brian Oliver (brian.oliver@oracle.com)
 */
public abstract class AbstractMultiplexingBackingMapListener extends MultiplexingMapListener {
	
	/**
	 * <p>The possible causes of backing map events.</p>
	 */
	public enum Cause {
		/**
		 * <p><code>Regular</code> is for regular insert, updates and deletes.</p>
		 */
		Regular,	
		
		/**
		 * <p><code>Eviction</code> is for deletes that are due to cache
                   * eviction.</p>
		 */
		Eviction,
		
		/**
		 * <p><code>Distribution</code> is for insert or delete events due to
                   * coherence having 
		 * to repartition data due to changes in cluster membership.</p> 
		 */
		Distribution
	}
	
	
	/**
	 * <p>The {@link BackingMapManagerContext} that owns this listener.  
	 * (all Backing {@link MapListener}s require a {@link BackingMapManagerContext})</p>
	 */
	private BackingMapManagerContext context;
	
	
	/**
	 * <p>Standard Constructor</p>
	 * 
	 * <p>The {@link BackingMapManagerContext} will be injected by Coherence during
	 * initialization and construction of the {@link BackingMapManager}.</p>
	 * 
	 * @param context
	 */
	public AbstractMultiplexingBackingMapListener(BackingMapManagerContext context) {
		this.context = context;
	}
	
	
	/**
	 * <p>The {@link BackingMapManagerContext} in which the Backing {@link MapListener}
	 * is operating.</p>
	 * 
	 * @return {@link BackingMapManagerContext}
	 */
	public BackingMapManagerContext getContext() {
		return context;
	}
	
	
	/**
	 * <p>This is the standard {@link MultiplexingMapListener} event handler.  In here
	 * we convert the internally formatted event into something a developer would 
	 * expect if using a client-side {@link MapListener}.</p>
	 * 
	 * <p>After converting the internally formatted event, this method calls 
          * the abstract {@link #onBackingMapEvent(MapEvent, Cause)}
	 * method that may be used to handle the actual event.</p>
	 */
	protected final void onMapEvent(MapEvent mapEvent) {
		
		// convert the mapEvent (in internal format) into a real event 
                  // we can deal with
		MapEvent realMapEvent = ConverterCollections.getMapEvent(mapEvent.getMap(),  mapEvent,  context.getKeyFromInternalConverter(), context.getValueFromInternalConverter());

		//determine the underlying cause of the map event
		Cause cause;
		if (context.isKeyOwned(mapEvent.getKey())) {     
			cause = mapEvent instanceof CacheEvent && ((CacheEvent) mapEvent).isSynthetic() ? Cause.Eviction : Cause.Regular;
		} else {
			cause = Cause.Distribution;
		}
		
		// now call the abstract event handler with the real event 
                  // and underlying cause
		onBackingMapEvent(realMapEvent, cause);
	}
	
	
	/**
	 * <p>Override this method to handle real backing map events.</p>
	 * 
	 * @param mapEvent A standard mapEvent (in Java format)
	 * @param cause The underlying cause of the event
	 */
	abstract protected void onBackingMapEvent(MapEvent mapEvent, Cause cause);

acceptor-config

acceptor-config

Used in: proxy-scheme.

Description

The acceptor-config element specifies the configuration info for a protocol-specific connection acceptor used by a proxy service to enable Coherence*Extend clients to connect to the cluster and use the services offered by the cluster without having to join the cluster.

The acceptor-config element must contain exactly one protocol-specific connection acceptor configuration element (either jms-acceptor or tcp-acceptor).

Elements

The following table describes the elements you can define within the acceptor-config element.

<use-filters>
    <filter-name>gzip</filter-name>
</use-filters>

<serializer>
  <class-name>com.tangosol.io.pof.ConfigurablePofContext</class-name>
  <init-params>
    <init-param>
      <param-type>string</param-type>
      <param-value>my-pof-types.xml</param-value>
    </init-param>
  </init-params>
</serializer>

access-controller

access-controller

Used in: security-config.

The following table describes the elements you can define within the access-controller element.

<init-params>
  <init-param id="1">
    <param-type>java.io.File</param-type>
    <param-value system-property="tangosol.coherence.security.keystore"></param-value>
  </init-param>
  <init-param id="2">
    <param-type>java.io.File</param-type>
    <param-value system-property="tangosol.coherence.security.permissions"></param-value>
  </init-param>
</init-params>

address-provider (cache)

address-provider

Used in: tcp-initiator

Description

Contains the configuration info for an address factory that implements the com.tangosol.net.AddressProvider interface.

Elements

The following table describes the elements you can define within the address-provider element.

allow-interfaces

allow-interfaces

Used in: <pof-config>

Description

The allow-interfaces element indicates whether the user-type class-name can specify Java interface types in addition to Java class types.

Valid values are "true" or "false". Default value is false.

Elements

Terminal element.

allow-subclasses

allow-subclasses

Used in: <pof-config>

Description

The allow-subclasses element indicates whether the user-type class-name can specify a Java class type that is abstract, and whether sub-classes of any specified user-type class-name will be permitted at runtime and automatically mapped to the specified super-class for purposes of obtaining a serializer.

Valid values are "true" or "false". Default value is false.

Elements

Terminal element.

Analyzing Reporter Content

Network Health

The Network Health report contains the primary aggregates for determining the health of the network communications. The network health file is a tab delimited file that is prefixed with the date in YYYYMMDDHH format and post fixed with "-network-health.txt". For example 2009013113-network-health.txt would be created on January 1, 2009 at 1:00 pm.

Network Health Detail

The Network Health report supporting node level details for determining the health of the network communications. The network health detail file is a tab delimited file that is prefixed with the date in YYYYMMDDHH format and post fixed with "-network-health-detail.txt". For example 2009013114-network-health.txt would be created on January 1, 2009 at 2:00 pm.

Memory Status

The Memory status report must be run as part of a report batch. The values are helpful in understanding memory consumption on each node and across the grid. For data to be included nodes must be configured to publish platform MBean information. The memory status file is a tab delimited file that is prefixed with the date in YYYYMMDDHH format and post fixed with "-memory-status.txt". For example 2009013115-memory-status.txt would be created on January 1, 2009 at 3 pm.

Cache Size

The cache size report can be executed either on demand or it can be added as part of the report batch and the Caches should have the <unit-calculator> set to BINARY. The cache size file is a tab delimited file that is prefixed with the date in YYYYMMDDHH format and post fixed with "-cache-size.txt". For example 2009013101-cache-size.txt would be created on January 1, 2009 at 1:00 am.

Service Report

The service report provides information to the requests processed, request failures, and request backlog, tasks processed, task failures and task backlog. Request Count and Task Count are useful to determine performance and throughput of the service. RequestPendingCount and Task Backlog are useful in determining capacity issues or blocked processes. Task Hung Count, Task Timeout Count, Thread Abandoned Count, Request Timeout Count are the number of unsuccessful executions that have occurred in the system.

Node List

Due to the transient nature of the node identifier (nodeId), the reporter logs out a list of nodes and the user defined <member-identity> information. The node list file is a tab delimited file that is prefixed with the date in YYYYMMDDHH format and post fixed with "-nodes.txt". For example 2009013101-nodes.txt would be created on January 1, 2009 at 1:00 am.

Proxy Report

The proxy file provides information about proxy servers and the information being transferred to clients. The Proxy file is a tab delimited file that is prefixed with the date in YYYYMMDDHH format and post fixed with "-report-proxy.txt". For example 2009013101-report-proxy.txt would be created on January 1, 200901.

async-store-manager

async-store-manager

Used in: external-scheme, paged-external-scheme.

Description

The async-store-manager element adds asynchronous write capabilities to other store manager implementations.

Supported store managers include:

• custom-store-manager - allows definition of custom implementations of store managers
• bdb-store-manager - uses Berkeley Database JE to implement an on-disk cache
• lh-file-manager - uses a Coherence LH on-disk database cache
• nio-file-manager - uses NIO to implement memory-mapped file based cache
• nio-memory-manager - uses NIO to implement an off JVM heap, in-memory cache

Implementation

This store manager is implemented by the com.tangosol.io.AsyncBinaryStoreManager class.

Elements

The following table describes the elements you can define within the async-store-manager element.

[\d]+[[.][\d]+]?[K|k|M|m]?[B|b]?

authorized-hosts

authorized-hosts

Used in: cluster-config.

Description

If specified, restricts cluster membership to the cluster nodes specified in the collection of unicast addresses, or address range. The unicast address is the address value from the authorized cluster nodes' unicast-listener element. Any number of host-address and host-range elements may be specified.

Elements

The following table describes the elements you can define within the authorized-hosts element.

The content override attributes xml-override and id can be optionally used to fully or partially override the contents of this element with XML document that is external to the base document.

authorized-hosts

authorized-hosts

Used in: cluster-config.

Description

If specified, restricts cluster membership to the cluster nodes specified in the collection of unicast addresses, or address range. The unicast address is the address value from the authorized cluster nodes' unicast-listener element. Any number of host-address and host-range elements may be specified.

Elements

The following table describes the elements you can define within the authorized-hosts element.

The content override attributes xml-override and id can be optionally used to fully or partially override the contents of this element with XML document that is external to the base document.

Automatically manage dynamic cluster membership

Cluster and Service objects

From any cache, the application can obtain a reference to the local representation of a cache's service. From any service, the application can obtain a reference to the local representation of the cluster.

CacheService service = cache.getCacheService();
Cluster      cluster = service.getCluster();

From the Cluster object, the application can determine the set of services that are running in the cluster:

for (Enumeration enum = cluster.getServiceNames(); enum.hasMoreElements(); )
    {
    String sName = (String) enum.nextElement();
    ServiceInfo info = cluster.getServiceInfo(sName);
    // ...
    }

The ServiceInfo object provides information about the service, including its name, type, version and membership.

For more information on this feature, see the API documentation for NamedCache, CacheService, Service, ServiceInfo and Cluster.

Member object

The primary information that an application can determine about each member in the cluster is:

• The Member's IP address
• What date/time the Member joined the cluster

As an example, if there are four servers in the cluster with each server running one copy ("instance") of the application and all four instances of the application are clustered together, then the cluster is composed of four Members. From the Cluster object, the application can determine what the local Member is:

Member memberThis = cluster.getLocalMember();

From the Cluster object, the application can also determine the entire set of cluster members:

Set setMembers = cluster.getMemberSet();

From the ServiceInfo object, the application can determine the set of cluster members that are participating in that service:

ServiceInfo info = cluster.getServiceInfo(sName);
Set setMembers = info.getMemberSet();

For more information on this feature, see the [API documentation for Member.

Listener interface and Event object

To listen to cluster and/or service membership changes, the application places a listener on the desired Service. As discussed before, the Service can come from a cache:

Service service = cache.getCacheService();

The Service can also be looked up by its name:

Service service = cluster.getService(sName);

To receive membership events, the application implements a MemberListener. For example, the following listener example prints out all the membership events that it receives:

public class MemberEventPrinter
        extends Base
        implements MemberListener
    {
    public void memberJoined(MemberEvent evt)
        {
        out(evt);
        }

    public void memberLeaving(MemberEvent evt)
        {
        out(evt);
        }

    public void memberLeft(MemberEvent evt)
        {
        out(evt);
        }
    }

The MemberEvent object carries information about the event type (joined / leaving / left), the member that generated the event, and the service that acts as the source of the event. Additionally, the event provides a method, isLocal(), that indicates to the application that it is this member that is joining or leaving the cluster. This is useful for recognizing soft restarts in which an application automatically rejoins a cluster after a failure occurs. For example:

public class RejoinEventPrinter
        extends Base
        implements MemberListener
    {
    public void memberJoined(MemberEvent evt)
        {
        if (evt.isLocal())
            {
            out("this member just rejoined the cluster: " + evt);
            }
        }

    public void memberLeaving(MemberEvent evt)
        {
        }

    public void memberLeft(MemberEvent evt)
        {
        }
    }

For more information on these feature, see the [API documentation for Service, MemberListener and MemberEvent.

backup-storage

backup-storage

Used in: distributed-scheme.

Description

The backup-storage element specifies the type and configuration of backup storage for a partitioned cache.

Elements

The following table describes the elements you can define within the backup-storage element.

[\d]+[[.][\d]]?[K|k|M|m|G|g]?[B|b]?

[\d]+[[.][\d]]?[K|k|M|m|G|g]?[B|b]?

bdb-store-manager

bdb-store-manager

Used in: external-scheme, paged-external-scheme, async-store-manager.

Berkeley Database JE Java class libraries are required to utilize a bdb-store-manager, visit the Berkeley Database JE product page for additional information.

Description

The BDB store manager is used to define external caches which will use Berkeley Database JE on-disk embedded databases for storage. See the persistent disk cache and overflow cache samples for examples of Berkeley based store configurations.

Implementation

This store manager is implemented by the com.tangosol.io.bdb.BerkeleyDBBinaryStoreManager class, and produces BinaryStore objects implemened by the com.tangosol.io.bdb.BerkeleyDBBinaryStore class.

Elements

The following table describes the elements you can define within the bdb-store-manager element.

Best Practices

Coherence and Cache Topologies

Coherence supports several cache topologies, but the replicated, partitioned, and near options will satisfy the vast majority of use cases. All are fully coherent and support cluster-wide locking and transactions:

• Replicated - Each machine contains a full copy of the dataset. Read access is instantaneous.
• Partitioned (or Distributed) - Each machine contains a unique partition of the dataset. Adding machines to the cluster will increase the capacity of the cache. Both read and write access involve network transfer and serialization/deserialization.
• Near - Each machine contains a small local cache which is synchronized with a larger Partitioned cache, optimizing read performance. There is some overhead involved with synchronizing the caches.

Data Access Patterns

Data access distribution (hot spots)

When caching a large dataset, typically a small portion of that dataset will be responsible for most data accesses. For example, in a 1000 object dataset, 80% of operations may be be against a 100 object subset. The remaining 20% of operations may be against the other 900 objects. Obviously the most effective return on investment will be gained by caching the 100 most active objects; caching the remaining 900 objects will provide 25% more effective caching while requiring a 900% increase in resources.

On the other hand, if every object is accessed equally often (for example in sequential scans of the dataset), then caching will require more resources for the same level of effectiveness. In this case, achieving 80% cache effectiveness would require caching 80% of the dataset versus 10%. (Note that sequential scans of partially cached data sets will generally defeat MRU, LFU and MRU-LFU eviction policies). In practice, almost all non-synthetic (benchmark) data access patterns are uneven, and will respond well to caching subsets of data.

In cases where a subset of data is active, and a smaller subset is particularly active, Near caching can be very beneficial when used with the "all" invalidation strategy (this is effectively a two-tier extension of the above rules).

Cluster-node affinity

Coherence's Near cache technology will transparently take advantage of cluster-node affinity, especially when used with the "present" invalidation strategy. This topology is particularly useful when used in conjunction with a sticky load-balancer. Note that the "present" invalidation strategy results in higher overhead (as opposed to "all") when the front portion of the cache is "thrashed" (very short lifespan of cache entries); this is due to the higher overhead of adding/removing key-level event listeners. In general, a cache should be tuned to avoid thrashing and so this is usually not an issue.

Read-write ratio and data sizes

Generally speaking, the following cache topologies are best for the following use cases:

• Replicated cache - small amounts of read-heavy data (e.g. metadata)
• Partitioned cache - large amounts of read-write data (e.g. large data caches)
• Near cache - similar to Partitioned, but has further benefits from read-heavy tiered access patterns (e.g. large data caches with hotspots) and "sticky" data access (e.g. sticky HTTP session data). Depending on the synchronization method (expiry, asynchronous, synchronous), the worst case performance may range from similar to a Partitioned cache to considerably worse.

Interleaving

Interleaving refers to the number of cache reads between each cache write. The Partitioned cache is not affected by interleaving (as it is designed for 1:1 interleaving). The Replicated and Near caches by contrast are optimized for read-heavy caching, and prefer a read-heavy interleave (e.g. 10 reads between every write). This is because they both locally cache data for subsequent read access. Writes to the cache will force these locally cached items to be refreshed, a comparatively expensive process (relative to the near-zero cost of fetching an object off the local memory heap). Note that with the Near cache technology, worst-case performance is still similar to the Partitioned cache; the loss of performance is relative to best-case scenarios.

Note that interleaving is related to read-write ratios, but only indirectly. For example, a Near cache with a 1:1 read-write ratio may be extremely fast (all writes followed by all reads) or much slower (1:1 interleave, write-read-write-read...).

Heap Size Considerations

Using several small heaps

For large datasets, Partitioned or Near caches are recommended. As the scalability of the Partitioned cache is linear for both reading and writing, varying the number of Coherence JVMs will not significantly affect cache performance. On the other hand, JVM memory management routines show worse than linear scalability. For example, increasing JVM heap size from 512MB to 2GB may substantially increase garbage collection (GC) overhead and pauses.

For this reason, it is common to use multiple Coherence instances per physical machine. As a general rule of thumb, current JVM technology works well up to 512MB heap sizes. Thererfore, using a number of 512MB Coherence instances will provide optimal performance without a great deal of JVM configuration or tuning.

For performance-sensitive applications, experimentation may provide better tuning. When considering heap size, it is important to find the right balance. The lower bound is determined by per-JVM overhead (and also, manageability of a potentially large number of JVMs). For example, if there is a fixed overhead of 100MB for infrastructure software (e.g. JMX agents, connection pools, internal JVM structures), then the use of JVMs with 256MB heap sizes will result in close to 40% overhead for non-cache data. The upper bound on JVM heap size is governed b