29.2. Deploying Your Own JBoss Cache Instance

It's quite common for users to deploy their own instances of JBoss Cache inside JBoss Enterprise Application Platform for custom use by their applications. In this section we describe the various ways caches can be deployed.

29.2.1. Deployment Via the CacheManager Service

The standard JBoss clustered services that use JBoss Cache obtain a reference to their cache from the Enterprise Application Platform's CacheManager service (see Section 21.2.1, “The JBoss Enterprise Application Platform CacheManager Service”). End user applications can do the same thing; here's how.
Section 29.1.1, “Editing the CacheManager Configuration” shows the configuration of the CacheManager's "CacheConfigurationRegistry" bean. To add a new configuration, you would add an additional element inside that bean's newConfigurations <map>: 
<bean name="CacheConfigurationRegistry" 
      class="org.jboss.ha.cachemanager.DependencyInjectedConfigurationRegistry">
   .....
   <property name="newConfigurations">
     <map keyClass="java.lang.String" valueClass="org.jboss.cache.config.Configuration">
                  
       <entry><key>my-custom-cache</key>
         <value>          
           <bean name="MyCustomCacheConfig" class="org.jboss.cache.config.Configuration">              
             .... details of the my-custom-cache configuration
           </bean> 
          </value>
       </entry>    
       .....
See Section 29.1.1, “Editing the CacheManager Configuration” for an example configuration.

29.2.1.1. Accessing the CacheManager

Once you've added your cache configuration to the CacheManager, the next step is to provide a reference to the CacheManager to your application. There are three ways to do this:
  • Dependency Injection
    If your application uses the JBoss Microcontainer for configuration, the simplest mechanism is to have it inject the CacheManager into your service. 
    <bean name="MyService" class="com.example.MyService">
   <property name="cacheManager"><inject bean="CacheManager"/></property>
</bean>
  • JNDI Lookup
    Alternatively, you can find look up the CacheManger is JNDI. It is bound under java:CacheManager. 
    import org.jboss.ha.cachemanager.CacheManager;

public class MyService {
   private CacheManager cacheManager;
   
   public void start() throws Exception {
       Context ctx = new InitialContext();
       cacheManager = (CacheManager) ctx.lookup("java:CacheManager");
   }
}
  • CacheManagerLocator
    JBoss Enterprise Application Platform also provides a service locator object that can be used to access the CacheManager. 
    import org.jboss.ha.cachemanager.CacheManager;
import org.jboss.ha.framework.server.CacheManagerLocator;

public class MyService {
   private CacheManager cacheManager;
   
   public void start() throws Exception {
       CacheManagerLocator locator = CacheManagerLocator.getCacheManagerLocator();
       // Locator accepts as param a set of JNDI properties to help in lookup;
       // this is not necessary inside the Enterprise Application Platform
       cacheManager = locator.getCacheManager(null);
   }
}
Once a reference to the CacheManager is obtained; usage is simple. Access a cache by passing in the name of the desired configuration. The CacheManager will not start the cache; this is the responsibility of the application. The cache may, however, have been started by another application running in the cache server; the cache may be shared. When the application is done using the cache, it should not stop. Just inform the CacheManager that the cache is no longer being used; the manager will stop the cache when all callers that have asked for the cache have released it. 
import org.jboss.cache.Cache;
import org.jboss.ha.cachemanager.CacheManager;
import org.jboss.ha.framework.server.CacheManagerLocator;

public class MyService {
   private CacheManager cacheManager;
   private Cache cache;
   
   public void start() throws Exception {
       Context ctx = new InitialContext();
       cacheManager = (CacheManager) ctx.lookup("java:CacheManager");
       
       // "true" param tells the manager to instantiate the cache if
       // it does not exist yet
       cache = cacheManager.getCache("my-cache-config", true);
       
       cache.start();
   }
   
   public void stop() throws Exception {
       cacheManager.releaseCache("my-cache-config");
   }
}
The CacheManager can also be used to access instances of POJO Cache. 
import org.jboss.cache.pojo.PojoCache;
import org.jboss.ha.cachemanager.CacheManager;
import org.jboss.ha.framework.server.CacheManagerLocator;

public class MyService {
   private CacheManager cacheManager;
   private PojoCache pojoCache;
   
   public void start() throws Exception {
       Context ctx = new InitialContext();
       cacheManager = (CacheManager) ctx.lookup("java:CacheManager");
       
       // "true" param tells the manager to instantiate the cache if
       // it does not exist yet
       pojoCache = cacheManager.getPojoCache("my-cache-config", true);
       
       pojoCache.start();
   }
   
   public void stop() throws Exception {
       cacheManager.releaseCache("my-cache-config");
   }
}