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