JBoss Cache MBeans

JBoss Cache 1.3 provides MBeans to expose cache operations via JMX as well as to present statistics that can be used to manage the cache.  Cache events are also available via JMX notifications.  Use of these MBeans is discussed in detail in the Management Information chapter of the JBossCache User Guide.

Accessing MBeans in a Server Environment

Each cache instance has an associated MBean that can be used to access and manipulate the cache.  This MBean is accessible from the MBean server through the service name specified in

the cache's configuration.  For example, the Tomcat clustering cache instance is accessible through the service named "jboss.cache:service=TomcatClusteringCache."

Most application servers provide an MBean container that can be used to visually inspect and work with MBeans deployed to the container.  For example, JBossAS provides the JMX Console to work with its MBeans.  Refer to server documentation on how to use this application.

JMX MBeans can also be accessed programmatically through an MBeanServerConnection.  See HowDoIGetRemoteAccessToMyMBean for information on how to accomplish this with JBossAS.  The JBossCache User Guide provides a code example showing how to do this for a JBossCache MBean.

JBoss Cache 1.3 introduces MBeans for its interceptors.  These MBeans provide information that can be used to manage the cache such as the number of cache hits and misses.  These MBeans are hierarchically associated with the cache's primary MBean and are named to reflect this relationship.  For example, the replication interceptor MBean for the TomcatClusteringCache instance will be accessible through a service named "jboss.cache:service=TomcatClusteringCache,treecache-interceptor=ReplicationInterceptor."

More details are provided in the User Guide.

Accessing MBeans in a Standalone Environment

JBoss Cache MBeans are also accessible when running in a non-server environment if the JVM is JDK 5.0 or later.  When running a standalone cache in a JDK 5 environment, you can access the cache's MBeans as follows.

1. Set the system property -Dcom.sun.management.jmxremote when starting the JVM where the cache will run.

2. Once the JVM is running, start the JDK 5 jconsole utility, located in the JDK's /bin directory.

3. When the utility loads, select your JVM and connect to it.  The JBoss Cache MBeans will be visible on the MBeans panel.

Acessing the TreeCache MBeans in JBossAS when the TreeCache is standalone

If you for some reason don't wan't to deploy the TreeCache instance in the deploy-folder in JBossAS , but as a standalone cache in a WAR-application, you can still access the MBean from the jmx-console.

Example: You have a WAR-application in wich you want a standalone cache. Put the treecache config file in the root of you classpath and create a singleton-wrapper around the TreeCache. The wrapper should have a init() metod that creates the cache instance and stores it in the singleton:

/**
 * TreeCacheSingleton
 *
 * Date: 2006-aug-17
 * @author Carl Abramsson
 */
package treecachedemo;

import org.jboss.cache.ConfigureException;
import org.jboss.cache.PropertyConfigurator;
import org.jboss.cache.TreeCache;


public final class TreeCacheSingleton {
    // Flag to indicate if the cache has been created
    private static boolean isInited;
    // The singleton
    private static TreeCache treecache;

    public static TreeCache getInstance() {
        if(!isInited)
            throw new IllegalStateException("The cache has not been inited!");
        return treecache;
    }

    public static synchronized void init() throws Exception {
        if(!isInited) {
            try {
                treecache = new TreeCache();
            } catch (Exception e) {
                throw new Exception("Could not create TreeCache!", e);
            }
            PropertyConfigurator config = new PropertyConfigurator();
            try {
                config.configure(treecache, "treecache.xml"); // Load config file from classpath
            } catch (ConfigureException e) {
                throw new Exception("Could not configure TreeCache!", e);
            }
            try {
                treecache.startService();
            } catch (Exception e) {
                throw new Exception("Could not start TreeCache!", e);
            }
            isInited = true;
        }
    }

    public static synchronized void stop() throws Exception {
        treecache.stopService();
        treecache.destroyService();
        treecache.destroy();
    }

    private TreeCacheSingleton() {
        // hide it, static only
    }
}

Init the singleton from a ServletContextListener:

package treecachedemo;

import javax.servlet.ServletContextListener;
import javax.servlet.ServletContextEvent;

/**
 * Inits the TreeCacheSingleton
 * <p></p>
 * Date: 2006-aug-17
 *
 * @author Carl Abramsson
 */
public class CacheControlListener implements ServletContextListener {
    public void contextInitialized(ServletContextEvent servletContextEvent) {
        try {
            TreeCacheSingleton.init();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    public void contextDestroyed(ServletContextEvent servletContextEvent) {
        try {
            TreeCacheSingleton.stop();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

In web.xml

<web-app>
    <listener>
        <listener-class>treecachedemo.CacheControlListener</listener-class>
    </listener>
</web-app>

Now the TreeCache instance should be started when the WAR-application starts, and nicely stopped.

And if you logon to the jmx-console in JBossAS the TreeCacheMBean should be there. It gets the name jboss.cache:service=[Name_of_you_cluster|name_of_you_cluster]

(Only verifed that this works with JBoss Cache 1.4.0 GA)