JBoss - Services Binding Management

http://docs.jboss.org/jbossas/docs/Server_Configuration_Guide/beta422/html/Additional_Services-Services_Binding_Management.html

10.5. 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 to resolve port conflicts. The binding service allows you centrally configure the ports for multiple JBoss instances. After the service is normally loaded by JBoss, the 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 set of configurable attributes it supports include:

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

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

• StoreURL : This is the URL of the configuration store contents, which is passed to the ServicesStoreinstance 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, “The binding service file structure”.

Figure 10.1. The binding service file structure

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 theServiceBindingManager ServerName attribute value. The server element content consists of one or moreservice-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 theServicesConfigDelegate 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 and 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 theServicesConfigDelegate implementation. The hostName and portName attributes only apply to theAttributeMappingDelegate 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 a element can have any number of attributes with a DTD.

The three ServicesConfigDelegate implementations are AttributeMappingDelegate, XSLTConfigDelegate, andXSLTFileDelegate.

10.5.1. AttributeMappingDelegate

The AttributeMappingDelegate class is an implementation of the ServicesConfigDelegate that expects adelegate-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.

10.5.2. XSLTConfigDelegate

The XSLTConfigDelegate class is an implementation of the ServicesConfigDelegate that expects adelegate-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 typeorg.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 example maps the port number on hypersonic datasource:

   
<service-config name="jboss.jca:service=ManagedConnectionFactory,name=DefaultDS" 
                delegateClass="org.jboss.services.binding.XSLTConfigDelegate">
    <delegate-config>
        <xslt-config configName="ManagedConnectionFactoryProperties"><![CDATA[
<xsl:stylesheet
      xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'>

  <xsl:output method="xml" />
  <xsl:param name="host"/>
  <xsl:param name="port"/>

  <xsl:template match="/">
    <xsl:apply-templates/>
  </xsl:template>

  <xsl:template match="config-property[@name='ConnectionURL']">
    <config-property type="java.lang.String" name="ConnectionURL">
       jdbc:hsqldb:hsql://<xsl:value-of select='$host'/>:<xsl:value-of select='$port'/>
    </config-property>
  </xsl:template>

  <xsl:template match="*|@*">
    <xsl:copy>
      <xsl:apply-templates select="@*|node()"/>
    </xsl:copy>
  </xsl:template>
</xsl:stylesheet>
]]>
        </xslt-config>
     </delegate-config>
     <binding host="localhost" port="1901"/>
</service-config>  

10.5.2. XSLTConfigDelegate

The XSLTConfigDelegate class is an implementation of the ServicesConfigDelegate that expects adelegate-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 typeorg.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 example maps the port number on hypersonic datasource:

   
<service-config name="jboss.jca:service=ManagedConnectionFactory,name=DefaultDS" 
                delegateClass="org.jboss.services.binding.XSLTConfigDelegate">
    <delegate-config>
        <xslt-config configName="ManagedConnectionFactoryProperties"><![CDATA[
<xsl:stylesheet
      xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'>

  <xsl:output method="xml" />
  <xsl:param name="host"/>
  <xsl:param name="port"/>

  <xsl:template match="/">
    <xsl:apply-templates/>
  </xsl:template>

  <xsl:template match="config-property[@name='ConnectionURL']">
    <config-property type="java.lang.String" name="ConnectionURL">
       jdbc:hsqldb:hsql://<xsl:value-of select='$host'/>:<xsl:value-of select='$port'/>
    </config-property>
  </xsl:template>

  <xsl:template match="*|@*">
    <xsl:copy>
      <xsl:apply-templates select="@*|node()"/>
    </xsl:copy>
  </xsl:template>
</xsl:stylesheet>
]]>
        </xslt-config>
     </delegate-config>
     <binding host="localhost" port="1901"/>
</service-config>  

10.5.3. XSLTFileDelegate

The XSLTFileDelegate class works similarly to the XSLTConfigDelegate except that instead of transforming an embedded XML fragment, the XSLT script transforms a file read in from the file system. Thedelegate-config takes exactly the same 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 a String value corresponding to an XML file that will be transformed. 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 following example maps the host and port values for the Tomcat connectors:

   
<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="8280"/>
</service-config> 

10.5.4. The Sample Bindings File

JBoss ships with service binding configuration file for starting up to three separate JBoss instances on one 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:

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

This creates duplicates of the server/production configuration file sets as server/jboss0 and server/jboss1, and then replaces the conf/jboss-service.xml descriptor with one that has the ServiceBindingManagerconfiguration 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}/misc-ex1-bindings.xml</attribute>
    <attribute name="StoreFactoryClassName">
        org.jboss.services.binding.XMLServicesStoreFactory
    </attribute>
</mbean>

Here the configuration name is ${jboss.server.name}. JBoss will replace that with name of the actual JBoss server configuration that we pass to the run script with 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 the misc-ex1-bindings.xml and apply the configured overrides. The jboss0configuration uses the default settings for the ports, while the jboss1 configuration adds 100 to each port number.

To test the sample configuration, 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 thejboss1 server. To test out that both instances work correctly, try accessing the web server of the first JBoss on port 8080 and then try the second JBoss instance on port 8180.