JBossCache with Hibernate

JBossCache can be used as a 2nd level cache provider for Hibernate, providing clustered, transactional caching.

This page discusses general best-practices and tips when using JBossCache with Hibernate. This is a live document and will continue to be updated.

Versions

• JBossCache versions prior to 1.2.2 are not recommended for use with Hibernate, due to deadlock issues that may arise.
• Hibernate versions prior to 3.0.2 are not recommended for use with JBossCache, for the same deadlock issues mentioned above.
• Hibernate >= 3.2 is required if you plan to use Optimistic Locking.

Recommended JBossCache configuration options

• Do not use a cache loader. Redundant, and an unnecessary overhead.
• Use an eviction policy to prevent the cache getting too large.
• Use the UserTransaction API where possible. This will ensure Hibernate and JBossCache participate in transactions together, in the manner they've been designed to.

Overall Recommendation:

• If you are only using a query cache or collection cache, use REPL_ASYNC.
• If you are only caching entities, use INVALIDATION_SYNC.
• If you are using a combination of query caching and entity caching, use REPL_SYNC.
• Always use Optimistic Locking as it improves concurrency.
• Hibernate 3.2 has special support for JBossCache optimistic locking through org.hibernate.cache.OptimisticTreeCache?

Looking up a TreeCache instance in Hibernate

• TreeCacheProvider? looks for a (hard coded) treecache.xml config file in it's classpath.
• Extend or rewrite TreeCacheProvider? to take in the config file name as a param or env variable.
• Use org.jboss.hibernate.cache.DeployedTreeCacheProvider? to look up a TreeCache deployed as an MBean in JBossAS.
• http://opensource2.atlassian.com/projects/hibernate/browse/HB-1396
• If you are using OPTIMISTIC locking, make sure you use the OptimisticTreeCacheProvider that ships with Hibernate 3.2.x and higher.

Specify Level 2 Cache Provider or Disable It

• Bug in JBoss AS 4.0.4RC1: if you don't specify level 2 cache provider, Hibernate looks for ehcache-1.1.jar, even though the documentation indicates use_second_level_cache defaults to false.
• See http://jira.jboss.com/jira/browse/JBAS-2868?page=all

Newer versions of JBoss Cache

• Invalidation instead of replication. Allows for the cache to invalidate data on remote caches rather than broadcasting updated state. Improves efficiency and scalability, reduces network load, but make sure you use INVALIDATION_SYNC since INVALIDATION_ASYNC with Hibernate may introduce inconsistencies in edge cases (See JBCACHE-806)
• Optimistic locking. Allows for greater concurrency and hence scalability.
• See hibernate-recommended-config.xml in /etc/META-INF on JBossCache's CVS tree for a sample config.
• A new TreeCacheProvider? for Hibernate that makes use of the new Options API.

Troubleshooting

• Pessimistic locking - TimeoutException errors reported indicating that write lock could not be acquired after 0ms
• Optimistic locking - DataNode version mistmatch errors reported even in non-concurrent environments

Related

• JBossCacheHibernateTransactionsStandaloneExample
• JBossHibernate
• JBossCache
• JBossCache documentation
• Hibernate docs

Other languages: