Galder’s Passionate Blog

What's the point of living if you can't love or hate?

New JBoss Cache based Hibernate Second Level Cache provider

I’m really pleased to announce the 1.0.0.GA release of a new JBoss Cache 1.4 series-based implementation of Hibernate‘s 3.2 Second Level Cache provider SPI. The Second Level Cache is a Hibernate feature that allows entities, collections and queries to be cached in memory beyond the scope of a transaction, reducing the number of trips to the database. Hibernate provides an SPI for second level cache implementations; the JBoss Cache-based implementation is primarily used in clustered applications where there is a need to maintain cache consistency around the cluster.

Over the past year, Brian Stansberry, lead of JBoss AS Clustering, has been working hard first, improving the JBoss Cache-based EJB3 Entity Second Level Cache for the AS/EAP 4.2/4.3 series and secondly, writing the JBoss Cache 2.x series-based implementation of the Hibernate 3.3 Second Level Cache which will be used in AS/EAP 5.x. Along the way, with the help of Steve Ebersole, lead of Hibernate, Brian has acquired a lot of expertise in this area as shown by the “Using JBoss Cache 2 as a Hibernate Second Level Cache” guide belonging to the Hibernate 3.3 series (Note: Readers interested in this blog entry should focus their attention on the “Chapter 2 – Core Concepts” to understand the interaction between Hibernate and JBoss Cache. The rest of the guide focuses on the Hibernate 3.3 and JBoss Cache 2.x integration, and this is of little interest to EAP or AS 4.x users as these Hibernate and JBoss Cache versions are more advanced that the ones supported in the EAP/AS versions mentioned).

JBoss Portal has been a consumer of the Hibernate Second Level Cache for quite a while now but unfortunately, it hasn’t been benefiting from the work done by Brian for a couple of reasons. First, JBoss Portal is still based in Hibernate 3.2, same as AS/EAP 4.2/4.3 and secondly, the improvements done to the EJB3 Entity Second Level Cache for AS/EAP 4.2/4.3 lived within the ejb3 project in AS/EAP and therefore, were not readily usable to other projects. This is not the case any more though.

A few weeks ago, Prabhat Jha, a Senior Engineer within JBoss division at Red Hat, was doing some scalability testing for JBoss Portal in a clustered environment but he was facing some issues as you can see from this forum entry. Brian believed that JBoss Portal could benefit from the work done to improve the Hibernate – JBoss Cache integration for EJB3 Entity Second Level Cache but he was quite busy working on AS 5, so I pinged him and volunteered to help with such task.

Essentially, I took the EJB3 Entity Second Level Cache integration code, put it in a separate project and enhanced it with lessons learned by Brian during the development of the JBoss Cache-based implementation of the Hibernate 3.3 Second Level Cache. The end result is a brand new JBoss Cache-based Hibernate Second Level Cache Provider that performs and scales much better than any previous Hibernate 3.2/JBoss Cache 1.4 Second Level Cache providers by analysing what Hibernate is trying to do and using that knowledge to eliminate all but required cluster message traffic. By doing this, the lock contention and potential deadlocks arising from synchronous communication (a requirement due to the need to keep entity data in synch across different nodes) are vastly reduced.

For example, amongst the enhancements, an option called hibernate.treecache.local.puts.only, whose default value is true, has been added that makes sure any put calls on the Second Level Cache as a result of a read operation from the database are done locally which means that data read from database is not replicated to other nodes. However, if put calls on the JBoss Cache Second Level Cache instance are as a result of an update of the data in the database, the new cache provider does replicate them. The effect is intra-cluster messaging traffic is greatly reduced, and each node in the cluster only caches data being used on that node. But if data is modified on any node, all nodes are made aware of the change, ensuring stale data isn’t left in a cache.

So, how do you integrate this new cache provider into your system?

  1. Download the latest cache provider jar from JBoss’ Maven2 repository.
  2. Modify your persistence.xml or hibernate.cfg.xml and enable second level cache:

     <property name="hibernate.cache.use_second_level_cache">
  3. Configure the cache provider using one of the three options below:
    • If JBoss Cache instance is bound to JMX (i.e. when deploying within JBoss Application Server), select JmxBoundTreeCacheProvider as cache provider and add the cache’s MBean object name:

       <property name="hibernate.cache.provider_class">
       <property name="hibernate.treecache.mbean.object_name">
    • If JBoss Cache instance is bound to JNDI, select JndiBoundTreeCacheProvider as the cache provider and add the cache’s JNDI name:

       <property name="hibernate.cache.provider_class">
       <property name="hibernate.cache.jndi">
    • If running Hibernate and JBoss Cache standalone, select TreeCacheProvider as the cache provider and add the path to cache’s configuration file:

       <property name="hibernate.cache.provider_class">
       <property name="hibernate.cache.provider_configuration_file_resource_path">
  4. Lastly, configure any of the following optional properties if required:
    • hibernate.cache.region_prefix – A prefix to use for second-level cache region names. This is a very useful option when trying to segregate (quite often isolated) deployments in the Second Level Cache. Each isolated deployment would use a different region prefix.
    • hibernate.treecache.local.puts.only – Explained above.
    • hibernate.cache.use_query_cache – Boolean property that enables/disables query cache. This option is only recommended if the same queries, with the same parameters, are used over and over again. Please note that if query cache is enabled, JBoss Cache instance must be configured with REPL_SYNC cache mode. Otherwise, if query cache disabled, which is default behaviour, it is recommended that JBoss Cache instance is configured with INVALIDATION_SYNC cache mode. When cache data is updated, invalidation provides much better performance than replication because other cluster nodes only need to be notified that data is invalid rather than having to serialize the updated data and send it over to them. A full detailed explanation of this can be found in “Using JBoss Cache 2 as a Hibernate Second Level Cache” guide for Hibernate 3.3 and JBoss Cache 2.x.
    • hibernate.treecache.querycache.local.writes.only – This is a similar boolean option to local puts only except that it controls the behaviour of the put operations in the query cache region. It’s enabled by default when query cache is also enabled.

Finally, JBoss Portal will bundle this new cache provider starting from 2.6.7 and 2.7.0, whose CR1 version was released last week.

Tagged as , , , + Categorized as JBoss


  1. Prabhat, thanks for linking that back!

  2. Great job Galder!

    Good to see this integration working…finally :)

  3. thank u r information

    it very useful

  4. Am I missing something? I get ClassCastExceptions when I try to use org.jboss.hibernate.jbc.cacheprovider.TreeCacheProvider. Looking at the code, the class does not implement org.hibernate.cache.CacheProvider. It was implemented in Beta 3, but it does not implement it in 1.0.0.GA.

    Recompiling with “implements org.hibernate.cache.CacheProvider” on TreeCacheProvider *does* work..

  5. Matt, you’re indeed right. The standalone version of the cache provider is not implementing CacheProvider which stops it from being usable. I’ve created a JIRA for it:

    Thanks for the feedback!

  6. I’ve configured hibernate.cache.provider_class as org.jboss.hibernate.jbc.cacheprovider.TreeCacheProvider in a standalone application.
    Is there a way to get the reference of UnderlyingCache in my application which is instantiated by hibernate? I need this instance to find out explicitly whether an object (of hibernate entity) is available in hibernate second level cache

  7. @Deepak

    I believe that if you pass on startup, you should be able to find the underlying cache instance via JConsole or VisualVM tools.

    Once you’ve found the underlying cache instance, just call printDetails() method and that you should show the cache’s contents.


  8. Once you have JConsole open, you need to go to the MBean view and access the MBean from there.

  9. Great Job Galder, we have running it on JBoss 4.0.5.
    Is it possible to configure an hibernate Session Factory to use different 2 Cache Configurations(one for the Entity and Collections and one for Timestamps and queries as described here

  10. Galder,

    Thanks for producing this module! Could you please tell me whether requiring JTA is a constraint of this hibernate-jboss module or jbosscache3 itself?


  11. @Serge,

    Possible yeah but requires deploying Hibernate 3.3 and JBoss Cache 2.x or 3.x inside your application in an isolated way because JBoss AS 4.0.x uses different Hibernate and JBoss Cache versions.

    I haven’t done this myself so I can’t help you further but my suggestion would be to upgrade to AS 5.0.0.GA and that way you don’t have to worry about this :)

  12. @Nikita,

    You’re welcome. It’s good to see other people benefiting from this work.

    JTA is just a dependency of JBoss Cache and Hibernate that allows you to operate with these two components within the scope of a transaction. It’s actually something good :)

  13. Hi Galder,
    your guides are excellent. Is there some chance you’re going to blog about JBossCache3 integration?
    I am going to migrate to JBoss5 and am missing some references about how to configure the hibernate second level cache with the new cache implementation; do you have some links to examples or documentation? I’m a bit confused by the wiki.

  14. Hi,

    can some one help me please!

    I’m trying to configure a hibernate cache provider like this :

    hibernate-configuration xmlns=”urn:jboss:hibernate-deployer:1.0″>






    but i have an exception :

    jboss.har:service=Hibernate -> java.lang.IllegalArgumentException: No such property hibernate for bean org.jboss.hibernate.jmx.Hibernate available [statisticsServiceName, beanName, defaultSchema, defaultCatalog, sessionFactoryName, querySubstitutions, secondLevelCacheEnabled, password, version, statGenerationEnabled, maxFetchDepth, username, useStructuredCacheEntriesEnabled, datasourceName, dirty, streamsForBinaryEnabled, getGeneratedKeysEnabled, hbm2ddlAuto, minimalPutsEnabled, instance, jdbcBatchSize, jdbcScrollableResultSetEnabled, cacheRegionFactoryClass, dialect, scanForMappingsEnabled, runningSince, cacheRegionPrefix, class, cacheProviderClass, sessionFactoryRunning, batchVersionedDataEnabled, harUrl, queryCacheEnabled, sessionFactoryInterceptor, deployedCacheManagerJndiName, showSqlEnabled, reflectionOptimizationEnabled, jdbcFetchSize, listenerInjector, sqlCommentsEnabled, deployedCacheJndiName, controller]


  15. @Sanne

    Thanks very much! Glad to see it was useful for you :)

    Re: JBossCache3 & JBoss 5

    Note that you shouldn’t be using the cache provider above for this combo. There’s already a much better cache provider available. It’s all explained in the wiki Brian Stansberry, JBoss AS Clustering Lead, wrote:

  16. @SAAD

    I can’t read the XML and exception pasted. Use and add the links to a comment and I’ll have a look to them.

  17. HI,

    can somme give me an example to how configuring a :



  18. Hi :

    @ Galder Zamarreño

    link :


  19. @SAAD, you’re mixing things up. You’re running old cache providers in AS 5. As indicated to @Sanne, follow instructions

    If you need further help, go to the JBoss User Forums :)

  20. Hi Galder,

    JBOSS Tree Cache is working fine but One case i got “ClassCastException”.
    whenever anychanges in code and publish in the WAS 6.1 server iam getting that EException.

    without modifications and whenever freshly start the server that time JBOSS Cacheing working fine…….
    please help me out,


  21. @Ganitha, hard to say why you get that ClassCastException, could be classloader isolation related. I’d suggest going to the JBoss Cache User Forums (, post your issue there and see if you can get further help.

  22. For all readers, Infinispan 4.0 based Hibernate Second Level Cache provider is now out too! See

  23. very good ! giving me a great help about integration hibernate and jbosscache above 1.4.0 edition

  24. very good ! Giving me a great help about integration hibernate and jbosscache above 1.4.0 edition.

    May you provide guide about integration hibernate and jbosscache3.2.1 core edition?
    (Hibernate5.0 beta edition already included jbosscache3.2.1.)

    my email is

    Thanks a lot!

    I’m looking forward to hearing from you.

  25. very good ! Giving me a great help about integration hibernate and jbosscache above 1.4.0 edition.

    May you provide guide about integration hibernate and jbosscache3.2.1 core edition?
    (Hibernate5.0 beta edition already included jbosscache3.2.1.)

    Hibernate3.3 is shipped with TreeCachedProvider, but Hibernate 3.5 doesn’t provide the class and advocates “hibernate.cache.region.factory_class=


    my email is

    Thanks a lot!

    I’m looking forward to hearing from you.

  26. @zhangyg, If you wanna use JBoss Cache 3.2.1, I’d suggest you use Hibernate 3.5 whose beta is already available and have a read to:

  27. Removed by administrator since its irrelevant.

  28. @pm, as said above, this is not a freaking general purpouse JBoss or JBoss Cache forum, so no, I won’t help you here. I will delete your message as well.

  29. To the very least you could be nice about it

  30. @pm, Don’t take this personally. I’m simply being blunt so that this post does not become a general purpose JBoss Cache forum.

  31. No worries galder!

  32. we are using Hibernate3.1 and JBoss 4.2 . In our project we need to configure JBossCache for the Clustered Environment. Which jar files for JBoss cache configuration should i need to use. and Can u provide the configuration for JBoss cache .?

Trackbacks & Pingbacks

  1. Galder’s Passionate Blog » Blog Archive » JBoss Cache based Hibernate Cache provider 1.0.1.GA Released

    [...] JBoss Cache 1.4 series-based implementation of Hibernate’s 3.2 Second Level Cache provider SPI announced back in September. So, what’s new in this release? First of all, the standalone version of the cache provider, [...]

  2. Hibernate och 2:nd level cache på JBoss 4 - codemonkey

    [...] Bra PDF om hibernate och jboss cache (kolla en bit ned, länken “Using JBoss Cache 2 as a Hibernate Second Level Cache”) [...]

Leave a Reply

custom writing paper | writing research papers | norske spilleautomater