Chapter 1. Introduction

1.1. Overview

JBoss Cache is a tree-structured, clustered, transactional cache. It includes support for maintaining cache consistency across multiple cache instances running in a cluster. It integrates with JTA transaction managers, supporting transaction-scoped locking of cache elements and automatic rollback of cache changes upon transaction rollback. It supports both pessimistic and optimistic locking, with the tree-structure of the cache allowing maximum concurrency.

All of these features make JBoss Cache an excellent choice for use as a Hibernate Second Level Cache, particularly in a clustered environment. A Hibernate Session is a transaction-scoped cache of persistent data -- data accessed via the Session is cached in the Session for the duration of the current transaction, and then is cleared. A Second Level Cache is an optional cluster or JVM-level cache whose contents are maintained beyond the life of a transaction and whose contents can be shared across transactions. Use of a Second Level Cache is configured as part of the configuration of the Hibernate SessionFactory. If a Second Level Cache is enabled, caching of an instance of a particular entity class or of results of a particular query can be configured on a class-by-class, collection-by-collection and query-by-query basis. See the Hibernate Reference Documentation for more on Second Level Cache basics and how to configure entity classes, collections and queries for caching.

The JBoss Cache Second Level Cache integration supports the transactional and read only cache concurrency strategies discussed in the Hibernate Reference Documentation. It supports query caching and is, of course, cluster safe.

1.2. Requirements

1.2.1. Dependencies

Second level caching with JBoss Cache 3 requires the use of JBoss Cache 3.1.0 or later. The core JBoss Cache project is used; the related POJO Cache project/library is not needed. The following jars, included with the JBoss Cache distribution, need to be on the classpath:

jbosscache-core.jar
commons-logging.jar
jboss-common-core.jar
jgroups.jar

JBoss Cache also needs to have the classes in the javax.transaction package on the classpath, but those are already included in the Hibernate distribution.

The hibernate-jbosscache.jar that is included with the Hibernate distribution also needs to be on the classpath.

A JBoss Cache configuration file, and usually a JGroups configuration file^[1], need to be on the classpath. The hibernate-jbosscache.jar includes standard configuration files in the org.hibernate.cache.jbc.builder package. The jbc-configs.xml file is for JBoss Cache and the jgroups-stacks.xml file is for JGroups. See Section 3.2, “Configuring JBoss Cache” and Section 3.3, “JGroups Configuration” for more details on these files. Users can create their own versions and tell the SessionFactory to use them; see Section 3.1, “Configuring the Hibernate Session Factory” for details.

1.2.2. JTA Transactional Support

JBoss Cache requires integration with a JTA TransactionManager in order to meet the requirements of the second level caching use case. This means your Hibernate application must be configured to use JTA:

You must configure a hibernate.transaction.manager_lookup_class.
You must configure a hibernate.transaction.factory_class, specifying a transaction factory that supports JTA. In practice, this means org.hibernate.transaction.JTATransactionFactory if you are using JTA directly, or org.hibernate.transaction.CMTTransactionFactory if you are accessing Hibernate via a CMT session bean.
Finally, make sure hibernate.current_session_context_class is either unset (backwards compatiblity), or set to "jta".

See the Hibernate Reference Documentation for an in-depth discussion of using Hibernate with JTA

1.3. Configuration Basics

The key steps in using JBoss Cache as a second level cache are to:

Tell Hibernate in your SessionFactory configuration that you want to use JBoss Cache as your Second Level Cache implementation:
```
hibernate.cache.region.factory_class=
   org.hibernate.cache.jbc.MultiplexedJBossCacheRegionFactory
```
There are a number of values that can be provided for the hibernate.cache.region.factory_class property, depending on how you want the JBoss Cache integration to work. Based on what factory class you specify, there are additional detail configuration properties you can add to further control that factory. However, simply specifying the MultiplexedJBossCacheRegionFactory shown above provides a reasonable set of default values useful for many applications. See Section 3.1.2, “Specifying the RegionFactory Implementation” for more details.
Do not set the legacy hibernate.cache.provider_class property when using JBoss Cache 3. That is a legacy property from before Hibernate 3.3's redesign of second level caching internals. It will not work with JBoss Cache 3.
Tell Hibernate you want 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
```

See Chapter 3, Configuration for full details on configuration.