You define your entity bean classes the normal way. Future versions of JBoss EJB 3.0 will support annotating entities and their relationship collections as cached, but for now you have to configure the underlying hibernate engine directly. Take a look at the persistence.xml file, which configures the caching options for hibernate via its optional property elements. The following element in persistence.xml defines that caching should be enabled:

<!-- Clustered cache with TreeCache -->
<property name="cache.provider_class">
    org.jboss.ejb3.entity.TreeCacheProviderHook
</property>
                

The following property element defines the object name of the cache to be used, i.e., the name of the TreeCache MBean shown above.

<property name="treecache.mbean.object_name">
    jboss.cache:service=EJB3EntityTreeCache
</property>
                

Finally, you should give a “region_prefix” to this configuration. This ensures that all cached items associated with this persistence.xml are properly grouped together in JBoss Cache. The jboss.cache:service=EJB3EntityTreeCache cache is a shared resource, potentially used by multiple persistence units. The items cached in that shared cache need to be properly grouped to allow the cache to properly manage classloading. <property name="hibernate.cache.region_prefix" value="myprefix"/>

If you do not provide a region prefix, JBoss will automatically provide one for you, building it up from the name of the EAR (if any) and the name of the JAR that includes the persistence.xml. For example, a persistence.xml packaged in foo.ear, bar.jar would be given “foo_ear,bar_jar” as its region prefix. This is not a particularly friendly region prefix if you need to use it to set up specialized eviction regions (see below), so specifying your own region prefix is recommended.

Next we need to configure what entities be cached. The default is to not cache anything, even with the settings shown above. We use the @org.hibernate.annotations.Cache annotation to tag entity beans that needs to be cached.

@Entity 
@Cache(usage=CacheConcurrencyStrategy.TRANSACTIONAL) 
public class Account implements Serializable { 
  // ... ... 
}
                

A very simplified rule of thumb is that you will typically want to do caching for objects that rarely change, and which are frequently read. You can fine tune the cache for each entity bean in the ejb3-entity-cache-service.xml configuration file. For instance, you can specify the size of the cache. If there are too many objects in the cache, the cache could evict oldest objects (or least used objects, depending on configuration) to make room for new objects. Assuming the region_prefix specified in persistence.xml was myprefix, the default name of the cache region for the com.mycompany.entities.Account entity bean /myprefix/com/mycompany/entities/Account.

<server>  
  <mbean code="org.jboss.cache.TreeCache" 
		 name="jboss.cache:service=EJB3EntityTreeCache"> 
		  ... ... 
	  <attribute name="EvictionPolicyConfig">  
		  <config>  
			  <attribute name="wakeUpIntervalSeconds">5</attribute>  
			  <region name="/_default_">  
				  <attribute name="maxNodes">5000</attribute>  
				  <attribute name="timeToLiveSeconds">1000</attribute>  
			  </region>  
		  <!-- Separate eviction rules for Account entities -->
			  <region name="/myprefix/com/mycompany/entities/Account">  
				  <attribute name="maxNodes">10000</attribute>  
				  <attribute name="timeToLiveSeconds">5000</attribute>  
			  </region>  
		  ... ... 
		 </config>  
	 </attribute>  
 </mbean> 
</server>

If you do not specify a cache region for an entity bean class, all instances of this class will be cached in the /_default region as defined above. The @Cache annotation exposes an optional attribute “region” that lets you specify the cache region where an entity is to be stored, rather than having it be automatically be created from the fully-qualified class name of the entity class.

@Entity 
@Cache(usage=CacheConcurrencyStrategy.TRANSACTIONAL,
region=”Account”) 
public class Account implements Serializable { 
// ... ... 
}

The eviction configuration would then become:

			
<server>  
	<mbean code="org.jboss.cache.TreeCache" 
	      name="jboss.cache:service=EJB3EntityTreeCache"> 
		... ... 
	<attribute name="EvictionPolicyConfig">  
	<config>  
		<attribute name="wakeUpIntervalSeconds">5</attribute>  
		<region name="/_default_">  
		<attribute name="maxNodes">5000</attribute>  
		<attribute name="timeToLiveSeconds">1000</attribute>  
			</region>  
		<!-- Separate eviction rules for Account entities -->
			<region name="/myprefix/Account">  
				<attribute name="maxNodes">10000</attribute>  
				<attribute name="timeToLiveSeconds">5000</attribute>  
			</region>  
			... ... 
	</config>  
	</attribute>  
	</mbean> 
</server>