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 = new DefaultCacheFactory();

   Cache cache = factory.createCache();

      

Here 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");

      

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 = new DefaultCacheFactory();

   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. Marginally 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.

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 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 = new DefaultCacheFactory();

   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 = 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.

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.