JBoss Cache is a tree-structured, clustered, transactional cache. It is the backbone for many fundamental JBoss Application Server clustering services, including - in certain versions - clustering JNDI, HTTP and EJB sessions.

JBoss Cache can also be used as a standalone transactional and clustered caching library or even an object oriented data store. It can even be embedded in other enterprise Java frameworks and application servers such as BEA WebLogic or IBM WebSphere, Tomcat, Spring, Hibernate, and many others. It is also very commonly used directly by standalone Java applications that do not run from within an application server, to maintain clustered state.

JBoss Cache offers a simple and straightforward API, where data (simple Java objects) can be placed in the cache and, based on configuration options selected, this data may be one or all of:

In addition, JBoss Cache offers a rich set of enterprise-class features:

A cache is organised as a tree, with a single root. Each node in the tree essentially contains a Map, which acts as a store for key/value pairs. The only requirement placed on objects that are cached is that they implement java.io.Serializable . Note that this requirement does not exist for Pojo Cache.

JBoss Cache can be either local or replicated. Local trees exist only inside the JVM in which they are created, whereas replicated trees propagate any changes to some or all other trees in the same cluster. A cluster may span different hosts on a network or just different JVMs on a single host.

When a change is made to an object in the cache and that change is done in the context of a transaction, the replication of changes is deferred until the transaction commits successfully. All modifications are kept in a list associated with the transaction for the caller. When the transaction commits, we replicate the changes. Otherwise, (on a rollback) we simply undo the changes locally resulting in zero network traffic and overhead. For example, if a caller makes 100 modifications and then rolls back the transaction, we will not replicate anything, resulting in no network traffic.

If a caller has no transaction associated with it (and isolation level is not NONE - more about this later), we will replicate right after each modification, e.g. in the above case we would send 100 messages, plus an additional message for the rollback. In this sense, running without a transaction can be thought of as analogous as running with auto-commit switched on in JDBC terminology, where each operation is committed automatically.

JBoss Cache works out of the box with most popular transaction managers, and even provides an API where custom transaction manager lookups can be written.

The cache is also completely thread-safe. It uses a pessimistic locking scheme for nodes in the tree by default, with an optimistic locking scheme as a configurable option. With pessimistic locking, the degree of concurrency can be tuned using a number of isolation levels, corresponding to database-style transaction isolation levels, i.e., SERIALIZABLE, REPEATABLE_READ, READ_COMMITTED, READ_UNCOMMITTED and NONE. Concurrency, locking and isolation levels will be discussed later.

JBoss Cache requires Java 5.0 (or newer).

However, there is a way to build JBoss Cache as a Java 1.4.x compatible binary using JBossRetro to retroweave the Java 5.0 binaries. However, Red Hat Inc. does not offer professional support around the retroweaved binary at this time and the Java 1.4.x compatible binary is not in the binary distribution. See this wiki page for details on building the retroweaved binary for yourself.

In addition to Java 5.0, at a minimum, JBoss Cache has dependencies on JGroups , and Apache's commons-logging . JBoss Cache ships with all dependent libraries necessary to run out of the box.

JBoss Cache is an open source product, using the business and OEM-friendly OSI-approved LGPL license. Commercial development support, production support and training for JBoss Cache is available through JBoss, a division of Red Hat Inc. JBoss Cache is a part of JBoss Professional Open Source JEMS (JBoss Enterprise Middleware Suite).

The Cache interface is the primary mechanism for interacting with JBoss Cache. It is constructed and optionally started using the CacheFactory . The CacheFactory allows you to create a Cache either from a Configuration object or an XML file. Once you have a reference to a Cache , you can use it to look up Node objects in the tree structure, and store data in the tree.

Reviewing the javadoc for the above interfaces is the best way to learn the API. Below we cover some of the main points.

An instance of the Cache interface can only be created via a CacheFactory . (This is unlike JBoss Cache 1.x, where an instance of the old TreeCache class could be directly instantiated.)

CacheFactory provides a number of overloaded methods for creating a Cache , but they all do the same thing:

An example of the simplest mechanism for creating and starting a cache, using the default configuration values:

         CacheFactory factory = DefaultCacheFactory.getInstance();
         Cache cache = factory.createCache();
      

Here we tell the CacheFactory to find and parse a configuration file on the classpath:

         CacheFactory factory = DefaultCacheFactory.getInstance();
         Cache cache = factory.createCache("cache-configuration.xml");
      

Here we configure the cache from a file, but want to programatically change a configuration element. So, we tell the factory not to start the cache, and instead do it ourselves:

         CacheFactory factory = DefaultCacheFactory.getInstance();
         Cache cache = factory.createCache("cache-configuration.xml", false);
         Configuration config = cache.getConfiguration();
         config.setClusterName(this.getClusterName());

         // Have to create and start cache before using it
         cache.create();
         cache.start();
      

Next, let's use the Cache API to access a Node in the cache and then do some simple reads and writes to that node.

         // Let's get ahold of the root node.
         Node rootNode = cache.getRoot();

         // Remember, JBoss Cache stores data in a tree structure.
         // All nodes in the tree structure are identified by Fqn objects.
         Fqn peterGriffinFqn = Fqn.fromString("/griffin/peter");

         // Create a new Node
         Node peterGriffin = rootNode.addChild(peterGriffinFqn);

         // let's store some data in the node
         peterGriffin.put("isCartoonCharacter", Boolean.TRUE);
         peterGriffin.put("favouriteDrink", new Beer());

         // some tests (just assume this code is in a JUnit test case)
         assertTrue(peterGriffin.get("isCartoonCharacter"));
         assertEquals(peterGriffinFqn, peterGriffin.getFqn());
         assertTrue(rootNode.hasChild(peterGriffinFqn));

         Set keys = new HashSet();
         keys.add("isCartoonCharacter");
         keys.add("favouriteDrink");

         assertEquals(keys, peterGriffin.getKeys());

         // let's remove some data from the node
         peterGriffin.remove("favouriteDrink");

         assertNull(peterGriffin.get("favouriteDrink");

         // let's remove the node altogether
         rootNode.removeChild(peterGriffinFqn);

         assertFalse(rootNode.hasChild(peterGriffinFqn));
      

The Cache interface also exposes put/get/remove operations that take an Fqn as an argument:

         Fqn peterGriffinFqn = Fqn.fromString("/griffin/peter");

         cache.put(peterGriffinFqn, "isCartoonCharacter", Boolean.TRUE);
         cache.put(peterGriffinFqn, "favouriteDrink", new Beer());

         assertTrue(peterGriffin.get(peterGriffinFqn, "isCartoonCharacter"));
         assertTrue(cache.getRootNode().hasChild(peterGriffinFqn));

         cache.remove(peterGriffinFqn, "favouriteDrink");

         assertNull(cache.get(peterGriffinFqn, "favouriteDrink");

         cache.removeNode(peterGriffinFqn);

         assertFalse(cache.getRootNode().hasChild(peterGriffinFqn));
      

The previous section used the Fqn class in its examples; now let's learn a bit more about that class.

A Fully Qualified Name (Fqn) encapsulates a list of names which represent a path to a particular location in the cache's tree structure. The elements in the list are typically String s but can be any Object or a mix of different types.

This path can be absolute (i.e., relative to the root node), or relative to any node in the cache. Reading the documentation on each API call that makes use of Fqn will tell you whether the API expects a relative or absolute Fqn .

The Fqn class provides are variety of constructors; see the javadoc for all the possibilities. The following illustrates the most commonly used approaches to creating an Fqn:

         
	    // Create an Fqn pointing to node 'Joe' under parent node 'Smith'
	    // under the 'people' section of the tree
	    
	    // Parse it from a String
	    Fqn<String> abc = Fqn.fromString("/people/Smith/Joe/");
	    
	    // Build it directly. A bit more efficient to construct than parsing
	    String[] strings = new String[] { "people", "Smith", "Joe" };
	    Fqn<String> abc = new Fqn<String>(strings);
	    
	    // Here we want to use types other than String
	    Object[] objs = new Object[]{ "accounts", "NY", new Integer(12345) };
	    Fqn<Object> acctFqn = new Fqn<Object>(objs);
     
      

Note that

Fqn<String> f = new Fqn<String>("/a/b/c");

is not the same as

Fqn<String> f = Fqn.fromString("/a/b/c");

The former will result in an Fqn with a single element, called "/a/b/c" which hangs directly under the cache root. The latter will result in a 3 element Fqn, where "c" idicates a child of "b", which is a child of "a", and "a" hangs off the cache root. Another way to look at it is that the "/" separarator is only parsed when it forms part of a String passed in to Fqn.fromString() and not otherwise.

The JBoss Cache API in the 1.x releases included many overloaded convenience methods that took a string in the "/a/b/c" format in place of an Fqn . In the interests of API simplicity, no such convenience methods are available in the JBC 2.x API.

It is good practice to stop and destroy your cache when you are done using it, particularly if it is a clustered cache and has thus used a JGroups channel. Stopping and destroying a cache ensures resources like the JGroups channel are properly cleaned up.

         cache.stop();
         cache.destroy();
      

Not also that a cache that has had stop() invoked on it can be started again with a new call to start() . Similarly, a cache that has had destroy() invoked on it can be created again with a new call to create() (and then started again with a start() call).

Although technically not part of the API, the mode in which the cache is configured to operate affects the cluster-wide behavior of any put or remove operation, so we'll briefly mention the various modes here.

JBoss Cache modes are denoted by the org.jboss.cache.config.Configuration.CacheMode enumeration. They consist of:

See the chapter on Clustering for more details on how the cache's mode affects behavior. See the chapter on Configuration for info on how to configure things like the cache's mode.

The @org.jboss.cache.notifications.annotation.CacheListener annotation is a convenient mechanism for receiving notifications from a cache about events that happen in the cache. Classes annotated with @CacheListener need to be public classes. In addition, the class needs to have one or more methods annotated with one of the method-level annotations (in the org.jboss.cache.notifications.annotation package). Methods annotated as such need to be public, have a void return type, and accept a single parameter of type org.jboss.cache.notifications.event.Event or one of it's subtypes.

Refer to the javadocs on the annotations as well as the Event subtypes for details of what is passed in to your method, and when.

Example:

   @CacheListener
   public class MyListener
   {

      @CacheStarted
      @CacheStopped
      public void cacheStartStopEvent(Event e)
      {
         switch (e.getType())
         {
            case Event.Type.CACHE_STARTED:
               System.out.println("Cache has started");
               break;
            case Event.Type.CACHE_STOPPED:
               System.out.println("Cache has stopped");
               break;
         }
      }

      @NodeCreated
      @NodeRemoved
      @NodeVisited
      @NodeModified
      @NodeMoved
      public void logNodeEvent(NodeEvent ne)
      {
         log("An event on node " + ne.getFqn() + " has occured");
      }
   }

         

Cache loaders are an important part of JBoss Cache. They allow persistence of nodes to disk or to remote cache clusters, and allow for passivation when caches run out of memory. In addition, cache loaders allow JBoss Cache to perform 'warm starts', where in-memory state can be preloaded from persistent storage. JBoss Cache ships with a number of cache loader implementations.

These CacheLoaders, along with advanced aspects and tuning issues, are discussed in the chapter dedicated to CacheLoaders .

Eviction policies are the counterpart to CacheLoaders. They are necessary to make sure the cache does not run out of memory and when the cache starts to fill, the eviction algorithm running in a separate thread offloads in-memory state to the CacheLoader and frees up memory. Eviction policies can be configured on a per-region basis, so different subtrees in the cache could have different eviction preferences. JBoss Cache ships with several eviction policies:

Detailed configuration and implementing custom eviction policies are discussed in the chapter dedicated to eviction policies. .

The org.jboss.cache.config.Configuration class (along with its component parts ) is a Java Bean that encapsulates the configuration of the Cache and all of its architectural elements (cache loaders, evictions policies, etc.)

The Configuration exposes numerous properties which are summarized in the configuration reference section of this book and many of which are discussed in later chapters. Any time you see a configuration option discussed in this book, you can assume that the Configuration class or one of its component parts exposes a simple property setter/getter for that configuration option.

As discussed in the User API section , before a Cache can be created, the CacheFactory must be provided with a Configuration object or with a file name or input stream to use to parse a Configuration from XML. The following sections describe how to accomplish this.

            
<?xml version="1.0" encoding="UTF-8"?>

<!-- ===================================================================== -->
<!--                                                                       -->
<!--  Sample JBoss Cache Service Configuration                             -->
<!--                                                                       -->
<!-- ===================================================================== -->

<server>
   
   <mbean code="org.jboss.cache.jmx.CacheJmxWrapper" name="jboss.cache:service=Cache">
   
      <!-- Configure the TransactionManager -->
      <attribute name="TransactionManagerLookupClass">
         org.jboss.cache.transaction.GenericTransactionManagerLookup
      </attribute>

      <!-- Node locking level : SERIALIZABLE
                                REPEATABLE_READ (default)
                                READ_COMMITTED
                                READ_UNCOMMITTED
                                NONE             -->
      <attribute name="IsolationLevel">READ_COMMITTED</attribute>

      <!-- Lock parent before doing node additions/removes -->
      <attribute name="LockParentForChildInsertRemove">true</attribute>

      <!-- Valid modes are LOCAL (default)
                           REPL_ASYNC
                           REPL_SYNC
                           INVALIDATION_ASYNC
                           INVALIDATION_SYNC   -->
      <attribute name="CacheMode">LOCAL</attribute>

      <!-- Max number of milliseconds to wait for a lock acquisition -->
      <attribute name="LockAcquisitionTimeout">15000</attribute>


      <!-- Specific eviction policy configurations. This is LRU -->
      <attribute name="EvictionConfig">
         <config>
            <attribute name="wakeUpIntervalSeconds">5</attribute>
            <attribute name="policyClass">org.jboss.cache.eviction.LRUPolicy</attribute>

            <!-- Cache wide default -->
            <region name="/_default_">
               <attribute name="maxNodes">5000</attribute>
               <attribute name="timeToLiveSeconds">1000</attribute>
            </region>
         </config>
      </attribute>
   </mbean>
</server>

         

            CacheFactory factory = DefaultCacheFactory.getInstance();
            Cache cache = factory.createCache("cache-configuration.xml");
         

            
            Configuration config = new Configuration();
            String tmlc = GenericTransactionManagerLookup.class.getName();
            config.setTransactionManagerLookupClass(tmlc);
            config.setIsolationLevel(IsolationLevel.READ_COMMITTED);
            config.setCacheMode(CacheMode.LOCAL);
            config.setLockParentForChildInsertRemove(true);
            config.setLockAcquisitionTimeout(15000);
            
            EvictionConfig ec = new EvictionConfig();
            ec.setWakeupIntervalSeconds(5);
            ec.setDefaultEvictionPolicyClass(LRUPolicy.class.getName());
            
            EvictionRegionConfig erc = new EvictionRegionConfig();
            erc.setRegionName("_default_");
            
            LRUConfiguration lru = new LRUConfiguration();
            lru.setMaxNodes(5000);
            lru.setTimeToLiveSeconds(1000);
            
            erc.setEvictionPolicyConfig(lru);
            
            List<EvictionRegionConfig> ercs = new ArrayList<EvictionRegionConfig>();
            ercs.add(erc);
            ec.setEvictionRegionConfigs(erc);
            
            config.setEvictionConfig(ec);
            
            CacheFactory factory = DefaultCacheFactory.getInstance();
            Cache cache = factory.createCache(config);         

         

A Configuration is composed of a number of subobjects:

Following is a brief overview of the components of a Configuration . See the javadoc and the linked chapters in this book for a more complete explanation of the configurations associated with each component.

Dynamically changing the configuration of some options while the cache is running is supported, by programmatically obtaining the Configuration object from the running cache and changing values. E.g.,

            Configuration liveConfig = cache.getConfiguration();
            liveConfig.setLockAcquisitionTimeout(2000);

         

A complete listing of which options may be changed dynamically is in the configuration reference section. An org.jboss.cache.config.ConfigurationException will be thrown if you attempt to change a setting that is not dynamic.

The Option API allows you to override certain behaviours of the cache on a per invocation basis. This involves creating an instance of org.jboss.cache.config.Option , setting the options you wish to override on the Option object and passing it in the InvocationContext before invoking your method on the cache.

E.g., to override the default node versioning used with optimistic locking:

            DataVersion v = new MyCustomDataVersion();
            cache.getInvocationContext().getOptionOverrides().setDataVersion(v);
            Node ch = cache.getRoot().addChild(Fqn.fromString("/a/b/c"));

         

E.g., to suppress replication of a put call in a REPL_SYNC cache:

            Node node = cache.getChild(Fqn.fromString("/a/b/c"));
            cache.getInvocationContext().getOptionOverrides().setLocalOnly(true);
            node.put("localCounter", new Integer(2));

         

See the javadocs on the Option class for details on the options available.

When used in a standalone Java program, all that needs to be done is to instantiate the cache using the CacheFactory and a Configuration instance or an XML file, as discussed in the User API and Configuration chapters.

The same techniques can be used when an application running in an application server wishes to programatically deploy a cache rather than relying on an application server's deployment features. An example of this would be a webapp deploying a cache via a javax.servlet.ServletContextListener .

If, after deploying your cache you wish to expose a management interface to it in JMX, see the section on Programatic Registration in JMX .

If JBoss Cache is run in JBoss AS then the cache can be deployed as an MBean simply by copying a standard cache configuration file to the server's deploy directory. The standard format of JBoss Cache's standard XML configuration file (as shown in the Configuration Reference ) is the same as a JBoss AS MBean deployment descriptor, so the AS's SAR Deployer has no trouble handling it. Also, you don't have to place the configuration file directly in deploy ; you can package it along with other services or JEE components in a SAR or EAR.

In AS 5, if you're using a server config based on the standard all config, then that's all you need to do; all required jars will be on the classpath. Otherwise, you will need to ensure jbosscache.jar and jgroups-all.jar are on the classpath. You may need to add other jars if you're using things like JdbmCacheLoader . The simplest way to do this is to copy the jars from the JBoss Cache distribution's lib directory to the server config's lib directory. You could also package the jars with the configuration file in Service Archive (.sar) file or an EAR.

It is possible to deploy a JBoss Cache 2.0 instance in JBoss AS 4.x (at least in 4.2.0.GA; other AS releases are completely untested). However, the significant API changes between the JBoss Cache 2.x and 1.x releases mean none of the standard AS 4.x clustering services (e.g. http session replication) that rely on JBoss Cache will work with JBoss Cache 2.x. Also, be aware that usage of JBoss Cache 2.x in AS 4.x is not something the JBoss Cache developers are making any significant effort to test, so be sure to test your application well (which of course you're doing anyway.)

Note in the example the value of the mbean element's code attribute: org.jboss.cache.jmx.CacheJmxWrapper . This is the class JBoss Cache uses to handle JMX integration; the Cache itself does not expose an MBean interface. See the JBoss Cache MBeans section for more on the CacheJmxWrapper .

Once your cache is deployed, in order to use it with an in-VM client such as a servlet, a JMX proxy can be used to get a reference to the cache:

         
      MBeanServer server = MBeanServerLocator.locateJBoss();
      ObjectName on = new ObjectName("jboss.cache:service=Cache");
      CacheJmxWrapperMBean cacheWrapper = 
        (CacheJmxWrapperMBean) MBeanServerInvocationHandler.newProxyInstance(server, on, 
                                                CacheJmxWrapperMBean.class, false);
      Cache cache = cacheWrapper.getCache();
      Node root = cache.getRoot(); // etc etc
   
      

The MBeanServerLocator class is a helper to find the (only) JBoss MBean server inside the current JVM. The javax.management.MBeanServerInvocationHandler class' newProxyInstance method creates a dynamic proxy implementing the given interface and uses JMX to dynamically dispatch methods invoked against the generated interface to the MBean. The name used to look up the MBean is the same as defined in the cache's configuration file.

Once the proxy to the CacheJmxWrapper is obtained, the getCache() will return a reference to the Cache itself.

Beginning with AS 5, JBoss AS also supports deployment of POJO services via deployment of a file whose name ends with -beans.xml . A POJO service is one whose implementation is via a "Plain Old Java Object", meaning a simple java bean that isn't required to implement any special interfaces or extend any particular superclass. A Cache is a POJO service, and all the components in a Configuration are also POJOS, so deploying a cache in this way is a natural step.

Deployment of the cache is done using the JBoss Microcontainer that forms the core of JBoss AS. JBoss Microcontainer is a sophisticated IOC framework (similar to Spring). A -beans.xml file is basically a descriptor that tells the IOC framework how to assemble the various beans that make up a POJO service.

The rules for how to deploy the file, how to package it, how to ensure the required jars are on the classpath, etc. are the same as for a JMX-based deployment .

Following is an example -beans.xml file. If you look in the server/all/deploy directory of an AS 5 installation, you can find several more examples.

         
<?xml version="1.0" encoding="UTF-8"?>

<deployment xmlns="urn:jboss:bean-deployer:2.0">

   <!-- First we create a Configuration object for the cache -->
   <bean name="ExampleCacheConfig"
   		 class="org.jboss.cache.config.Configuration">
      
      <!-- Externally injected services -->  
      <property name="runtimeConfig">
         <bean name="ExampleCacheRuntimeConfig" class="org.jboss.cache.config.RuntimeConfig">
            <property name="transactionManager">
               <inject bean="jboss:service=TransactionManager" 
                       property="TransactionManager"/>
            </property>
            <property name="muxChannelFactory"><inject bean="JChannelFactory"/></property>
         </bean>
      </property>
      
      <property name="multiplexerStack">udp</property>

      <property name="clusterName">Example-EntityCache</property>
        
      <!--
              Node locking level : SERIALIZABLE
                                   REPEATABLE_READ (default)
                                   READ_COMMITTED
                                   READ_UNCOMMITTED
                                   NONE
      -->
      <property name="isolationLevel">REPEATABLE_READ</property>

      <!--     Valid modes are LOCAL
                               REPL_ASYNC
                               REPL_SYNC
      -->
      <property name="cacheMode">REPL_SYNC</property>

      <!--  The max amount of time (in milliseconds) we wait until the
            initial state (ie. the contents of the cache) are retrieved from
            existing members in a clustered environment
      -->
      <property name="initialStateRetrievalTimeout">15000</property>

      <!--    Number of milliseconds to wait until all responses for a
              synchronous call have been received.
      -->
      <property name="syncReplTimeout">20000</property>

      <!--  Max number of milliseconds to wait for a lock acquisition -->
      <property name="lockAcquisitionTimeout">15000</property>
        
      <property name="exposeManagementStatistics">true</property>
      
      <!-- Must be true if any entity deployment uses a scoped classloader -->
      <property name="useRegionBasedMarshalling">true</property>
      <!-- Must match the value of "useRegionBasedMarshalling" -->
      <property name="inactiveOnStartup">true</property>

      <!--  Specific eviction policy configurations. This is LRU -->
      <property name="evictionConfig">
      	 <bean name="ExampleEvictionConfig" 
      	       class="org.jboss.cache.config.EvictionConfig">
      	    <property name="defaultEvictionPolicyClass">
      	       org.jboss.cache.eviction.LRUPolicy
      	    </property>
            <property name="wakeupIntervalSeconds">5</property>
            <property name="evictionRegionConfigs">
               <list>
                  <bean name="ExampleDefaultEvictionRegionConfig" 
                        class="org.jboss.cache.config.EvictionRegionConfig">
                     <property name="regionName">/_default_</property>
            	     <property name="evictionPolicyConfig">
                        <bean name="ExampleDefaultLRUConfig" 
                              class="org.jboss.cache.eviction.LRUConfiguration">
                           <property name="maxNodes">5000</property>
                           <property name="timeToLiveSeconds">1000</property>
                        </bean>
                     </property>
                  </bean>
               </list>
            </property>
         </bean>
      </property>
      
   </bean>
   
   <!-- Factory to build the Cache. -->
   <bean name="DefaultCacheFactory" class="org.jboss.cache.DefaultCacheFactory">      
      <constructor factoryClass="org.jboss.cache.DefaultCacheFactory" 
                   factoryMethod="getInstance"/>
   </bean>
   
   <!-- The cache itself -->
   <bean name="ExampleCache" class="org.jboss.cache.CacheImpl">
      
      <constructor factoryMethod="createCache">
          <factory bean="DefaultCacheFactory"/>
          <parameter><inject bean="ExampleCacheConfig"/></parameter>
          <parameter>false</false>
      </constructor>
          
   </bean>

</deployment>      

      

See the JBoss Microcontainer documentation ^[2] for details on the above syntax. Basically, each bean element represents an object; most going to create a Configuration and its constituent parts .

An interesting thing to note in the above example is the use of the RuntimeConfig object. External resources like a TransactionManager and a JGroups ChannelFactory that are visible to the microcontainer are dependency injected into the RuntimeConfig . The assumption here is that in some other deployment descriptor in the AS, the referenced beans have been described.

With the 1.x JBoss Cache releases, a proxy to the cache could be bound into JBoss AS's JNDI tree using the AS's JRMPProxyFactory service. With JBoss Cache 2.x, this no longer works. An alternative way of doing a similar thing with a POJO (i.e. non-JMX-based) service like a Cache is under development by the JBoss AS team ^[3] . That feature is not available as of the time of this writing, although it will be completed before AS 5.0.0.GA is released. We will add a wiki page describing how to use it once it becomes available.

JBoss Cache includes JMX MBeans to expose cache functionality and provide statistics that can be used to analyze cache operations. JBoss Cache can also broadcast cache events as MBean notifications for handling via JMX monitoring tools.

               CacheFactory factory = DefaultCacheFactory.getInstance();
               // Build but don't start the cache
               // (although it would work OK if we started it)
               Cache cache = factory.createCache("cache-configuration.xml", false);

               CacheJmxWrapperMBean wrapper = new CacheJmxWrapper(cache);
               MBeanServer server = getMBeanServer(); // however you do it
               ObjectName on = new ObjectName("jboss.cache:service=TreeCache");
               server.registerMBean(wrapper, on);

               // Invoking lifecycle methods on the wrapper results
               // in a call through to the cache
               wrapper.create();
               wrapper.start();

               ... use the cache

               ... on application shutdown

               // Invoking lifecycle methods on the wrapper results
               // in a call through to the cache
               wrapper.stop();
               wrapper.destroy();
            

               Configuration config = buildConfiguration(); // whatever it does

               CacheJmxWrapperMBean wrapper = new CacheJmxWrapper(config);
               MBeanServer server = getMBeanServer(); // however you do it
               ObjectName on = new ObjectName("jboss.cache:service=TreeCache");
               server.registerMBean(wrapper, on);

               // Call to wrapper.create() will build the Cache if one wasn't injected
               wrapper.create();
               wrapper.start();

               // Now that it's built, created and started, get the cache from the wrapper
               Cache cache = wrapper.getCache();

               ... use the cache

               ... on application shutdown

               wrapper.stop();
               wrapper.destroy();

            

               
<?xml version="1.0" encoding="UTF-8"?>

<deployment xmlns="urn:jboss:bean-deployer:2.0">

   <!-- First we create a Configuration object for the cache -->
   <bean name="ExampleCacheConfig"
   		 class="org.jboss.cache.config.Configuration">
      
      ... build up the Configuration
      
   </bean>
   
   <!-- Factory to build the Cache. -->
   <bean name="DefaultCacheFactory" class="org.jboss.cache.DefaultCacheFactory">      
      <constructor factoryClass="org.jboss.cache.DefaultCacheFactory" 
                   factoryMethod="getInstance"/>
   </bean>
   
   <!-- The cache itself -->
   <bean name="ExampleCache" class="org.jboss.cache.CacheImpl">
      
      <constructor factoryMethod="createnewInstance">
          <factory bean="DefaultCacheFactory"/>
          <parameter><inject bean="ExampleCacheConfig"/></parameter>
          <parameter>false</false>
      </constructor>
          
   </bean>
   
   <!-- JMX Management -->
   <bean name="ExampleCacheJmxWrapper" class="org.jboss.cache.jmx.CacheJmxWrapper">
      
      <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.cache:service=ExampleTreeCache", 
                         exposedInterface=org.jboss.cache.jmx.CacheJmxWrapperMBean.class, 
                         registerDirectly=true)</annotation>
      
      <constructor>
          <parameter><inject bean="ExampleCache"/></parameter>
      </constructor>
          
   </bean>

</deployment>      

            

               
<?xml version="1.0" encoding="UTF-8"?>

<deployment xmlns="urn:jboss:bean-deployer:2.0">

   <!-- First we create a Configuration object for the cache -->
   <bean name="ExampleCacheConfig"
   		 class="org.jboss.cache.config.Configuration">
      
      ... build up the Configuration
      
   </bean>
    
   <bean name="ExampleCache" class="org.jboss.cache.jmx.CacheJmxWrapper">
      
      <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.cache:service=ExampleTreeCache", 
                         exposedInterface=org.jboss.cache.jmx.CacheJmxWrapperMBean.class, 
                         registerDirectly=true)</annotation>
      
      <constructor>
          <parameter><inject bean="ExampleCacheConfig"/></parameter>
      </constructor>
          
   </bean>

</deployment>      

            

            
         MyListener listener = new MyListener();
         NotificationFilterSupport filter = null;

         // get reference to MBean server
         Context ic = new InitialContext();
         MBeanServerConnection server = (MBeanServerConnection)ic.lookup("jmx/invoker/RMIAdaptor");

         // get reference to CacheMgmtInterceptor MBean
         String cache_service = "jboss.cache:service=TomcatClusteringCache";
         ObjectName mgmt_name = new ObjectName(cache_service);

         // configure a filter to only receive node created and removed events
         filter = new NotificationFilterSupport();
         filter.disableAllTypes();
         filter.enableType(CacheNotificationBroadcaster.NOTIF_NODE_CREATED);
         filter.enableType(CacheNotificationBroadcaster.NOTIF_NODE_REMOVED);

         // register the listener with a filter
         // leave the filter null to receive all cache events
         server.addNotificationListener(mgmt_name, listener, filter, null);

         // ...

         // on completion of processing, unregister the listener
         server.removeNotificationListener(mgmt_name, listener, filter, null);
         
         

            
         private class MyListener implements NotificationListener, Serializable
         {
            public void handleNotification(Notification notification, Object handback)
            {
               String message = notification.getMessage();
               String type = notification.getType();
               Object userData = notification.getUserData();

               System.out.println(type + ": " + message);

               if (userData == null)
               {
                  System.out.println("notification data is null");
               }
               else if (userData instanceof String)
               {
                  System.out.println("notification data: " + (String) userData);
               }
               else if (userData instanceof Object[])
               {
                  Object[] ud = (Object[]) userData;
                  for (Object data : ud)
                  {
                     System.out.println("notification data: " + data.toString());
                  }
               }
               else
               {
                  System.out.println("notification data class: " + userData.getClass().getName());
               }
            }
         }
         
         

4.5.5. Accessing Cache MBeans in a Standalone Environment

JBoss Cache MBeans are easily accessed when running cache instances in an application server that provides an MBean server interface such as JBoss JMX Console. Refer to your server documentation for instructions on how to access MBeans running in a server's MBean container.

In addition, though, JBoss Cache MBeans are also accessible when running in a non-server environment if the JVM is JDK 5.0 or later. When running a standalone cache in a JDK 5.0 environment, you can access the cache's MBeans as follows.

1. Set the system property -Dcom.sun.management.jmxremote when starting the JVM where the cache will run.
2. Once the JVM is running, start the JDK 5.0 jconsole utility, located in your JDK's /bin directory.
3. When the utility loads, you will be able to select your running JVM and connect to it. The JBoss Cache MBeans will be available on the MBeans panel.

Note that the jconsole utility will automatically register as a listener for cache notifications when connected to a JVM running JBoss Cache instances.

The following figure shows cache interceptor MBeans in jconsole . Cache statistics are displayed for the CacheMgmtInterceptor :

Figure 4.1. CacheMgmtInterceptor MBean in jconsole

A compatibility matrix is maintained on the JBoss Cache website, which contains information on different versions of JBoss Cache, JGroups and JBoss AS.

A Cache consists of a collection of Node instances, organised in a tree structure. Each Node contains a Map which holds the data objects to be cached. It is important to note that the structure is a mathematical tree, and not a graph; each Node has one and only one parent, and the root node is denoted by the constant fully qualitied name, Fqn.ROOT .

The reason for organising nodes as such is to improve concurrent access to data and make replication and persistence more fine-grained.

Figure 6.1. Data structured as a tree

In the diagram above, each box represents a JVM. You see 2 caches in separate JVMs, replicating data to each other. These VMs can be located on the same physical machine, or on 2 different machines connected by a network link. The underlying group communication between networked nodes is done using JGroups .

Any modifications (see API chapter ) in one cache instance will be replicated to the other cache. Naturally, you can have more than 2 caches in a cluster. Depending on the transactional settings, this replication will occur either after each modification or at the end of a transaction, at commit time. When a new cache is created, it can optionally acquire the contents from one of the existing caches on startup.

In addition to Cache and Node interfaces, JBoss Cache exposes more powerful CacheSPI and NodeSPI interfaces, which offer more control over the internals of JBoss Cache. These interfaces are not intended for general use, but are designed for people who wish to extend and enhance JBoss Cache, or write custom Interceptor or CacheLoader instances.

Figure 6.2. SPI Interfaces

The CacheSPI interface cannot be created, but is injected into Interceptor and CacheLoader implementations by the setCache(CacheSPI cache) methods on these interfaces. CacheSPI extends Cache so all the functionality of the basic API is made available.

Similarly, a NodeSPI interface cannot be created. Instead, one is obtained by performing operations on CacheSPI , obtained as above. For example, Cache.getRoot() : Node is overridden as CacheSPI.getRoot() : NodeSPI .

It is important to note that directly casting a Cache or Node to it's SPI counterpart is not recommended and is bad practice, since the inheritace of interfaces it is not a contract that is guaranteed to be upheld moving forward. The exposed public APIs, on the other hand, is guaranteed to be upheld.

Since the cache is essentially a collection of nodes, aspects such as clustering, persistence, eviction, etc. need to be applied to these nodes when operations are invoked on the cache as a whole or on individual nodes. To achieve this in a clean, modular and extensible manner, an interceptor chain is used. The chain is built up of a series of interceptors, each one adding an aspect or particular functionality. The chain is built when the cache is created, based on the configuration used.

It is important to note that the NodeSPI offers some methods (such as the xxxDirect() method family) that operate on a node directly without passing through the interceptor stack. Plugin authors should note that using such methods will affect the aspects of the cache that may need to be applied, such as locking, replication, etc. Basically, don't use such methods unless you really know what you're doing!

6.3.1. Interceptors

An Interceptor is an abstract class, several of which comprise an interceptor chain. It exposes an invoke() method, which must be overridden by implementing classes to add behaviour to a call before passing the call down the chain by calling super.invoke() .

Figure 6.3. SPI Interfaces

JBoss Cache ships with several interceptors, representing different configuration options, some of which are:

• TxInterceptor - looks for ongoing transactions and registers with transaction managers to participate in synchronization events
• ReplicationInterceptor - replicates state across a cluster using a JGroups channel
• CacheLoaderInterceptor - loads data from a persistent store if the data requested is not available in memory

The interceptor chain configured for your cache instance can be obtained and inspected by calling CacheSPI.getInterceptorChain() , which returns an ordered List of interceptors.

6.3.1.1. Writing Custom Interceptors

Custom interceptors to add specific aspects or features can be written by extending Interceptor and overriding invoke() . The custom interceptor will need to be added to the interceptor chain by using the CacheSPI.addInterceptor() method.

Adding custom interceptors via XML is not supported at this time.

Some aspects and functionality is shared by more than a single interceptor. Some of these have been encapsulated into managers, for use by various interceptors, and are made available by the CacheSPI interface.

Early versions of JBoss Cache simply wrote cached data to the network by writing to an ObjectOutputStream during replication. Over various releases in the JBoss Cache 1.x.x series this approach was gradually deprecated in favour of a more mature marshalling framework. In the JBoss Cache 2.x.x series, this is the only officially supported and recommended mechanism for writing objects to datastreams.

Figure 6.4. The Marshaller interface

When used to cluster state of application servers, applications deployed in the application tend to put instances of objects specific to their application in the cache (or in an HttpSession object) which would require replication. It is common for application servers to assign separate ClassLoader instances to each application deployed, but have JBoss Cache libraries referenced by the application server's ClassLoader .

To enable us to successfully marshall and unmarshall objects from such class loaders, we use a concept called regions. A region is a portion of the cache which share a common class loader (a region also has other uses - see eviction policies ).

A region is created by using the Cache.getRegion(Fqn fqn, boolean createIfNotExists) method, and returns an implementation of the Region interface. Once a region is obtained, a class loader for the region can be set or unset, and the region can be activated/deactivated. By default, regions are active unless the InactiveOnStartup configuration attribute is set to true .

JBoss Cache can be configured to be either local (standalone) or clustered. If in a cluster, the cache can be configured to replicate changes, or to invalidate changes. A detailed discussion on this follows.

7.1.2. Replicated Caches

Replicated caches replicate all changes to some or all of the other cache instances in the cluster. Replication can either happen after each modification (no transactions), or at the end of a transaction (commit time).

Replication can be synchronous or asynchronous . Use of either one of the options is application dependent. Synchronous replication blocks the caller (e.g. on a put() ) until the modifications have been replicated successfully to all nodes in a cluster. Asynchronous replication performs replication in the background (the put() returns immediately). JBoss Cache also offers a replication queue, where modifications are replicated periodically (i.e. interval-based), or when the queue size exceeds a number of elements, or a combination thereof.

Asynchronous replication is faster (no caller blocking), because synchronous replication requires acknowledgments from all nodes in a cluster that they received and applied the modification successfully (round-trip time). However, when a synchronous replication returns successfully, the caller knows for sure that all modifications have been applied to all cache instances, whereas this is not be the case with asynchronous replication. With asynchronous replication, errors are simply written to a log. Even when using transactions, a transaction may succeed but replication may not succeed on all cache instances.

7.1.2.1. Replicated Caches and Transactions

When using transactions, replication only occurs at the transaction boundary - i.e., when a transaction commits. This results in minimising replication traffic since a single modification is broadcast rather than a series of individual modifications, and can be a lot more efficient than not using transactions. Another effect of this is that if a transaction were to roll back, nothing is broadcast across a cluster.

Depending on whether you are running your cluster in asynchronous or synchronous mode, JBoss Cache will use either a single phase or two phase commit protocol, respectively.

7.1.2.1.1. One Phase Commits

Used when your cache mode is REPL_ASYNC. All modifications are replicated in a single call, which instructs remote caches to apply the changes to their local in-memory state and commit locally. Remote errors/rollbacks are never fed back to the originator of the transaction since the communication is asynchronous.

7.1.2.1.2. Two Phase Commits

Used when your cache mode is REPL_SYNC. Upon committing your transaction, JBoss Cache broadcasts a prepare call, which carries all modifications relevant to the transaction. Remote caches then acquire local locks on their in-memory state and apply the modifications. Once all remote caches respond to the prepare call, the originator of the transaction broadcasts a commit. This instructs all remote caches to commit their data. If any of the caches fail to respond to the prepare phase, the originator broadcasts a rollback.

Note that although the prepare phase is synchronous, the commit and rollback phases are asynchronous. This is because Sun's JTA specification does not specify how transactional resources should deal with failures at this stage of a transaction; and other resources participating in the transaction may have indeterminate state anyway. As such, we do away with the overhead of synchronous communication for this phase of the transaction. That said, they can be forced to be synchronous using the SyncCommitPhase and SyncRollbackPhase configuration attributes.

7.1.2.2. Buddy Replication

Buddy Replication allows you to suppress replicating your data to all instances in a cluster. Instead, each instance picks one or more 'buddies' in the cluster, and only replicates to these specific buddies. This greatly helps scalability as there is no longer a memory and network traffic impact every time another instance is added to a cluster.

One of the most common use cases of Buddy Replication is when a replicated cache is used by a servlet container to store HTTP session data. One of the pre-requisites to buddy replication working well and being a real benefit is the use of session affinity , more casually known as sticky sessions in HTTP session replication speak. What this means is that if certain data is frequently accessed, it is desirable that this is always accessed on one instance rather than in a round-robin fashion as this helps the cache cluster optimise how it chooses buddies, where it stores data, and minimises replication traffic.

If this is not possible, Buddy Replication may prove to be more of an overhead than a benefit.

7.1.2.2.1. Selecting Buddies

Figure 7.1. BuddyLocator

Buddy Replication uses an instance of a BuddyLocator which contains the logic used to select buddies in a network. JBoss Cache currently ships with a single implementation, NextMemberBuddyLocator , which is used as a default if no implementation is provided. The NextMemberBuddyLocator selects the next member in the cluster, as the name suggests, and guarantees an even spread of buddies for each instance.

The NextMemberBuddyLocator takes in 2 parameters, both optional.

• numBuddies - specifies how many buddies each instance should pick to back its data onto. This defaults to 1.
• ignoreColocatedBuddies - means that each instance will try to select a buddy on a different physical host. If not able to do so though, it will fall back to colocated instances. This defaults to true .

7.1.2.2.2. BuddyPools

Also known as replication groups , a buddy pool is an optional construct where each instance in a cluster may be configured with a buddy pool name. Think of this as an 'exclusive club membership' where when selecting buddies, BuddyLocator s that support buddy pools would try and select buddies sharing the same buddy pool name. This allows system administrators a degree of flexibility and control over how buddies are selected. For example, a sysadmin may put two instances on two separate physical servers that may be on two separate physical racks in the same buddy pool. So rather than picking an instance on a different host on the same rack, BuddyLocator s would rather pick the instance in the same buddy pool, on a separate rack which may add a degree of redundancy.

7.1.2.2.3. Failover

In the unfortunate event of an instance crashing, it is assumed that the client connecting to the cache (directly or indirectly, via some other service such as HTTP session replication) is able to redirect the request to any other random cache instance in the cluster. This is where a concept of Data Gravitation comes in.

Data Gravitation is a concept where if a request is made on a cache in the cluster and the cache does not contain this information, it asks other instances in the cluster for the data. In other words, data is lazily transferred, migrating only when other nodes ask for it. This strategy prevents a network storm effect where lots of data is pushed around healthy nodes because only one (or a few) of them die.

If the data is not found in the primary section of some node, it would (optionally) ask other instances to check in the backup data they store for other caches. This means that even if a cache containing your session dies, other instances will still be able to access this data by asking the cluster to search through their backups for this data.

Once located, this data is transferred to the instance which requested it and is added to this instance's data tree. The data is then (optionally) removed from all other instances (and backups) so that if session affinity is used, the affinity should now be to this new cache instance which has just taken ownership of this data.

Data Gravitation is implemented as an interceptor. The following (all optional) configuration properties pertain to data gravitation.

• dataGravitationRemoveOnFind - forces all remote caches that own the data or hold backups for the data to remove that data, thereby making the requesting cache the new data owner. This removal, of course, only happens after the new owner finishes replicating data to its buddy. If set to false an evict is broadcast instead of a remove, so any state persisted in cache loaders will remain. This is useful if you have a shared cache loader configured. Defaults to true .
• dataGravitationSearchBackupTrees - Asks remote instances to search through their backups as well as main data trees. Defaults to true . The resulting effect is that if this is true then backup nodes can respond to data gravitation requests in addition to data owners.
• autoDataGravitation - Whether data gravitation occurs for every cache miss. By default this is set to false to prevent unnecessary network calls. Most use cases will know when it may need to gravitate data and will pass in an Option to enable data gravitation on a per-invocation basis. If autoDataGravitation is true this Option is unnecessary.

7.1.2.2.4. Configuration

                     
<!-- Buddy Replication config -->
<attribute name="BuddyReplicationConfig">
   <config>

      <!-- Enables buddy replication. This is the ONLY mandatory configuration element here. -->
      <buddyReplicationEnabled>true</buddyReplicationEnabled>

      <!-- These are the default values anyway -->
      <buddyLocatorClass>org.jboss.cache.buddyreplication.NextMemberBuddyLocator</buddyLocatorClass>

      <!--  numBuddies is the number of backup nodes each node maintains. ignoreColocatedBuddies means
            that each node will *try* to select a buddy on a different physical host. If not able to do so though,
            it will fall back to colocated nodes. -->
      <buddyLocatorProperties>
         numBuddies = 1
         ignoreColocatedBuddies = true
      </buddyLocatorProperties>

      <!-- A way to specify a preferred replication group. If specified, we try and pick a buddy which shares
           the same pool name (falling back to other buddies if not available). This allows the sysdmin to
           hint at backup buddies are picked, so for example, nodes may be hinted topick buddies on a different
           physical rack or power supply for added fault tolerance. -->
      <buddyPoolName>myBuddyPoolReplicationGroup</buddyPoolName>

      <!-- Communication timeout for inter-buddy group organisation messages (such as assigning to and
           removing from groups, defaults to 1000. -->
      <buddyCommunicationTimeout>2000</buddyCommunicationTimeout>

      <!-- Whether data is removed from old owners when gravitated to a new owner. Defaults to true. -->
      <dataGravitationRemoveOnFind>true</dataGravitationRemoveOnFind>

      <!-- Whether backup nodes can respond to data gravitation requests, or only the data owner is
           supposed to respond.  Defaults to true. -->
      <dataGravitationSearchBackupTrees>true</dataGravitationSearchBackupTrees>

      <!-- Whether all cache misses result in a data gravitation request. Defaults to false, requiring
           callers to enable data gravitation on a per-invocation basis using the Options API. -->
      <autoDataGravitation>false</autoDataGravitation>

   </config>
</attribute>


                  

If a cache is configured for invalidation rather than replication, every time data is changed in a cache other caches in the cluster receive a message informing them that their data is now stale and should be evicted from memory. Invalidation, when used with a shared cache loader (see chapter on Cache Loaders) would cause remote caches to refer to the shared cache loader to retrieve modified data. The benefit of this is twofold: network traffic is minimised as invalidation messages are very small compared to replicating updated data, and also that other caches in the cluster look up modified data in a lazy manner, only when needed.

Invalidation messages are sent after each modification (no transactions), or at the end of a transaction, upon successful commit. This is usually more efficient as invalidation messages can be optimised for the transaction as a whole rather than on a per-modification basis.

Invalidation too can be synchronous or asynchronous, and just as in the case of replication, synchronous invalidation blocks until all caches in the cluster receive invalidation messages and have evicted stale data while asynchronous invalidation works in a 'fire-and-forget' mode, where invalidation messages are broadcast but doesn't block and wait for responses.

State Transfer refers to the process by which a JBoss Cache instance prepares itself to begin providing a service by acquiring the current state from another cache instance and integrating that state into its own state.

Figure 8.1. The CacheLoader interface

The interaction between JBoss Cache and a CacheLoader implementation is as follows. When CacheLoaderConfiguration (see below) is non-null, an instance of each configured CacheLoader is created when the cache is created, and started when the cache is started.

CacheLoader.create() and CacheLoader.start() are called when the cache is started. Correspondingly, stop() and destroy() are called when the cache is stopped.

Next, setConfig() and setCache() are called. The latter can be used to store a reference to the cache, the former is used to configure this instance of the CacheLoader . For example, here a database cache loader could establish a connection to the database.

The CacheLoader interface has a set of methods that are called when no transactions are used: get() , put() , remove() and removeData() : they get/set/remove the value immediately. These methods are described as javadoc comments in the interface.

Then there are three methods that are used with transactions: prepare() , commit() and rollback() . The prepare() method is called when a transaction is to be committed. It has a transaction object and a list of modfications as argument. The transaction object can be used as a key into a hashmap of transactions, where the values are the lists of modifications. Each modification list has a number of Modification elements, which represent the changes made to a cache for a given transaction. When prepare() returns successfully, then the cache loader must be able to commit (or rollback) the transaction successfully.

JBoss Cache takes care of calling prepare(), commit() and rollback() on the cache loaders at the right time.

The commit() method tells the cache loader to commit the transaction, and the rollback() method tells the cache loader to discard the changes associated with that transaction.

See the javadocs on this interface for a detailed explanation on each method and the contract implementations would need to fulfil.

Cache loaders are configured as follows in the JBoss Cache XML file. Note that you can define several cache loaders, in a chain. The impact is that the cache will look at all of the cache loaders in the order they've been configured, until it finds a valid, non-null element of data. When performing writes, all cache loaders are written to (except if the ignoreModifications element has been set to true for a specific cache loader. See the configuration section below for details.

         

...

<!-- Cache loader config block -->
<attribute name="CacheLoaderConfiguration">
   <config>
      <!-- if passivation is true, only the first cache loader is used; the rest are ignored -->
      <passivation>false</passivation>
      <!-- comma delimited FQNs to preload -->
      <preload>/</preload>
      <!-- are the cache loaders shared in a cluster? -->
      <shared>false</shared>

      <!-- we can now have multiple cache loaders, which get chained -->
      <!-- the 'cacheloader' element may be repeated -->
      <cacheloader>

         <class>org.jboss.cache.loader.JDBCCacheLoader</class>

         <!-- properties to pass in to the cache loader -->
         <properties>
            cache.jdbc.driver=com.mysql.jdbc.Driver
            cache.jdbc.url=jdbc:mysql://localhost:3306/jbossdb
            cache.jdbc.user=root
            cache.jdbc.password=
            cache.jdbc.sql-concat=concat(1,2)
         </properties>

         <!-- whether the cache loader writes are asynchronous -->
         <async>false</async>

         <!-- only one cache loader in the chain may set fetchPersistentState to true.
              An exception is thrown if more than one cache loader sets this to true. -->
         <fetchPersistentState>true</fetchPersistentState>

         <!-- determines whether this cache loader ignores writes - defaults to false. -->
         <ignoreModifications>false</ignoreModifications>

         <!-- if set to true, purges the contents of this cache loader when the cache starts up.
              Defaults to false. -->
         <purgeOnStartup>false</purgeOnStartup>

         <!-- defines the cache loader as a singleton store where only the coordinator of the
              cluster will store modifications. -->
         <singletonStore>
            <!-- if true, singleton store functionality is enabled, defaults to false -->
            <enabled>false</enabled>

            <!-- implementation class for singleton store functionality which must extend
                 org.jboss.cache.loader.AbstractDelegatingCacheLoader. Default implementation
                 is org.jboss.cache.loader.SingletonStoreCacheLoader -->
            <class>org.jboss.cache.loader.SingletonStoreCacheLoader</class>

            <!-- properties and default values for the default singleton store functionality
                 implementation -->
            <properties>
               pushStateWhenCoordinator=true
               pushStateWhenCoordinatorTimeout=20000
            </properties>
         </singletonStore>
      </cacheloader>

   </config>
</attribute>

      

The class element defines the class of the cache loader implementation. (Note that, because of a bug in the properties editor in JBoss AS, backslashes in variables for Windows filenames might not get expanded correctly, so replace="false" may be necessary). Note that an implementation of cache loader has to have an empty constructor.

The properties element defines a configuration specific to the given implementation. The filesystem-based implementation for example defines the root directory to be used, whereas a database implementation might define the database URL, name and password to establish a database connection. This configuration is passed to the cache loader implementation via CacheLoader.setConfig(Properties) . Note that backspaces may have to be escaped.

preload allows us to define a list of nodes, or even entire subtrees, that are visited by the cache on startup, in order to preload the data associated with those nodes. The default ("/") loads the entire data available in the backend store into the cache, which is probably not a good idea given that the data in the backend store might be large. As an example, /a, /product/catalogue loads the subtrees /a and /product/catalogue into the cache, but nothing else. Anything else is loaded lazily when accessed. Preloading makes sense when one anticipates using elements under a given subtree frequently. .

fetchPersistentState determines whether or not to fetch the persistent state of a cache when joining a cluster. Only one configured cache loader may set this property to true; if more than one cache loader does so, a configuration exception will be thrown when starting your cache service.

async determines whether writes to the cache loader block until completed, or are run on a separate thread so writes return immediately. If this is set to true, an instance of org.jboss.cache.loader.AsyncCacheLoader is constructed with an instance of the actual cache loader to be used. The AsyncCacheLoader then delegates all requests to the underlying cache loader, using a separate thread if necessary. See the Javadocs on AsyncCacheLoader for more details. If unspecified, the async element defaults to false .

Note on using the async element: there is always the possibility of dirty reads since all writes are performed asynchronously, and it is thus impossible to guarantee when (and even if) a write succeeds. This needs to be kept in mind when setting the async element to true.

ignoreModifications determines whether write methods are pushed down to the specific cache loader. Situations may arise where transient application data should only reside in a file based cache loader on the same server as the in-memory cache, for example, with a further shared JDBCCacheLoader used by all servers in the network. This feature allows you to write to the 'local' file cache loader but not the shared JDBCCacheLoader . This property defaults to false , so writes are propagated to all cache loaders configured.

purgeOnStatup empties the specified cache loader (if ignoreModifications is false ) when the cache loader starts up.

shared indicates that the cache loader is shared among different cache instances, for example where all instances in a cluster use the same JDBC settings t talk to the same remote, shared database. Setting this to true prevents repeated and unnecessary writes of the same data to the cache loader by different cache instances. Default value is false .

The currently available implementations shipped with JBoss Cache are as follows.

                     
<attribute name="CacheLoaderConfiguration">
<config>
   <passivation>false</passivation>
   <preload>/some/stuff</preload>
   <cacheloader>
      <class>org.jboss.cache.loader.JDBCCacheLoader</class>

      <properties>
         cache.jdbc.table.name=jbosscache
         cache.jdbc.table.create=true
         cache.jdbc.table.drop=true
         cache.jdbc.table.primarykey=jbosscache_pk
         cache.jdbc.fqn.column=fqn
         cache.jdbc.fqn.type=varchar(255)
         cache.jdbc.node.column=node
         cache.jdbc.node.type=blob
         cache.jdbc.parent.column=parent
         cache.jdbc.driver=oracle.jdbc.OracleDriver
         cache.jdbc.url=jdbc:oracle:thin:@localhost:1521:JBOSSDB
         cache.jdbc.user=SCOTT
         cache.jdbc.password=TIGER
         cache.jdbc.sql-concat=concat(1,2)
      </properties>

      <async>false</async>
      <fetchPersistentState>true</fetchPersistentState>
      <ignoreModifications>false</ignoreModifications>
      <purgeOnStartup>false</purgeOnStartup>
   </cacheloader>
</config>
</attribute>

                  

                  
<attribute name="CacheLoaderConfiguration">
<config>
   <passivation>false</passivation>
   <preload>/some/stuff</preload>
   <cacheloader>
      <class>org.jboss.cache.loader.JDBCCacheLoader</class>

      <properties>
         cache.jdbc.datasource=java:/DefaultDS
      </properties>

      <async>false</async>
      <fetchPersistentState>true</fetchPersistentState>
      <ignoreModifications>false</ignoreModifications>
      <purgeOnStartup>false</purgeOnStartup>
   </cacheloader>
</config>
</attribute>

               

                  
<attribute name="CacheLoaderConfiguration">
<config>
   <passivation>false</passivation>
   <preload>/some/stuff</preload>
   <cacheloader>
      <class>org.jboss.cache.loader.JDBCCacheLoader</class>

      <properties>
         cache.jdbc.table.name=jbosscache
         cache.jdbc.table.create=true
         cache.jdbc.table.drop=true
         cache.jdbc.table.primarykey=jbosscache_pk
         cache.jdbc.fqn.column=fqn
         cache.jdbc.fqn.type=varchar(255)
         cache.jdbc.node.column=node
         cache.jdbc.node.type=blob
         cache.jdbc.parent.column=parent
         cache.jdbc.driver=oracle.jdbc.OracleDriver
         cache.jdbc.url=jdbc:oracle:thin:@localhost:1521:JBOSSDB
         cache.jdbc.user=SCOTT
         cache.jdbc.password=TIGER
         cache.jdbc.sql-concat=concat(1,2)
         cache.jdbc.connection.factory=org.jboss.cache.loader.C3p0ConnectionFactory
         c3p0.maxPoolSize=20
         c3p0.checkoutTimeout=5000
      </properties>

      <async>false</async>
      <fetchPersistentState>true</fetchPersistentState>
      <ignoreModifications>false</ignoreModifications>
      <purgeOnStartup>false</purgeOnStartup>
   </cacheloader>
</config>
</attribute>

               

            
<attribute name="CacheLoaderConfiguration">
<config>
   <cacheloader>
      <class>org.jboss.cache.loader.TcpDelegatingCacheLoader</class>
      <properties>
         host=myRemoteServer
         port=7500
      </properties>
   </cacheloader>
</config>
</attribute>

         

A cache loader can be used to enforce node passivation and activation on eviction in a cache.

Cache Passivation is the process of removing an object from in-memory cache and writing it to a secondary data store (e.g., file system, database) on eviction. Cache Activation is the process of restoring an object from the data store into the in-memory cache when it's needed to be used. In both cases, the configured cache loader will be used to read from the data store and write to the data store.

When an eviction policy in effect evicts a node from the cache, if passivation is enabled, a notification that the node is being passivated will be emitted to the cache listeners and the node and its children will be stored in the cache loader store. When a user attempts to retrieve a node that was evicted earlier, the node is loaded (lazy loaded) from the cache loader store into memory. When the node and its children have been loaded, they're removed from the cache loader and a notification is emitted to the cache listeners that the node has been activated.

To enable cache passivation/activation, you can set passivation to true. The default is false . When passivation is used, only the first cache loader configured is used and all others are ignored.

This section discusses different patterns of combining different cache loader types and configuration options to achieve specific outcomes.

8.5.2. Replicated Caches With All Caches Sharing The Same Store

The following figure shows 2 JBoss Cache instances sharing the same backend store:

Figure 8.2. 2 nodes sharing a backend store

Both nodes have a cache loader that accesses a common shared backend store. This could for example be a shared filesystem (using the FileCacheLoader), or a shared database. Because both nodes access the same store, they don't necessarily need state transfer on startup. ^[6] Rather, the FetchInMemoryState attribute could be set to false, resulting in a 'cold' cache, that gradually warms up as elements are accessed and loaded for the first time. This would mean that individual caches in a cluster might have different in-memory state at any given time (largely depending on their preloading and eviction strategies).

When storing a value, the writer takes care of storing the change in the backend store. For example, if node1 made change C1 and node2 C2, then node1 would tell its cache loader to store C1, and node2 would tell its cache loader to store C2.

8.5.3. Replicated Caches With Only One Cache Having A Store

Figure 8.3. 2 nodes but only one accesses the backend store

This is a similar case to the previous one, but here only one node in the cluster interacts with a backend store via its cache loader. All other nodes perform in-memory replication. The idea here is all application state is kept in memory in each node, with the existence of multiple caches making the data highly available. (This assumes that a client that needs the data is able to somehow fail over from one cache to another.) The single persistent backend store then provides a backup copy of the data in case all caches in the cluster fail or need to be restarted.

Note that here it may make sense for the cache loader to store changes asynchronously, that is not on the caller's thread, in order not to slow down the cluster by accessing (for example) a database. This is a non-issue when using asynchronous replication.

A weakness with this architecture is that the cache with access to the cache loader becomes a single point of failure. Furthermore, if the cluster is restarted, the cache with the cache loader must be started first (easy to forget). A solution to the first problem is to configure a cache loader on each node, but set the singletonStore configuration to true. With this kind of setup, one but only one node will always be writing to a persistent store. However, this complicates the restart problem, as before restarting you need to determine which cache was writing before the shutdown/failure and then start that cache first.

8.5.4. Replicated Caches With Each Cache Having Its Own Store

Figure 8.4. 2 nodes each having its own backend store

Here, each node has its own datastore. Modifications to the cache are (a) replicated across the cluster and (b) persisted using the cache loader. This means that all datastores have exactly the same state. When replicating changes synchronously and in a transaction, the two phase commit protocol takes care that all modifications are replicated and persisted in each datastore, or none is replicated and persisted (atomic updates).

Note that JBoss Cache is not an XA Resource, that means it doesn't implement recovery. When used with a transaction manager that supports recovery, this functionality is not available.

The challenge here is state transfer: when a new node starts it needs to do the following:

1. Tell the coordinator (oldest node in a cluster) to send it the state. This is always a full state transfer, overwriting any state that may already be present.

2. The coordinator then needs to wait until all in-flight transactions have completed. During this time, it will not allow for new transactions to be started.

3. Then the coordinator asks its cache loader for the entire state using loadEntireState() . It then sends back that state to the new node.

4. The new node then tells its cache loader to store that state in its store, overwriting the old state. This is the CacheLoader.storeEntireState() method

5. As an option, the transient (in-memory) state can be transferred as well during the state transfer.

6. The new node now has the same state in its backend store as everyone else in the cluster, and modifications received from other nodes will now be persisted using the local cache loader.

8.5.5. Hierarchical Caches

If you need to set up a hierarchy within a single JVM, you can use the LocalDelegatingCacheLoader . This type of hierarchy can currently only be set up programmatically.

Hierarchical caches could also be set up spanning more than one JVM or server, using the TcpDelegatingCacheLoader .

Figure 8.5. TCP delegating cache loader

8.5.6. Multiple Cache Loaders

You can set up more than one cache loader in a chain. Internally, a delegating ChainingCacheLoader is used, with references to each cache loader you have configured. Use cases vary depending on the type of cache loaders used in the chain. One example is using a filesystem based cache loader, colocated on the same host as the JVM, used as an overflow for memory. This ensures data is available relatively easily and with low cost. An additional remote cache loader, such as a TcpDelegatingCacheLoader provides resilience between server restarts.

Figure 8.6. Multiple cache loaders in a chain

JBoss Cache is a thread safe caching API, and uses its own efficient mechanisms of controlling concurrent access. It uses a pessimistic locking scheme by default for this purpose. Optimistic locking may alternatively be used, and is discussed later.

10.1.3. Optimistic Locking

The motivation for optimistic locking is to improve concurrency. When a lot of threads have a lot of contention for access to the data tree, it can be inefficient to lock portions of the tree - for reading or writing - for the entire duration of a transaction as we do in pessimistic locking. Optimistic locking allows for greater concurrency of threads and transactions by using a technique called data versioning, explained here. Note that isolation levels (if configured) are ignored if optimistic locking is enabled.

10.1.3.1. Architecture

Optimistic locking treats all method calls as transactional ^[7] . Even if you do not invoke a call within the scope of an ongoing transaction, JBoss Cache creates an implicit transaction and commits this transaction when the invocation completes. Each transaction maintains a transaction workspace, which contains a copy of the data used within the transaction.

For example, if a transaction calls cache.getRoot().getChild( Fqn.fromString("/a/b/c") ) , nodes a, b and c are copied from the main data tree and into the workspace. The data is versioned and all calls in the transaction work on the copy of the data rather than the actual data. When the transaction commits, its workspace is merged back into the underlying tree by matching versions. If there is a version mismatch - such as when the actual data tree has a higher version than the workspace, perhaps if another transaction were to access the same data, change it and commit before the first transaction can finish - the transaction throws a RollbackException when committing and the commit fails.

Optimistic locking uses the same locks we speak of above, but the locks are only held for a very short duration - at the start of a transaction to build a workspace, and when the transaction commits and has to merge data back into the tree.

So while optimistic locking may occasionally fail if version validations fail or may run slightly slower than pessimistic locking due to the inevitable overhead and extra processing of maintaining workspaces, versioned data and validating on commit, it does buy you a near-SERIALIZABLE degree of data integrity while maintaining a very high level of concurrency.

10.1.3.2. Data Versioning

Optimistic locking makes use of the DataVersion interface (and an internal and default DefaultDataVersion implementation to keep a track of node versioning. In certain cases, where cached data is an in-memory representation of data from an external source such as a database, it makes sense to align the versions used in JBoss Cache with the versions used externally. As such, using the options API , it is possible to set the DataVersion you wish to use on a per-invocation basis, allowing you to implement the DataVersion interface to hold the versioning information obtained externally before putting your data into the cache.

10.1.3.3. Configuration

Optimistic locking is enabled by using the NodeLockingScheme XML attribute, and setting it to "OPTIMISTIC":

               
   ...
   <!--
   Node locking scheme:
   OPTIMISTIC
   PESSIMISTIC (default)
   -->
   <attribute name="NodeLockingScheme">OPTIMISTIC</attribute>
   ...
   
            

JBoss Cache can be configured to use and participate in JTA compliant transactions. Alternatively, if transaction support is disabled, it is equivalent to setting AutoCommit to on where modifications are potentially ^[8] replicated after every change (if replication is enabled).

What JBoss Cache does on every incoming call is:

In order to do this, the cache has to be provided with a reference to environment's javax.transaction.TransactionManager . This is usually done by configuring the cache with the class name of an implementation of the TransactionManagerLookup interface. When the cache starts, it will create an instance of this class and invoke its getTransactionManager() method, which returns a reference to the TransactionManager .

JBoss Cache ships with JBossTransactionManagerLookup and GenericTransactionManagerLookup . The JBossTransactionManagerLookup is able to bind to a running JBoss AS instance and retrieve a TransactionManager while the GenericTransactionManagerLookup is able to bind to most popular Java EE application servers and provide the same functionality. A dummy implementation - DummyTransactionManagerLookup - is also provided, primarily for unit tests. Being a dummy, this is just for demo and testing purposes and is not recommended for production use.

An alternative to configuring a TransactionManagerLookup is to programatically inject a reference to the TransactionManager into the Configuration object's RuntimeConfig element:

         TransactionManager tm = getTransactionManager(); // magic method
         cache.getConfiguration().getRuntimeConfig().setTransactionManager(tm);         
      

Injecting the TransactionManager is the recommended approach when the Configuration is built by some sort of IOC container that already has a reference to the TM.

When the transaction commits, we initiate either a one- two-phase commit protocol. See replicated caches and transactions for details.

This is what a typical XML configuration file looks like. It is recommended that you use one of the configurations shipped with the JBoss Cache distribution and tweak according to your needs rather than write one from scratch.

         
<?xml version="1.0" encoding="UTF-8"?>

<!-- ===================================================================== -->
<!--                                                                       -->
<!--  Sample JBoss Cache Service Configuration                             -->
<!--                                                                       -->
<!-- ===================================================================== -->

<server>
   
   <!-- ==================================================================== -->
   <!-- Defines JBoss Cache configuration                                      -->
   <!-- ==================================================================== -->

   <!-- Note the value of the 'code' attribute has changed since JBC 1.x -->
   <mbean code="org.jboss.cache.jmx.CacheJmxWrapper" name="jboss.cache:service=Cache">
   
      <!-- Ensure JNDI and the TransactionManager are started before the
           cache.  Only works inside JBoss AS; ignored otherwise -->
      <depends>jboss:service=Naming</depends>
      <depends>jboss:service=TransactionManager</depends>

      <!-- Configure the TransactionManager -->
      <attribute name="TransactionManagerLookupClass">
         org.jboss.cache.transaction.GenericTransactionManagerLookup
      </attribute>

      <!-- Node locking level : SERIALIZABLE
                                REPEATABLE_READ (default)
                                READ_COMMITTED
                                READ_UNCOMMITTED
                                NONE             -->
      <attribute name="IsolationLevel">REPEATABLE_READ</attribute>

      <!-- Lock parent before doing node additions/removes -->
      <attribute name="LockParentForChildInsertRemove">true</attribute>

      <!-- Valid modes are LOCAL (default)
                           REPL_ASYNC
                           REPL_SYNC
                           INVALIDATION_ASYNC
                           INVALIDATION_SYNC   -->
      <attribute name="CacheMode">REPL_ASYNC</attribute>

      <!-- Name of cluster. Needs to be the same for all JBoss Cache nodes in a
           cluster in order to find each other. 
      -->
      <attribute name="ClusterName">JBossCache-Cluster</attribute>

      <!--Uncomment next three statements to use the JGroups multiplexer.
         This configuration is dependent on the JGroups multiplexer being
         registered in an MBean server such as JBossAS.  This type of
         dependency injection only works in the AS; outside it's up to
         your code to inject a ChannelFactory if you want to use one. 
      -->
      <!--
      <depends optional-attribute-name="MultiplexerService" 
      		proxy-type="attribute">jgroups.mux:name=Multiplexer</depends>
      <attribute name="MultiplexerStack">tcp</attribute>
      -->

      <!-- JGroups protocol stack properties.
         ClusterConfig isn't used if the multiplexer is enabled above.
      -->
      <attribute name="ClusterConfig">
         <config>
            <!-- UDP: if you have a multihomed machine, set the bind_addr 
                 attribute to the appropriate NIC IP address -->
            <!-- UDP: On Windows machines, because of the media sense feature
                 being broken with multicast (even after disabling media sense)
                 set the loopback attribute to true -->
            <UDP mcast_addr="228.1.2.3" mcast_port="48866"
                 ip_ttl="64" ip_mcast="true"
                 mcast_send_buf_size="150000" mcast_recv_buf_size="80000"
                 ucast_send_buf_size="150000" ucast_recv_buf_size="80000"
                 loopback="false"/>
            <PING timeout="2000" num_initial_members="3"/>
            <MERGE2 min_interval="10000" max_interval="20000"/>
            <FD shun="true"/>
            <FD_SOCK/>
            <VERIFY_SUSPECT timeout="1500"/>
            <pbcast.NAKACK gc_lag="50" retransmit_timeout="600,1200,2400,4800"
                           max_xmit_size="8192"/>
            <UNICAST timeout="600,1200,2400",4800/>
            <pbcast.STABLE desired_avg_gossip="400000"/>
            <FC max_credits="2000000" min_threshold="0.10"/>
            <FRAG2 frag_size="8192"/>
            <pbcast.GMS join_timeout="5000" join_retry_timeout="2000"
                        shun="true" print_local_addr="true"/>
            <pbcast.STATE_TRANSFER/>
         </config>
      </attribute>
      
      <!--
          The max amount of time (in milliseconds) we wait until the
          initial state (ie. the contents of the cache) are retrieved from
          existing members in a clustered environment
      -->
      <attribute name="StateRetrievalTimeout">20000</attribute>

      <!--
          Number of milliseconds to wait until all responses for a
          synchronous call have been received.
      -->
      <attribute name="SyncReplTimeout">20000</attribute>

      <!-- Max number of milliseconds to wait for a lock acquisition -->
      <attribute name="LockAcquisitionTimeout">15000</attribute>


      <!-- Specific eviction policy configurations. This is LRU -->
      <attribute name="EvictionConfig">
         <config>
            <attribute name="wakeUpIntervalSeconds">5</attribute>
            <!-- This defaults to 200000 if not specified -->
            <attribute name="eventQueueSize">200000</attribute>
            <attribute name="policyClass">org.jboss.cache.eviction.LRUPolicy</attribute>

            <!-- Cache wide default -->
            <region name="/_default_">
               <attribute name="maxNodes">5000</attribute>
               <attribute name="timeToLiveSeconds">1000</attribute>
            </region>
            <region name="/org/jboss/data">
               <attribute name="maxNodes">5000</attribute>
               <attribute name="timeToLiveSeconds">1000</attribute>
            </region>
            <region name="/org/jboss/test/data">
               <attribute name="maxNodes">5</attribute>
               <attribute name="timeToLiveSeconds">4</attribute>
            </region>
            <region name="/test">
               <attribute name="maxNodes">10000</attribute>
               <attribute name="timeToLiveSeconds">4</attribute>
            </region>
            <region name="/maxAgeTest">
               <attribute name="maxNodes">10000</attribute>
               <attribute name="timeToLiveSeconds">8</attribute>
               <attribute name="maxAgeSeconds">10</attribute>
            </region>
         </config>
      </attribute>
   </mbean>
</server>

      

A list of definitions of each of the XML attributes used above. If the description of an attribute states that it is dynamic , that means it can be changed after the cache is created and started.

The following table describes the statistics currently available and may be collected via JMX.

The following table depicts the JMX notifications available for JBoss Cache as well as the cache events to which they correspond. These are the notifications that can be received through the CacheJmxWrapper MBean. Each notification represents a single event published by JBoss Cache and provides user data corresponding to the parameters of the event.