The JMS Binding (binding.message) Documentation

The messaging binding or JMS binding enables the interaction of SCA components with messaging providers. The binding allows SCA components to consume messages, which might be sent by other SCA components or non-SCA clients, and then invoke the native operations based on message content.

Here is a service that uses the message binding.

/**
 * @service
 * @binding.message
 * @protocol stomp
 * @destination queue://OrderEntryQ
 * 
 * @types http://example.org/OrderTracking OrderTracking.xsd
 */
class OrderService 
{

    /**
     * @reference
     * @binding.message http://localhost/ManufService.php?msd
     * @response queue://OrderResponse
     * @wsdl ./ManufService.wsdl
     * @responseTimeout 5000
     */
	public $manuf_service;

    /**
     * 
     * @param orderType http://example.org/OrderTracking
     * @return string order number
     */
    function placeOrder($order) 
    { 
	 return $manuf_service->order($order);

    }

    /**
     * @param string $orderNum The Order Number
     * @return orderType http://example.org/OrderTracking
     */
    function trackOrder($orderNum) 
    {
       . . .
    }

}

Binding Configuration

@ a Service

An SCA service is easily exposed as a message service simply by adding the @binding.message annotation to the service doc comment block. You will also need to provide information about the message provider, which the binding is connected, using the configuration annotations (see table 1 below). The message binding generates a MSD (Message Service Description) file automatically from the comment block. The generated MSD file can be used later at a reference to simplify binding configuration.

Here is an example of message binding for connecting to an IBM Websphere MQ broker.

/**
 * @service
 * @binding.message
 * @protocol wmq
 * @destination queue://OrderService
 * @broker QM_MANUF
 * @port 1414
 * @host L33H84F
 */
class OrderService 
{
       . . .
}

@ a Reference

You can add extra configurations at a reference, and please note that those configurations will override some of the settings in the msd file.

class SomeSCAService 
{
    /**
     * @reference
     * @binding.message ManufService.msd
     * @response queue://OrderResponse
     * @wsdl ./ManufService.wsdl
     */
	public $manuf_service;

     . . .
}

From a php file:

$service = SCA::getService('ManufService.msd',
   'message',
   array('wsdl' => './ManufService.wsdl',
         'response' => 'queue://OrderResponse');

Table 1 - List of Configuration Annotations

User ID and password will not appear on the auto-generated MSD file for security reasons.

More Examples

1. One way (asynchronous) and minimal binding example

The following example shows a minimal binding configuration, where protocol is the only mandatory element.

/**
 * @service
 * @binding.message
 * @protocol stomp
 */
class OrderService 
{. . .}

For a one way binding, which requires no response queue, but a wsdl schema describing the service interface is still mandatory for packaging request messages.

/**
 * @reference
 * @binding.message OrderService.msd
 * @wsdl ./OrderService.wsdl
 */
public $order_service;

2. Request and response (synchronous) example

To support request/response operations, you need to specify a response queue. The response queue could be specified at the service as the example below. Alternatively, you can specify a response queue at a reference, and the service will look for the JMS replyTo header in request messages.

/**
 * @service
 * @binding.message
 * @protocol stomp
 * @response queue://OrderResponse
 */
class OrderService 
{ . . .}

The following example shows the case where a five second timeout is set for receiving a response message. The default value of responseTimeout is -1, which means the reference is not going to expect a response, and that is asynchronous way. If you wish to use request/response operations, you need to give then a timeout for waiting the response, or zero for indefinite time.

/**
 * @reference
 * @binding.message OrderService.msd
 * @wsdl ./OrderService.wsdl
 * @responseTimeout 5000
 */
public $order_service;

3. Bidirectional binding (asynchronous) and correlation scheme example

The following example shows the configuration using the @callbackwsdl annotation to specify a wsdl call-back interface. The service also needs a setter function 'setMyServiceCallback' for the runtime to set the call-back reference. The service does not specify a call-back queue, but uses the 'scaCallbackQueue' header in request messages. Apparently, both request messages and call-back massages are sent asynchronously.

/**
 * @service
 * @binding.message
 * @protocol stomp
 * @callbackwsdl MyServiceCallBack.wsdl
 * @correlationScheme RequestCorrelIDToCorrelID
 */
class OrderService 
{ 
private $callback;

public function setMyServiceCallback($callbackProxy) {
    $this->callback = $callbackProxy;
}

/**
 * @param string $order (the result)
 */
public function submitOrder($order) {
    . . .
    $this->callback->receiveResult($result);
}

. . .
}

In this case, the reference will not only be a consumer of a service, but also provide a call-back service to the other service. As the example below, the reference is required to specify a callback queue using the @callbackqueue annotation, and make sure it is the same queue of which the callback service is listening to.

/**
 * @service
 * @binding.message
 * @protocol activemq
 * @destination queue://MyCallbackQ
 * @JMSCorrelationID CLIENT-001:1
 */
class MyServiceCallBack
{ 
	/**
 * @reference
 * @binding.message OrderService.msd
 * @wsdl ./OrderService.wsdl
 * @callbackqueue queue://MyCallbackQ
 * @JMSCorrelationID CLIENT-001:1
 */
public $order_service;

/**
 * @param string $result (the result)
 */
public function receiveResult($result) {
    . . .
}

. . .
}

The above example also shows a good use of the correlation scheme. The remote service uses the 'RequestCorrelIDToCorrelID' scheme which means that the request message's Correlation-ID will be used when sending reply or callback messages. On the other hand, the reference uses @JMSCorrelationID annotation to specify a Correlation-ID for all its requests, while the callback service uses the same annotation to consume messages of the same Correlation-ID.

Deployment

Unlike any of other bindings, it is not necessary to place a PHP message service component under the document root of your web server. The service can be started from a console anywhere (e.g. >php MyService.php ). Once the service is started, it will keep trying to get request messages from the queue, and it can be terminated by pressing Ctrl + C.

Pre-requisites

The PHP_SAM (Simple Asynchronous Messaging for PHP) extension is required for accessing a messaging server. You can find more information about SAM and download it from this page http://pecl.php.net/package/sam .

To use stomp protocol php_sockets extension must also be enabled.

If you intend to use an IBM Messaging and Queuing middleware products (such as Websphere MQ) as the message provider, then you also need the SAM_XMS extension and IBM Message Service Client for C/C++. For more information, you may want to check the Prerequisites section of SAM Documentation [1].

Outstanding Issues

...

References

[1] SAM Documentation http://project-sam.awardspace.com/docs/ref.sam.html
[2] OSOA SCA JMS Binding Specification V1.00 http://www.osoa.org/download/attachments/35/SCA_JMSBinding_V100.pdf?version=2