ActiveVOS JMS Transport Options

ActiveVOS JMS

Transport options

Technical Note

V1.2

© 2011 Active Endpoints Inc. ActiveVOS is a trademark of Active Endpoints, Inc. All other company and product names are the property of their respective owners.

2011

0

Copyright © 2011, Active Endpoints, Inc. Page 2 of 15

Content ActiveVOS JMS Support ....................................................................................................... 3 JMS Invoke Handler ............................................................................................................. 4 Message Exchange Patterns ................................................................................................ 4

JMS Partner Role for One-Way Request ......................................................................... 4 JMS Partner Role for Request-Response using Temporary Reply Queue ....................... 5 JMS Partner Role for Request-Response with durable reply queue ............................... 6

Setting JMS Message Properties .......................................................................................... 7 Using JMS Policy .................................................................................................................. 8

Specifying JMS Policy ...................................................................................................... 9 Security Policy...................................................................................................................... 9 ActiveVOS JMS Listener ..................................................................................................... 10 Content Validation ............................................................................................................. 10 Determining Request Format (SOAP or XML) .................................................................... 10 Determining the Target Service Name .............................................................................. 10 Sending Replies .................................................................................................................. 11 Messaging Manager .......................................................................................................... 12 About Active Endpoints ..................................................................................................... 15


ActiveVOS JMS Support The Web Service Interactions using JMS available on the Active Endpoints

web site describes how to define processes that interact with Web

Services using JMS for the transport. The sample accompanying the

document includes a set of examples that demonstrate four Message

Exchange patterns (MEP) supported by ActiveVOS.

This technical note provides you with reference information on the use

of JMS with ActiveVOS. The following capabilities are provided by the

ActiveVOS Server.

Supported Message Formats:

SOAP – Serialized SOAP Envelope as message payload

Plain XML – Request and Response documents as plain XML with no SOAP envelope.

Supported JMS Message Types:

Text – Message contents serialized as xml text

Bytes – Message contents serialized as a byte array

Supported MEP:

One-Way Request

Request-Response with temporary reply destination

Request-Response with durable reply destination

Asynchronous message exchange


JMS Invoke Handler To send a request using JMS Transport, you specify “JMS Service” as the

invoke handler. The <wsa:Address> for the endpoint needs to indicate

the target queue and, optionally, the service name formatted as <queue

JNDI name>?<service name>. Here are two examples:

<wsa:Address>queue/SampleQ1</wsa:Address>

<wsa:Address>queue/SampleQ1?ServiceName</wsa:Address>

The queue JNDI name is used to lookup the destination from the JMS

provider. It is important to understand that ActiveVOS requires the

queue’s JNDI name and not queue’s name. That means your JMS service

provider must use JNDI. Using a stand-alone JMS message server

requires all destinations be put as administered object in a JNDI store.

The service name is used by the message receiver on the other side to

determine the target service you are invoking.

Message Exchange Patterns

JMS Partner Role for One-Way Request For a one-way operation specify the following partner role definition and

message properties.

Partner Role Definition

<partnerRole endpointReference="static" invokeHandler="JMS Service "> <wsa:EndpointReference>

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

</wsa:EndpointReference> </partnerRole>

Message Content

Message Format: SOAP (default)

Message Type: Text (default)

Message Properties (note the capitalization of these properties)

JmsTargetService = OneWayService (a name of your choosing)

JmsCorrelationID = wsa:MessageId


JmsReplyDestination = none

JMSReplyTo = none

JMS Partner Role for Request-Response using

Temporary Reply Queue If the operation you are invoking is a one-way request, the message is

sent and the invoke activity completes. If the operation is two-way, the

receiver needs to send a reply and the sender needs to tell the receiver

where to send it.

If no reply information is provided, the JMS invoker will create a

temporary queue destination to receive the reply. Temporary

destinations are a standard JMS mechanism for supporting two way

exchanges where the response does not need to be durable. The

advantage to using a temporary destination is that it exists only for the

duration of the invoke activity, messages are not persisted, and no

correlation information is necessary, reducing overhead.

For a request-response operation specify the following partner role

definition and message properties.


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

</wsa:Address> </wsa:EndpointReference> </partnerRole>

Request Message Content



Request Message Properties (note the capitalization of these

properties)

JmsTargetService = JMSTwoWayService



JMSReplyTo = Temporary Reply Queue Destination object

Response Message Content


Message Format: SOAP (matches request)

Message Type: Text (matches request)

Response Message Properties (note the capitalization of these

properties)

JmsTargetService = (not needed)

JmsCorrelationID = (not needed)


JMSReplyTo = none

JMS Partner Role for Request-Response with durable

reply queue A temporary destination may not be appropriate for replies that need to

be made durable and persistent for failover and recovery. To specify a

durable reply destination, you need to provide a permanent destination

name specified as a wsa:ReplyTo endpoint in the partner role definition


<partnerRole endpointReference="static" invokeHandler=" JMS Service "> <wsa:EndpointReference> <wsa:Address>queue/com.activee.jms.bpel.queue?JMSTwoWayService </wsa:Address> <wsa:ReferenceProperties> <wsa:ReplyTo> <wsa:Address>queue/com.activee.jms.reply.queue </wsa:Address> </wsa:ReplyTo> </wsa:ReferenceProperties> </wsa:EndpointReference> </partnerRole>

Message Content




JmsTargetService = JMSTwoWayService


JmsReplyDestination = queue/com.activee.jms.reply.queue

JMSReplyTo = none

Response Message Content


Message Format: SOAP (matches request)

Message Type: Text (matches request)

Response Message Properties (note the capitalization of these

properties)

JmsTargetService = (not needed)

JmsCorrelationID = wsa:RelatesTo = wsa:MessageId from request


JMSReplyTo = none

Notice that the reply address specifies only the queue name with no

service name specified. The service name is not necessary for a two-way

response message.

If you are sending a one-way request and expect a callback, you also

need to specify the callback address and service using a wsa:ReplyTo

endpoint. In this case you also indicate the target service for the callback

request.

wsa:ReplyTo Definition

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

Setting JMS Message Properties If 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:ReferenceParameters

<wsa:EndpointReference> <wsa:Address>queue/com.activee.jms.bpel.queue?JMSOneWayService </wsa:Address> <wsa:ReferenceParameters> <wsa:ReplyTo> <wsa:Address> queue/com.activee.jms.bpel.queue?JMSCallbackService </wsa:Address> </wsa:ReplyTo> <abx:param name=”someProperty” value=”value”/> </wsa:ReferenceParameters> </wsa:EndpointReference>

Message Content





JmsTargetService = JMSOneWayService


JmsReplyDestination = queue/com.activee.jms.bpel.queue

JMSReplyTo = none

someProperty = value

Using JMS Policy The message sender (partner role) controls the messaging options used

for JMS. When we receive 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 WS-Policy assertions on the

endpoint. Users may specify additional QoS attributes for JMS message

delivery as a partner role policy assertion:

JMS Policy Schema

  <xs:simpleType name="jmsMessageTypeEnum"> <xs:restriction base="xs:string"> <xs:enumeration value="text"/> <xs:enumeration value="bytes"/> </xs:restriction> </xs:simpleType>  <xs:simpleType name="jmsMessageFormatType"> <xs:restriction base="xs:string"> <xs:enumeration value="soap"/> <xs:enumeration value="xml"/> </xs:restriction> </xs:simpleType> <xs:element name="JMSDeliveryOptions"> <xs:complexType> <xs:attribute name="jmsMessageType" type="tns:jmsMessageTypeEnum" use="optional"/> <xs:attribute name="jmsMessageFormat"


type="tns:jmsMessageFormatType" use="optional"/> <xs:attribute name="jmsExpiration" type="xs:long"

use="optional"/> <xs:attribute name="jmsPriority"

type="xs:int" use="optional"/>

<xs:attribute name="jmsCorrelationID" type="xs:string"

use="optional"/> <xs:attribute name="jmsManagerID"

type="xs:string" use="optional"/>

<xs:attribute name="jmsDeliveryMode" type="xs:string" use="optional"/>

<xs:attribute name="jmsTTL" type="xs:long" use="optional"/>

</xs:complexType> </xs:element>

Specifying JMS Policy A sample partner role definition (invoke handler = JMS Service and

Endpoint Type = static) with a JMS policy is shown below:

<wsa:EndpointReference xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/addressing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <wsa:Address>queue/JMSSampleQ3</wsa:Address> <wsa:ReferenceProperties>

<wsa:ReplyTo xmlns="http://schemas.xmlsoap.org/ws/2003/03/addressing"> <wsa:Address>queue/JMSSampleQ3DurableReply</wsa:Address> </wsa:ReplyTo>

</wsa:ReferenceProperties>

<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 jmsDeliveryMode="persistent" jmsManagerID="JBossMessageManager" jmsMessageFormat="xml" jmsMessageType="text" jmsPriority="1" jmsTTL="20"/>

</wsp:Policy>

</wsa:EndpointReference>

Security Policy For SOAP messages, all of our WS-Security features are available to help

provide message level authentication, encryption and signature support.

For plain XML messages, message level security is not available and users

will need to control access by configuring authorization restrictions on


JNDI lookups for the destinations through the application server’s admin

console.

ActiveVOS JMS Listener When a message is received by the ActiveVOS JMS listener, the listener

will create a JMS context from the message.

Content Validation Valid content is an XML Document serialized as Text or Bytes. Response

messages will be returned with the same message type as the request

(i.e. bytes message request gets a bytes message response)

For a plain XML, all messages (request, response, & fault) must consist of

a single part containing an XML document.

Determining Request Format (SOAP or XML) If the root element of the XML document is a soap:Envelope, the request

is treated as a SOAP request and is processed using the ActiveVOS JMS

receiver. Otherwise it is treated as a plain XML request.

If the SOAP envelope contains ws-addressing headers these are de-

serialized and placed on the context.

Determining the Target Service Name In order to dispatch the request to the engine, we must determine the

target service. The target service is determined as follows:

JmsTargetService message property

If the property is not set, we will extract the service name from the wsa:To header. The service name is assumed to be the query parameter (delimited by ‘?’) in the URI.

If we can’t determine the target service from message properties or addressing, the listener will use the configured default service name (see Messaging Manager section).

If there is no default service configured, we throw an exception. Note: The use of the target service is required. In order for ActiveVOS to match the signature against the PortType operations a PortType is required. To obtain the PortType a target service is required minimally.


This differs from the case of HTTP requests where the URL (i.e. active-bpel/services/<<ServiceName>>) of the service suffices. JMS differs as outlined above.

Sending Replies In order to deliver a reply for a request-response operation ActiveVOS

needs to determine the reply destination from the request message.

Reply Destination

If the JMSReplyTo Destination is set on the request message, ActiveVOS

will use this destination. The destination will be considered a temporary

destination and the BPEL response cannot be durable reply. Temporary

destinations are, by definition, temporary and cannot be accessed during

recovery or on another node due to failover.

It is important to note that the JMSReplyTo value can only be a

temporary destination. A temporary destination object is created by the

process and is available to ActiveVOS during run-time. This is not the

case for durable destinations – they must be accessed using JNDI and are

not available during run-time. For durable replyTo destinations

ActiveVOS uses the JmsReplyDestination custom JMS header property to

carry the JNDI name of a durable destination. If you have a standalone

JMS client you will need to examine both JMSReplyTo and

JmsReplyDestination fields to determine the replyTo destination. If your

client is another process running in ActiveVOS engine this will be handled

automatically for you.

A durable reply destination must be one that is accessible by name

through the messaging manager’s JNDI lookup.

The reply destination name is determined as follows:

- JmsReplyDestination header property - If not set, we will get the destination name from the wsa:ReplyTo

header from the SOAP message. The URI for the reply should be given as <destination name>?<service name>.

Note: The wsa:ReplyTo can be used with the ActiveVOS invoke handler for both plain XML and SOAP. The only time one needs to set the property manually is if the request is a) produced by a client other than our invoke handler, AND b) the request does not have appropriate wsa SOAP headers such as a plain XML request.


Correlation Id

The response correlation id will be set to match the request correlation

id.

If no correlation id was set on the request, ActiveVOS will use the

wsa:RelatesTo header on the response message.

It is important to understand that ActiveVOS does not support

correlation on JMSMessageID value. A JMS MessageID is provider-

specific and is not available during JMS SEND. For engine-managed

correlation, ActiveVOS will create an ID and initialize with it the standard

JmsCorrelationID header property.

Do not attempt to use a standalone client that receives a message,

initializes the JmsCorrelationID of the reply with the JMSMessageID it

received, and then submit it back – this pattern will not work.

Messaging Manager The JMS Manager Name is the manager’s provider name. By default,

ActiveVOS will send messages using a default JMS provider. However,

you can specify what provider to use in the Policy as the attribute

"jmsManagerID" of JMSDeliveryOptions element. Here is its schema:

<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 jmsManagerID=”xxxxxx”/>

</wsp:Policy>

“xxxxxx” above represents the name with which you created a JMS

provider in admin console.

The provider used to support JMS transport is configured in the

ActiveVOS Console on the Messaging Service page. This allows users to

specify the settings that allow the engine to establish connections to a

JMS server.

A link to the Messaging Service is found under Extended Services in the

left-hand navigation bar.


JMS Provider Type is a drop-down list of configuration templates that

contain some pre-defined default settings for the type of JMS provider

being used. Theoretically, any provider that provides JNDI access to JMS

resources can be used with our product. If the specific provider is not on

the list, users should choose “Other JMS” to populate the configuration

with some commonly used, generic JNDI properties.

Connection Factory Name is the JNDI name of the JMS connection

factory.

Deliver Mode is the setting that controls whether or not the JMS

provider persists messages to storage for all processes. An individual

process can have a different persistence setting, which overrides this

setting. Enable this setting to persist messages in the event of a JMS

failure. When this mode is enabled, ActiveVOS instructs the JMS provider

to ensure that a message is not lost in transit in case of a JMS provider

failure. It is logged to stable storage. Note that persistent delivery

requires that your JMS provider be configured with storage. Also, there is

usually a performance hit with persisting messages. The default is

disabled, which means the messages are sent with non-persistent

delivery mode. This mode does not require any knowledge of how a

provider is configured for storage.

Time to Live is the setting that allows you to specify the amount of time

an unconsumed message remains on a queue. If a message will become

obsolete after a certain period, you may want to set an expiration time.

The expiration of obsolete messages conserves storage and computing

resources.The default setting is zero, which means that the default for

the provider is used. Typically, this means that messages never expire

and remain on the queue forever. It should be noted that the manager

default for TTL may be overridden via policy for a specific invoke. The

jmsTTL attribute is used to specify the value in milliseconds.

<abp:JMSDeliveryOptions jmsTTL="2000"/>

This option is settable from the JMS policy dialog in designer.

Initial Context Properties are the set of name-value pairs used to

establish a connection to the server hosting the JMS resources for access

via JNDI lookup.


As an example, by selecting “Weblogic” as the provider type, a set of

default initial context properties that are generally used by Weblogic

clients is displayed to the user. Users would then update the values for

the URL, username, and password to match the users’ environment.

Queues & Listeners, Topics & Listeners

This section is where the listeners that receive messages on behalf of the

ActiveVOS engine are configured. At a minimum, a single listener bound

to a JNDI location on the server is needed to dispatch incoming messages

to the engine.

If more destinations are required to service requests, new definitions can

be added by clicking the “Add Queue” button.

The following properties are used to configure the destination and

listener class:

Queue Name/Topic Name (mandatory) descriptive name for the

configuration. This is the descriptive name for the listener

Note: The name must be a simple NCName. It is used a key used by the

ActiveVOS engine’s configuration of the internal JMS provider. This is

unlike JNDI names that often contain characters that cannot be used in

configuration paths thus the need for a separate entry.

JNDI Location (mandatory) location name used for JNDI

lookups

It is important to understand that ActiveVOS requires queue JNDI name,

not a queue name. That means your JMS service provider must use JNDI

store, which is not an issue if you work with application server

messaging. However, using a stand-alone JMS message server requires

all destinations be put as administered object in a JNDI store.

Listener Class (optional) Message listener class name

Selector (optional) JMS message selector string

Default Service Name is an optional property where users can specify

the name of the BPEL service to use when the target service cannot be

determined from the addressing headers or message properties.


About Active Endpoints Active Endpoints (www.activevos.com) is the leading developer of visual

orchestration systems. VOS empowers line of business project teams to

create applications using services and industry standards, making their

businesses more agile and effective. Active Endpoints’ ActiveVOS

promotes mass adoption of SOA-enabled applications by focusing on

accelerating project delivery time with a standards-based, easy to use

system. Active Endpoints is headquartered in Waltham, MA with

development facilities in Shelton, CT.

To find out how Active Endpoints can help your business, visit

http://www.activevos.com, call +1 781 547 2900 and press 1 for Sales, or

email us at [email protected].

http://www.activevos.com/

http://www.activevos.com/

Documents

ActiveVOS JMS Transport Options