Chapter 3. Configuration

3.1. Configuration Overview

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.

3.2. Creating a Configuration

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.

3.2.1. Parsing an XML-based Configuration File

The most convenient way to configure JBoss Cache is via an XML file. The JBoss Cache distribution ships with a number of configuration files for common use cases. It is recommended that these files be used as a starting point, and tweaked to meet specific needs.

Here is a simple example configuration file:

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

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

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

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

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

      <!-- Valid modes are LOCAL (default)
                           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">
            <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>


Another, more complete, sample XML file is included in the configuration reference section of this book, along with a handy look-up table explaining the various options.

For historical reasons, the format of the JBoss Cache configuraton file follows that of a JBoss AS Service Archive (SAR) deployment descriptor (and still can be used as such inside JBoss AS ). Because of this dual usage, you may see elements in some configuration files (such as depends or classpath ) that are not relevant outside JBoss AS. These can safely be ignored.

Here's how you tell the CacheFactory to create and start a cache by finding and parsing a configuration file on the classpath:

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

3.2.2. Programmatic Configuration

In addition to the XML-based configuration above, the Configuration can be built up programatically, using the simple property mutators exposed by Configuration and its components. When constructed, the Configuration object is preset with JBoss Cache defaults and can even be used as-is for a quick start.

Following is an example of programatically creating a Configuration configured to match the one produced by the XML example above, and then using it to create a Cache :

            Configuration config = new Configuration();
            String tmlc = GenericTransactionManagerLookup.class.getName();
            EvictionConfig ec = new EvictionConfig();
            EvictionRegionConfig erc = new EvictionRegionConfig();
            LRUConfiguration lru = new LRUConfiguration();
            List<EvictionRegionConfig> ercs = new ArrayList<EvictionRegionConfig>();
            CacheFactory factory = DefaultCacheFactory.getInstance();
            Cache cache = factory.createCache(config);         


Even the above fairly simple configuration is pretty tedious programming; hence the preferred use of XML-based configuration. However, if your application requires it, there is no reason not to use XML-based configuration for most of the attributes, and then access the Configuration object to programatically change a few items from the defaults, add an eviction region, etc.

Note that configuration values may not be changed programmatically when a cache is running, except those annotated as @Dynamic . Dynamic properties are also marked as such in the configuration reference table. Attempting to change a non-dynamic property will result in a ConfigurationException .

3.2.3. Using an IOC Framework

The Configuration class and its component parts are all Java Beans that expose all config elements via simple setters and getters. Therefore, any good IOC framework should be able to build up a Configuration from an XML file in the framework's own format. See the deployment via the JBoss micrcontainer section for an example of this.

3.3. Composition of a Configuration Object

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.

  • Configuration : top level object in the hierarchy; exposes the configuration properties listed in the configuration reference section of this book.
  • BuddyReplicationConfig : only relevant if buddy replication is used. General buddy replication configuration options. Must include a:
  • BuddyLocatorConfig : implementation-specific configuration object for the BuddyLocator implementation being used. What configuration elements are exposed depends on the needs of the BuddyLocator implementation.
  • EvictionConfig : only relevant if eviction is used. General eviction configuration options. Must include at least one:
  • EvictionRegionConfig : one for each eviction region; names the region, etc. Must include a:
  • EvictionPolicyConfig : implementation-specific configuration object for the EvictionPolicy implementation being used. What configuration elements are exposed depends on the needs of the EvictionPolicy implementation.
  • CacheLoaderConfig : only relevant if a cache loader is used. General cache loader configuration options. Must include at least one:
  • IndividualCacheLoaderConfig : implementation-specific configuration object for the CacheLoader implementation being used. What configuration elements are exposed depends on the needs of the CacheLoader implementation.
  • RuntimeConfig : exposes to cache clients certain information about the cache's runtime environment (e.g. membership in buddy replication groups if buddy replication is used.) Also allows direct injection into the cache of needed external services like a JTA TransactionManager or a JGroups ChannelFactory .

3.4. Dynamic Reconfiguration

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


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.

3.5. Overriding the Configuration Via the Option API

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();
            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"));
            node.put("localCounter", new Integer(2));


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