Binding Services and References

A JMS provider can be used as the transport for one-way and request-response operations. A minimal one-way configuration is shown below:

<component name="OneWayClient">
   <implementation.java class="..."/>
   <reference name="service">
      <binding.jms>
         <destination name="serviceQueue"/>
      </binding.jms>
   </reference>
</component>

<component name="OneWayService">
   <implementation.java class="..."/>
   <service>
      <binding.jms>
         <destination name="serviceQueue"/>
      </binding.jms>
   </service>
</component>

The above configuration uses the "serviceQueue" queue to propagate messages.

Non-Blocking Operations

When writing asynchronous Java components, it is important to remember the @OneWay annotation. If a method is not marked with @OneWay, it will be taken as a request-response operation even if the return value is void. This means the operation will block until a response message is received.

Configuring request-response operations involves specifying a separate response queue in addition to the forward queue:

<component name="RequestResponseClient">
   <implementation.java class="..."/>
   <reference name="service">
      <binding.jms>
         <destination name="serviceQueue"/>
         <response>
            <destination name="responseQueue"/>
         </response>
      </binding.jms>
   </reference>
</component>

<component name="RequestResponseService">
   <implementation.java class="..."/>
   <service>
      <binding.jms>
         <destination name="serviceQueue"/>
         <response>
            <destination name="responseQueue"/>
         </response>
      </binding.jms>
   </service>
</component>

Using Callbacks

While JMS is an asynchronous model, it is important to note that the client component will block on request-response operations until a response is received. In some cases, this is the desired behavior. In other situations, such as long-running interactions, looser coupling is required where the client can continue processing without waiting for a response to be returned. Callbacks can be used to provide responses at some later point in time. Configuring callbacks involves specifying a callback queue:

<component name="CallbackClient">
   <implementation.java class="..."/>
   <reference name="service">
      <binding.jms>
         <destination name="serviceQueue"/>
      </binding.jms>
      <callback>
         <binding.jms>
            <destination name="callbackQueue"/>
         </binding.jms>
      </callback>
   </reference>
</component>

<component name="CallbackService">
   <implementation.java class="..."/>
   <service>
      <binding.jms>
         <destination name="serviceQueue"/>
      </binding.jms>
      <callback>
         <binding.jms>
            <destination name="callbackQueue"/>
         </binding.jms>
      </callback>
   </service>
</component>

When the CallbackClient invokes the CallbackService, the call will return immediately. At some later point in time, a reponse will be delivered asynchronously using the "callbackQueue" queue.

In the previous examples, queues where assumed to be externally configured using Fabric3 server settings or the JMS provider. The JMS binding can also be configured to create queues dynamically by using the @create attribute on the destination element and setting it to "ifnotexist" or "always". Similarly, the JMS connection factory can be configured directly on the binding using the connectionFactory element.

Wire Formats

The JMS binding supports multiple wire formats including object serialization, JMS message types, and JAXB serialization. If a parameter type is annotated with the JAXB @XmlRootElement annotation, parameters will be sent as XML using a JMS text message. Otherwise, the JMS binding will introspect the parameter types and select the most appropriate message type (e.g. object, bytes, etc).