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.
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 VM command line arguments do.
Its configurable attributes include:
Both attributes are illustrated in Example 10.1, “An example SystemPropertiesService jboss-service descriptor”.
Example 10.1. An example SystemPropertiesService jboss-service descriptor
<server> <mbean code="org.jboss.varia.property.SystemPropertiesService" name="jboss.util:type=Service,name=SystemProperties"> <!-- Load properties from each of the given comma seperated URLs --> <attribute name="URLList"> http://somehost/some-location.properties, ./conf/somelocal.properties </attribute> <!-- Set propertuies using the properties file style. --> <attribute name="Properties"> property1=This is the value of my property property2=This is the value of my other property </attribute> </mbean> </server>
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 property editors 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 property editors from the system classpath.
Its supported attributes include:
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 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 MBean server. 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:
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 Figure 10.2, “How the ServiceConfigurator queries the ServiceBindingManager”.
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.
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 ... [echo] Preparing jboss0 configuration fileset [mkdir] Created dir: /tmp/jboss-3.2.6/server/jboss0 [copy] Copying 259 files to /tmp/jboss-3.2.6/server/jboss0 [copy] Copying 1 file to /tmp/jboss-3.2.6/server/jboss0/conf [copy] Copying 1 file to /tmp/jboss-3.2.6/server [echo] Preparing jboss1 configuration fileset [mkdir] Created dir: /tmp/jboss-3.2.6/server/jboss1 [copy] Copying 259 files to /tmp/jboss-3.2.6/server/jboss1 BUILD SUCCESSFUL
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> <attribute name="StoreFactoryClassName"> org.jboss.services.binding.XMLServicesStoreFactory </attribute> </mbean>
The attribute values are:
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.
The DTD showin in Figure 10.3, “The binding service XMLServicesStoreFactory DTD”. is the one supported by the XMLServicesStoreFactory class. The elements are:
The two ServicesConfigDelegate implementations 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>
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. 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.
The sample listing illustrates the usage of AttributeMappingDelegate.
<service-config name="jboss:service=Naming" delegateClass="org.jboss.services.binding.AttributeMappingDelegate"> <delegate-config portName="Port"/> <binding port="1099" /> </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:
<!-- jbossweb-tomcat50.sar --> <service-config name="jboss.web:service=WebServer" delegateClass="org.jboss.services.binding.XSLTFileDelegate" > <delegate-config> <xslt-config configName="ConfigFile"><![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:variable name="portHttps" select="$port + 363"/> <xsl:template match="/"> <xsl:apply-templates/> </xsl:template> <xsl:template match = "Connector"> <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:when test="(name() = 'redirectPort')"> <xsl:attribute name="redirectPort"><xsl:value-of select="$portHttps" /> </xsl:attribute> </xsl:when> <xsl:when test="(name() = 'port' and . = '8443')"> <xsl:attribute name="port"><xsl:value-of select="$portHttps" /> </xsl:attribute> </xsl:when> <xsl:otherwise> <xsl:attribute name="{name()}"><xsl:value-of select="." /> </xsl:attribute> </xsl:otherwise> </xsl:choose> </xsl:for-each> <xsl:apply-templates/> </Connector> </xsl:template> <xsl:template match="*|@*"> <xsl:copy> <xsl:apply-templates select="@*|node()"/> </xsl:copy> </xsl:template> </xsl:stylesheet> ]]> </xslt-config> </delegate-config> <binding port="8180"/> </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:
16:04:39,246 INFO [WebService] Using RMI server codebase: http://toki.local:8183/ 16:04:40,442 INFO [NamingService] Started jnpPort=1199, rmiPort=1198, backlog=50, bindAdd ress=/0.0.0.0, Client SocketFactory=null, Server SocketFactory=org.jboss.net.sockets.Defau ltSocketFactory@ad093076 16:05:28,596 INFO [Http11Protocol] Initializing Coyote HTTP/1.1 on http-0.0.0.0-8180 16:05:55,165 INFO [Http11Protocol] Starting Coyote HTTP/1.1 on http-0.0.0.0-8180 16:05:56,061 INFO [ChannelSocket] JK2: ajp13 listening on /0.0.0.0:8109
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.
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:
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).
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:
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. The following is an example of configuring a Scheduler to call a Schedulable implementation as well as a configuration for calling a MBean.
Example 10.2. An example Scheduler jboss-service descriptor
<server> <mbean code="org.jboss.varia.scheduler.Scheduler" name="jboss.docs.chap10:service=Scheduler"> <attribute name="StartAtStartup">true</attribute> <attribute name="SchedulableClass">org.jboss.chap10.ex2.ExSchedulable</attribute> <attribute name="SchedulableArguments">TheName,123456789</attribute> <attribute name="SchedulableArgumentTypes">java.lang.String,long</attribute> <attribute name="InitialStartDate">NOW</attribute> <attribute name="SchedulePeriod">60000</attribute> <attribute name="InitialRepetitions">-1</attribute> </mbean> </server>
The SchedulableClass org.jboss.chap10.ex2.ExSchedulable example class is given in Example 10.3, “The ExSchedulable class code”.
Example 10.3. The 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 Scott.Stark@jboss.org * @version $Revision: 1.7 $ */ 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.6/server/default/deploy
The server console shows the following which includes the first two timer invocations, seperated by 60 seconds:
16:44:49,275 INFO [ExSchedulable] ctor, name: TheName, value: 123456789 16:44:50,365 INFO [ExSchedulable] perform, now: Fri Oct 15 16:44:50 CDT 2004, remainingRe petitions: -1, name: TheName, value: 123456789 16:45:50,317 INFO [ExSchedulable] perform, now: Fri Oct 15 16:45:50 CDT 2004, remainingRe petitions: -1, name: TheName, value: 123456789 16:46:50,319 INFO [ExSchedulable] perform, now: Fri Oct 15 16:46:50 CDT 2004, remainingRe petitions: -1, name: TheName, value: 123456789
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 addition of support for a trace level priority. The Logger class delegates to a LoggerPlugin instance. The class diagram for Logger and LoggerPlugin are shown in 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.
The Log4jService MBean configures the Apache log4j system. JBoss uses the log4j framework as its internal logging API.
The WebService MBean provides dynamic class loading for RMI access to the server EJBs. The configurable attributes for the WebService are as follows: