An MBean is a Java object that implements one of the standard MBean interfaces and follows the associated design patterns. The MBean for a resource exposes all necessary information and operations that a management application needs to control the resource.

The scope of the management interface of an MBean includes the following:

JMX defines four types of MBeans to support different instrumentation needs:

We will present an example of a Standard and a Model MBean in the section that discusses extending JBoss with your own custom services.

JMX Notifications are an extension of the Java event model. Both the MBean server and MBeans can send notifications to provide information. The JMX specification defines the javax.management package Notification event object, NotificationBroadcaster event sender, and NotificationListener event receiver interfaces. The specification also defines the operations on the MBean server that allow for the registration of notification listeners.

There is a collection of metadata classes that describe the management interface of an MBean. Users can obtain a common metadata view of any of the four MBean types by querying the MBean server with which the MBeans are registered. The metadata classes cover an MBean's attributes, operations, notifications, and constructors. For each of these, the metadata includes a name, a description, and its particular characteristics. For example, one characteristic of an attribute is whether it is readable, writable, or both. The metadata for an operation contains the signature of its parameter and return types.

The different types of MBeans extend the metadata classes to be able to provide additional information as required. This common inheritance makes the standard information available regardless of the type of MBean. A management application that knows how to access the extended information of a particular type of MBean is able to do so.

A key component of the agent level is the managed bean server. Its functionality is exposed through an instance of the javax.management.MBeanServer. An MBean server is a registry for MBeans that makes the MBean management interface available for use by management applications. The MBean never directly exposes the MBean object itself; rather, its management interface is exposed through metadata and operations available in the MBean server interface. This provides a loose coupling between management applications and the MBeans they manage.

MBeans can be instantiated and registered with the MBeanServer by the following:

When you register an MBean, you must assign it a unique object name. The object name then becomes the unique handle by which management applications identify the object on which to perform management operations. The operations available on MBeans through the MBean server include the following:

Protocol adaptors and connectors are required to access the MBeanServer from outside the agent's JVM. Each adaptor provides a view via its protocol of all MBeans registered in the MBean server the adaptor connects to. An example adaptor is an HTML adaptor that allows for the inspection and editing of MBeans using a Web browser. As was indicated in Figure 2.2, “The Relationship between the components of the JMX architecture”, there are no protocol adaptors defined by the current JMX specification. Later versions of the specification will address the need for remote access protocols in standard ways.

A connector is an interface used by management applications to provide a common API for accessing the MBean server in a manner that is independent of the underlying communication protocol. Each connector type provides the same remote interface over a different protocol. This allows a remote management application to connect to an agent transparently through the network, regardless of the protocol. The specification of the remote management interface will be addressed in a future version of the JMX specification.

Adaptors and connectors make all MBean server operations available to a remote management application. For an agent to be manageable from outside of its JVM, it must include at least one protocol adaptor or connector. JBoss currently includes a custom HTML adaptor implementation and a custom JBoss RMI adaptor.

The JMX agent services are objects that support standard operations on the MBeans registered in the MBean server. The inclusion of supporting management services helps you build more powerful management solutions. Agent services are often themselves MBeans, which allow the agent and their functionality to be controlled through the MBean server. The JMX specification defines the following agent services:

Any JMX-compliant implementation will provide all of these agent services. However, JBoss does not rely on any of these standard agent services.

Debugging class loading issues comes down to finding out where a class was loaded from. A useful tool for this is the code snippet shown in Example 2.7, “Obtaining debugging information for a Class” taken from the org.jboss.util.Debug class of the book examples.

Class clazz =...;
StringBuffer results = new StringBuffer();

ClassLoader cl = clazz.getClassLoader();
results.append("\n" + clazz.getName() + "(" + 
               Integer.toHexString(clazz.hashCode()) + ").ClassLoader=" + cl);
ClassLoader parent = cl;

while (parent != null) {
    results.append("\n.."+parent);
    URL[] urls = getClassLoaderURLs(parent);

    int length = urls != null ? urls.length : 0;
    for(int u = 0; u < length; u ++) {
	results.append("\n...."+urls[u]);
    }

    if (showParentClassLoaders == false) {
	break;
    }
    if (parent != null) {
	parent = parent.getParent();
    }
}

CodeSource clazzCS = clazz.getProtectionDomain().getCodeSource();
if (clazzCS != null) {
    results.append("\n++++CodeSource: "+clazzCS);
} else {
    results.append("\n++++Null CodeSource");
}

The key items are shown in bold. The first is that every Class object knows its defining ClassLoader and this is available via the getClassLoader() method. The defines the scope in which the Class type is known as we have just seen in the previous sections on class cast exceptions, illegal access exceptions and linkage errors. From the ClassLoader you can view the hierarchy of class loaders that make up the parent delegation chain. If the class loader is a URLClassLoader you can also see the URLs used for class and resource loading.

The defining ClassLoader of a Class cannot tell you from what location that Class was loaded. To determine this you must obtain the java.security.ProtectionDomain and then the java.security.CodeSource. It is the CodeSource that has the URL location from which the class originated. Note that not every Class has a CodeSource. If a class is loaded by the bootstrap class loader then its CodeSource will be null. This will be the case for all classes in the java.* and javax.* packages, for example.

Beyond that it may be useful to view the details of classes being loaded into the JBoss server. You can enable verbose logging of the JBoss class loading layer using a Log4j configuration fragment like that shown in Example 2.8, “An example log4j.xml configuration fragment for enabling verbose class loading logging”.

<appender name="UCL" class="org.apache.log4j.FileAppender">
    <param name="File" value="${jboss.server.home.dir}/log/ucl.log"/>
    <param name="Append" value="false"/>
    <layout class="org.apache.log4j.PatternLayout">
        <param name="ConversionPattern" value="[%r,%c{1},%t] %m%n"/>
    </layout>
</appender>
<category name="org.jboss.mx.loading" additivity="false">
    <priority value="TRACE" class="org.jboss.logging.XLevel"/>
    <appender-ref ref="UCL"/>
</category>

This places the output from the classes in the org.jboss.mx.loading package into the ucl.log file of the server configurations log directory. Although it may not be meaningful if you have not looked at the class loading code, it is vital information needed for submitting bug reports or questions regarding class loading problems. If you have a class loading problem that appears to be a bug, submit it to the JBoss project on SourceForge and include this log file as an attachment. If the log file is too big, compress it and mail it to [email protected].

Another useful source of information on classes is the UnifiedLoaderRepository itself. This is an MBean that contains operations to display class and package information. The default repository is located under a standard JMX name of JMImplementation:name=Default,service=LoaderRepository, and its MBean can be accessed via the JMX console by following its link from the front page. The JMX console view of this MBean is shown in Figure 2.4, “The default class LoaderRepository MBean view in the JMX console”.

Figure 2.4. The default class LoaderRepository MBean view in the JMX console

Two useful operations you will find here are getPackageClassLoaders(String) and displayClassInfo(String). The getPackageClassLoaders operation returns a set of class loaders that have been indexed to contain classes or resources for the given package name. The package name must have a trailing period. If you type in the package name org.jboss.ejb., the following information is displayed:

[org.jboss.mx.loading.UnifiedClassLoader3@e26ae7{
  url=file:/private/tmp/jboss-4.0.1/server/default/tmp/deploy/tmp11895jboss-service.xml,
  addedOrder=2}]

This is the string representation of the set. It shows one UnifiedClassLoader3 instance with a primary URL pointing to the jboss-service.xml descriptor. This is the second class loader added to the repository (shown by addedOrder=2). It is the class loader that owns all of the JARs in the lib directory of the server configuration (e.g., server/default/lib).

The view the information for a given class, use the displayClassInfo operation, passing in the fully qualified name of the class to view. For example, if we use org.jboss.jmx.adaptor.html.HtmlAdaptorServlet which is from the package we just looked at, the following description is displayed:

The information is a dump of the information for the Class instance in the loader repository if one has been loaded, followed by the class loaders that are seen to have the class file available. If a class is seen to have more than one class loader associated with it, then there is the potential for class loading related errors.

If you need to deploy multiple versions of an application you need to use deployment based scoping. With deployment based scoping, each deployment creates its own class loader repository in the form of a HeirarchicalLoaderRepository3 that looks first to the UnifiedClassLoader3 instances of the deployment units included in the EAR before delegating to the default UnifiedLoaderRepository3. To enable an EAR specific loader repository, you need to create a META-INF/jboss-app.xml descriptor as shown in Example 2.9, “An example jboss-app.xml descriptor for enabled scoped class loading at the EAR level.”.

<jboss-app>
    <loader-repository>some.dot.com:loader=webtest.ear</loader-repository>
</jboss-app>

The value of the loader-repository element is the JMX object name to assign to the repository created for the EAR. This must be unique and valid JMX ObjectName, but the actual name is not important.

The previous discussion of the core class loading components introduced the custom UnifiedClassLoader3 and UnifiedLoaderRepository3 classes that form a shared class loading space. The complete class loading picture must also include the parent class loader used by UnifiedClassLoader3s as well as class loaders introduced for scoping and other specialty class loading purposes. Figure 2.5, “A complete class loader view” shows an outline of the class hierarchy that would exist for an EAR deployment containing EJBs and WARs.

Figure 2.5. A complete class loader view

The following points apply to this figure:

In its current form there are some advantages and disadvantages to the JBoss class loading architecture. Advantages include:

Disadvantages include:

The create(ObjectName) method is called whenever an event occurs that affects the named services state. This could be triggered by an explicit invocation by the SARDeployer, a notification of a new class, or another service reaching its created state.

When a service's create method is called, all services on which the service depends have also had their create method invoked. This gives an MBean an opportunity to check that required MBeans or resources exist. A service cannot utilize other MBean services at this point, as most JBoss MBean services do not become fully functional until they have been started via their start method. Because of this, service implementations often do not implement create in favor of just the start method because that is the first point at which the service can be fully functional.

The start(ObjectName) method is called whenever an event occurs that affects the named services state. This could be triggered by an explicit invocation by the SARDeployer, a notification of a new class, or another service reaching its started state.

When a service's start method is called, all services on which the service depends have also had their start method invoked. Receipt of a start method invocation signals a service to become fully operational since all services upon which the service depends have been created and started.

The stop(ObjectName) method is called whenever an event occurs that affects the named services state. This could be triggered by an explicit invocation by the SARDeployer, notification of a class removal, or a service on which other services depend reaching its stopped state.

The destroy(ObjectName) method is called whenever an event occurs that affects the named services state. This could be triggered by an explicit invocation by the SARDeployer, notification of a class removal, or a service on which other services depend reaching its destroyed state.

Service implementations often do not implement destroy in favor of simply implementing the stop method, or neither stop nor destroy if the service has no state or resources that need cleanup.

Let's start with a simple XMBean variation of the standard MBean version of the JNDIMap that adds the descriptive information about the attributes and operations and their arguments. The following listing shows the jboss-service.xml descriptor and the jndimap-xmbean1.xml XMBean descriptor. The source can be found in the src/main/org/jboss/chap2/xmbean directory of the book examples.

<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE server PUBLIC    
                     "-//JBoss//DTD MBean Service 3.2//EN"
                     "http://www.jboss.org/j2ee/dtd/jboss-service_3_2.dtd">
<server>
    <mbean code="org.jboss.chap2.xmbean.JNDIMap"
           name="chap2.xmbean:service=JNDIMap" 
           xmbean-dd="META-INF/jndimap-xmbean.xml">
        <attribute name="JndiName">inmemory/maps/MapTest</attribute>
        <depends>jboss:service=Naming</depends>
    </mbean>
</server>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mbean PUBLIC
          "-//JBoss//DTD JBOSS XMBEAN 1.0//EN"
          "http://www.jboss.org/j2ee/dtd/jboss_xmbean_1_0.dtd">
<mbean>
    <description>The JNDIMap XMBean Example Version 1</description>
    <descriptors>
        <persistence persistPolicy="Never" persistPeriod="10"
            persistLocation="data/JNDIMap.data" persistName="JNDIMap"/>
        <currencyTimeLimit value="10"/>
        <state-action-on-update value="keep-running"/>
    </descriptors>
    <class>org.jboss.test.jmx.xmbean.JNDIMap</class>
    <constructor>
        <description>The default constructor</description>
        <name>JNDIMap</name>
    </constructor>  
    <!-- Attributes -->
    <attribute access="read-write" getMethod="getJndiName" setMethod="setJndiName">
        <description>
            The location in JNDI where the Map we manage will be bound
        </description>
        <name>JndiName</name>
        <type>java.lang.String</type>
        <descriptors>
            <default value="inmemory/maps/MapTest"/>
        </descriptors>
    </attribute>
    <attribute access="read-write" getMethod="getInitialValues"
               setMethod="setInitialValues">
        <description>The array of initial values that will be placed into the
            map associated with the service. The array is a collection of
            key,value pairs with elements[0,2,4,...2n] being the keys and
            elements [1,3,5,...,2n+1] the associated values. The
            "[Ljava.lang.String;" type signature is the VM representation of the
            java.lang.String[] type. </description>
        <name>InitialValues</name>
        <type>[Ljava.lang.String;</type>
        <descriptors>
            <default value="key0,value0"/>
        </descriptors>
    </attribute>  
    <!-- Operations -->
    <operation>
        <description>The start lifecycle operation</description>
        <name>start</name>
    </operation>
    <operation>
        <description>The stop lifecycle operation</description>
        <name>stop</name>
    </operation>
    <operation impact="ACTION">
        <description>Put a value into the map</description>
        <name>put</name>
        <parameter>
            <description>The key the value will be store under</description>
            <name>key</name>
            <type>java.lang.Object</type>
        </parameter>
        <parameter>
            <description>The value to place into the map</description>
            <name>value</name>
            <type>java.lang.Object</type>
        </parameter>
    </operation>
    <operation impact="INFO">
        <description>Get a value from the map</description>
        <name>get</name>
        <parameter>
            <description>The key to lookup in the map</description>
            <name>get</name>
            <type>java.lang.Object</type>
        </parameter>
        <return-type>java.lang.Object</return-type>
    </operation>  
    <!-- Notifications -->
    <notification>
        <description>The notification sent whenever a value is get into the map
            managed by the service</description>
        <name>javax.management.Notification</name>
        <notification-type>org.jboss.chap2.xmbean.JNDIMap.get</notification-type>
    </notification>
    <notification>
        <description>The notification sent whenever a value is put into the map
            managed by the service</description>
        <name>javax.management.Notification</name>
        <notification-type>org.jboss.chap2.xmbean.JNDIMap.put</notification-type>
    </notification>
</mbean>

You can build, deploy and test the XMBean as follows:

[examples]$ ant -Dchap=chap2 -Dex=xmbean1  run-example
...
run-examplexmbean1:
     [copy] Copying 1 file to /tmp/jboss-4.0.1/server/default/deploy
     [java] JNDIMap Class: org.jboss.mx.modelmbean.XMBean
     [java] JNDIMap Operations: 
     [java]  + void start()
     [java]  + void stop()
     [java]  + void put(java.lang.Object chap2.xmbean:service=JNDIMap,java.lang.Object cha
p2.xmbean:service=JNDIMap)
     [java]  + java.lang.Object get(java.lang.Object chap2.xmbean:service=JNDIMap)
     [java]  + java.lang.String getJndiName()
     [java]  + void setJndiName(java.lang.String chap2.xmbean:service=JNDIMap)
     [java]  + [Ljava.lang.String; getInitialValues()
     [java]  + void setInitialValues([Ljava.lang.String; chap2.xmbean:service=JNDIMap)
     [java] handleNotification, event: null
     [java] key=key0, value=value0
     [java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:s
ervice=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.put,sequenceNumber=3,timeStamp=10986315
27823,message=null,userData=null]
     [java] JNDIMap.put(key1, value1) successful
     [java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:s
ervice=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.get,sequenceNumber=4,timeStamp=10986315
27940,message=null,userData=null]
     [java] JNDIMap.get(key0): null
     [java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:s
ervice=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.get,sequenceNumber=5,timeStamp=10986315
27985,message=null,userData=null]
     [java] JNDIMap.get(key1): value1
     [java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:s
ervice=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.put,sequenceNumber=6,timeStamp=10986315
27999,message=null,userData=null]

The functionality is largely the same as the Standard MBean with the notable exception of the JMX notifications. A Standard MBean has no way of declaring that it will emit notifications. An XMBean may declare the notifications it emits using notification elements as is shown in the version 1 descriptor. We see the notifications from the get and put operations on the test client console output. Note that there is also an jmx.attribute.change notification emitted when the InitialValues attribute was changed. This is because the ModelMBean interface extends the ModelMBeanNotificationBroadcaster which supports AttributeChangeNotificationListeners.

The other major difference between the Standard and XMBean versions of JNDIMap is the descriptive metadata. Look at the chap2.xmbean:service=JNDIMap in the JMX Console, and you will see the attributes section as shown in Figure 2.18, “The Version 1 JNDIMapXMBean jmx-console view”.

Figure 2.18. The Version 1 JNDIMapXMBean jmx-console view

Notice that the JMX Console now displays the full attribute description as specified in the XMBean descriptor rather than MBean Attribute text seen in standard MBean implementations. Scroll down to the operations and you will also see that these now also have nice descriptions of their function and parameters.

In version 2 of the XMBean we add support for persistence of the XMBean attributes. The updated XMBean deployment descriptor is given below.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mbean PUBLIC
          "-//JBoss//DTD JBOSS XMBEAN 1.0//EN"
          "http://www.jboss.org/j2ee/dtd/jboss_xmbean_1_0.dtd">
<mbean>
    <description>The JNDIMap XMBean Example Version 2</description>
    <descriptors>
        <persistence persistPolicy="OnUpdate" persistPeriod="10"
            persistLocation="${jboss.server.data.dir}" persistName="JNDIMap.ser"/>
        <currencyTimeLimit value="10"/>
        <state-action-on-update value="keep-running"/>
        <persistence-manager value="org.jboss.mx.persistence.ObjectStreamPersistenceManager"/>
    </descriptors>   <class>org.jboss.test.jmx.xmbean.JNDIMap</class>
    <constructor>
        <description>The default constructor</description>
        <name>JNDIMap</name>
    </constructor>  
    <!-- Attributes -->
    <attribute access="read-write" getMethod="getJndiName" setMethod="setJndiName">
        <description>
            The location in JNDI where the Map we manage will be bound
        </description>
        <name>JndiName</name>
        <type>java.lang.String</type>
        <descriptors>
            <default value="inmemory/maps/MapTest"/>
        </descriptors>
    </attribute>
    <attribute access="read-write" getMethod="getInitialValues"
               setMethod="setInitialValues">
        <description>The array of initial values that will be placed into the
            map associated with the service. The array is a collection of
            key,value pairs with elements[0,2,4,...2n] being the keys and
            elements [1,3,5,...,2n+1] the associated values</description>
        <name>InitialValues</name>
        <type>[Ljava.lang.String;</type>
        <descriptors>
            <default value="key0,value0"/>
        </descriptors>
    </attribute>  
    <!-- Operations -->
    <operation>
        <description>The start lifecycle operation</description>
        <name>start</name>
    </operation>
    <operation>
        <description>The stop lifecycle operation</description>
        <name>stop</name>
    </operation>
    <operation impact="ACTION">
        <description>Put a value into the nap</description>
        <name>put</name>
        <parameter>
            <description>The key the value will be store under</description>
            <name>key</name>
            <type>java.lang.Object</type>
        </parameter>
        <parameter>
            <description>The value to place into the map</description>
            <name>value</name>
            <type>java.lang.Object</type>
        </parameter>
    </operation>
    <operation impact="INFO">
        <description>Get a value from the map</description>
        <name>get</name>
        <parameter>
            <description>The key to lookup in the map</description>
            <name>get</name>
            <type>java.lang.Object</type>
        </parameter>
        <return-type>java.lang.Object</return-type>
    </operation>  
    <!-- Notifications -->
    <notification>
        <description>The notification sent whenever a value is get into the map
            managed by the service</description>
        <name>javax.management.Notification</name>
        <notification-type>org.jboss.chap2.xmbean.JNDIMap.get</notification-type>
    </notification>
    <notification>
        <description>The notification sent whenever a value is put into the map
            managed by the service</description>
        <name>javax.management.Notification</name>
        <notification-type>org.jboss.chap2.xmbean.JNDIMap.put</notification-type>
    </notification>
</mbean>

Build, deploy and test the version 2 XMBean as follows:

[examples]$ ant -Dchap=chap2 -Dex=xmbean2 -Djboss.deploy.conf=rmi-adaptor run-example
...
run-examplexmbean2:
     [java] JNDIMap Class: org.jboss.mx.modelmbean.XMBean
     [java] JNDIMap Operations: 
     [java]  + void start()
     [java]  + void stop()
     [java]  + void put(java.lang.Object chap2.xmbean:service=JNDIMap,java.lang.Object cha
p2.xmbean:service=JNDIMap)
     [java]  + java.lang.Object get(java.lang.Object chap2.xmbean:service=JNDIMap)
     [java]  + java.lang.String getJndiName()
     [java]  + void setJndiName(java.lang.String chap2.xmbean:service=JNDIMap)
     [java]  + [Ljava.lang.String; getInitialValues()
     [java]  + void setInitialValues([Ljava.lang.String; chap2.xmbean:service=JNDIMap)
     [java] handleNotification, event: null
     [java] key=key10, value=value10
     [java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:s
ervice=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.put,sequenceNumber=7,timeStamp=10986326
93716,message=null,userData=null]
     [java] JNDIMap.put(key1, value1) successful
     [java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:s
ervice=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.get,sequenceNumber=8,timeStamp=10986326
93857,message=null,userData=null]
     [java] JNDIMap.get(key0): null
     [java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:s
ervice=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.get,sequenceNumber=9,timeStamp=10986326
93896,message=null,userData=null]
     [java] JNDIMap.get(key1): value1
     [java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:s
ervice=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.put,sequenceNumber=10,timeStamp=1098632
693925,message=null,userData=null]

There is nothing manifestly different about this version of the XMBean at this point because we have done nothing to test that changes to attribute value are actually persisted. Perform this test by running example xmbean2a several times:

[examples] ant -Dchap=chap2 -Dex=xmbean2a run-example
...
     [java] InitialValues.length=2
     [java] key=key10, value=value10

[examples] ant -Dchap=chap2 -Dex=xmbean2a run-example
...
     [java] InitialValues.length=4
     [java] key=key10, value=value10
     [java] key=key2, value=value2

[examples] ant -Dchap=chap2 -Dex=xmbean2a run-example
...
     [java] InitialValues.length=6
     [java] key=key10, value=value10
     [java] key=key2, value=value2
                    [java] key=key3, value=value3

The org.jboss.chap2.xmbean.TestXMBeanRestart used in this example obtains the current InitialValues attribute setting, and then adds another key/value pair to it. The client code is shown below.

package org.jboss.chap2.xmbean;

import javax.management.Attribute;
import javax.management.ObjectName;
import javax.naming.InitialContext;

import org.jboss.jmx.adaptor.rmi.RMIAdaptor;

/**
 *  A client that demonstrates the persistence of the xmbean
 *  attributes. Every time it run it looks up the InitialValues
 *  attribute, prints it out and then adds a new key/value to the
 *  list.
 *  
 *  @author [email protected]
 *  @version $Revision: 1.5 $
 */
public class TestXMBeanRestart
{
    /**
     * @param args the command line arguments
     */
    public static void main(String[] args) throws Exception
    {
	InitialContext ic = new InitialContext();
	RMIAdaptor server = (RMIAdaptor) ic.lookup("jmx/rmi/RMIAdaptor");
	
	// Get the InitialValues attribute
	ObjectName name = new ObjectName("chap2.xmbean:service=JNDIMap");
	String[] initialValues = (String[])
	    server.getAttribute(name, "InitialValues");
	System.out.println("InitialValues.length="+initialValues.length);
	int length = initialValues.length;
	for (int n = 0; n < length; n += 2) {
	    String key = initialValues[n];
	    String value = initialValues[n+1];
	    
	    System.out.println("key="+key+", value="+value);
	}
	// Add a new key/value pair
	String[] newInitialValues = new String[length+2];
	System.arraycopy(initialValues, 0, newInitialValues,
			 0, length);
	newInitialValues[length] = "key"+(length/2+1);
	newInitialValues[length+1] = "value"+(length/2+1);
	
	Attribute ivalues = new
	    Attribute("InitialValues", newInitialValues);
	server.setAttribute(name, ivalues);
    }
}

At this point you may even shutdown the JBoss server, restart it and then rerun the initial example to see if the changes are persisted across server restarts:

[examples]$ ant -Dchap=chap2 -Dex=xmbean2 run-example
...
 
run-examplexmbean2:
     [java] JNDIMap Class: org.jboss.mx.modelmbean.XMBean
     [java] JNDIMap Operations: 
     [java]  + void start()
     [java]  + void stop()
     [java]  + void put(java.lang.Object chap2.xmbean:service=JNDIMap,java.lang.Object cha
p2.xmbean:service=JNDIMap)
     [java]  + java.lang.Object get(java.lang.Object chap2.xmbean:service=JNDIMap)
     [java]  + java.lang.String getJndiName()
     [java]  + void setJndiName(java.lang.String chap2.xmbean:service=JNDIMap)
     [java]  + [Ljava.lang.String; getInitialValues()
     [java]  + void setInitialValues([Ljava.lang.String; chap2.xmbean:service=JNDIMap)
     [java] handleNotification, event: null
     [java] key=key10, value=value10
     [java] key=key2, value=value2
     [java] key=key3, value=value3
     [java] key=key4, value=value4
     [java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:s
ervice=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.put,sequenceNumber=3,timeStamp=10986336
64712,message=null,userData=null]
     [java] JNDIMap.put(key1, value1) successful
     [java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:s
ervice=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.get,sequenceNumber=4,timeStamp=10986336
64821,message=null,userData=null]
     [java] JNDIMap.get(key0): null
     [java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:s
ervice=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.get,sequenceNumber=5,timeStamp=10986336
64860,message=null,userData=null]
     [java] JNDIMap.get(key1): value1
     [java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:s
ervice=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.put,sequenceNumber=6,timeStamp=10986336
64877,message=null,userData=null]
     [java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:s
ervice=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.put,sequenceNumber=7,timeStamp=10986336
64895,message=null,userData=null]
     [java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:s
ervice=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.put,sequenceNumber=8,timeStamp=10986336
64899,message=null,userData=null]
     [java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:s
ervice=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.put,sequenceNumber=9,timeStamp=10986336
65614,message=null,userData=null]   

You see that the last InitialValues attribute setting is in fact visible.

The last example version of the JNDIMap XMBean will demonstrate customization of the server interceptor stack as well as exposing a subset of the XMBean management interface via a typed proxy to a remote client using RMI/JRMP. On the server side we will add a simple security interceptor that only allows access to attributes or operations by a user specified in the interceptor configuration. We will also use another custom interceptor to implement the MBean detached invoker pattern described in Section 2.7, “Remote Access to Services, Detached Invokers”. By implementing this pattern in an invoker rather than the XMBean, we demonstrate how to introduce a remote access aspect without having to modify the existing JNDIMap implementation.

We will use the JRMPProxyFactory service to expose the ClientInterface to remote clients.

public interface ClientInterface
{
    public String[] getInitialValues();
    public void setInitialValues(String[] keyValuePairs);
    public Object get(Object key);
    public void put(Object key, Object value);
} 

Our test client will obtain the ClientInterface proxy from JNDI and interact with the XMBean through RMI style calls instead of the RMIAdaptor and MBean Server style used previously.

package org.jboss.chap2.xmbean;

import javax.naming.InitialContext;
import org.jboss.security.SecurityAssociation;
import org.jboss.security.SimplePrincipal;

/** 
 *  A client that accesses an XMBean through its RMI interface
 *  @author [email protected]
 *  @version $Revision: 1.5 $
 */
public class TestXMBean3
{
    
    /**
     * @param args the command line arguments
     */
    public static void main(String[] args) throws Exception
    {
        InitialContext ic = new InitialContext();
        ClientInterface xmbean = (ClientInterface) 
            ic.lookup("secure-xmbean/ClientInterface");
        
        // This call should fail because we have not set a security context
        try {
            String[] tmp = xmbean.getInitialValues();
            throw new IllegalStateException("Was able to call getInitialValues");
        } catch(Exception e) {
            System.out.println("Called to getInitialValues failed as expected: "
                               + e.getMessage());
        }
        
        // Set a security context using the SecurityAssociation
        SecurityAssociation.setPrincipal(new SimplePrincipal("admin"));
        
        // Get the InitialValues attribute
        String[] initialValues = xmbean.getInitialValues();
        for(int n = 0; n < initialValues.length; n += 2) {
            String key = initialValues[n];
            String value = initialValues[n+1];
            
            System.out.println("key="+key+", value="+value);
        }
        
        // Invoke the put(Object, Object) op
        xmbean.put("key1", "value1");
        System.out.println("JNDIMap.put(key1,
                        value1) successful");
        Object result0 = xmbean.get("key0");
        System.out.println("JNDIMap.get(key0): "+result0);
        Object result1 = xmbean.get("key1");
        System.out.println("JNDIMap.get(key1): "+result1);
        
        // Change the InitialValues
        initialValues[0] += ".1";
        initialValues[1] += ".2";
        xmbean.setInitialValues(initialValues);
        
        initialValues = xmbean.getInitialValues();
        for(int n = 0; n < initialValues.length; n += 2) {
            String key = initialValues[n];
            String value = initialValues[n+1];
            
            System.out.println("key="+key+", value="+value);
        }
    }
}

The deployment descriptor is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mbean PUBLIC
          "-//JBoss//DTD JBOSS XMBEAN 1.0//EN"
          "http://www.jboss.org/j2ee/dtd/jboss_xmbean_1_0.dtd"
          [<!ATTLIST interceptor adminName CDATA #IMPLIED>]>
<mbean>
    <description>The JNDIMap XMBean Example Version 3</description>
    <descriptors>
        <interceptors>
            <interceptor code="org.jboss.chap2.xmbean.ServerSecurityInterceptor" 
                         adminName="admin"/>
            <interceptor code="org.jboss.chap2.xmbean.InvokerInterceptor"/>
            <interceptor code="org.jboss.mx.interceptor.PersistenceInterceptor2"/>
            <interceptor code="org.jboss.mx.interceptor.ModelMBeanInterceptor"/>
            <interceptor code="org.jboss.mx.interceptor.ObjectReferenceInterceptor"/>
        </interceptors>
        <persistence persistPolicy="Never"/>
        <currencyTimeLimit value="10"/>
        <state-action-on-update value="keep-running"/>
    </descriptors>
    <class>org.jboss.test.jmx.xmbean.JNDIMap</class>
    <constructor>
        <description>The default constructor</description>
        <name>JNDIMap</name>
    </constructor>  
    <!-- Attributes -->
    <attribute access="read-write" getMethod="getJndiName" setMethod="setJndiName">
        <description>
            The location in JNDI where the Map we manage will be bound
        </description>
        <name>JndiName</name>
        <type>java.lang.String</type>
        <descriptors>
            <default value="inmemory/maps/MapTest"/>
        </descriptors>
    </attribute>
    <attribute access="read-write" getMethod="getInitialValues" 
               setMethod="setInitialValues">
        <description>The array of initial values that will be placed into the
            map associated with the service. The array is a collection of
            key,value pairs with elements[0,2,4,...2n] being the keys and
            elements [1,3,5,...,2n+1] the associated values</description>
        <name>InitialValues</name>
        <type>[Ljava.lang.String;</type>
        <descriptors>
            <default value="key0,value0"/>
        </descriptors>
    </attribute>  
    <!-- Operations -->
    <operation>
        <description>The start lifecycle operation</description>
        <name>start</name>
    </operation>
    <operation>
        <description>The stop lifecycle operation</description>
        <name>stop</name>
    </operation>
    <operation impact="ACTION">
        <description>Put a value into the nap</description>
        <name>put</name>
        <parameter>
            <description>The key the value will be store under</description>
            <name>key</name>
            <type>java.lang.Object</type>
        </parameter>
        <parameter>
            <description>The value to place into the map</description>
            <name>value</name>
            <type>java.lang.Object</type>
        </parameter>
    </operation>
    <operation impact="INFO">
        <description>Get a value from the map</description>
        <name>get</name>
        <parameter>
            <description>The key to lookup in the map</description>
            <name>get</name>
            <type>java.lang.Object</type>
        </parameter>
        <return-type>java.lang.Object</return-type>
    </operation>
</mbean>

The addition over the previous versions of the JNDIMap XMBean is the interceptors element shown in bold in the listing. This defines the interceptor stack through which all MBean attribute access and operations pass. The first two interceptors, org.jboss.chap2.xmbean.ServerSecurityInterceptor and org.jboss.chap2.xmbean.InvokerInterceptor are the example custom interceptors. The remaining three interceptors are the standard ModelMBean interceptors. Because we have a persistence policy of Never, we could in fact remove the standard org.jboss.mx.interceptor.PersistenceInterceptor2. The JMX interceptors are an ordered chain of filters. The standard base class of an interceptor is shown below.

package org.jboss.mx.interceptor;

import javax.management.MBeanInfo;
import org.jboss.mx.server.MBeanInvoker;

/**
 * Base class for all interceptors.
 *
 * @see org.jboss.mx.interceptor.StandardMBeanInterceptor
 * @see org.jboss.mx.interceptor.LogInterceptor
 *
 * @author <a href="mailto:[email protected]">Juha Lindfors</a>.
 * @version $Revision: 1.5 $
 *
 */
public class AbstractInterceptor implements Interceptor
{
    // Attributes ----------------------------------------------------
    protected Interceptor next = null;
    protected String name = null;
    protected MBeanInfo info;
    protected MBeanInvoker invoker;
    
    // Constructors --------------------------------------------------
    public AbstractInterceptor()
    {
        this(null);
    }
    public AbstractInterceptor(String name)
    {
        this.name = name;
    }
    public AbstractInterceptor(MBeanInfo info,
                               MBeanInvoker invoker)
    {
        this.name = getClass().getName();
        this.info = info;
        this.invoker = invoker;
    }
    
    // Public --------------------------------------------------------
    public Object invoke(Invocation invocation) 
        throws InvocationException
    {
        return getNext().invoke(invocation);
    }
    
    public Interceptor getNext()
    {
        return next;
    }
    
    public Interceptor setNext(Interceptor interceptor)
    {
        this.next = interceptor;
        return interceptor;
    }
    
}

The custom interceptors for the version 3 XMBean example are the ServerSecurityInterceptor and the InvokerInterceptor. The ServerSecurityInterceptor intercepts invoke operations and validates that the Invocation context include an admin principal.

package org.jboss.chap2.xmbean;

import java.security.Principal;

import org.jboss.logging.Logger;
import org.jboss.mx.interceptor.AbstractInterceptor;
import org.jboss.mx.interceptor.Invocation;
import org.jboss.mx.interceptor.InvocationException;
import org.jboss.security.SimplePrincipal;


/** 
 * A simple security interceptor example that restricts access to a
 * single principal
 *
 * @author [email protected]
 * @version $Revision: 1.5 $
 */
 
public class ServerSecurityInterceptor extends AbstractInterceptor
{
    private static Logger log = Logger.getLogger(ServerSecurityInterceptor.class);
    private SimplePrincipal admin = new SimplePrincipal("admin");
    
    public String getAdminName()
    {
        return admin.getName();
    }
    public void setAdminName(String name)
    {
        admin = new SimplePrincipal(name);
    }

    public Object invoke(Invocation invocation) 
        throws InvocationException
    {
        String opName = invocation.getName();

        // If this is not the invoke(Invocation) op just pass it along
        if (opName.equals("invoke") == false) {
            return getNext().invoke(invocation);
        }

        Object[] args = invocation.getArgs();
        org.jboss.invocation.Invocation invokeInfo =
            (org.jboss.invocation.Invocation) args[0];
        Principal caller = invokeInfo.getPrincipal();
        log.info("invoke, opName="+opName+", caller="+caller);

        // Only the admin caller is allowed access
        if (caller == null || caller.equals(admin) == false) {
            throw new InvocationException(new SecurityException("Caller=" + 
                                                                caller + 
                                                                " is not allowed access"));
        }
        return getNext().invoke(invocation);
    }
}

The InvokerInterceptor implements the detached invoker pattern. This is discussed in detail in Section 2.7, “Remote Access to Services, Detached Invokers”.

package org.jboss.chap2.xmbean;

import java.lang.reflect.Method;
import java.util.HashMap;
import javax.management.Descriptor;
import javax.management.MBeanInfo;

import org.jboss.logging.Logger;
import org.jboss.mx.interceptor.AbstractInterceptor;
import org.jboss.mx.interceptor.Invocation;
import org.jboss.mx.interceptor.InvocationException;
import org.jboss.mx.server.MBeanInvoker;
import org.jboss.invocation.MarshalledInvocation;

/** An interceptor that handles the
 *
 * @author [email protected]
 * @version $Revision: 1.5 $
 */
public class InvokerInterceptor 
    extends AbstractInterceptor
{
    private static Logger log = Logger.getLogger(InvokerInterceptor.class);
    private Class exposedInterface = ClientInterface.class;
    private HashMap methodMap = new HashMap();
    private HashMap invokeMap = new HashMap();

    public InvokerInterceptor(MBeanInfo info,
                              MBeanInvoker invoker)
    {
        super(info, invoker);
        try {
            Descriptor[] descriptors = invoker.getDescriptors();
            Object resource = invoker.getResource();
            Class[] getInitialValuesSig = {};
            Method getInitialValues =
		exposedInterface.getDeclaredMethod("getInitialValues",
						   getInitialValuesSig);
            Long hash = new Long(MarshalledInvocation.calculateHash(getInitialValues));
            InvocationInfo invokeInfo = 
		new InvocationInfo("InitialValues",
				   Invocation.ATTRIBUTE, 
				   Invocation.READ, getInitialValuesSig,
				   descriptors, resource);
            methodMap.put(hash, getInitialValues);
            invokeMap.put(getInitialValues, invokeInfo);
            log.debug("getInitialValues hash:"+hash);

            Class[] setInitialValuesSig = {String[].class};
            Method setInitialValues = 
		exposedInterface.getDeclaredMethod("setInitialValues",
						   setInitialValuesSig);

            hash = new Long(MarshalledInvocation.calculateHash(setInitialValues));
            invokeInfo = new InvocationInfo("InitialValues",
                                            Invocation.ATTRIBUTE, 
					    Invocation.WRITE, 
					    setInitialValuesSig,
                                            descriptors, resource);
            methodMap.put(hash, setInitialValues);
            invokeMap.put(setInitialValues, invokeInfo);
            log.debug("setInitialValues hash:"+hash);

            Class[] getSig = {Object.class};
            Method get = exposedInterface.getDeclaredMethod("get",
                                                            getSig);
            hash = new Long(MarshalledInvocation.calculateHash(get));
            invokeInfo = new InvocationInfo("get",
                                            Invocation.OPERATION, 
					    Invocation.READ, getSig,
                                            descriptors, resource);
            methodMap.put(hash, get);
            invokeMap.put(get, invokeInfo);
            log.debug("get hash:"+hash);

            Class[] putSig = {Object.class, Object.class};
            Method put = exposedInterface.getDeclaredMethod("put",
                                                            putSig);
            hash = new Long(MarshalledInvocation.calculateHash(put));
            invokeInfo = new InvocationInfo("put",
                                            Invocation.OPERATION, 
					    Invocation.WRITE, putSig,
                                            descriptors, resource);
            methodMap.put(hash, put);
            invokeMap.put(put, invokeInfo);
            log.debug("putt hash:"+hash);
        } catch(Exception e) {
            log.error("Failed to init InvokerInterceptor", e);
        }
    }

    public Object invoke(Invocation invocation) 
        throws InvocationException
    {
        String opName = invocation.getName();
        Object[] args = invocation.getArgs();
        Object returnValue = null;
        if (opName.equals("invoke") == true) {
            org.jboss.invocation.Invocation invokeInfo =
                (org.jboss.invocation.Invocation) args[0];
            // Set the method hash to Method mapping
            if (invokeInfo instanceof MarshalledInvocation) {
                MarshalledInvocation mi = (MarshalledInvocation) invokeInfo;
                mi.setMethodMap(methodMap);
            }

            // Invoke the exposedInterface method via reflection if
            // this is an invoke
            Method method = invokeInfo.getMethod();
            Object[] methodArgs = invokeInfo.getArguments();
            InvocationInfo info = (InvocationInfo) invokeMap.get(method);
            Invocation methodInvocation = info.getInvocation(methodArgs);
            returnValue = getNext().invoke(methodInvocation);
        } else {
            returnValue = getNext().invoke(invocation);
        }
        return returnValue;
    }

    /**
     * A class that holds the ClientInterface method info needed to build
     * the JMX Invocation to pass down the interceptor stack.
     */
    private class InvocationInfo
    {
        private int type;
        private int impact;
        private String name;
        private String[] signature;
        private Descriptor[] descriptors;
        private Object resource;


        InvocationInfo(String name, int type, int impact,
                       Class[] signature, Descriptor[] descriptors, 
                       Object resource)
        {
            this.name = name;
            this.type = type;
            this.impact = impact;
            this.descriptors = descriptors;
            this.resource = resource;
            this.signature = new String[signature.length];
            for(int s = 0; s < signature.length; s ++) {
                this.signature[s] = signature[s].getName();
            }
        }

        Invocation getInvocation(Object[] args)
        {
            return new Invocation(name, type, impact, args, signature,
                                  descriptors, resource);
        }
    }
}

The deployment descriptor should include the interceptor stack.

<?xml version='1.0' encoding='UTF-8' ?>
<server>
    <mbean code="org.jboss.chap2.xmbean.JNDIMap"
        name="chap2.xmbean:service=JNDIMap,version=3" 
        xmbean-dd="META-INF/jndimap-xmbean3.xml">
        <attribute name="JndiName">inmemory/maps/MapTest</attribute>
        <depends>jboss:service=Naming</depends>
    </mbean>  
    <!-- The JRMP invoker proxy configuration for
                        the naming service -->
    <mbean code="org.jboss.invocation.jrmp.server.JRMPProxyFactory" 
           name="jboss.test:service=proxyFactory,type=jrmp,target=JNDIMap">
        <!-- Use the standard JRMPInvoker from
                        conf/jboss-service.xml -->
        <attribute name="InvokerName">jboss:service=invoker,type=jrmp</attribute>
        <attribute name="TargetName">chap2.xmbean:service=JNDIMap,version=3</attribute>
        <attribute name="JndiName">secure-xmbean/ClientInterface</attribute>
        <attribute name="ExportedInterface">
            org.jboss.chap2.xmbean.ClientInterface
        </attribute>
        <attribute name="ClientInterceptors">
            <iterceptors>
                <interceptor>org.jboss.proxy.ClientMethodInterceptor</interceptor>
                <interceptor>org.jboss.proxy.SecurityInterceptor</interceptor>
                <interceptor>org.jboss.invocation.InvokerInterceptor</interceptor>
            </iterceptors>
        </attribute>
        <depends>jboss:service=invoker,type=jrmp</depends>
        <depends>chap2.xmbean:service=JNDIMap,version=3</depends>
    </mbean>
</server>

[examples] ant -Dchap=chap2 -Dex=xmbean3 config
...
config:
     [echo] Preparing rmi-adaptor configuration fileset
     [copy] Copying 60 files to /tmp/jboss-3.2.6/server/rmi-adaptor
   [delete] Deleting directory /tmp/jboss-3.2.6/server/rmi-adaptor/deploy/jmx-invoker-adap
tor-server.sar
   [delete] Deleting directory /tmp/jboss-3.2.6/server/rmi-adaptor/deploy/management

[examples]$ ant -Dchap=chap2 -Dex=xmbean3 run-example
...
run-examplexmbean3:
     [java] Called to getInitialValues failed as expected: Caller=null is not allowed access
     [java] key=key0, value=value0
     [java] JNDIMap.put(key1, value1) successful
     [java] JNDIMap.get(key0): null
     [java] JNDIMap.get(key1): value1
     [java] key=key0.1, value=value0.2

[examples]$ ant -Dchap=chap2 -Dex=xmbean3 run-example
...
run-examplexmbean3:
     [java] Called to getInitialValues failed as expected: Caller=null is not allowed access
     [java] key=key0.1, value=value0.2
     [java] JNDIMap.put(key1, value1) successful
     [java] JNDIMap.get(key0): null
     [java] JNDIMap.get(key1): value1
     [java] key=key0.1.1, value=value0.2.2