Version 36

    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.



    • 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.

    • JBoss Cache >= 3.0.0 and Hibernate >= 3.3.0 is your optimal configuration, using MVCC as a locking scheme on JBoss Cache.


    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 JBoss Cache participate in transactions together, in the manner they've been designed to.






    + data correctness for all caches.

    - performance and scalability

    Does not provide as much concurrency as OPTIMISTIC


    Recommended for Query and Collection caches. Query cache requires REPL to work.

    Does not provide as much concurrency as OPTIMISTIC


    Recommended for Entity Caches. Will not work correctly with Query cache.

    Does not provide as much concurrency as OPTIMISTIC


    Better throughput and scalability than INVALIDATION_SYNC at the risk of data integrity when the network is stressed and in certain high-concurrency edge cases

    Does not provide as much concurrency as OPTIMISTIC


    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.  Use MVCC if you are using JBoss Cache >= 3.0.0.

    • Hibernate 3.2 has special support for JBoss Cache optimistic locking through org.hibernate.cache.OptimisticTreeCache

    • If you are using MVCC, use org.hibernate.cache.TreeCache as your provider and make sure your cache is configured to use MVCC.


    Looking up a TreeCache instance in Hibernate


    Specify Level 2 Cache Provider or Disable It


    Newer versions of JBoss Cache

    With JBoss Cache 1.3.0 or newer, you have additional features that improve integration with Hibernate.


    • 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.


    With JBoss Cache 3.0.0 or newer, you have JBossCacheMVCC locking which deprecates both Optimistic and Pessimistic locking and should be used as a default.  It provides a very high degree of concurrency while providing all of the consistency guarantees of pessimistic locking.