The ServiceBindingManager provides a centralized point for specifying the addresses and ports services should use when creating sockets. It also makes it easy to configure alternate "sets" of port configurations, allowing different AS instances running on the same machine to avoid port conflicts by having each use a separate set of ports. In AS 4, this latter benefit was the main reason for having the ServiceBindingManager. Beginning with AS 5.1 another important benefit is the possibility it provides to managment tools like Jopr/JON to centralize socket configuration in one place.  This is possible because the ServiceBindingManager now provides a management interface via the AS ProfileService's ManagementView.

The purpose of this document is to describe that management interface.

For background information on the ServiceBindingManager, see the AS5ServiceBindingManager page.

The AS testsuite module includes a number of tests of the SBM management interface functionality. Looking at those tests is a good way to understand how to program to the management interface. They can be found at:

• http://anonsvn.jboss.org/repos/jbossas/branches/Branch_5_x/testsuite/src/main/org/jboss/test/profileservice/test/ServiceBindingManagedObjectsTestCase.java
• http://anonsvn.jboss.org/repos/jbossas/branches/Branch_5_x/testsuite/src/main/org/jboss/test/profileservice/override/test/ServiceBindingManagedObjectsTestCase.java
• http://anonsvn.jboss.org/repos/jbossas/branches/Branch_5_x/testsuite/src/main/org/jboss/test/profileservice/override/restart/test/ServiceBindingManagedObjectsTestCase.java
  

Obtaining a Reference to the ManagedComponent for the ServiceBindingManager

The AS deploys a special MC bean which provides the managment interface for the SBM (org.jboss.services.binding.managed.ServiceBindingManagementObject).  The following code snippet from the above referenced test cases shows how to find the SBM's ManagedComponent:

ManagementView managementView = getManagementView(); // via JNDI lookup
ComponentType type = new ComponentType("MCBean", "ServiceBindingManager");
ManagedComponent component = managementView.getComponent("ServiceBindingManager", type);

Properties and Operations Exposed by the ServiceBindingManagementObject

At its core, what the SBM does is pretty simple. It takes 2 main types of inputs:

1. A set of ServiceBindingMetadata describing the "standard" or default binding values.
2. A set of metadata describing the available "ServiceBindingSets" (e.g. ports-default, ports-01), the most important piece of which is the offset that should be applied to the "standard" port values to obtain the runtime value for that particular binding set.

Internally, the SBM uses those two inputs and generates a simple data object for each standard binding for each binding set.

Finally, the SBM exposes a configuration property describing which binding set should be consulted at runtime when the MC requests a binding value from it.

From the above description, the managed properties exposed by the SBM's ManagedComponent fall out naturally.

• activeBindingSetName -- read/write property exposing the name of the binding set which should be consulted at runtime on the particular server. A SimpleValue whose getValue() method returns a String. ViewUse.CONFIGURATION.
  
• standardBindings -- read/write property exposing the set of "standard" binding metadata. A CollectionValue each of whose elements is a CompositeValue describing a single ServiceBindingMetadata. See below for details on the CompositeValue. ViewUse.CONFIGURATION.
• bindingSets -- read/write property exposing a set describing the available ServiceBindingSets. A CollectionValue each of whose elements is a CompositeValue describing a single ServiceBindingSet. See below for details on the CompositeValue. ViewUse.CONFIGURATION.
• serviceBindings -- a read only property exposing the full set of available runtime binding information (i.e. the result of applying the standard binding to each ServiceBindingSet). A CompositeValue whose keys are the names of the available binding sets (e.g. ports-default, ports-01.)  The value store under each key is a CollectionValue each of whose elements is a CompositeValue describing a single ServiceBinding. See below for details on the CompositeValue. ViewUse.STATISTIC.

The SBM does not expose any managed operations.

Updating the SBM then becomes a matter of updating the relevant property. Standard bindings or ServiceBindingSets can be added or removed, or the contents of each can be updated. See the above referenced tests for a number of examples. Admittedly, the interface is rather coarse grained (e.g. to change only one field on a single standard binding, you have to post the entire standard binding set back to the server.)  But, it was found that this approach was the best way to ensure that persistence of updates worked properly.

CompositeValue Structures

The previous section described a number of CollectionValues, the elements of which are CompositeValues describing a particular object. Following are the details on those collection values.

ServiceBindingMetadata

A ServiceBindingMetadata is a server-side object that acts as an input into the SBM function that creates the ServiceBinding objects used at runtime (e.g. the ServiceBindingMetadata's port property is combined with a ServiceBindingSet's portOffset property to derive the final ServiceBinding's port property.)  The CompositeValue describing a ServiceBindingMetadata has the following sets of key/value pairs:

• serviceName -- the name of the service to which the binding applies. Cannot be null. SimpleValue whose value type is String.
• bindingName -- a qualifier identifying which particular binding within the service this is. Can be null. SimpleValue whose value type is String.
• fullyQualifiedName -- concatentation of serviceName and bindingName. This is essentially a read-only property, since the server will ignore any modification and recalculate the fullyQualifiedName from the serviceName and bindingName. SimpleValue whose value type is String.
• description -- description of the binding. Can be null. SimpleValue whose value type is String.. ViewUse.CONFIGURATION.
• hostName  -- the host name or string notation IP address to use for the binding. Can be (and usually is) null. SimpleValue whose value type is String.
• port  -- the port to use for the binding. Cannot be null. SimpleValue whose value type is int.
• fixedHostName -- whether the host name should remain fixed in all binding sets. SimpleValue whose value type is boolean.
• fixedPort -- whether the port should remain fixed in all binding sets. SimpleValue whose value type is boolean.

ServiceBindingSet

A ServiceBindingSet is a server-side object that acts as an input into the SBM function that creates the ServiceBinding objects used at runtime (e.g. ServiceBindingSet's portOffset property is combined with each ServiceBindingMetadata's port property to derive the final ServiceBinding's port property.)  The CompositeValue describing a ServiceBindingMetadata has the following sets of key/value pairs:

• name -- the name of the binding set. Cannot be null. SimpleValue whose value type is String.
• defaultHostName -- the host name that should be used for all bindings whose configuration does not specify fixedHostName as true. Cannot be null. SimpleValue whose value type is String.
• portOffset -- value to add to the port configuration for a standard binding to derive the port to use in this binding set. Cannot be null. SimpleValue whose value type is int.
• overrideBindings -- a set of ServiceBindingMetadata that only apply to this binding set. These can either be used to override the values from the standard binding sets with custom values for this binding set (e.g. if the approach of generating a unique value by adding the portOffset is inadequate). Or they can be used to add bindings that only apply to this binding set. A CollectionValue each of whose elements is a CompositeValue describing a ServiceBindingMetadata. See above for details on the CompositeValue.

ServiceBinding

A ServiceBinding is a runtime object created by combining a ServiceBindingMetadata with a ServiceBindingSet. It only applies to a particular set.  These represent the actual values the SBM would return if asked for binding information.   The CompositeValue describing a ServiceBinding has the following sets of key/value pairs, all:

• serviceName -- the name of the service to which the binding applies. Will not be null. SimpleValue whose value type is String.
• bindingName -- a qualifier identifying which particular binding within the service this is. May be null. SimpleValue whose value type is String.
• fullyQualifiedName -- concatentation of serviceName and bindingName. SimpleValue whose value type is String.
  
• description -- description of the binding. May be null. SimpleValue whose value type is String.
• hostName  -- the host name or string notation IP address to use for the binding. Will not be null. SimpleValue whose value type is String.
• bindAddress -- the hostName expressed as an IP address's bytes.  ArrayValue whose value type is byte[].
• port  -- the port to use for the binding. Will not be null. SimpleValue whose value type is int.