ActiveVOS JMS Transport options Technical Note

ActiveVOS JMS Transport options Technical Note 2009 Active Endpoints Inc. ActiveVOS is a trademark of Active Endpoints, Inc. All other company and product names are the property of their respective owners. 2009

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... 10 JMS BPEL Listener... 10 Content Validation... 10 Determine Request Format (SOAP or XML)... 10 Determine the Target Service Name... 10 Sending Replies... 11 Messaging Manager... 12 About Active Endpoints... 14 Copyright 2009, Active Endpoints, Inc. Page 2 of 15

ActiveVOS JMS Support The Web Service Interactions using JMS available on the Active Endpoints web site describes how to define process that interact with Web Services using JMS for the transport. The sample accompanying the document includes a set of examples that demonstrate the following Message Exchange patterns (MEP). One-Way Request Request-Response with temporary reply destination Request-Response with durable reply destination Asynchronous message exchange This technical note provides you with reference information on the use of ActiveVOS s support of JMS. The following capabilities are provided. 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 durable reply destination Request-Response with temporary reply destination Copyright 2009, Active Endpoints, Inc. Page 3 of 15

JMS Invoke Handler To send a request using JMS Transport, you specify jms:address 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 request the following being placed on the queue with JNDI name queue/com.activee.jms.bpel.queue Partner Role Definition to use: <partnerrole endpointreference="static" invokehandler="jms:address"> <wsa:endpointreference> <wsa:address>queue/com.activee.jms.bpel.queue?onewayservice</wsa:add ress> </wsa:endpointreference> </partnerrole> Message Content: Message Format: SOAP (default) Message Type: Text (default) Message Properties: JMSTargetService = OneWayService (a name of your choosing) JMSCorrelationId = wsa:messageid JMSReplyDestination = none JMSReplyTo = none Copyright 2009, Active Endpoints, Inc. Page 4 of 15

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 is complete. 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, messages are not persisted, and no correlation information is necessary, reducing overhead. For a request-response operation, Partner Role Definition to use: <wsa:endpointreference> <wsa:address>queue/com.activee.jms.bpel.queue?jmstwowayservice</wsa: Address> </wsa:endpointreference> </partnerrole> Request Message Content: Message Format: SOAP (default) Message Type: Text (default) Request Message Properties: JMSTargetService = JMSTwoWayService JMSCorrelationId = wsa:messageid JMSReplyDestination = none JMSReplyTo = Temporary Reply Queue Destination object Response Message Content: Message Format: SOAP (matches request) Message Type: Text (matches request) Response Message Properties: Copyright 2009, Active Endpoints, Inc. Page 5 of 15

JMSTargetService = (not needed) JMSCorrelationId = (not needed) JMSReplyDestination = none 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 as a wsa:replyto endpoint. Partner Role Definition to use: <partnerrole endpointreference="static" invokehandler="jms:address"> <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: Message Format: SOAP (default) Message Type: Text (default) Message Properties: JMSTargetService = JMSTwoWayService JMSCorrelationId = wsa:messageid 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: Copyright 2009, Active Endpoints, Inc. Page 6 of 15

JMSTargetService = (not needed) JMSCorrelationId = wsa:relatesto = wsa:messageid from request JMSReplyDestination = none JMSReplyTo = none 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. If you are sending a one-way request and expect a callback, you also 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 to use: <wsa:replyto> <wsa:address>queue/com.activee.jms.reply.queue?jmscallbackservice</w sa: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</ws a:address> </wsa:replyto> <abx:param name= someproperty value= value /> </wsa:referenceparameters> </wsa:endpointreference> Message Content: Message Format: SOAP (default) Message Type: Text (default) Message Properties: JMSTargetService = JMSOneWayService Copyright 2009, Active Endpoints, Inc. Page 7 of 15

JMSCorrelationId = wsa:messageid 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"/> Copyright 2009, Active Endpoints, Inc. Page 8 of 15

<xs:attribute name="jmsmanagerid" type="xs:string" use="optional"/> </xs:complextype> </xs:element> Specifying JMS Policy Partner Role Definition to use: <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.activeendpoints.com/ws/2005/12/policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/poli cy"> <abp:jmsdeliveryoptions jmsmessagetype="bytes" jmsmessageformat="xml" jmspriority="1" jmscorrelationid= 12345678 jmsexpiration = 9999999999 /> </wsp:policy> </wsa:endpointreference> </partnerrole> Message Content: Message Format: Bytes (set by jmsmessagetype) Message Type: Plain XML (set by jmsmessageformat) Message Properties: JMSTargetService = JMSOneWayService JMSCorrelationId = 12345678 JMSReplyDestination = none JMSReplyTo = none JMSPriority = 1 JMSExpiration = 9999999999 The message type, message format, and priority attributes may be set using the policy UI in the designer. Other attributes, such as the correlation id and expiration may be set dynamically at runtime through a copy operation to the partner endpoint. Copyright 2009, Active Endpoints, Inc. Page 9 of 15

If no correlation id override is set in policy, the value is set to the wsa:messageid. 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 app server s admin console. JMS BPEL Listener When a message is received by the JMS BPEL 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. Determine 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 Axis JMS receiver. Otherwise it is treated as a plain XML request. If the OAP envelope contains ws-addressing headers, these are deserialized and placed on the context. Determine 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 Copyright 2009, Active Endpoints, Inc. Page 10 of 15

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. activebpel/services/<<servicename>>) of the service suffices. JMS differs as outlined above. Sending Replies In order to deliver a reply for a request-response operation we need to determine the reply destination from the request message. Reply Destination If the JMSReplyTo Destination is set on the request message, we 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: Copyright 2009, Active Endpoints, Inc. Page 11 of 15

- 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, we 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 providerspecific 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.activeendpoints.com/ws/2005/12/policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"> <abp:jmsdeliveryoptions jmsmanagerid= xxxxxx /> </wsp:policy> Xxxx above represents the name with which you created a JMS provider in admin console. Copyright 2009, Active Endpoints, Inc. Page 12 of 15

The provider used to support JMS transport is configured in the BPEL admin 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. 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 BEA Weblogic as the provider type, a set of default initial context properties that are generally used by Weblogic clients is displayed to the user. The user would then update the values for the URL, username, and password to match his or her environment. Initially, the product will be installed with the ABE Internal JMS provider configured by default. This is an internal implementation of the JMS 1.1 specification that allows processes to send and receive JMS messages within the BPEL engine. This provider can be used to test sending and receiving messages from one process to another, but cannot be accessed directly by clients outside of the BPEL engine. In order to enable connectivity with external clients and services over JMS, the user needs to configure connections to an external JMS server. Queues & Listeners, Topics & Listeners This section is where the listeners that receive messages on behalf of the BPEL 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. Copyright 2009, Active Endpoints, Inc. Page 13 of 15

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 Copyright 2009, Active Endpoints, Inc. Page 14 of 15

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 info@activevos.com. Copyright 2009, Active Endpoints, Inc. Page 15 of 15