[jboss-user] [JBoss Cache] Document updated/added: "JBossCacheHibernate"

[Manik Surtani]

User development,

The document "JBossCacheHibernate", was updated Feb 22, 2010
by Manik Surtani.

To view the document, visit:
http://community.jboss.org/docs/DOC-10265#cf

Document:
--------------------------------------------------------------
h2. 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.
 
h3.  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.
* JBoss Cache >= 3.0.0 and Hibernate >= 3.3.0 is your optimal configuration, using MVCC as a locking scheme on JBoss Cache.
 
h3.  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 http://www.hibernate.org/42.html#A5 where possible.  This will ensure Hibernate and JBoss Cache participate in transactions together, in the manner they've been designed to.
 
|| +CACHE MODE+ || OPTIMISTIC LOCKING || PESSIMISTIC LOCKING ||
| REPL_SYNC | + data correctness for all caches.
- performance and scalability | Does not provide as much concurrency as OPTIMISTIC |
| REPL_ASYNC | Recommended for Query and Collection caches. Query cache requires REPL to work. | Does not provide as much concurrency as OPTIMISTIC |
| INVALIDATION_SYNC | Recommended for Entity Caches. Will not work correctly with Query cache. | Does not provide as much concurrency as OPTIMISTIC |
| INVALIDATION_ASYNC | 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 |
 
h4.  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.

 
h3.  Looking up a TreeCache instance in Hibernate
* If using JBoss Cache 1.4.x and Hibernate 3.2.x, please use one of the http://community.jboss.org/docs/DOC-12948 targeted for these libraries.
* If using JBoss Cache 2.x or 3.x and Hibernate 3.3.x, please check the corresponding Hibernate JBoss Cache guide.

 
h3.  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
 
h3.  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 http://jira.jboss.com/jira/browse/JBCACHE-806)
* http://community.jboss.org/docs/DOC-11544.  Allows for greater concurrency and hence scalability.
* See http://anoncvs.forge.jboss.com/viewrep/JBoss/JBossCache/etc/META-INF/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 http://community.jboss.org/docs/DOC-10277.
 
With JBoss Cache 3.0.0 or newer, you have http://community.jboss.org/docs/DOC-10272 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.
 
h3.  Troubleshooting
 
* Pessimistic locking - http://community.jboss.org/docs/DOC-12761
* Optimistic locking - http://community.jboss.org/docs/DOC-9505
 
 
h3.  Related
 
* http://community.jboss.org/docs/DOC-10267
* http://community.jboss.org/docs/DOC-10394
* http://community.jboss.org/docs/DOC-10242
* http://docs.jboss.com/jbcache/
* http://www.hibernate.org/5.html

--------------------------------------------------------------