JBoss Cache is a tree-structured, clustered, transactional cache. It can be used in a standalone, non-clustered environment, to cache frequently accessed data in memory thereby removing data retrieval or calculation bottlenecks while providing "enterprise" features such as JTA compatibility, eviction and persistence.

JBoss Cache is also a clustered cache, and can be used in a cluster to replicate state providing a high degree of failover. A variety of replication modes are supported, including invalidation and buddy replication, and network communications can either be synchronous or asynchronous.

When used in a clustered mode, the cache is an effective mechanism of building high availability, fault tolerance and even load balancing into custom applications and frameworks. For example, the JBoss Application Server and Red Hat's Enterprise Application Platform make extensive use of JBoss Cache to cluster services such as HTTP and EJB sessions, as well as providing a distributed entity cache for JPA.

JBoss Cache can - and often is - used outside of JBoss AS, in other Java EE environments such as Spring, Tomcat, Glassfish, BEA WebLogic, IBM WebSphere, and even in standalone Java programs thanks to its minimal dependency set.

JBoss Cache requires a Java 5.0 (or newer) compatible virtual machine and set of libraries, and is developed and tested on Sun's JDK 5.0 and JDK 6.

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, as well as several optional jars for optional features.

JBoss Cache is an open source project, 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.

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. The cache organizes data into a tree structure, made up of nodes. 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.

Note that the diagram above only depicts some of the more popular API methods. 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.

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

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

   CacheFactory factory = new DefaultCacheFactory();

   Cache cache = factory.createCache();

      

In this example, we tell the CacheFactory to find and parse a configuration file on the classpath:

   CacheFactory factory = new DefaultCacheFactory();

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

      

In this example, 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 = new DefaultCacheFactory();

   Cache cache = factory.createCache("/opt/configurations/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, lets 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 a hold 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("favoriteDrink", 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("favoriteDrink");


   assertEquals(keys, peterGriffin.getKeys());


   // let's remove some data from the node

   peterGriffin.remove("favoriteDrink");


   assertNull(peterGriffin.get("favoriteDrink");


   // 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, for convenience:

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


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

   cache.put(peterGriffinFqn, "favoriteDrink", new Beer());


   assertTrue(peterGriffin.get(peterGriffinFqn, "isCartoonCharacter"));

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


   cache.remove(peterGriffinFqn, "favoriteDrink");


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


   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 Strings 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 factory methods; 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 abc = Fqn.fromString("/people/Smith/Joe/");

        

   // Here we want to use types other than String

   Fqn acctFqn = Fqn.fromElements("accounts", "NY", new Integer(12345));

     

Note that

Fqn f = Fqn.fromElements("a", "b", "c");

is the same as

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

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 network sockets and maintenance threads 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 cache mode affects behavior. See the chapter on Configuration for info on how to configure things like cache mode.

JBoss Cache provides a convenient mechanism for registering notifications on cache events.

   Object myListener = new MyCacheListener();

   cache.addCacheListener(myListener);

      

Similar methods exist for removing or querying registered listeners. See the javadocs on the Cache interface for more details.

Basically any public class can be used as a listener, provided it is annotated with the @CacheListener annotation. 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 its 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 CACHE_STARTED:

               System.out.println("Cache has started");

               break;

            case 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 cache loaders, along with advanced aspects and tuning issues, are discussed in the chapter dedicated to cache loaders.

Eviction policies are the counterpart to cache loaders. They are necessary to make sure the cache does not run out of memory and when the cache starts to fill, an eviction algorithm running in a separate thread evicts in-memory state and frees up memory. If configured with a cache loader, the state can then be retrieved from the cache loader if needed.

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"?>



<jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

            xmlns="urn:jboss:jbosscache-core:config:3.0">

</jbosscache>

   Configuration config = new Configuration();

   config.setTransactionManagerLookupClass( GenericTransactionManagerLookup.class.getName() );

   config.setIsolationLevel(IsolationLevel.READ_COMMITTED);

   config.setCacheMode(CacheMode.LOCAL);

   config.setLockAcquisitionTimeout(15000);


   CacheFactory factory = new DefaultCacheFactory();

   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.

      // first start a transaction

      cache.getInvocationContext().getOptionOverrides().setForceWriteLock(true);

      Node n = cache.getNode(Fqn.fromString("/a/b/c"));

      // make changes to the node

      // commit transaction        

   

      Node node = cache.getChild(Fqn.fromString("/a/b/c"));

      cache.getInvocationContext().getOptionOverrides().setLocalOnly(true);

      node.put("localCounter", new Integer(2));

            

The batching API, introduced in JBoss Cache 3.x, is intended as a mechanism to batch the way calls are replicated independent of JTA transactions.

This is useful when you want to batch up replication calls within a scope finer than that of any ongoing JTA transactions.

To use batching, you need to enable invocation batching in your cache configuration, either on the Configuration object:

   Configuration.setInvocationBatchingEnabled(true);

      

or in your XML file:

   <invocationBatching enabled="true"/>

      

By default, invocation batching is disabled. Note that you do not have to have a transaction manager defined to use batching.

Once you have configured your cache to use batching, you use it by calling startBatch() and endBatch() on Cache. E.g.,

   Cache cache = getCache();


   // not using a batch

   cache.put("/a", "key", "value"); // will replicate immediately


   // using a batch

   cache.startBatch();

   cache.put("/a", "key", "value");

   cache.put("/b", "key", "value");

   cache.put("/c", "key", "value");

   cache.endBatch(true); // This will now replicate the modifications since the batch was started.


   cache.startBatch();

   cache.put("/a", "key", "value");

   cache.put("/b", "key", "value");

   cache.put("/c", "key", "value");

   cache.endBatch(false); // This will "discard" changes made in the batch


      

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.

After creation, you could share your cache instance among different application components either by using an IOC container such as Spring, JBoss Microcontainer, etc., or by binding it to JNDI, or simply holding a static reference to the cache.

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

Beginning with AS 5, JBoss AS 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.

For each configurable option exposed by the Configuration components, a getter/setter must be defined in the configuration class. This is required so that JBoss Microcontainer can, in typical IOC way, call these methods when the corresponding properties have been configured.

You need to ensure that the jbosscache-core.jar and jgroups.jar libraries are in your server's lib directory. This is usually the case when you use JBoss AS in its all configuration. Note that you will have to bring in any optional jars you require, such as jdbm.jar based on your cache configuration.

The following is an example -beans.xml file. If you look in the server/all/deploy directory of a JBoss 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 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>

        

      <property name="isolationLevel">REPEATABLE_READ</property>



      <property name="cacheMode">REPL_SYNC</property>



      <property name="stateRetrievalTimeout">15000</property>



      <property name="syncReplTimeout">20000</property>



      <property name="lockAcquisitionTimeout">15000</property>

        

      <property name="exposeManagementStatistics">true</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.Cache">

      

      <constructor factoryMethod="createCache">

          <factory bean="DefaultCacheFactory"/>

          <parameter class="org.jboss.cache.config.Configuration"><inject bean="ExampleCacheConfig"/></parameter>

          <parameter class="boolean">false</parameter>

      </constructor>

          

   </bean>



</deployment>      

See the JBoss Microcontainer documentation for details on the above syntax. Basically, each bean element represents an object and is used to create a Configuration and its constituent parts The DefaultCacheFactory bean constructs the cache, conceptually doing the same thing as is shown in the User API chapter.

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 already been described.

This feature is not available as of the time of this writing. 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 = new DefaultCacheFactory();

   // Build but don't start the cache

   // (although it would work OK if we started it)

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


   MBeanServer server = getMBeanServer(); // however you do it

   ObjectName on = new ObjectName("jboss.cache:service=Cache");

   

   JmxRegistrationManager jmxManager = new JmxRegistrationManager(server, cache, on);

   jmxManager.registerAllMBeans();


   ... use the cache


   ... on application shutdown


   jmxManager.unregisterAllMBeans();

   cache.stop();


            

   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</parameter>

      </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());

         }

      }

   }

         

Within a major version, releases of JBoss Cache are meant to be compatible and interoperable. Compatible in the sense that it should be possible to upgrade an application from one version to another by simply replacing jars. Interoperable in the sense that if two different versions of JBoss Cache are used in the same cluster, they should be able to exchange replication and state transfer messages. Note however that interoperability requires use of the same JGroups version in all nodes in the cluster. In most cases, the version of JGroups used by a version of JBoss Cache can be upgraded.

As such, JBoss Cache 2.x.x is not API or binary compatible with prior 1.x.x versions. On the other hand, JBoss Cache 2.1.x will be API and binary compatible with 2.0.x.

We have made best efforts, however, to keep JBoss Cache 3.x both binary and API compatible with 2.x. Still, it is recommended that client code is updated not to use deprecated methods, classes and configuration files.

A configuration parameter, Configuration.setReplicationVersion(), is available and is used to control the wire format of inter-cache communications. They can be wound back from more efficient and newer protocols to "compatible" versions when talking to older releases. This mechanism allows us to improve JBoss Cache by using more efficient wire formats while still providing a means to preserve interoperability.

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