Services Binding Management

With all the independently deployed services available in JBoss, running multiple instances on a given machine can be a tedious exercise in configuration file editing to resolve port conflicts. The binding service allows you to centrally configure the ports for multiple JBoss instances. After the service is normally loaded by JBoss, ServiceConfigurator queries the service binding manager to apply any overrides that may exist for the service. The service binding manager is configured in conf/jboss-service.xml. The configurable attributes it supports include the following:

• ServerName This is the name of the server configuration with which this JBoss instance is associated. The binding manager will apply the overrides defined for the named configuration.

• StoreFactoryClassName This is the name of the class that implements the ServicesStoreFactory interface. You may provide your own implementation or use the default XML based store, org.jboss.services.binding.XMLServicesStoreFactory. The factory provides a ServicesStore instance that is responsible for providing the named configuration sets.

• StoreURL This is the URL of the configuration store contents, which is passed to the ServicesStore instance to load the server configuration sets from. For the XML store, this is a simple service binding file.

The following is a sample service binding manager configuration that uses the ports-01 configuration from the sample-bindings.xml file provided in the JBoss examples directory:

 <mbean code="org.jboss.services.binding.ServiceBindingManager"        name="jboss.system:service=ServiceBindingManager">     <attribute name="ServerName">ports-01</attribute>     <attribute name="StoreURL">         ../docs/examples/binding-manager/sample-bindings.xml     </attribute>     <attribute name="StoreFactoryClassName">         org.jboss.services.binding.XMLServicesStoreFactory     </attribute> </mbean> 

The structure of the binding file is shown in Figure 10.1.

Figure 10.1. The binding service file structure.

The elements of this configuration are as follows:

• service-bindings This is 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 classname of the ServicesConfigDelegate implementation that knows how to handle bindings for the target service. Its contents consist of an optional delegate-config element and one or more binding elements.

• binding A binding element specifies a named port and address pair. It has an optional name attribute that can be used to provide multiple bindings 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 apply only 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 are arbitrary, but there is no way to specify, and an element can have any number of attributes with a DTD.

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

 <delegate-config portName="portAttrName" hostName="hostAttrName">     <attribute name="someAttrName">someHostPortExpr</attribute>     <!-- ... --> </delegate-config> 

portAttrName is the attribute name of the MBean service to which the binding port value should be applied, and 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, the binding port is not applied. Likewise, if the hostName attribute is not specified, the binding host is not applied. The optional attribute elements 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 and hostName attribute values and attribute element content may reference system properties, using the ${ x} syntax that is supported by the JBoss services descriptor.

The following example illustrates the usage of AttributeMappingDelegate:

 <service-config name="jboss:service=Naming"        delegate>     <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 ServicesConfigDelegate that expects a delegate-config element in this 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 defaultcalled host and portand their values are set to the configuration host and port bindings.

XSLTConfigDelegate is used to transform services whose port/interface configuration is specified by using a nested XML fragment. The following example 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"          delegate>          <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> 

JBoss ships with a service binding configuration file for starting up to three separate JBoss instances on one host.

Next, let's walk through the steps to bring up the two instances and look at the sample configuration.

You start by making two server configuration file sets called j boss0 and jboss1 by running the following command from this book's examples directory:

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

This creates duplicates of the server/default configuration file sets as server/jboss0 and server/jboss1, and then it 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> 

Here the configuration name is ${jboss.server.name}. JBoss replaces this with the name of the actual JBoss server configuration that you pass to the run script by using the -c option. That will be either jboss0 or jboss1, depending on which configuration is being run. The binding manager will find the corresponding server configuration section from chap10ex1-bindings.xml and apply the configured overrides. The jboss0 configuration uses the default settings for the ports, and the jboss1 configuration adds 100 to each port number.

To test the sample configuration, you can start two JBoss instances, using the jboss0 and jboss1 configuration file sets created previously. You can observe that the port numbers in the console log are different for the jboss1 server. To test whether both instances work correctly, you can try to access the web server of the first JBoss on port 8080 and then try the second JBoss instance on port 8180.