Chapter 3. Configuration

Chapter 3. Configuration
Prev		Next

There are three main areas of configuration involved in using JBoss Cache 2 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.region.jbc2.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.jbc2.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.

3.1.2. Specifying the `RegionFactory` Implementation

Hibernate 3.3 ships with the following RegionFactory implementations that work with JBoss Cache 2. Select the one that is appropriate to your needs and use it with the hibernate.cache.region.factory_class configuration option.

org.hibernate.cache.jbc2.SharedJBossCacheRegionFactory: Instantiates a single JBoss Cache instance for use with all cache data types (entities, collections, queries, timestamps).
org.hibernate.cache.jbc2.JndiSharedJBossCacheRegionFactory: Uses a single JBoss Cache instance for all cache data types. However, does not instantiate the JBoss Cache instance itself; instead looks for an existing cache in JNDI. This allows sharing of a single JBoss Cache instance across multiple Hibernate session factories running in the same environment.
org.hibernate.cache.jbc2.MultiplexedJBossCacheRegionFactory: Supports using multiple JBoss Cache instances with different cache data types (entities, collections, queries, timestamps) assigned to different JBoss Cache instances. Instantiates a JBoss Cache CacheManager to manage the JBoss Cache instances.
org.hibernate.cache.jbc2.JndiMultiplexedJBossCacheRegionFactory: Functions like JndiMultiplexedJBossCacheRegionFactory, but instead of instantiating its own CacheManager it looks for an existing one in JNDI. This allows sharing of the various JBoss Cache instances across multiple Hibernate session factories running in the same environment.

3.1.3. The `SharedJBossCacheRegionFactory`

The SharedJBossCacheRegionFactory supports a number of additional configuration options:

hibernate.cache.region.jbc2.cfg.shared: Classpath or filesystem resource containing JBoss Cache configuration settings the underlying cache should use. Default value is treecache.xml.
hibernate.cache.region.jbc2.cfg.multiplexer.stacks: Classpath or filesystem resource containing JGroups protocol stack configurations the ChannelFactory should use. Default is org/hibernate/cache/jbc2/builder/jgroups-stacks.xml, a file found in the hibernate-jbosscache2.jar.

Note that the default treecache.xml file does not exist; it is up to the user to provide it.

3.1.4. The `JndiSharedJBossCacheRegionFactory`

The JndiSharedJBossCacheRegionFactory supports an additional configuration option:

hibernate.cache.region.jbc2.cfg.shared: Specifies the JNDI name under which the JBoss Cache instance to use is bound. Note that although this configuration property has the same name as the one used by SharedJBossCacheRegionFactory, the meaning here is different. Note also that in this class' usage of the property, there is no default value -- the user must specify the property.

The JndiSharedJBossCacheRegionFactory requires that the JBoss Cache instance 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 created and bound in JNDI before the Hibernate SessionFactory is created.

3.1.5. The `MultiplexedJBossCacheRegionFactory`

The MultiplexedJBossCacheRegionFactory supports a number of additional configuration options:

hibernate.cache.region.jbc2.configs: Classpath or filesystem resource containing JBoss Cache configurations the CacheManager should use. Default is org/hibernate/cache/jbc2/builder/jbc2-configs.xml, a file found in the hibernate-jbosscache2.jar.
hibernate.cache.region.jbc2.cfg.multiplexer.stacks: Classpath or filesystem resource containing JGroups protocol stack configurations the ChannelFactory should use. Default is org/hibernate/cache/jbc2/builder/jgroups-stacks.xml, a file found in the hibernate-jbosscache2.jar.
hibernate.cache.region.jbc2.cfg.entity: Name of the configuration that should be used for entity caches. Default value is optimistic-entity.
hibernate.cache.region.jbc2.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.region.jbc2.cfg.ts: Name of the configuration that should be used for timestamp caches. Default value is timestamps-cache.
hibernate.cache.region.jbc2.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.

Many of the default values name JBoss Cache configurations in the standard jbc2-configs.xml file found in the hibernate-jbosscache2.jar. See Section 3.2.4, “Standard JBoss Cache Configurations” for details on those configurations. If you want to set hibernate.cache.region.jbc2.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.jbc2.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.region.jbc2.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.region.jbc2.cfg.entity: Name of the configuration that should be used for entity caches. Default value is optimistic-entity.
hibernate.cache.region.jbc2.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.region.jbc2.cfg.ts: Name of the configuration that should be used for timestamp caches. Default value is timestamps-cache.
hibernate.cache.region.jbc2.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.region.jbc2.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.

Prev		Next
2.3. Matching JBC Behavior to Types of Data	Home	3.2. Configuring JBoss Cache