Hibernate.orgCommunity Documentation
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.
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.
Hibernate 3.5 ships with the following RegionFactory
implementations that work with JBoss Cache 3. Select the
one that is appropriate to your needs and use it with
the hibernate.cache.region.factory_class
configuration option.
org.hibernate.cache.jbc.SharedJBossCacheRegionFactory
Instantiates a single JBoss Cache instance for use with all cache data types (entities, collections, queries, timestamps).
org.hibernate.cache.jbc.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.jbc.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.jbc.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.
The SharedJBossCacheRegionFactory
supports a
number of additional configuration options:
hibernate.cache.jbc.cfg.shared
Classpath or filesystem resource containing JBoss Cache
configuration settings the underlying cache should use.
Default value is treecache.xml
.
hibernate.cache.jbc.cfg.multiplexer.stacks
Classpath or filesystem resource containing JGroups protocol
stack configurations the ChannelFactory
should use. Default is
org/hibernate/cache/jbc/builder/jgroups-stacks.xml
,
a file found in the hibernate-jbosscache.jar
.
Note that the default treecache.xml
file does
not exist; it is up to the user to provide it.
The JndiSharedJBossCacheRegionFactory
supports an
additional configuration option:
hibernate.cache.jbc.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.
The MultiplexedJBossCacheRegionFactory
supports a
number of additional configuration options:
hibernate.cache.jbc.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.jbc.cfg.multiplexer.stacks
Classpath or filesystem resource containing JGroups protocol
stack configurations the ChannelFactory
should use. Default is
org/hibernate/cache/jbc/builder/jgroups-stacks.xml
,
a file found in the hibernate-jbosscache.jar
.
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
.
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.
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.
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
.
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.
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.
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.
Let's look at how to specify a few of the JBoss Cache configuration options that are most relevant to the Hibernate use case.
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>
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>
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>
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.
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>
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
This topic deserves a chapter of it's own. See Chapter 4, Cache Eviction.
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.
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.
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.
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.
Copyright © 2009 Red Hat, Inc.