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
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"?>
<cache-configs>
<!-- A config appropriate for entity/collection caching. -->
<cache-config name="optimistic-entity">
<!-- Node locking scheme -->
<attribute name="NodeLockingScheme">OPTIMISTIC</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:
OPTIMISTIC
PESSIMISTIC (default)
-->
<attribute name="NodeLockingScheme">OPTIMISTIC</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-jbosscache2.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-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 |
|---|---|---|---|---|---|
| optimistic-entity | E/C/Q | E/C/Q | INVALIDATION_SYNC | OPTIMISTIC |
no |
| pessimistic-entity | E/C/Q | E/C/Q | INVALIDATION_SYNC | PESSIMISTIC |
no |
| local-query | Q | Q | LOCAL | PESSIMISTIC |
no |
| replicated-query | Q | -- | LOCAL | OPTIMISTIC |
no |
| timestamps-cache | T | T | REPL_ASYNC | PESSIMISTIC |
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 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.