Version 4
Created by galder.zamarreno on Nov 14, 2008 9:04 AM. Last modified by galder.zamarreno on Nov 17, 2008 9:15 AM.

    As indicated in this blog entry, a new JBoss Cache based Hibernate Cache Provider has been created for the JBoss Cache 1.4.x and Hibernate 3.2.x series. The aim of this wiki is to explain who should be using this new cache provider and how to configure it.

     

    What's New?

    It includes certain performance tweaks which are the result of EJB3 and JBoss Portal performance tests. These options are enabled by default which means that in the majority of cases you shouldn't need to change them. A full explanation of these tweaks can be found in the advanced section.

     

    Who Should Be Using It?

    Users deploying Hibernate 3.2.x Entities who require Second Level Cache under these circumstances:

    • Deploying Hibernate Entities in EAP/AS 4.2 or 4.3. If deploying EJB3 entities, there's no urgent need to use this cache provider as the EJB3 integration layer already includes some of the optimisations implemented in this new cache provider.
    • Deploying Hibernate Entities standalone or in another application server, i.e. BEA.

     

    How To Configure?

    1. Download the latest cache provider jar from JBoss’ Maven2 repository.

    2. Modify your hibernate.cfg.xml and enable second level cache:

    <property name="hibernate.cache.use_second_level_cache">true</property>

    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">
  org.jboss.hibernate.jbc.cacheprovider.JmxBoundTreeCacheProvider
</property>
<property name="hibernate.treecache.mbean.object_name">
  portal:service=TreeCache,type=hibernate
</property>
    • 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">
  org.jboss.hibernate.jbc.cacheprovider.JndiBoundTreeCacheProvider
</property>
<property name="hibernate.cache.jndi">
  JndiBoundTreeCacheInstance
</property>
    • If running Hibernate and JBoss Cache standalone or within third party Application Server, select TreeCacheProvider as the cache provider and add the path to cache’s configuration file:
    <property name="hibernate.cache.provider_class">
  org.jboss.hibernate.jbc.cacheprovider.TreeCacheProvider
</property>
<property name="hibernate.cache.provider_configuration_file_resource_path">
  /home/me/jbosscache.xml
</property>

    Note 1: org.jboss.hibernate.jbc.cacheprovider.TreeCacheProvider is only fully functional since 1.0.1.GA release.

    Note 2: In 1.0.0.GA, default value for hibernate.cache.provider_configuration_file_resource_path was treecache-optimistic.xml but from 1.0.1.GA, this has been changed to treecache.xml to match old standalone standalone JBoss Cache based cache provider. If treecache.xml is not present, old default, treecache-optimistic.xml, is looked up in case it's present. See JBCLUSTER-217 for more information.

    Reference: Advanced Configuration Options

    General Options

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

    Performance Options

    • hibernate.treecache.local_puts_only - First of all, please note that in 1.0.0.GA, this property used to be called hibernate.treecache.local.puts.only but this name has been deprecated since 1.0.1.GA, see JBCLUSTER-212. The aim of this property, whose default value is true, is to 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.
    • hibernate.treecache.querycache.local_writes_only - First of all, please note that in 1.0.0.GA, this property used to be called hibernate.treecache.querycache.local.writes.only but this name has been deprecated since 1.0.1.GA, see JBCLUSTER-212. This is a similar boolean option to local puts only except that it controls the behaviour of the query cache region. If query cache has been enabled, this property controls whether the query cache is only populated and updated locally or instead it's replicated. It’s enabled by default when query cache is also enabled.

    Frequently Asked Questions

    Q. Where Is The Source Code?

    Please visit the project's source code repository.

    Q. Where To Post User Questions?

    Please open a new forum entry in the JBoss Clustering User Forum

    Q. Where To Post Cache Provider Design/Development Questions?

    Please open a new forum entry in the Design of Clustering on JBoss

    Q. Where To Report Bugs Or Request New Features?

    Go to JBoss JIRA and open a new bug or feature request in the JBCLUSTER project and select "Hibernate-Cache-Provider" as Component.

     

    Ideas For Future Improvements

    Migrate cache provider to Hibernate so that everyone can take advantage of this new provider without the need of needing an extra jar. Any takers?