New in OSCache 2.0 is support for clustering of caches. OSCache currently ships with implementations that allow you to use either JavaGroups or JMS as the underlying broadcast protocol.

Caches across a cluster only broadcast messages when flush events occur. This means that the content of the caches are built up independently on each server, but whenever content becomes stale on one server it is made stale on them all. This provides a very high performing solution since we never have to pass cached objects around the cluster. And since there is no central server that is in charge of the cluster, the clustering is very robust.

Configuring OSCache to cluster is very simple. Follow either the JMS or the JavaGroups instructions below depending on which protocol you want to use.

JMS Configuration

Configure your JMS server. OSCache requires that a JMS ConnectionFactory and a Topic are available via JNDI. See your JMS server's documentation for details.

Add the JMS broadcasting listener to your oscache.properties file like this:

cache.event.listeners=com.opensymphony.oscache.plugins.clustersupport.JMSBroadcastingListener

(Note that this listener requires JMS 1.1 or higher, however legacy support for 1.0.x is also provided. If your JMS server only supports JMS 1.0.x then use JMS10BroadcastingListener instead of JMSBroadcastingListener. The rest of this documentation applies equally to both the 1.1 and 1.0 listeners.)

The JMS listener supports the following configuration parameters:

• cache.cluster.jms.topic.factory - The JNDI name that binds the JMS topic connection factory. This should match the name that is specified in your JMS server's configuration. Typically it will be something like "java:comp/env/jms/TopicConnectionFactory"
• cache.cluster.jms.topic.name - The JNDI name of the topic that will be used for the OSCache sending the messages. This should match the name of a topic that is configured on your JMS server. Typically this value will be something like "java:comp/env/jms/OSCacheTopic".
• cache.cluster.jms.node.name - A name that uniquely identifies this node in the cluster. This is used to prevent nodes from processing their own broadcast messages. Each node in the cluster must have a different value, for example "node1", "node2", ... .

If you are running OSCache from a standalone application or are not running in an environment where new InitialContext() will find your JNDI InitialContextFactory or provider URL, you will have to specify them either in a jndi.properties file or as system properties. See the InitalContext documentation for details.

JavaGroups Configuration

Just make sure you have jgroups-all.jar file in your classpath (for a webapp put it in WEB-INF/lib), and add the JavaGroups broadcasting listener to your oscache.properties file like this:

cache.event.listeners=com.opensymphony.oscache.plugins.clustersupport.JavaGroupsBroadcastingListener

In most cases, that's it! OSCache will now broadcast any cache flush events across the LAN. The jgroups-all.jar library is not included with the binary distribution due to its size, however you can obtain it either by downloading the full OSCache distribution, or by visiting the JavaGroups website.

If you want to run more than one OSCache cluster on the same LAN, you will need to use different multicast IP addresses. This allows the caches to exist in separate multicast groups and therefore not interfere with each other. The IP to use can be specified in your oscache.properties file by the cache.cluster.multicast.ip property. The default value is 231.12.21.132, however you can use any class D IP address. Class D address fall in the range 224.0.0.0 through 239.255.255.255.

If you need more control over the multicast configuration (eg setting network timeout or time-to-live values), you can use the cache.cluster.properties configuration property. Use this instead of the cache.cluster.multicast.ip property. The default value is:

UDP(mcast_addr=231.12.21.132;mcast_port=45566;ip_ttl=32;\
mcast_send_buf_size=150000;mcast_recv_buf_size=80000):\
PING(timeout=2000;num_initial_members=3):\
MERGE2(min_interval=5000;max_interval=10000):\
FD_SOCK:VERIFY_SUSPECT(timeout=1500):\
pbcast.NAKACK(gc_lag=50;retransmit_timeout=300,600,1200,2400,4800;max_xmit_size=8192):\
UNICAST(timeout=300,600,1200,2400):\
pbcast.STABLE(desired_avg_gossip=20000):\
FRAG(frag_size=8096;down_thread=false;up_thread=false):\
pbcast.GMS(join_timeout=5000;join_retry_timeout=2000;shun=false;print_local_addr=true)

See the JavaGroups site for more information. In particular, look at the documentation of Channels in the User's Guide.