CHAPTER 10 MBean Services Miscellany

This chapter discusses useful MBean services that are not discussed elsewhere either because they are utility services not necessary for running JBoss, or they don't fit into a current section of the book.

System Properties Management

The management of system properties can be done using the org.jboss.varia.property.SystemPropertiesService MBean. It supports setting of the VM global property values just as java.lang.System.setProperty method and the -Dproperty=value VM command line arguments do.

Its configurable attributes include:

Properties: a specification of multiple property name=value pairs using the java.util.Properites.load(java.io.InputStream) method format. Each property=value statement is given on a separate line within the body of the Properties attribute element.
URLList: a comma seperated list of URL strings from which to load properties file formatted content. If a component in the list is a relative path rather than a URL it will be treated as a file path relative to the <jboss-dist>/server/<config> directory. For example, a component of "conf/local.properties" would be treated as a file URL that points to the <jboss-dist>/server/default/conf/local.properties file when running with the "default" configuration file set.

Both attributes are illustrated in See An example SystemPropertiesService jboss-service descriptor..

An example SystemPropertiesService jboss-service descriptor

<mbean code="org.jboss.varia.property.SystemPropertiesService"

name="jboss.util:type=Service,name=SystemProperties">

http://somehost/some-location.properties,

./conf/somelocal.properties

</attribute>

property1=This is the value of my property

property2=This is the value of my other property

</attribute>

</mbean>

</server>

Property Editor Management

Support for managing java.bean.PropertyEditor instances is available through the org.jboss.varia.property.PropertyEditorManagerService MBean. This is a simple service that help define PropertyEditors using the java.bean.PropertyEditorManager class. This service is used in the main jboss-service.xml file to preload the custom JBoss PropertyEditor implementations. This is necessary for some JDK1.3.0 VMs that will only load PropertyEditors from the system classpath.

Its supported attributes include:

BootstrapEditors: This is a listing of property_editor_class=editor_value_type_class pairs defining the PropertyEditor to type mappings that should be preloaded into the PropertyEditorManager class using its registerEditor (Class targetType, Class editorClass) method. The value type of this attribute is a string so that it may be set from a string without requiring a custom PropertyEditor .
Editors: This serves the same function as the BootstrapEditors attribute, but its type is a java.util.Properties class, and so setting this from a string value requires a custom PropertyEditor for Properties . In situations where custom PropertyEditor s can be loaded from the thread context class loader, this may be used instead of the BootstrapEditors attribute.
EditorSearchPath: This attribute allows one to set the PropertyEditorManager editor packages search path.

Services Binding Management

With all of the independently deployed services available in JBoss, running multiple instances on a given machine can be a tedious exercise in configuration file editing. The binding service, org.jboss.services.binding.ServiceBindingManager , allows one to map service attribute values from a central location. After a service's descriptor file is parsed and the initial attribute values have been applied to the service, the ServiceConfigurator queries the ServiceBindingManager to apply any overrides that may exist for the service. The ServicesBindingManager acts a coordinator between the ServiceConfigurator , a store of configuration overrides, the service configuration, and a configuration delegate that knows how to apply a configuration to a service. The classes in this act are shown in See Class diagram for the org.jboss.services.binding package of the ServiceBindingManager..

FIGURE 10-1. Class diagram for the org.jboss.services.binding package of the ServiceBindingManager

The first thing to note about the ServiceBindingManager is that it implements the JMX MBeanRegistration interface methods as its life cycle notification interface rather than the JBoss service interface. This is necessary because the ServiceBindingManager operates on other services attribute values. Attributes are set before any JBoss service life cycle methods are called, and so the ServiceBindingManager must be active as soon as it is registered with the MBeanServer . The setup of the ServiceBindingManager occurs in the postRegister(Boolean) callback method.

The ServiceBindingManager is associated with a ServicesStore through a ServicesStoreFactory . The ServicesStoreFactory is set through an attribute of the ServiceBindingManager . The set of configurable attributes of the ServiceBindingManager include:

ServerName: The name of the server this manager is associated with. This is a logical name used to lookup ServiceConfig s from the ServicesStore .
StoreFactoryClassName: The name of the class that implements the ServicesStoreFatory interface. You may provide your own implementation, or use the default XML based store org.jboss.services.binding.XMLServicesStoreFactory .
StoreURL: The URL of the configuration store contents. This is passed to the load(URL) method of the ServicesStore instance obtained from the ServicesStoreFactory .

A ServicesStore is just a collection of ServiceConfig objects keyed by a JBoss instance name and the JMX ObjectName of the service. A ServiceConfig is a collection of ServiceBinding objects and a ServicesConfigDelegate that knows how to map a ServiceBinding onto a target MBean. The ServiceConfig may also contain an arbitrary configuration for the delegate. A ServiceBinding is a named (interface, port) pair.

So what happens when the ServiceBindingManager is asked to override a service's configuration? The sequence of events is illustrated by See How the ServiceConfigurator queries the ServiceBindingManager..

FIGURE 10-2. How the ServiceConfigurator queries the ServiceBindingManager

The ServiceConfigurator queries the ServiceBindingManager to apply any configuration overrides for the MBean given by the applyServiceConfig method JMX ObjectName .
The ServiceBindingManager queries the ServicesStore for the ServiceConfig for the named service, specifying the identity of the JBoss server instance in which it is operating. This is an attribute of the ServiceBindingManager , and can be taken from a system property as we will see in an example. If the ServicesStore contains a configuration override for the indicated <serverName, serviceName> pair, it returns the ServiceConfig .
If there was a ServiceConfig , the ServiceBindingManager queries it for the name of the class implementing the ServicesConfigDelegate interface.
The ServicesConfigDelegate class is loaded using the thread context class loader and an instance is created.
The ServicesConfigDelegate instance is then asked to apply the ServiceConfig using the provided MBeanServer . The delegate would using the delegate config information along with the binding(s) to override the indicated attributes of the service by invoking attribute setters, or even operations on the service using the MBeanServer . The target service name is available in the ServiceConfig .

That is the generic overview of the ServiceBindingManager . Let's take a look at how you can use this service to bring up two JBoss instances of the default configuration set of services on the same machine to make this more concrete.

Running Two JBoss Instances

JBoss ships with a service configuration ServiceBindingManager for the along with a sample ServicesStore XML file for starting two JBoss instances on the same host. Here we will walk through the steps to bring up the two instances and look at the sample configuration. Start by making two server configuration file sets called jboss0 and jboss1 by running the following command from the book examples directory:

[nr@toki examples]$ ant -Dchap=chap10 -Dex=1 run-example

Buildfile: build.xml

...

run-example1:

[echo] Preparing jboss0 configuration fileset

[mkdir] Created dir: /tmp/jboss-3.2.3/server/jboss0

[copy] Copying 148 files to /tmp/jboss-3.2.3/server/jboss0

[copy] Copied 2 empty directories to /tmp/jboss-3.2.3/server/jboss0

[copy] Copying 1 file to /tmp/jboss-3.2.3/server/jboss0/conf

[copy] Copying 1 file to /tmp/jboss-3.2.3/server

[echo] Preparing jboss1 configuration fileset

[mkdir] Created dir: /tmp/jboss-3.2.3/server/jboss1

[copy] Copying 148 files to /tmp/jboss-3.2.3/server/jboss1

[copy] Copied 2 empty directories to /tmp/jboss-3.2.3/server/jboss1

BUILD SUCCESSFUL

Total time: 8 seconds

This creates duplicates of the server/default configuration file sets as server/jboss0 and server/jboss1, and then replaces the conf/jboss-service.xml descriptor with one that has the ServiceBindingManager configuration enabled as follows:

<mbean code="org.jboss.services.binding.ServiceBindingManager"

name="jboss.system:service=ServiceBindingManager">

<attribute name="ServerName">${jboss.server.name}</attribute>

<attribute name="StoreURL">${jboss.server.base.dir}/chap10ex1-bindings.xml</attribute>

org.jboss.services.binding.XMLServicesStoreFactory

</attribute>

</mbean>

The attribute values are:

ServerName: This is the unique name for the JBoss server instance that will be used to distinguish what configuration overrides to apply. Here the ${jboss.server.name} variable reference is the configuration file set directory name, either jboss0 or jboss1 in this example.
StoreURL: This is the location of the ServicesStore configuration data that defines the overrides for the jboss0 and jboss1 instances. The ${jboss.server.base.dir} variable reference is the URL to the root of the JBoss server directory. We are using the chap10ex1-bindings.xml which was installed as part of the example 1 setup.
StoreFactoryClassName: This the default XML based ServicesStore implement ion.

The chap10ex1-bindings.xml file contains two server configurations named jboss0 and jboss1. The jboss0 configuration uses the default settings for the ports, while the jboss1 configuration adds 100 to each port number. The bindings file is a duplicate of the docs/examples.binding-service.sample-bindings.xml with jboss0 and jboss1 as the server names.

FIGURE 10-3. The binding service XMLServicesStoreFactory DTD

The DTD showin in See The binding service XMLServicesStoreFactory DTD. is the one supported by the XMLServicesStoreFactory class. The elements are:

service-bindings: the root element of the configuration file. It contains one or more server elements.
server: This is the base of a JBoss server instance configuration. It has a required name attribute that defines the JBoss instance name to which it applies. This is the name that correlates with the ServiceBindingManager ServerName attribute value. The server element content consists of one or more service-config elements.
service-config: This element represents a configuration override for an MBean service. It has a required name attribute that is the JMX ObjectName string of the MBean service the configuration applies to. It also has a required delegateClass name attribute that specifies the class name of the ServicesConfigDelegate implementation that knows how to handle bindings for the target service. Its contents consists of an optional delegate-config element and one or more binding elements.
binding: A binding element specifies a named port, address pair. It has an optional name that can be used to provide multiple binding for a service. An example would be multiple virtual hosts for a web container. The port and address are specified via the optional port and host attributes respectively. If the port is not specified it defaults to 0 meaning choose an anonymous port. If the host is not specified it defaults to null meaning any address.
delegate-config: The delegate-config element is an arbitrary XML fragment for use by the ServicesConfigDelegate implementation. The hostName and portName attributes only apply to the AttributeMappingDelegate of the example and are there to prevent DTD aware editors from complaining about their existence in the AttributeMappingDelegate configurations. Generally both the attributes and content of the delegate-config is arbitrary, but there is no way to specify and a element can have any number of attributes with a DTD.

The two ServicesConfigDelegate are AttributeMappingDelegate and XSLTConfigDelegate . The AttributeMappingDelegate class is an implementation of the ServicesConfigDelegate that expects a delegate-config element of the form:

<delegate-config portName="portAttrName" hostName="hostAttrName">

<attribute name="someAttrName">someHostPortExpr</attribute>

...

</delegate-config>

where the portAttrName is the attribute name of the MBean service to which the binding port value should be applied, and the hostAttrName is the attribute name of the MBean service to which the binding host value should be applied. If the portName attribute is not specified then the binding port is not applied. Likewise, if the hostName attribute is not specified then the binding host is not applied. The optional attribute element(s) specify arbitrary MBean attribute names whose values are a function of the host and/or port settings. Any reference to ${host} in the attribute content is replaced with the host binding and any ${port} reference is replaced with the port binding. As of the 3.2.2RC4 release, the portName, hostName attribute values and attribute element content may reference system properties using the ${x} syntax that is supported by the JBoss services descriptor.

From the sample listing, lines 7-12 illustrate an example of the AttributeMappingDelegate usage:

<service-config name="jboss:service=Naming"

delegateClass="org.jboss.services.binding.AttributeMappingDelegate"

<delegate-config portName="Port"/>

</service-config>

Here the "jboss:service=Naming" MBean service has its Port attribute value overridden to 1099. The corresponding setting from the jboss1 server configuration overrides the port to 1199.

The XSLTConfigDelegate class is an implementation of the ServicesConfigDelegate that expects a delegate-config element of the form:

<delegate-config>

<xslt-config configName="ConfigurationElement"><![CDATA[

Any XSL document contents...

]]>

</xslt-config>

<xslt-param name="param-name">param-value</xslt-param>

...

</delegate-config>

The xslt-config child element content specifies an arbitrary XSL script fragment that is to be applied to the MBean service attribute named by the configName attribute. The named attribute must be of type org.w3c.dom.Element . The optional xslt-param elements specify XSL script parameter values for parameters used in the script. There are two XSL parameters defined by default called host and port, and their values are set to the configuration host and port bindings.

The XSLTConfigDelegate is used to transform services whose port/interface configuration is specified using a nested XML fragment. The following illustrates an example from the jboss1 server section which maps the Tomcat servlet container listening port to 8180 and maps the AJP listening port to 8109:

<service-config name="jboss.web:service=WebServer"

delegateClass="org.jboss.services.binding.XSLTConfigDelegate"

<delegate-config>

<xslt-config configName="Config"><![CDATA[

<xsl:stylesheet

xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'>

<xsl:output method="xml" />

<xsl:param name="port"/>

<xsl:variable name="portAJP" select="$port - 71"/>

<xsl:template match="/">

<xsl:apply-templates/>

</xsl:template>

<xsl:template match = "Connector">

<xsl:for-each select="@*">

<xsl:choose>

<xsl:when test="(name() = 'port' and . = '8080')">

<xsl:attribute name="port"><xsl:value-of select="$port" /></xsl:attribute>

</xsl:when>

<xsl:when test="(name() = 'port' and . = '8009')">

<xsl:attribute name="port"><xsl:value-of select="$portAJP" /></xsl:attribute>

</xsl:when>

<xsl:otherwise>

<xsl:attribute name="{name()}"><xsl:value-of select="." /></xsl:attribute>

</xsl:otherwise>

</xsl:choose>

</xsl:for-each>

</Connector>

</xsl:template>

<xsl:template match="*|@*">

<xsl:copy>

<xsl:apply-templates select="@*|node()"/>

</xsl:copy>

</xsl:template>

</xsl:stylesheet>

]]>

</xslt-config>

</delegate-config>

</service-config>

To test the sample configuration, start two JBoss instances using the jboss0 and jboss1 configuration file sets created previously by running the chap10 example1 build. Looking at the console for the service port numbers you should see the overridden mappings. For the jboss1 server for example, here are some of the non-standard ports that show up:

2004-05-06 13:39:27,346 INFO [org.jboss.naming.NamingService] Started jnpPort=1299, rmiPort=1298, backlog=50, bindAddress=/0.0.0.0, Client SocketFactory=null, Server SocketFactory=org.jboss.net.sockets.DefaultSocketFactory@ad093076

2004-05-06 13:39:27,445 INFO [org.jboss.naming.NamingService] Listening on port 1299

2004-05-06 13:39:36,152 DEBUG [org.apache.coyote.http11.Http11Protocol] Attribute port: 8280

2004-05-06 13:39:36,208 INFO [org.apache.coyote.http11.Http11Protocol] Initializing Coyote HTTP/1.1 on port 8280

2004-05-06 13:39:36,422 INFO [org.apache.coyote.http11.Http11Protocol] Starting Coyote HTTP/1.1 on port 8280

2004-05-06 13:39:36,645 DEBUG [org.apache.jk.server.JkCoyoteHandler] setProperty port 8209

2004-05-06 13:39:36,900 DEBUG [org.apache.jk.server.JkMain] Substituting port channelSocket.port 8209

2004-05-06 13:39:36,978 DEBUG [org.apache.jk.server.JkMain] Processing channelSocket::channelSocket port

2004-05-06 13:39:36,978 DEBUG [org.apache.jk.server.JkMain] Setting port on channelSocket org.apache.jk.common.ChannelSocket@1ee2de

2004-05-06 13:39:36,978 DEBUG [org.apache.jk.server.JkMain] setProperty org.apache.jk.common.ChannelSocket@1ee2de port=8209

Scheduling Tasks

Java includes a simple timer based capability through the java.util.Timer and java.util.TimerTask utility classes. JMX also includes a mechanism for scheduling JMX notifications at a given time with an optional repeat interval as the javax.management.timer.TimerMBean agent service.

JBoss includes two variations of the JMX timer service in the org.jboss.varia.scheduler.Scheduler and org.jboss.varia.scheduler.ScheduleManager MBeans. Both MBeans rely on the JMX timer service for the basic scheduling. They extend the behavior of the timer service as described in the following sections.

org.jboss.varia.scheduler.Scheduler

The Scheduler differs from the TimerMBean in that the Scheduler directly invokes a callback on an instance of a user defined class, or an operation of a user specified MBean.

InitialStartDate: Date when the initial call is scheduled. It can be either:
NOW: date will be the current time plus 1 seconds
A number representing the milliseconds since 1/1/1970
Date as String able to be parsed by SimpleDateFormat with default format pattern "M/d/yy h:mm a".If the date is in the past the Scheduler will search a start date in the future with respect to the initial repetitions and the period between calls. This means that when you restart the MBean (restarting JBoss etc.) it will start at the next scheduled time. When no start date is available in the future the Scheduler will not start.

For example, if you start your Schedulable everyday at Noon and you restart your JBoss server then it will start at the next Noon (the same if started before Noon or the next day if start after Noon).

InitialRepetitions: The number of times the scheduler will invoke the target's callback. If -1 then the callback will be repeated until the server is stopped.
StartAtStartup: A flag that determines if the Scheduler will start when it receives its startService life cycle notification. If true the Scheduler starts on its startup. If false, an explicit startSchedule operation must be invoked on the Scheduler to begin.
SchedulePeriod: The interval between scheduled calls in milliseconds. This value must be bigger than 0.
SchedulableClass: The fully qualified class name of the org.jboss.varia.scheduler.Schedulable interface implementation that is to be used by the Scheduler . The SchedulableArguments and SchedulableArgumentTypes must be populated to correspond to the constructor of the Schedulable implementation.
SchedulableArguments: A comma seperated list of arguments for the Schedulable implementation class constructor. Only primitive data types, String and classes with a constructor that accepts a String as its sole aregument are supported.
SchedulableArgumentTypes: A comma seperated list of argument types for the Schedulable implementation class constructor. This will be used to find the correct constructor via reflection. Only primitive data types, String and classes with a constructor that accepts a String as its sole aregument are supported.
SchedulableMBean: Specifies the fully qualified JMX ObjectName name of the schedulable MBean to be called. If the MBean is not available it will not be called but the remaining repetitions will be decremented. When using SchedulableMBean the SchedulableMBeanMethod must also be specified.
SchedulableMBeanMethod: Specifies the operation name to be called on the schedulable MBean. It can optionally be followed by an opening bracket, a comma seperated list of parameter keywords, and a closing bracket. The supported parameter keywords include:
NOTIFICATION which will be replaced by the timers notification instance (javax.management.Notification)
DATE which will be replaced by the date of the notification call (java.util.Date)
REPETITIONS which will be replaced by the number of remaining repetitions (long)
SCHEDULER_NAME which will be replaced by the ObjectName of the Scheduler
Any fully qualified class name which the Scheduler will set to null. This allows

A given Scheduler instance only support a single schedulable instance. If you need to configure multiple scheduled events you would use multiple Scheduler instances, each with a unique ObjectName . 10-2 gives an example of configuring a Scheduler to call a Schedulable implementation as well as a configuration for calling a MBean.

An example Scheduler jboss-service descriptor

<mbean code="org.jboss.varia.scheduler.Scheduler"

name="jboss.docs.chap10:service=Scheduler">

<attribute name="SchedulableClass">org.jboss.chap10.ex2.ExSchedulable</attribute>

<attribute name="SchedulableArguments">TheName,123456789</attribute>

<attribute name="SchedulableArgumentTypes">java.lang.String,long</attribute>

</mbean>

</server>

The SchedulableClass org.jboss.chap10.ex2.ExSchedulable example class is given in See The Listing 10-2 ExSchedulable class code..

The See An example Scheduler jboss-service descriptor. ExSchedulable class code

package org.jboss.chap10.ex2;

import java.util.Date;

import org.jboss.varia.scheduler.Schedulable;

import org.apache.log4j.Logger;

/** A simple Schedulable example.

* @author [email protected]

* @version $Revision: 1.1 $

public class ExSchedulable implements Schedulable

{

private static final Logger log = Logger.getLogger(ExSchedulable.class);

private String name;

private long value;

public ExSchedulable(String name, long value)

{

this.name = name;

this.value = value;

log.info("ctor, name: " + name + ", value: " + value);

}

public void perform(Date now, long remainingRepetitions)

{

log.info("perform, now: " + now +

", remainingRepetitions: " + remainingRepetitions +

", name: " + name + ", value: " + value);

}

Deploy the timer sar by running:

[nr@toki examples]$ ant -Dchap=chap10 -Dex=2 run-example

...

run-example2:

[copy] Copying 1 file to /tmp/jboss-3.2.3/server/default/deploy

The server console shows the following which includes the first two timer invocations, seperated by 60 seconds:

19:05:01,760 INFO [MainDeployer] Starting deployment of package: file:/private/tmp/jboss-3.2.3/server/default/deploy/chap10-ex2.sar

19:05:02,047 INFO [ExSchedulable] ctor, name: TheName, value: 123456789

19:05:02,071 INFO [Scheduler] Started jboss.docs.chap10:service=Scheduler

19:05:02,167 INFO [MainDeployer] Deployed package: file:/private/tmp/jboss-3.2.3/server/default/deploy/chap10-ex2.sar

19:05:03,050 INFO [ExSchedulable] perform, now: Tue May 04 19:05:03 CDT 2004, remainingRepetitions: -1, name: TheName, value: 123456789

19:06:03,049 INFO [ExSchedulable] perform, now: Tue May 04 19:06:03 CDT 2004, remainingRepetitions: -1, name: TheName, value: 123456789

19:07:03,050 INFO [ExSchedulable] perform, now: Tue May 04 19:07:03 CDT 2004, remainingRepetitions: -1, name: TheName, value: 123456789

The JBoss Logging Framework

In 3.2 the logging framework has been generalized to allow for any particular framework implementation. The JBoss classes themselves use the org.jboss.logging.Logger as the factory and logging interface. This class is essentially identical to the Log4j org.apache.log4j.Logger class, with the one addition support for a trace level priority. In 3.2, the Logger class delegated to a LoggerPlugin instance rather than an org.apache.log4j.Logger as was the case in 3.0. The class diagram for the Logger and LoggerPlugin are shown in See The JBoss logging framework classes...

FIGURE 10-4. The JBoss logging framework classes.

By default we continue to use the Log4j framework as the underlying logging implementation, and this is what the org.jboss.logging.Log4jLoggerPlugin provides. To integrate an alternate logging implementation, you would provide an implementation of the LoggerPlugin interface and specify that it should be used by setting the org.jboss.logging.Logger.pluginClass system property to implementation class name. To disable all logging, you can use the org.jboss.logging.NullLoggerPlugin . This implementation simply provides empty versions of the LoggerPlugin methods.

org.jboss.logging.Log4jService

The Log4jService MBean configures the Apache log4j system. JBoss uses the log4j framework as its internal logging API.

ConfigurationURL: The URL for the log4j configuration file. This can refer to either a XML document parsed by the org.apache.log4j.xml.DOMConfigurator or a Java properties file parsed by the org.apache.log4j.PropertyConfigurator . The type of the file is determined by the URL content type, or if this is null, the file extension. The default setting of "resource:log4j.xml" refers to the conf/log4j.xml file of the active server configuration file set.
RefreshPeriod: The time in seconds between checks for changes in the log4 configuration specified by the ConfigurationURL attribute. The default value is 60 seconds.
CatchSystemErr: This boolean flag if true, indicates if the System.err stream should be redirected onto a log4j category called STDERR. The default is true.
CatchSystemOut: This boolean flag if true, indicates if the System.out stream should be redirected onto a log4j category called STDOUT. The default is true.
Log4jQuietMode: This boolean flag if true, sets the org.apache.log4j.helpers.LogLog.setQuiteMode. As of log4j1.2.8 this needs to be set to avoid a possible deadlock on exception at the appender level. See bug#696819.

RMI Dynamic Class Loading

org.jboss.web.WebService

The WebService MBean provides dynamic class loading for RMI access to the server EJBs. The configurable attributes for the WebService are as follows:

Port: the WebService listening port number. A port of 0 will use any available port.
Host: Set the name of the public interface to use for the host portion of the RMI codebase URL.
BindAddress: the specific address the WebService listens on. This can be used on a multi-homed host for a java.net.ServerSocket that will only accept connect requests to one of its addresses.
Backlog: The maximum queue length for incoming connection indications (a request to connect) is set to the backlog parameter. If a connection indication arrives when the queue is full, the connection is refused.
DownloadServerClasses: A flag indicating if the server should attempt to download classes from thread context class loader when a request arrives that does not have a class loader key prefix.