JBoss Custom MBean Plugin

Extending the JBoss Plugin

The bundled JBoss plugin provides auto-inventory, monitoring, control and log/config tracking for the JBoss server and J2EE services. The majority of this functionality is implemented via JMX and can be extended using XML plugins to manage custom MBeans. There are examples of such plugins included with the agent and pdk bundles in the pdk/examples/services/ directory. These include:

hq-plugin-deployer-plugin.xml - Management via the HQ Plugin Deployer MBean (Download)

jboss-entity-container-plugin.xml - Management via JBoss Entity Container MBeans (Download)

Plugin Components

Service Type

ObjectName

Configuration Properties

Metrics

Control

Auto Inventory

Custom Properties

Log/Config Tracking

Service Type

The JBoss server type defines several service types such as EJBs, Connection Pools and JMS Queues. Custom plugins define additional service types to provide management via custom MBeans. The service tag is used to create new types like so:

<service name="HQ Plugin Deployer"
         server="JBoss"
         version="4.0">
</service>

The server attribute must be that of JBoss and version attribute one of 3.2 or 4.0. The name attribute is the choice of the plugin implementor. These services will become part of the HQ inventory model, displayed along with the builtin JBoss service types throughout the UI and shell. JBoss service extensions will also inherit the server's configuration properties used to connect to the MBeanServer:

java.naming.provider.url

java.naming.security.principal

java.naming.security.credentials

ObjectName

In order to access custom MBeans, the plugin must define its JMX ObjectName to be used with various MBeanServer interface methods. Only one ObjectName is defined per-service type using the property tag within the service tag:

<property name="OBJECT_NAME"
          value="hyperic.jmx:type=Service,name=ProductPluginDeployer"/>

Configuration Properties

In the example above, the OBJECT_NAME is hard-coded since there is only one instance of the Plugin Deployer MBean. Configuration Properties are used to support multiple instances that follow the same ObjectName pattern. For example, the Entity Container plugin uses an ObjectName with the following pattern:

<property name="OBJECT_NAME"
          value="jboss.j2ee:jndiName=%jndiName%,service=EJB"/>

Where the ObjectName Domain is always jboss.j2ee and service attribute value is always EJB, but the jndiName attribute will be different for each instance of the MBean. The Entity Container plugin defines a config option with the name jndiName:

<config>
  <option name="jndiName"
          description="JNDI Name"
          default="LocalMeasurementTemplate"/>
</config>

As with other plugins, these config options will be displayed in the Inventory tab of the service resource in the UI.

The value of the jndiName attribute (%jndiName%) within the OBJECT_NAME is replaced with the value of the configuration property when used by the plugin, for example:

"jboss.j2ee:jndiName=LocalMeasurementTemplate,service=EJB"

Metrics

Metrics are defined just as they are with other plugins, but in the case of custom JBoss services the OBJECT_NAME property is used to compose the metric template attribute:

<metric name="Create Count"
        template="${OBJECT_NAME}:CreateCount"
        category="THROUGHPUT"
        indicator="true"
        collectionType="trendsup"/>

This results in the template being expanded, for example, to:

template="jboss.j2ee:jndiName=LocalMeasurementTemplate,service=EJB:CreateCount"

Where CreateCount is an attribute of the MBean and can be collected internally using the MBeanServer interface like so:

ObjectName name = new ObjectName("jboss.j2ee:jndiName=LocalMeasurementTemplate,service=EJB");

return MBeanServer.getAttribute(name, "CreateCount");

The MBean interface attributes collected by jboss-entity-container-plugin.xml as metrics are as follows:

public interface EntityContainerMBean {

    public String getStateString();

    public long getCreateCount();

    public long getRemoveCount();

    public long getCacheSize();

}

Control

With the OBJECT_NAME property defined, MBean operations can be exposed as HQ control actions simply by adding the list of method names:

<actions include="stop,start,flushCache"/>

The plugin must also define the control implementation class (resides in jboss-plugin.jar):

<plugin type="control"
        class="org.hyperic.hq.plugin.jboss.JBossServiceControlPlugin"/>

The control actions will then be invoked as MBean operations by the JBoss plugin like so:

ObjectName name = new ObjectName("jboss.j2ee:jndiName=LocalMeasurementTemplate,service=EJB");

return MbeanServer.invoke(name, "flushCache", new Object[0], new String[0]);

Which maps to the following MBean operation:

public interface EntityContainerMBean {

    public void flushCache();

}

If an MBean operation requires arguments, they can be passed in using the HQ control UI. Only String arguments are currently supported.
The HQ Plugin Deployer example provides the following control actions:

<actions include="setProperty,getProperty"/>

Which map to the following MBean operations:

public interface ProductPluginDeployerMBean {

    public void setProperty(String name, String value);

    public String getProperty(String name);

}

Auto Inventory

Auto Inventory is supported for custom JBoss services, again driven by the OBJECT_NAME property. Not enabled by default, to enable use the following within the service tag:

<plugin type="autoinventory"/>

The JBoss plugin uses the MBeanServer.queryNames method to discover a service for each MBean instance. In the case where the OBJECT_NAME contains configuration properties, the properties will be auto-configured.

Custom Properties

Discovery of Custom Properties is supported, again using the OBJECT_NAME and MBeanServer.getAttribute. Simply define a properties tag with any number of property tags where the name attribute value is that of an MBean attribute:

<properties>
  <property name="RegisteredPluginNames"
            description="Registered Product Plugins"/>
</properties>

Which maps to the following MBean interface method:

public interface ProductPluginDeployerMBean {

    public ArrayList getRegisteredPluginNames();

}

Log/Config Tracking

Should your plugin wish to track log and/or config files, simply use the generic classes which are included in pdk/lib/hq-product.jar and available for use by all plugins:

<property name="DEFAULT_LOG_FILE"
          value="log/mybean.log"/>

<plugin type="log_track"
        class="org.hyperic.hq.product.Log4JLogTrackPlugin"/>

<property name="DEFAULT_CONFIG_FILE"
          value="conf/mybean-service.xml,conf/mybean.policy"/>

<plugin type="config_track"
        class="org.hyperic.hq.product.ConfigFileTrackPlugin"/>

Future versions of the JBoss plugin will add support for log/config tracking via javax.management.Notification related classes.