24.2. Deploying Your Own JBoss Cache Instance

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

24.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 Web Platform's CacheManager service (see Section 17.1.3.1, “The JBoss Enterprise Web Platform CacheManager Service”). End user applications can do the same thing.

Section 24.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 24.1.1, “Editing the CacheManager Configuration” for an example configuration.

24.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 your application to the CacheManager. 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 look up the CacheManager in 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 Web 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 isn't necessary inside the Enterprise Web 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 doesn't 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 doesn't exist yet
       pojoCache = cacheManager.getPojoCache("my-cache-config", true);
       
       pojoCache.start();
   }
   
   public void stop() throws Exception {
       cacheManager.releaseCache("my-cache-config");
   }
}