Web Service Binding Handlers

It may be necessary to access and modify SOAP message headers or content when invoking a service or receiving a request. Fabric3 provides a generic binding handler framework that can be extended to provide low-level access to SOAP messages.

To do this, a class that implements org.fabric3.spi.binding.handler.BindingHandler must be provided as a Fabric3 extension components:

public interface BindingHandler<T> {

    /**
     * The fully qualified binding name corresponding to the SCA architected binding name scheme binding.xxxx.
     *
     * @return the fully qualified binding name
     */
    QName getType();

    /**
     * Handles an outbound (reference-side) message.
     *
     * @param context the binding-specific transport context
     * @param message the current message
     */
    void handleOutbound(Message message, T context);

    /**
     * Handles an inbound (service-side) message.
     *
     * @param context the binding-specific transport context
     * @param message the current message
     */
    void handleInbound(T context, Message message);

}

BindingHandler implementations that require access Web Service SOAP messages must use javax.xml.soap.SOAPMessage as the parameterized type. Below is an example handler:

@EagerInit
public class SOAPHandler implements BindingHandler<SOAPMessage> {
    private static final QName BINDING = new QName(Constants.SCA_NS, "binding.ws");

    private BindingHandlerRegistry registry;

    public SOAPHandler(@Reference BindingHandlerRegistry registry) {
        this.registry = registry;
    }

    @Init
    public void init() {
        registry.register(this);
    }

    @Destroy
    public void destroy() {
        registry.unregister(this);
    }

    public QName getType() {
        return BINDING;
    }

    public void handleOutbound(Message message, SOAPMessage context) {

    }

    public void handleInbound(SOAPMessage soapMessage, Message message) {

    }
}

Note the component is eager-initialized and registers with the BindingHandlerRegistry. Fabric3 extension components are configured using the implementation.system type as shown below:

<composite xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912"
           xmlns:sca="http://docs.oasis-open.org/ns/opencsa/sca/200912"
           xmlns:f3="urn:fabric3.org"
           targetNamespace="urn:fabric3.org"
           name="TestWsHandlerExtensionComposite">

    <component name="SOAPHandler">
        <f3:implementation.system class="org.fabric3.tests.binding.handler.SOAPHandler"/>
    </component>

</composite>

Finally, the component and its configuration must be packaged as an extension contribution with a manifest (sca-contribution.xml) similar to the following:

Error rendering macro 'code': Invalid value specified for parameter 'lang'

<contribution xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912"
              xmlns:f3="urn:fabric3.org"
              f3:extension="true">
    <import.java package="org.fabric3.spi.*"/>
    <deployable composite="f3:TestWsHandlerExtensionComposite"/>
</contribution>

To install the extension, place it in the server /extensions directory.