12.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 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 responsible for providing the names 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 12.1, “The binding service file structure”.
The binding service file structure

Figure 12.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 the ServiceBindingManagerServerName 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 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 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 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, and XSLTFileDelegate.

12.5.1. AttributeMappingDelegate

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.