Chapter 3. Configuration

There are three main areas of configuration involved in using JBoss Cache 3 for your Hibernate Second Level Cache: configuring the Hibernate SessionFactory, configuring the underlying JBoss Cache instance(s), and configuring the JGroups ChannelFactory. If you use the standard JBoss Cache and JGroups configurations that ship with the hibernate-jbosscache2.jar, then all you need to worry about is the SessionFactory configuration.

3.1. Configuring the Hibernate Session Factory

3.1.1. Basics

There are five basic steps to configuring the SessionFactory:

Make sure your Hibernate is configured to use JTA transactions. See Section 1.2.2, “JTA Transactional Support” for details.
Tell Hibernate you whether to enable caching of entities and collections. No need to set this property if you don't:
```
hibernate.cache.use_second_level_cache=true
```
Tell Hibernate you want to enable caching of query results. No need to set this property if you don't:
```
hibernate.cache.use_query_cache=true
```
If you have enabled caching of query results, tell Hibernate if you want to suppress costly replication of those results around the cluster. No need to set this property if you want query results replicated:
```
hibernate.cache.jbc.query.localonly=true
```
Finally, you need to tell Hibernate what RegionFactory implementation to use to manage your caches. You do this by setting the hibernate.cache.region.factory_class configuration option.
```
hibernate.cache.region.factory_class=
   org.hibernate.cache.jbc.MultiplexedJBossCacheRegionFactory
```
To determine the correct factory class, you must decide whether you need just one underlying JBoss Cache instance to support the different types of caching you will be doing, or whether you need more than one. See Chapter 2, Core Concepts and particularly Section 2.3.4, “Bringing It All Together” for more on how to make that decision. Once you know the answer, see Section 3.1.2, “Specifying the RegionFactory Implementation” to find the factory class that best meets your needs.
Once you've specified your factory class, there may be other factory-class-specific configurations you may want to set. The available options are explained below.

Many of the default values name JBoss Cache configurations in the standard jbc-configs.xml file found in the hibernate-jbosscache.jar. See Section 3.2.4, “Standard JBoss Cache Configurations” for details on those configurations. If you want to set hibernate.cache.jbc.configs and use your own JBoss Cache configuration file, you can still take advantage of these default names; just name the configurations in your file to match.

This is all looks a bit complex, so let's show what happens if you just configure the defaults, with query caching enabled:

hibernate.cache.use_second_level_cache=true
hibernate.cache.use_query_cache=true
hibernate.cache.region.factory_class=
   org.hibernate.cache.jbc.MultiplexedJBossCacheRegionFactory

You would end up using two JBoss Cache instances:

One, for the entities, collection and queries, would use the optimistic-entity configuration. This cache would use optimistic locking, synchronous invalidation and would disable initial state transfer.
The second, for timestamps, would use the timestamps-cache configuration. This cache would use pessimistic locking, asynchronous replication and would enable initial state transfer.

See Section 3.2.4, “Standard JBoss Cache Configurations” for more on these standard cache configurations.

If you hadn't set hibernate.cache.use_query_cache=true you'd just have the single optimistic-entity cache, shared by the entities and collections.

3.1.6. The `JndiMultiplexedJBossCacheRegionFactory`

The JndiMultiplexedJBossCacheRegionFactory supports the following additional configuration options:

hibernate.cache.jbc.cachefactory: Specifies the JNDI name under which the CacheManager to use is bound. There is no default value -- the user must specify the property.
hibernate.cache.jbc.cfg.entity: Name of the configuration that should be used for entity caches. Default value is mvcc-entity.
hibernate.cache.jbc.cfg.collection: Name of the configuration that should be used for collection caches. No default value, as by default we try to use the same JBoss Cache instance that is used for entity caching.
hibernate.cache.jbc.cfg.timestamps: Name of the configuration that should be used for timestamp caches. Default value is timestamps-cache.
hibernate.cache.jbc.cfg.query: Name of the configuration that should be used for query caches. By default, tries to use the same cache as is used for entity caching. If there is no entity cache, the default value is local-query.

See Section 3.1.5, “The MultiplexedJBossCacheRegionFactory” for a discussion of how the various hibernate.cache.jbc.cfg options combine to determine what JBoss Cache instances are used.

The JndiMultiplexedJBossCacheRegionFactory requires that the JBoss Cache CacheManager is already bound in JNDI; it will not create and bind one if it isn't. It is up to the the user to ensure the cache is CacheManager and bound in JNDI before the Hibernate SessionFactory is created.

3.1.7. Legacy Configuration Properties

A number of the configuration properties discussed above have changed their name from Hibernate 3.3 to Hibernate 3.5. However, to aid users moving applications from 3.3 to 3.5, the legacy property names are still supported. The legacy property names are:

hibernate.cache.region.jbc2.query.localonly
hibernate.cache.region.jbc2.cfg.shared
hibernate.cache.region.jbc2.cfg.multiplexer.stacks
hibernate.cache.region.jbc2.configs
hibernate.cache.region.jbc2.cfg.entity
hibernate.cache.region.jbc2.cfg.collection
hibernate.cache.region.jbc2.cfg.query
hibernate.cache.region.jbc2.cfg.ts

To understand the meaning of these legacy properties, just change .region.jbc2 to .jbc and see the documentation above. The only exception to that is hibernate.cache.region.jbc2.cfg.ts has been changed to hibernate.cache.jbc.cfg.timestamps.

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 jbc-configs.xml file that ships with hibernate-jbosscache.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"?>

<cache-configs>

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

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


    <!-- 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
        
    </cache-config>
    
</cache-configs>

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.

3.2.3.1. 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
                     REPL_ASYNC
                     REPL_SYNC
                     INVALIDATION_ASYNC
                     INVALIDATION_SYNC
-->
<attribute name="CacheMode">INVALIDATION_SYNC</attribute>

3.2.3.2. 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:
        MVCC
        PESSIMISTIC (default)
-->
<attribute name="NodeLockingScheme">MVCC</attribute>

3.2.3.3. 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:
        READ_COMMITTED
        REPEATABLE_READ
-->
<attribute name="IsolationLevel">READ_COMMITTED</attribute>

3.2.3.4. 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">
   <config>
      <UDP mcast_addr="228.10.10.10"
           mcast_port="45588"
           tos="8"  
           
           ... many more details
           
      <pbcast.STATE_TRANSFER/>
      <pbcast.FLUSH timeout="0"/>
   </config>
</attribute>

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

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

3.2.3.6. 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-jbosscache.jar

3.2.3.7. 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-jbosscache.jar's jbc-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
mvcc-entity	E/C/Q	E/C/Q	INVALIDATION_SYNC	MVCC	no
optimistic-entity	E/C/Q	--	INVALIDATION_SYNC	OPTIMISTIC	no
pessimistic-entity	E/C/Q	--	INVALIDATION_SYNC	PESSIMISTIC	no
local-query	Q	Q	LOCAL	MVCC	no
replicated-query	Q	--	LOCAL	MVCC	no
timestamps-cache	T	T	REPL_ASYNC	MVCC	yes
mvcc-shared	E/C/Q/T	--	REPL_SYNC	MVCC	yes
optimistic-shared	E/C/Q/T	--	REPL_SYNC	OPTIMISTIC	yes
pessimistic-shared	E/C/Q/T	--	REPL_SYNC	PESSIMISTIC	yes

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 MVCC or PESSIMISTIC locking use isolation level READ_COMMITTED. There are also four other standard configurations not shown in the table that use REPEATABLE_READ: mvcc-entity-repeatable, mvcc-shared-repeatable, 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.

3.3. JGroups Configuration

JGroups configuration is a complex area that goes well beyond the scope of this document. Users interested in exploring the details are encouraged to visit the JGroups website at http://www.jgroups.org as well as the JGroups wiki page at jboss.com.

The jgroups-stacks.xml file found in the org.hibernate.cache.jbc.builder package in the hibernate-jbosscache.jar provides a good set of standard JGroups configurations; these should be suitable for most needs. If you need to create your own configuration set, we recommend that you start with this file as a base.

3.3.1. Transport -- UDP vs. TCP

The JGroups transport refers to the mechanism JGroups uses for sending messages to the group members. Choosing which transport to use is the main JGroups-related decision users will need to make. There are three transport types:

UDP -- uses UDP multicast for transmitting messages to all members of the group. Multicast is efficient for the Second Level Cache use case, particularly with larger clusters, since maintaining cache consistency means many messages need to be sent to all members. UDP-based channel configurations are used in the JBoss Cache configurations in the standard jbc-configs.xml file that ships with Hibernate.
TCP -- uses multiple TCP unicasts for transmitting messages to all members of the group. Less efficient for the Second Level Cache use case, particularly as clusters get larger, i.e. over 4 to 6 nodes. However, in some network environments UDP multicast is not an option, in which case TCP is available.
If a TCP-based channel is used, there are a couple of options available for how a channel "discovers" the other members in the group when it first starts.
- TCP + TCPPING -- here a static list of all the possible nodes in the cluster must be provided. The TCPPING "discovery" protocol uses that static list to probe for available peers, using TCP messages. The downside here is the need to provide and maintain the static list. The upside, for multicast-averse environments, is all communication uses TCP.
- TCP + MPING -- here the MPING "discovery" protocol uses UDP multicast to probe for available peers; once they are detected all regular message traffic uses TCP. The downside here, for the multicast-averse, is that multicast is used. The upside is there is no need for a static configuration of all possible peers.
The TCP-based configurations in the jgroups-stacks.xml file found in hibernate-jbosscache.jar all use TCP + MPING. This is because there is no way for the Hibernate authors to provide a meaningful static configuration for TCPPING. If you want to use TCP + TCPPING you will need to provide your own JGroups configuration file.
TUNNEL -- a specialized protocol designed for cases where cluster members need to communicate across firewalls. See the JGroups documentation for details.

3.3.2. Standard JGroups Configurations

By default the Second Level Cache will use JGroups configurations found in the jgroups-stacks.xml file included in hibernate-jbosscache2.jar. Following are their names and a brief description of each:

udp: UDP multicast-based config; appropriate for all cache types. Includes JGroups flow control (FC) which is needed for caches that send significant numbers of asynchronous messages (i.e. timestamp caches and entity/collection caches configured for replication instead of invalidation). If you're not sure and want to use UDP multicast, this is the best choice.
udp-sync: UDP multicast-based config that omits JGroups flow control (FC). Optimal for caches that send little or no asynchronous messages, i.e. entity/collection caches configured for invalidation. Unsuitable for timestamp caches or entity/collection caches configured for replication.
tcp: TCP-based config with UDP multicast discovery (MPING). Includes JGroups flow control (FC); see udp above for the significance of that.
tcp-sync: TCP-based config with UDP multicast discovery (MPING). Omits JGroups flow control (FC); see udp-sync above for the significance of that.
tunnel: Uses a specialized protocol designed for cases where cluster members need to communicate across firewalls. See the JGroups documentation for details.