It's complex because the problem is more complex than the existing implementation could adequately address. See http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossCacheHibernateAlignment.
Biggest difference is that Hibernate now uses 4 different types of caching regions, with necessarily different semantics for each. The proper integration of each of those region types expands the number of classes in the integration.
The Hibernate READ_ONLY caching strategy is also now supported; that adds a few trivial classes.
Building the 4 region types from a single shared JBC instance is supported, as is using different JBC instances that use a single underlying multiplexed JGroups channel. That adds a few classes. Arguably the single shared JBC instance approach should be dropped; that's a better discussion for the Hibernate dev list or forums, since it's really a question of what Hibernate wants to provide.
Hibernate previously supported more Provider impls than the 2 you mentioned. There were also flavors that used a JNDI lookup instead of direct cache instantiation. Same still applies.
Thanks for the information.
Can you give me any information on what might be the consequence of using at least the old OptimisticTreeCache implementation changed to work against JBC2.0 for use with EntityManager? And can you explain how the eviction configuration might work -- or not -- with the old provider?
If you want to use a Provider impl, have a look at TreeCacheProviderHook and OptimisticTreeCacheProviderHook in the AS trunk ejb3 module, org.jboss,ejb3.entity package. Those are based on AS 4.2.0 classes that have some bug fixes in them that aren't in the Hibernate classes, particularly related to classloading issues. In AS trunk I converted them to the JBC 2.0 API. Those classes will be replaced by the new Hibernate stuff, and may have bugs, but they may save you some work.
It's been a while, but IIRC, the biggest problem with the trunk classes is timestamp caching doesn't work properly -- the JBC 2.0 putForExternalRead semantic won't work for timestamps. Timestamps need to be replicated async, so you'd need to use Option.setForceAsynchronous(true) (only in 2.1.0) to make that happen if the cache region is for the timestamps cache.
Another caveat is INVALIDATION shouldn't be used if query caching is enabled. INVALIDATION_SYNC is the best choice for entity/collection caching but is absolutely incorrect for timestamp caching. Hence the move to using different multiplexed JBC instances.
Re: eviction, let's say you've given a region prefix to your session factory of "foo" and are caching an entity of type com.foo.Bar. Query caching is enabled.
With a Provider, you'd end up with these regions in JBC:
Typically you'd set up an LRU eviction region config for /foo/com/foo/Bar and probably another for /foo/org/hibernate/cache/StandardQueryCache. What the maxNodes, timeToLiveSeconds etc should be would depend on... well the normal stuff. :-)
You should never set up an eviction region that results in eviction of data under /foo/org/hibernate/cache/UpdateTimestampsCache. This precludes just setting up a region for /foo or just using /_default_ when you are using query caching.
With the new RegionFactory approach, you'd have these JBC regions:
Typically you'd set up an LRU eviction region config for /foo/com/foo/Bar and probably another for /foo/org/hibernate/cache/StandardQueryCache -- exactly the same as with Provider. The existence of the ENTITY and COLL subtrees is an internal detail you don't need to care about -- unless you want to separately configure eviction of entities vs collections.
Note too that with RegionFactory you could just set up an eviction region for /foo and thereby cover the entities, collections and queries. I deliberately put the timestamps in their own /TS namespace to make this possible.
Thanks for the detailed explanation. Hopefully you or someone can turn some of your detailed posts into documentation for JBoss Cache's Hibernate integration. :-) Being able to understand how to configure eviction correctly is nice to know as well.
For our application, absolute correctness is not required, since most data is read-only or changes rarely, so likely we'll live with async INVALIDATION, at least until your solution ships.
Thanks for the detailed explanation. Hopefully you or someone can turn some of your detailed posts into documentation for JBoss Cache's Hibernate integration. :-)
Did I just hear a volunteer? :-)
Seriously though, the intent is to have good docs for this by Hibernate 3.3.0.GA.