<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<body link="#355491" alink="#4262a1" vlink="#355491" style="background: #e2e2e2; margin: 0; padding: 20px;">
<div>
<table cellpadding="0" bgcolor="#FFFFFF" border="0" cellspacing="0" style="border: 1px solid #dadada; margin-bottom: 30px; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td>
<table border="0" cellpadding="0" cellspacing="0" bgcolor="#FFFFFF" style="border: solid 2px #ccc; background: #dadada; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td bgcolor="#000000" valign="middle" height="58px" style="border-bottom: 1px solid #ccc; padding: 20px; -moz-border-radius-topleft: 3px; -moz-border-radius-topright: 3px; -webkit-border-top-right-radius: 5px; -webkit-border-top-left-radius: 5px;">
<h1 style="color: #333333; font: bold 22px Arial, Helvetica, sans-serif; margin: 0; display: block !important;">
<!-- To have a header image/logo replace the name below with your img tag -->
<!-- Email clients will render the images when the message is read so any image -->
<!-- must be made available on a public server, so that all recipients can load the image. -->
<a href="http://community.jboss.org/index.jspa" style="text-decoration: none; color: #E1E1E1">JBoss Community</a></h1>
</td>
</tr>
<tr>
<td bgcolor="#FFFFFF" style="font: normal 12px Arial, Helvetica, sans-serif; color:#333333; padding: 20px; -moz-border-radius-bottomleft: 4px; -moz-border-radius-bottomright: 4px; -webkit-border-bottom-right-radius: 5px; -webkit-border-bottom-left-radius: 5px;"><h3 style="margin: 10px 0 5px; font-size: 17px; font-weight: normal;">
Hibernate JbossCache integration
</h3>
<span style="margin-bottom: 10px;">
created by <a href="http://community.jboss.org/people/marilenc">Marilen Corciovei</a> in <i>JBoss Cache</i> - <a href="http://community.jboss.org/docs/DOC-15863">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">
<div class="jive-rendered-content"><h2>Introduction</h2><p>JbossCache is a wonderfully complex piece of software. Trying to use  it with Hibernate might seem an easy task at first but in reality it can  also prove wonderfully complicated.</p><p>First question is: <strong>why would you consider using it in the first place?</strong> Compared to ehcache for instance there are a few theoretical  advantages: clustering (scalability), configurability and jmx  monitoring.</p><p>Next question which is not quite obvious is <strong>which version to use?</strong> The answer is a bit complicated since there are a lot of changes in  versions which vary from architectural to configuration points. This  document is concerned with integration of hibernate 3.3.1 with jboss  cache 3.1.0 (Cascabel) as they are shipped in jboss 5.1.0.GA.</p><h2>Choices</h2><p>I think most people consider that cache integration should be a  matter of switching a config option. I cannot argue with this logic and  for them the most appropriate configuration (as described in most  documents) is as following (if using a hibernate-service.xml .har  configuration):</p><div class="wp_syntax"><div class="code"><pre class="xml" style="font-family: monospace;"><property name="cacheRegionFactoryClass">org.hibernate.cache.jbc2.MultiplexedJBossCacheRegionFactory</property></pre></div></div><p>along with activation of second level and query cache:</p><div class="wp_syntax"><div class="code"><pre class="xml" style="font-family: monospace;"><property name="queryCacheEnabled">true</property>
<property name="secondLevelCacheEnabled">true</property></pre></div></div><p>This will probably work from start but also from start you will loose one of the advantages: jmx monitoring</p><p>Let’s go back to the cacheRegionFactoryClass and it’s  hibernate.cache.region.factory_class equivalent. The hibernate  documentation states there are 4 options for this property. Here is my  understanding of them:</p><ul><li><code>SharedJBossCacheRegionFactory</code> will create a Cache (as  in org.jboss.cache.Cache) based on a treecache.xml configuration and use  it for it’s caching purposes. You can provide your configuration (in  fact you must provide it) and everything seems perfect except that you  cannot have jmx instrumentation. I have found no way to obtain the Cache  from a SessionFactory and pass it to a CacheJmxWrapper for  instrumentation.</li><li><code>JndiSharedJBossCacheRegionFactory</code> seems the perfect  solution for the above problem as you can create your cache and jmx via a  -jboss-beans.xml configuration and then pass it to hibernate. <strong>Can you? No.</strong> As there is no way to bind the cache to JNDI from the -jboss-beans.xml  configuration. No problem I might say. I will bind it myself. However  the Cache object is not serializable and you will end with an exception.  <strong>No again.</strong></li></ul><pre>javax.naming.CommunicationException [Root exception is java.io.NotSerializableException:</pre><ul><li><code>MultiplexedJBossCacheRegionFactory</code> is the most  recommended solution. What it does is to create multiple Caches managed  by a CacheManager. Remember: you can still have multiple cache regions  with different eviction policies even in a single cache so the reason  for multiple caches seems an extreme case for me such as: having  different passivations or transport options. Note that this CacheManager  is created by hibernate and is not exposed to jmx. If you want to have a  clustering environment with not much fuss you will end up with jboss  default cache manager which also creates several Cache’s of it’s own.</li><li><code>JndiMultiplexedJBossCacheRegionFactory</code> seems then a  wises choice as it will let you connect/use the existing CacheManager  created by jboss (I will discuss configuration issues later).</li></ul><h2>Configuration</h2><p>Here are some example configurations for the cases described above.</p><h3>treecache.xml for the SharedJbossCacheRegionFactory</h3><p>You have to put it somewhere in the classpath root, for instance in  your .har file. The following example is local, does not uses jgroups  and has a special region for timestamps.</p><div class="wp_syntax"><div class="code"><pre class="xml" style="font-family: monospace;"><span><?xml version="1.0" encoding="UTF-8"?>
<jbosscache xmlns:xsi="</span><a class="jive-link-external-small" href="http://www.w3.org/2001/XMLSchema-instance" target="_blank">http://www.w3.org/2001/XMLSchema-instance</a><span>" xmlns="urn:jboss:jbosscache-core:config:3.1">
     <!--
      isolation levels supported: READ_COMMITTED and REPEATABLE_READ
      nodeLockingSchemes: mvcc, pessimistic (deprecated), optimistic (deprecated)
    -->
     <locking isolationLevel="REPEATABLE_READ" lockParentForChildInsertRemove="false" lockAcquisitionTimeout="20000" nodeLockingScheme="mvcc" writeSkewCheck="false" useLockStriping="true" concurrencyLevel="500" />
     <!-- Used to register a transaction manager and participate in ongoing transactions. -->
     <transaction transactionManagerLookupClass="org.jboss.cache.transaction.GenericTransactionManagerLookup" syncRollbackPhase="false" syncCommitPhase="false" />
     <!-- Used to register JMX statistics in any available MBean server -->
     <jmxStatistics enabled="true" />
     <!-- If region based marshalling is used, defines whether new regions are inactive on startup. -->
     <startup regionsInactiveOnStartup="true" />
     <!--
      Used to register JVM shutdown hooks.
      hookBehavior: DEFAULT, REGISTER, DONT_REGISTER
    -->
     <shutdown hookBehavior="DEFAULT" />
     <!-- Used to define async listener notification thread pool size -->
     <listeners asyncPoolSize="1" asyncQueueSize="100000" />
     <!-- Used to enable invocation batching and allow the use of Cache.startBatch()/endBatch() methods. -->
     <invocationBatching enabled="false" />
     <!-- serialization related configuration, used for replication and cache loading -->
     <serialization objectInputStreamPoolSize="12" objectOutputStreamPoolSize="14" version="3.0.0" marshallerClass="org.jboss.cache.marshall.VersionAwareMarshaller" useLazyDeserialization="false" useRegionBasedMarshalling="false" />
     <!--
      Eviction configuration.  WakeupInterval defines how often the eviction thread runs, in milliseconds.  0 means
      the eviction thread will never run.
   -->
     <eviction wakeUpInterval="500">
          <default algorithmClass="org.jboss.cache.eviction.LRUAlgorithm" eventQueueSize="200000">
               <property name="maxNodes" value="5000" />
               <property name="timeToLive" value="40000" />
          </default>
          <region name="/TS" algorithmClass="org.jboss.cache.eviction.NullEvictionAlgorithm">
          </region>
     </eviction>
</jbosscache></span></pre></div></div><h3>-jboss-beans.xml deployement</h3><p>Of a cache which cannot be bound to jndi and passed to SharedJbossCacheRegionFactory, also local:</p><div class="wp_syntax"><div class="code"><pre class="xml" style="font-family: monospace;"><?xml version="1.0" encoding="UTF-8"?>
<deployment xmlns="urn:jboss:bean-deployer:2.0">
   <!-- First we create a Configuration object for the cache -->
   <bean name="DiapasonCacheConfig"
         class="org.jboss.cache.config.Configuration">
      <property name="runtimeConfig">
         <bean class="org.jboss.cache.config.RuntimeConfig">
            <property name="transactionManager">
               <inject bean="jboss:service=TransactionManager"
                       property="TransactionManager"/>
            </property>
            <!--
            <property name="muxChannelFactory"><inject bean="JChannelFactory"/></property>
            -->
         </bean>
      </property>
      <property name="multiplexerStack">udp</property>
      <property name="clusterName">Diapason-EntityCache</property>
      <property name="isolationLevel">REPEATABLE_READ</property>
      <property name="cacheMode">LOCAL</property>
      <property name="stateRetrievalTimeout">15000</property>
      <property name="syncReplTimeout">20000</property>
      <property name="lockAcquisitionTimeout">15000</property>
      <property name="exposeManagementStatistics">true</property>
   </bean>
   <!-- Factory to build the Cache. -->
   <bean name="DefaultCacheFactory" class="org.jboss.cache.DefaultCacheFactory">     
      <constructor factoryClass="org.jboss.cache.DefaultCacheFactory"
                   factoryMethod="getInstance" />
   </bean>
   <!-- The cache itself -->
   <bean name="DiapasonCache" class="org.jboss.cache.Cache">
      <constructor factoryMethod="createCache">
          <factory bean="DefaultCacheFactory"/>
          <parameter class="org.jboss.cache.config.Configuration"><inject bean="DiapasonCacheConfig"/></parameter>
          <parameter class="boolean">false</parameter>
      </constructor>
   </bean>
   <!-- JMX Management -->
   <bean name="DiapasonCacheJmxWrapper" class="org.jboss.cache.jmx.CacheJmxWrapper">
      <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.cache:service=DiapasonTreeCache", exposedInterface=org.jboss.cache.jmx.CacheJmxWrapperMBean.class, registerDirectly=true)</annotation>
      <constructor>
          <parameter><inject bean="DiapasonCache"/></parameter>
      </constructor>
   </bean>
<!-- a bean I tried to use to register the cache to jndi, ignore
     <bean name="CacheX" class="ro.len.CacheX">
          <property name="cache"><inject bean="DiapasonCache"/></property>
   </bean>
-->
</deployment></pre></div></div><h3>MultiplexedJBossCacheRegionFactory</h3><p>No config is needed in this case as hibernate will use 2 files <code>jbc2-configs.xml</code> and <code>jgroups-stacks.xml</code> both found in <code>hibernate-jbosscache2.jar</code>.  Of course if you want to take advantage of the configurability of Jboss  Cache you will have to take these files and adapt them to your need.</p><h3>JndiMultiplexedJBossCacheRegionFactory</h3><p>This option will give you most of the things you want and can be configured as following:</p><div class="wp_syntax"><div class="code"><pre class="xml" style="font-family: monospace;"><property name="cacheRegionFactoryClass">org.hibernate.cache.jbc2.JndiMultiplexedJBossCacheRegionFactory</property>
<property name="deployedCacheManagerJndiName">java:/CacheManager</property></pre></div></div><p>This will make use of the existing CacheManager which is registered  to JNDI. However if using the “default” configuration for jboss this is  not the case. You will need to copy jboss-cache-manager.sar and   jgroups-channelfactory.sar from the all/deploy/cluster to  default/deploy/cluster along with an extra jar for pojo cache  (jbosscache-pojo.jar, still don’t know the use of that).</p><p>In order to configure your cache you will need to edit the  jboss-cache-manager-jboss-beans.xml file notably the optimistic-entity  entry which hibernate will use.</p><h2>Conclusions</h2><p>You might ask: <strong>why use jboss cache after all?</strong> it does seem a bit too complicated. I think you can find at least the following benefits:</p><ul><li>Configurability related to <strong>cache regions</strong>. This  seems the most interesting benefit from my point of view, can be done in  any of the previous configs and does not require a CacheManager or  clustering.This is where you can configure various eviction policies.  You might want for instance some data to be evicted much slower than  other or some data never to evicted. This means of course some mapping  (.hbm) changes in case of entities consisting in adding the region  attribute to the cache part of the mapping and some code change in case  of queries. </li><li><strong>JMX</strong> is of great use. First, it allows to see that  the eviction configured really works and second it shows lock problems  which unfortunately where a problem in previous jboss cache versions (as  in jboss 4.2.2 GA). Let’s hope it will no longer be the case.</li><li>Of least importance for most people it will be <strong>clustering</strong>.  But even if initially it might be of reduced importance it’s good to  know if you ever need it support is already there and only some  configuration is required</li></ul><h2>Links</h2><p>Finally here are some links which I read a lot of times in the  process of testing these configurations and are the base for this  article which intended to be much more shorter:</p><ul><li><a class="jive-link-external-small" href="http://docs.jboss.org/jbosscache/3.1.0.CR1/userguide_en/html_single/index.html">documentation for this cache version</a></li><li><a class="jive-link-external-small" href="http://docs.jboss.org/jbossclustering/hibernate-caching/3.3/en-US/html_single/index.html">hibernate, jboss cache integration</a></li><li><a class="jive-link-message-small" href="http://community.jboss.org/message/270922#270922">post discussing the jmx/jndi exposure</a> (found it later but describes similar observations)</li><li><a class="jive-link-external-small" href="http://www.len.ro/2010/02/jboss-migration-4-2-2-ga-to-5-1-0-ga/">migration from jboss 4 to 5 document</a> (why I arrived to this problem)</li></ul></div>
<div style="background-color: #f4f4f4; padding: 10px; margin-top: 20px;">
<p style="margin: 0;">Comment by <a href="http://community.jboss.org/docs/DOC-15863">going to Community</a></p>
<p style="margin: 0;">Create a new document in JBoss Cache at <a href="http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2052">Community</a></p>
</div></td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</div>
</body>
</html>