3.2. Configuring JBoss Cache

JBoss Cache provides a great many different configuration options; here we are just going to look at a few that are most relevant to the Second Level Cache use case. Please see the JBoss Cache User Guide for full details.

3.2.1. Configuring a Single Standalone Cache

To configure a single standalone cache (i.e. for use by a SharedJBossCacheRegionFactory), you need to create a standard JBoss Cache XML configuration file and place it on the classpath. See the JBoss Cache User Guide and the JBoss Cache distribution for examples of JBoss Cache configuration files.

If the resource path to your file is treecache.xml, the SharedJBossCacheRegionFactory will find it by default; otherwise you will need to use a configuration option to tell it where it is. See Section 3.1.3, “The SharedJBossCacheRegionFactory for instruction on how to do that.

3.2.2. Managing Multiple Caches via a CacheManager

If you are using MultiplexedJBossCacheRegionFactory you will need to provide a set of JBoss Cache configurations for its CacheManager to use. (Or, use the set in the jbc2-configs.xml file that ships with hibernate-jbosscache2.jar.) The XML file used by a CacheManager is very similar to the usual config file used by a standalone cache; the biggest difference is it can include multiple, named, configurations. The format looks like this:

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


    <!-- A config appropriate for entity/collection caching. -->
    <cache-config name="optimistic-entity">

        <!-- Node locking scheme -->
        <attribute name="NodeLockingScheme">OPTIMISTIC</attribute> 
        ..... other configuration attributes

    <!-- A config appropriate for entity/collection caching that
         uses pessimistic locking -->
    <cache-config name="pessimistic-entity">

        <!-- Node locking scheme -->
        <attribute name="NodeLockingScheme">PESSIMISTIC</attribute>   
        ..... other configuration attributes

Each <cache-config> element contains a complete cache configuration, with the same contents as what you would place in the <mbean> element in a standalone cache configuration file. The name attribute on the <cache-config> element provides the identifier for the configuration; users of the CacheManager will provide this name when requesting a JBoss Cache instance that uses this configuration.

3.2.3. JBoss Cache Configuration Details

Let's look at how to specify a few of the JBoss Cache configuration options that are most relevant to the Hibernate use case. CacheMode

The JBoss Cache CacheMode attribute encapsulates whether the cache uses replication, invalidation or local mode, as well as whether messages should be synchronous or asynchronous. See Section 2.2.1, “Replication vs. Invalidation vs. Local Mode” and Section 2.2.2, “Synchronous vs. Asynchronous” for a discussion of these concepts.

The CacheMode is configured as follows:

<!-- Legal modes are LOCAL
<attribute name="CacheMode">INVALIDATION_SYNC</attribute> NodeLockingScheme

The JBoss Cache NodeLockingScheme attribute configures whether optimistic locking or pessimistic locking should be used. See Section 2.2.3, “Locking Scheme” for a discussion of locking.

The NodeLockingScheme is configured as follows:

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

The JBoss Cache IsolationLevel attribute configures whether READ_COMMITTED or REPEATABLE_READ semantics are needed if pessimistic locking is used. It has no effect if optimistic locking is used. See Section 2.2.4, “Isolation Level” for a discussion of isolation levels.

The IsolationLevel is configured as follows:

<!-- Isolation level:
<attribute name="IsolationLevel">READ_COMMITTED</attribute> JGroups Channel Configuration

Each JBoss Cache instance (except those with CacheMode LOCAL) will need a JGroups Channel. The cache configuration needs to tell JGroups how to set up the channel's protocol stack. This is configured as follows:

<attribute name="MultiplexerStack">udp</attribute>

An alternate approach is to include the full protocol stack configuration in the JBoss Cache configuration:

<!-- JGroups protocol stack properties. -->
<attribute name="ClusterConfig">
      <UDP mcast_addr=""
           ... many more details
      <pbcast.FLUSH timeout="0"/>

See Section 3.3, “JGroups Configuration” for more on JGroups configuration. Initial State Transfer

See Section 2.2.5, “Initial State Transfer” for a discussion of the concept of initial state transfer.

Initial State Transfer is configured as follows:

<!-- Whether or not to fetch state on joining a cluster. -->
<attribute name="FetchInMemoryState">false</attribute> Region-Based Marshalling

JBoss Cache includes a feature called Region Based Marshalling that helps ensure the correct classloader is in place when objects are serialized and deserialized as part of replication and invalidation messages. This feature adds some overhead, but it allows your cache to work in complex classloading environments such as those found in many application servers. It can be disabled if your application meets the following criteria:

  • No cached entities use custom types (i.e. types persisted as BLOBs or CLOBs or as a Hibernate UserType) in their fields, and no entities use complex primary keys.

  • OR all custom types and complex primary key types are visible to the classloader that loads JGroups.

Region based marshalling is configured as follows:

 Whether to use marshalling or not. Default is "false".
<attribute name="UseRegionBasedMarshalling">true</attribute>
<!-- Must match the value of "UseRegionBasedMarshalling" -->
<attribute name="InactiveOnStartup">true</attribute>

Region based marshalling is enabled in the standard cache configurations that ship with hibernate-jbosscache2.jar Eviction

This topic deserves a chapter of it's own. See Chapter 4, Cache Eviction.

3.2.4. Standard JBoss Cache Configurations

Hibernate ships with a number of standard JBoss Cache configurations in the hibernate-jbosscache2.jar's jbc2-configs.xml file. The following table highlights the key features of each configuration.

Table 3.1. Standard JBoss Cache Configurations

Name Valid For Optimal For CacheMode Locking State Transfer






replicated-query Q -- LOCAL OPTIMISTIC




optimistic-shared E/C/Q/T -- REPL_SYNC OPTIMISTIC


pessimistic-shared E/C/Q/T -- REPL_SYNC PESSIMISTIC


A few notes on the above table:

  • Valid For and Optimal For describe the suitability of the configuration for the four types of data -- Entities, Collections, Queries and Timestamps.

  • State Transfer indicates whether an initial state transfer will be performed when a cache region is activated.

  • Each of the configurations uses the udp JGroups protocol stack configuration (except local-query, which doesn't use JGroups at all). Since they all use the same stack, if more than one of these caches is created they will share their JGroups resources. See Section 3.3.2, “Standard JGroups Configurations” for a description of the standard stacks.

  • The configurations that use PESSIMISTIC locking use isolation level READ_COMMITTED. There are also two other standard configurations not shown in the table that use REPEATABLE_READ: pessimistic-entity-repeatable and pessimistic-shared-repeatable. In all other respects those configurations are the same as the similarly named non- "-repeatable" configurations shown in the table.

These standard configurations are a good choice for many applications. The primary reason users may want to use their own configurations is to support more complex eviction setups. See Chapter 4, Cache Eviction for more on the kinds of things you can do with eviction.