JMS Binding Handlers

It may be necessary to access and modify JMS 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 JMS messages.

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

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 JMS messages must use javax.jms.Message as the parameterized type. Below is an example handler:

@Scope("COMPOSITE")
public class TestHandler implements BindingHandler<javax.jms.Message>{
    private static final QName BINDING = new QName(Constants.SCA_NS, "binding.jms");

    public QName getType() {
        return BINDING;
    }
    
    public void handleOutbound(Message message, javax.jms.Message context) {
       // ...
    }

    public void handleInbound(javax.jms.Message context, Message message) {
       //...
    }

}

Note the handler is composite-scoped. Although this is not necessary, most handlers are threadsafe and making them composite-scoped will avoid the overhead associated with stateless-scoped implementations. The handler configuration is shown below. Note the component may be contained in the same contribution as the services or references it applies to or in a different contribution if used for more than one application:

<component name="TestHandler">
   <implementation.java class="org.fabric3.tests.binding.jms.handler.TestHandler"/>
</component>

The manifest (sca-contribution.xml) of the contribution containing the handler must contain the following imports:

<contribution ...>
    <import.java package="org.fabric3.spi.*" version="1.9.6"/>
    <import.java package="javax.jms.*" version="1.1.0"/></contribution>

Finally, the handler may be used on a binding as follows:

<component name="HandlerService">
   <implementation.java class="org.fabric3.tests.binding.metro.handler.HandlerServiceImpl"/>
   <service name="HandlerService">
      <binding.jms ...>
         <f3:handler target="TestHandler"/>
      </binding.jms>
   </service>
</component>