19.2.1. Configure the distributed cache

To avoid round trips to the database, you can use a cache for your entities. JBoss EJB 3.0 entity beans are implemented by Hibernate, which has support for a second-level cache. The Hibernate setup used for the JBoss EJB 3.0 implementation uses JBoss Cache as its underlying second-level cache implementation. The second-level cache provides the following functionalities.

If you persist a cache enabled entity bean instance to the database via the entity manager the entity will inserted into the cache.
If you update an entity bean instance and save the changes to the database via the entity manager the entity will updated in the cache.
If you remove an entity bean instance from the database via the entity manager the entity will removed from the cache.
If loading a cached entity from the database via the entity manager, and that entity does not exist in the database, it will be inserted into the cache.

The JBoss Cache service for EJB 3.0 entity beans is configured in a TreeCache MBean in the deploy/ejb3-entity-cache-service.xml file. The name of the cache MBean service is jboss.cache:service=EJB3EntityTreeCache. Below are the contents of the ejb3-entity-cache-service.xml file in the standard JBoss distribution. Again, we omitted the JGroups configuration element ClusterConfig.

 
 <server>
  <mbean code="org.jboss.cache.TreeCache" 
 name="jboss.cache:service=EJB3EntityTreeCache">
	  
  <depends>jboss:service=Naming</depends>
  <depends>jboss:service=TransactionManager</depends> 
    
  <!-- Name of cluster. Needs to be the same on all nodes in the clusters, 
	       in order to find each other --> 
	  <attribute name="ClusterName">
  		${jboss.partition.name:DefaultPartition}-EntityCache
	  </attribute>
	  
	  <!-- Configure the TransactionManager -->
	 <attribute name="TransactionManagerLookupClass">
	   org.jboss.cache.JBossTransactionManagerLookup
	 </attribute>
	  
	 <attribute name="IsolationLevel">REPEATABLE_READ</attribute>
	 <attribute name="CacheMode">REPL_SYNC</attribute> 
	  
	 <!-- Must be true if any entity deployment uses a scoped classloader --> 
	 <attribute name="UseRegionBasedMarshalling">true</attribute> 
	 <!-- Must match the value of "useRegionBasedMarshalling" --> 
	 <attribute name="InactiveOnStartup">true</attribute>
	  
	 <attribute name="ClusterConfig">
	  ... ...
	 </attribute>
	  
	 <attribute name="InitialStateRetrievalTimeout">17500</attribute>
	 <attribute name="SyncReplTimeout">17500</attribute>
	 <attribute name="LockAcquisitionTimeout">15000</attribute>
	  
	 <attribute name="EvictionPolicyClass">
	 org.jboss.cache.eviction.LRUPolicy
	 </attribute>
	  
	 <!--  Specific eviction policy configurations. This is LRU -->
	  <attribute name="EvictionPolicyConfig">
	  <config>
	  <attribute name="wakeUpIntervalSeconds">5</attribute>
	  <!--  Cache wide default -->
		  <region name="/_default_">
		  <attribute name="maxNodes">5000</attribute>
		  <attribute name="timeToLiveSeconds">1000</attribute>
		  </region>
	  </config>
	 </attribute>
	 </mbean>
</server>

This is a replicated cache, so, if running within a cluster, and the cache is updated, changes to the entries in one node will be replicated to the corresponding entries in the other nodes in the cluster.

JBoss Cache allows you to specify timeouts to cached entities. Entities not accessed within a certain amount of time are dropped from the cache in order to save memory. The above configuration sets up a default configuration region that says that at most the cache will hold 5000 nodes, after which nodes will start being evicted from memory, least-recently used nodes last. Also, if any node has not been accessed within the last 1000 seconds, it will be evicted from memory. In general, a node in the cache represents a cached item (entity, collection, or query result set), although there are also a few other node that are used for internal purposes. If the above values of 5000 maxNodes and 1000 idle seconds are invalid for your application(s), you can change the cache-wide defaults. You can also add separate eviction regions for each of your entities; more on this below.

Now, we have JBoss Cache configured to support distributed caching of EJB 3.0 entity beans. We still have to configure individual entity beans to use the cache service.