Using a Java Messaging Service Invoke Handler

ActiveVOS Designer User’s Guide

Using a Java Messaging Service Invoke Handler

ActiveVOS supports a Java Messaging Service (JMS) invoke handler for invoking endpoints. This means that you can bypass the standard ActiveVOS engine invocation framework of SOAP over HTTP with a SOAP over JMS invocation or a plain XML message over JMS. With a JMS invocation, your process can communicate with any of the Message-Oriented Middleware (MOM) applications that your server supports. This means when you invoke a partner service you can:

Connect to MOM queues
Set the names of MOM queues on which the server should return the response
Create the MOM message that contains the SOAP envelope
Drop the MOM message that contains the SOAP envelope

Providing Deployment Description for JMS Invoke Handler

In the Process Deployment Descriptor file of a BPEL process, you can specify the details of a JMS invoke handler that provides AXIS with the details needed to call the JMS transport mechanism.

On the Partner Links page of the PDD editor, select jms as the Invoke Handler for the partner role.

In the Endpoint Reference text box, add the details specific to JMS transport.

The details you can provide include:

Queue or topic look up name
For a request/response service, the reply queue as a wsa:ReplyTo header as a ReferenceParameter for routing responses (see example below)
Additional JMS message properties, included as wsa:ReferenceParameters on the partner endpoint
Optionally, you can include a JMS policy assertion on the partner role (See examples below)

Providing the Endpoint Reference Details

In ActiveVOS server, SOAP messages delivered over JMS use WS-Addressing headers to route requests to the appropriate service.

The target queue and, optionally, the service name of a JMS invoke is specified in the Address element of the endpoint reference, formatted as <queue JNDI name>/<service name>.

Example 1:

<wsa:EndpointReference>

  <wsa:Address>queue/com.activee.jms.bpel.queue

     /WSSReceiverService</wsa:Address>

</wsa:EndpointReference>

This translates into looking up the queue using a JNDI name of:

queue/com.activee.jms.bpel.queue

with a target service name of WSSReceiverService. The service name is used by the message receiver on the other side to determine the target service you are invoking.

Example 2: Using a <wsa:ReplyTo> for Two-Way Operation

For synchronous operations, where a durable response is not required, the JMS mechanism of a temporary queue handles messages for an invoked service. Note that the temporary queue cannot be accessed during recovery or on another node due to failover.

If the activity is long running, or requires failover, you can specify the response location in a <wsa:ReplyTo> element in the Endpoint Reference definition. For example:

<wsa:EndpointReference>

  <wsa:Address>...</wsa:Address>

   <wsa:ReferenceProperties>

    <wsa:ReplyTo>

     <wsa:Address>queue/com.activee.jms.reply.queue/

         </wsa:Address>

    </wsa:ReplyTo>

   </wsa:ReferenceProperties>

</wsa:EndpointReference>

Notice that the reply address specifies only the queue name with no service. The service name is not necessary for a two-way response message.

Example 3: Using a <wsa:ReplyTo> for CallBack Operation

If the operation is a one-way with a callback, specify the <wsa:ReplyTo> endpoint as follows:

    <wsa:ReplyTo>

     <wsa:Address>queue/com.activee.jms.reply.queue

        /JMSCallbackService

         </wsa:Address>

    </wsa:ReplyTo>

Example 4: Adding JMS Properties to the Endpoint Reference

f you need to populate additional JMS string properties on an invoke, they should be included as wsa:ReferenceParameters on the partner endpoint. These properties are also included as SOAP headers if sending as a SOAP envelope.

   <wsa:ReferenceProperties>

    <wsa:ReplyTo></wsa:Address>...</wsa:Address>

       </wsa:ReplyTo>

      <abx:param name="someProperty" value="value"/>

   </wsa:ReferenceProperties>

Adding a JMS Delivery Options Policy Assertion to a Partner Role

The message sender (partner role) controls the messaging options used for JMS. When ActiveVOS receives a two-way request, the reply is sent mirroring the options used for the request. For example, if the request message is a bytes message formatted as plain XML, the response will likewise be a bytes message formatted as plain XML. The options used for sending a JMS request are controlled through a WS-Policy assertion on the endpoint. You may specify additional attributes for JMS message delivery as a partner role policy assertion.

The basic policy attributes are displayed in the JMS Delivery Options Policy Assertion dialog. For instructions on using this policy assertion, see Adding Policy Assertions.

Message Type: Text (default) or Bytes	A text message content is XML text. A bytes message content is a byte array.
Message Format: XML (default) or SOAP	XML is the default format. It is either a request or response document as plain XML with no SOAP envelope.For plain XML messages, message level security is not available and you must control access by configuring authorization restrictions on JNDI lookups for the destinations through your application server's admin console. SOAP refers to a SOAP envelope as message payload. For SOAP messages, all WS-Security features are available to provide message level authentication, encryption and signature support.
Priority	If desired, specify a non-negative integer for a message handling priority
JMS Manager ID	In the Administration Console of ActiveVOS server, you can add multiple JMS configurations. If you want to use one other than the default, you can specify the configuration name.

Note: Other attributes, such as the correlation id and expiration may be set dynamically at runtime through a copy operation to the partner endpoint.

A correlation id pattern uses a single queue for all responses. If no correlation id is set on the request, ActiveVOS use the wsa:RelatesTo header on the response message, which equals wsa:MessageID.

Expiration is time in milliseconds from its dispatch time that a produced message should be retained by the message system.

Here is an example of a policy assertion added to a partner endpoint dynamically in a copy operation:

<partnerRole endpointReference=

   "static" invokeHandler="jms:Address">

   <wsa:EndpointReference>

   <wsa:Address>queue

       /com.activee.jms.bpel.queue?JMSOneWayService

   </wsa:Address>

   <wsp:Policy xmlns:abp="http://schemas.active-endpoints.com

      /ws/2005/12/policy"

   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">

      <abp:JMSDeliveryOptions

      jmsMessageType="bytes"

      jmsMessageFormat="xml"

      jmsPriority="1"

      jmsCorrelationID="12345678"

      jmsExpiration = "9999999999"/>

   </wsp:Policy>

   </wsa:EndpointReference>

</partnerRole>

Configuring the Messaging Service in the ActiveVOS Server Administration Console

To take advantage of JMS messaging, your ActiveVOS administrator must enable the JMS Message Service within the Administration Console. See the ActiveVOS Server Administration Console Online Help for details.