HIBERNATE - Relational Persistence for Idiomatic Java

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

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-jbosscache2.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-jbosscache2.jar includes standard configuration files in the org.hibernate.cache.jbc2.builder package. The jbc2-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.

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:

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

Entities are the most common type of data cached in the second level cache. Entity caching requires the following semantics in a clustered cache:

Collection caching refers to the case where a cached entity has as one of its fields a collection of other entities. Hibernate handles this field specially in the second level cache; a special area in the cache is created where the primary keys of the entities in the collection are stored.

The management of collection caching is very similar to entity caching, with a few differences:

In essence, for collections Hibernate only supports cache reads and the put operation, with any modification of the collection resulting in cluster-wide invalidation of that collection from the cache. If the collection field is accessed again, a new read from the database will be done, followed by another cache put.

Hibernate supports caching of query results in the second level cache. The HQL statement that comprised the query is cached (including any parameter values) along with the primary keys of all entities that comprise the result set.

The semantics of query caching are significantly different from those of entity caching. A database row that reflects an entity's state can be locked, with cache updates applied with that lock in place. The semantics of entity caching take advantage of this fact to help ensure cache consistency across the cluster. There is no clear database analogue to a query result set that can be efficiently locked to ensure consistency in the cache. As a result, the fail-fast semantics used with the entity caching put operation are not available; instead query caching has semantics akin to an entity insert, including costly synchronous cluster updates and the JBoss Cache two phase commit protocol. Furthermore, Hibernate must agressively invalidate query results from the cache any time any instance of one of the entity classes involved in the query's WHERE clause changes. All such query results are invalidated, even if the change made to the entity instance would not have affected the query result. It is not performant for Hibernate to try to determine if the entity change would have affected the query result, so the safe choice is to invalidate the query. See Section 2.1.4, “Timestamps” for more on query invalidation.

The effect of all this is that query caching is less likely to provide a performance boost than entity/collection caching. Use it with care and benchmark your application with it enabled and disabled. Be careful about replicating query results; caching them locally only on the node that executed the query will be more performant unless the query is quite expensive, is very likely to be repeated on other nodes, and is unlikely to be invalidated out of the cache.^[2].

The JBoss Cache-based implementation of query caching adds a couple of interesting semantics, both designed to ensure that query cache operations don't block transactions from proceeding:

Timestamp caching is an internal detail of query caching. As part of each query result, Hibernate stores the timestamp of when the query was executed. There is also a special area in the cache (the timestamps cache) where, for each entity class, the timestamp of the last update to any instance of that class is stored. When a query result is read from the cache, its timestamp is compared to the timestamps of all entities involved in the query. If any entity has a later timestamp, the cached result is discarded and a new query against the database is executed.

The semantics of of the timestamp cache are quite different from those of the entity, collection and query caches.

JBoss Cache provides three different choices for how a node in the cluster should interact with the rest of the cluster when its local state is updated:

In JBoss Cache terms, synchronous vs. asynchronous refers to whether a thread that initiates a cluster-wide message blocks until that message has been received, processed and acknowledged by the other members of the cluster. Synchronous means the thread blocks; asynchronous means the message is sent and the thread immediately returns; more of a "fire and forget". An example of a message would be a set of cache inserts, updates and removes sent out to the cluster as part of a transaction commit.

In almost all cases, the cache should be configured to use synchronous messages, as these are the only way to ensure data consistency across the cluster. JBoss Cache supports programatically overriding the default configured behavior on a per-call basis, so for the special cases where sending a message asynchronously is appropriate, the Hibernate/JBoss Cache integration code will force the call to go asynchronously. So, configure your caches to use synchronous messages.

JBoss Cache supports both optimistic and pessimistic locking schemes. See the JBoss Cache User Guide for an in depth discussion of these options. In the Second Level Cache use case, the main benefit of optimistic locking is that updates of cached entities by one transaction do not block reads of the cached entity by other transactions, yet REPEATABLE_READ semantics are preserved.

If you are using optimistic locking and data versioning in Hibernate for your entities, you should use it in the entity cache as well. If you are not using data versioning, pessimistic locking should be a better choice. Optimistic locking has a higher level of runtime overhead than pessimistic locking, and in most Second Level Cache use cases a REPEATABLE_READ semantic from the cache is not required (see Section 2.2.4, “Isolation Level” for details on why not).

If the PESSIMISTIC node locking scheme is used, JBoss Cache supports a number of different isolation level configurations that specify how different transactions coordinate the locking of nodes in the cache. These are somewhat analogous to database isolation levels; see the JBoss Cache User Guide for an in depth discussion of these options. For the Second Level Cache use case, only two are valid: READ_COMMITTED and REPEATABLE_READ. In both cases, cache reads do not block for other reads. In both cases a transaction that writes to a node in the cache tree will hold an exclusive lock on that node until the transaction commits, causing other transactions that wish to read the node to block. In the REPEATABLE_READ case, the read lock held by an uncommitted transaction that has read a node will cause another transaction wishing to write to that node to block until the read transaction commits. This ensures the reader transaction can read the node again and get the same results, i.e. have a repeatable read.

READ_COMMITTED allows the greatest concurrency, since reads don't block each other and also don't block a write.

If the OPTIMISTIC node locking scheme is used, any isolation level configuration is ignored by the cache. Optimistic locking provides a repeatable read semantic but does not cause writes to block for reads.

In most cases, a REPEATABLE_READ setting on the cache is not needed, even if the application wants repeatable read semantics. This is because the Second Level Cache is just that -- a secondary cache. The primary cache for an entity or collection is the Hibernate Session object itself. Once an entity or collection is read from the second level cache, it is cached in the Session for the life of the transaction. Subsequent reads of that entity/collection will be resolved from the Session cache itself -- there will be no repeated read of the Second Level Cache by that transaction. So, there is no benefit to a REPEATABLE_READ configuration in the Second Level Cache.

The only exception to this is if the application uses Session's evict() or clear() methods to remove data from the Session cache and during the course of the same transaction wants to read that same data again with a repeatable read semantic.

Note that for query and timestamp caches, the behavior of the Hibernate/JBC integration will not allow repeatable read semantics even if JBC is configured for REPEATABLE_READ. A cache read will not result in a read lock in the cache being held for the life of the transaction. So, for these caches there is no benefit to a REPEATABLE_READ configuration.

When a new node joins a running cluster, it can request from an existing member a copy of that member's current cache contents. This process is known as an initial state transfer. Doing an initial state transfer allows the new member to have a "hot cache"; i.e. as user requests come in, data will already be cached, helping avoid an initial set of reads from the database.

However, doing an initial state transfer comes at a cost. The node providing the state needs to lock its entire tree, serialize it and send it over the network. This could be a large amount of data and the transfer could take a considerable period of time to process. While the transfer is ongoing, the state provider is holding locks on its cache, preventing any local or replicated updates from proceeeding. All work around the cache can come to a halt for a period.

Because of this cost, we generally recommend avoiding initial state transfers in the second level cache use case. The exception to this is the timestamps cache. For the timestamps cache, an initial state transfer is required.

Eviction refers to the process by which old, relatively unused, or excessively voluminous data can be dropped from the cache, allowing the cache to remain within a memory budget. Generally, applications that use the Second Level Cache should configure eviction. See Chapter 4, Cache Eviction for details.

Buddy replication refers to a JBoss Cache feature whereby each node in the cluster replicates its cached data to a limited number (often one) of "buddies" rather than to all nodes in the cluster. Buddy replication should not be used in a Second Level Cache. It is intended for use cases where one node in the cluster "owns" some data , and just wants to make a backup copy of the data to provide high availability. The data (e.g. a web session) is never meant to be accessed simultaneously on two different nodes in the cluster. Second Level Cache data does not meet this "ownership" criteria; entities are meant to be simultaneously usable by all nodes in the cluster.

Cache Loading refers to a JBoss Cache feature whereby cached data can be persisted to disk. The persisted data either serves as a highly available copy of the data in case of a cluster restart, or as an overflow area for when the amount of cached data exceeds an application's memory budget. Cache loading should not be used in a Second Level Cache. The underlying database from which the cached data comes already serves the same functions; adding a cache loader to the mix is just wasteful.

As mentioned previously, Hibernate 3.3 introduced the RegionFactory API as its mechanism for managing the Second Level Cache. This API makes it possible for implementations to know at all times whether they are working with entities, collections, queries or timestamps. That knowledge allows the Hibernate/JBoss Cache integration layer to make the best use of the various options JBoss Cache provides.

A Hibernate user doesn't need to understand the RegionFactory API in any detail at all; the main point is internally it makes possible independent management of the different cache types.

The CacheManager API is a new feature of JBoss Cache 2.1. It provides an API for managing multiple distinct JBoss Cache instances in the same VM. Basically a CacheManager is instantiated and provided a set of named cache configurations. An application like the Hibernate/JBoss Cache integration layer accesses the CacheManager and asks for a cache configured with a particular named configuration.

Again,a Hibernate user doesn't need to understand the CacheManager; it's an internal detail. The thing to understand is that the task of a Hibernate Second Level Cache user is to:

See Chapter 3, Configuration for more on how to do this.

JGroups is the group communication library JBoss Cache uses to send messages around a cluster. Each cache has a JGroups Channel; different channels around the cluster that have the same name and compatible configurations detect each other and form a group for message transmission.

A Channel is a fairly heavy object, typically using a good number of threads, several sockets and some good sized network I/O buffers. Creating multiple different channels in the same VM was therefore costly, and was an administrative burden as well, since each channel would need separate configuration to use different network addresses or ports. Architecturally, this mitigated against having multiple JBoss Cache instances in an application, since each would need its own Channel.

Added in JGroups 2.5 and much improved in the JGroups 2.6 series is the concept of sharable JGroups resources. Basically, the heavyweight JGroups elements can be shared. An application (e.g. the Hibernate/JBoss Cache integration layer) uses a JGroups ChannelFactory. The ChannelFactory is provided with a set of named channel configurations. When a Channel is needed (e.g. by a JBoss Cache instance), the application asks the ChannelFactory for the channel by name. If different callers ask for a channel with the same name, the ChannelFactory ensures that they get channels that share resources.

The effect of all this is that if a user wants to use four separate JBoss Cache instances, one for entity caching, one for collection caching, one for query caching and one for timestamp caching, those four caches can all share the same underlying JGroups resources.

The task of a Hibernate Second Level Cache user is to:

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

So, we've seen that Hibernate caches up to four different types of data (entities, collections, queries and timestamps) and that Hibernate 3.3 + JBoss Cache 2 gives you the flexibility to use a separate underlying JBoss Cache, with different behavior, for each type. You can actually deploy four separate caches, one for each type.

In practice, four separate caches are unnecessary. For example, entities and collection caching have similar enough semantics that there is no reason not to share a JBoss Cache instance between them. The queries can usually use the same cache as well. Similarly, queries and timestamps can share a JBoss Cache instance configured for replication, with the hibernate.cache.region.jbc2.query.localonly=true configuration letting you turn off replication for the queries if you want to.

Here's a decision tree you can follow:

Once you've made these decisions, you know whether you need just one underlying JBoss Cache instance, or more than one. Next we'll see how to actually configure the setup you've selected.

There are five basic steps to configuring the SessionFactory:

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.

The SharedJBossCacheRegionFactory supports a number of additional configuration options:

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:

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:

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:

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:

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.

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.

<!-- Legal modes are LOCAL
                     REPL_ASYNC
                     REPL_SYNC
                     INVALIDATION_ASYNC
                     INVALIDATION_SYNC
-->
<attribute name="CacheMode">INVALIDATION_SYNC</attribute>

<!-- Node locking scheme:
        OPTIMISTIC
        PESSIMISTIC (default)
-->
<attribute name="NodeLockingScheme">OPTIMISTIC</attribute>

<!-- Isolation level:
        READ_COMMITTED
        REPEATABLE_READ
-->
<attribute name="IsolationLevel">READ_COMMITTED</attribute>

<attribute name="MultiplexerStack">udp</attribute>

<!-- 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>

<!-- Whether or not to fetch state on joining a cluster. -->
<attribute name="FetchInMemoryState">false</attribute>

<!--
 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>

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.

A few notes on the above 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.

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:

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:

The JBoss Cache eviction process is fairly straightforward. Whenever a node in a cache read or written to, added or removed, the cache finds the eviction region (see below) that contains the node and passes an eviction event object to the eviction policy (see below) associated with the region. The eviction policy uses the stream of events it receives to track activity in the region. Periodically, a background thread runs and contacts each region's eviction policy. The policy uses its knowledge of the activity in the region, along with any configuration it was provided at startup, to determine which if any cache nodes should be evicted from memory. It then tells the cache to evict those nodes. Evicting a node means dropping it from the cache's in-memory state. The eviction only occurs on that cache instance; there is no cluster-wide eviction.

An important point to understand is that eviction proceeds independently on each peer in the cluster, with what gets evicted depending on the activity on that peer. There is no "global eviction" where JBoss Cache removes a piece of data in every peer in the cluster in order to keep memory usage inside a budget. The Hibernate/JBC integration layer may remove some data globally, but that isn't done for the kind of memory management reasons we're discussing in this chapter.

An effect of this is that even if a cache is configured for replication, if eviction is enabled the contents of a cache will be different between peers in the cluster; some may have evicted some data, while others will have evicted different data. What gets evicted is driven by what data is accessed by users on each peer.

Controlling when data is evicted from the cache is a matter of setting up appropriate eviction regions and configuring appropriate eviction policies for each region.

JBoss Cache stores its data in a set of nodes organized in a tree structure. An eviction region is a just a portion of the tree to which an eviction policy has been assigned. The name of the region is the FQN of the topmost node in that portion of the tree. An eviction configuration always needs to include a special region named _default_; this region is rooted in the root node of the tree and includes all nodes not covered by other regions.

It's possible to define regions that overlap. In other words, one region can be defined for /a/b/c, and another defined for /a/b/c/d (which is just the d subtree of the /a/b/c sub-tree). The algorithm that assigns eviction events to eviction regions handles scenarios like this consistently by always choosing the first region it encounters. So, if the algorithm needed to decide how to handle an event affecting /a/b/c/d/e, it would start from there and work its way up the tree until it hits the first defined region - in this case /a/b/c/d.

An Eviction Policy is a class that knows how to handle eviction events to track the activity in its region. It may have a specialized set of configuration properties that give it rules for when a particular node in the region should be evicted. It can then use that configuration and its knowledge of activity in the region to to determine what nodes to evict.

JBoss Cache ships with a number of eviction policies. See the JBoss Cache User Guide for a discussion of all of them. Here we are going to focus on just two.

All FQNs in a second level cache include two elements:

The FQN for the cache region where entities of a particular class are stored is derived as follows:

/ + Region Prefix + / + Region Name + /ENTITY

If no region prefix was specified, the leading / and Region Prefix is not included in the FQN. So, if hibernate.cache.region_prefix was set to "appA" and a class was mapped like this:

<class name="org.example.Foo">
    <cache usage="transactional" region="foo_region"/>
    ....
</class>

The FQN of the region where Foo entities would be cached is /appA/foo_region/ENTITY.

If the class mapping does not include a region attribute, the region name is based on the name of the entity class, e.g.

<class name="org.example.Bar">
    <cache usage="transactional"/>
    ....
</class>

the FQN of the region where Bar entities would be cached is /appA/org/example/Bar/ENTITY.

The FQN for the cache region where entities of a particular class is stored is derived as follows:

/ + Region Prefix + / + Region Name + /COLL

So, let's say our example Foo entity included a collection field bars that we wanted to cache:

<class name="org.example.Foo">
    <cache usage="transactional"/>
    ....
    <set name="bars">
        <cache usage="transactional" region="foo_region"/>
        <key column="FOO_ID"/>
        <one-to-many class="org.example.Bar"/>
    </set>
</class>

The FQN of the region where the collection would be cached would be /appA/foo_region/COLL.

If the collection's <cache> element did not include a region, the FQN would be /appA/org/example/Foo/COLL.

Queries follow this pattern:

/ + Region Prefix + / + Region Name + /QUERY

Say we had the following query (again with a region prefix set to "appA"):

List blogs = sess.createQuery("from Blog blog " + 
                              "where blog.blogger = :blogger")
    .setEntity("blogger", blogger)
    .setMaxResults(15)
    .setCacheable(true)
    .setCacheRegion("frontpages")
    .list();

The FQN of the region where this query's results would be cached would be /appA/frontpages/QUERY.

If the call to setCacheRegion("frontpages") were ommitted, the Region Name portion of the FQN would be based on a Hibernate class: /appA/org/hibernate/cache/StandardQueryCache/QUERY

Timestamps follow this pattern:

/TS/ + Region Prefix + /org/hibernate/cache/UpdateTimestampsCache

again with a / and the Region Prefix portion omitted if no region prefix was set.

Note that in the timestamps case the special constant ("TS") comes at the start of the FQN rather than the end. This makes it easier to ensure that eviction is never enabled for the timestamps region.