activevos jms transport options
TRANSCRIPT
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
Copyright © 2011, Active Endpoints, Inc. Page 3 of 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
Copyright © 2011, Active Endpoints, Inc. Page 4 of 15
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
Copyright © 2011, Active Endpoints, Inc. Page 5 of 15
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.
Partner Role Definition
<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 (note the capitalization of these
properties)
JmsTargetService = JMSTwoWayService
JmsCorrelationID = wsa:MessageId
JmsReplyDestination = none
JMSReplyTo = Temporary Reply Queue Destination object
Response Message Content
Copyright © 2011, Active Endpoints, Inc. Page 6 of 15
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)
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 specified as a wsa:ReplyTo endpoint in the partner role definition
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
Message Format: SOAP (default)
Message Type: Text (default)
Message Properties (note the capitalization of these properties)
JmsTargetService = JMSTwoWayService
JmsCorrelationID = wsa:MessageId
JmsReplyDestination = queue/com.activee.jms.reply.queue
JMSReplyTo = none
Response Message Content
Copyright © 2011, Active Endpoints, Inc. Page 7 of 15
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
JmsReplyDestination = none
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
Copyright © 2011, Active Endpoints, Inc. Page 8 of 15
Message Format: SOAP (default)
Message Type: Text (default)
Message Properties (note the capitalization of these properties)
JmsTargetService = JMSOneWayService
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
<!-- ///////////////////////////////////////////////////////// JMS Transport Policy Assertions //////////////////////////////////////////////////////// --> <!-- Simple enumeration type for the jms message
type attribute. Default is 'text'. --> <xs:simpleType name="jmsMessageTypeEnum"> <xs:restriction base="xs:string"> <xs:enumeration value="text"/> <xs:enumeration value="bytes"/> </xs:restriction> </xs:simpleType> <!-- Simple enumeration type for the jms message format attribute. Default is 'soap'. --> <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"
Copyright © 2011, Active Endpoints, Inc. Page 9 of 15
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
Copyright © 2011, Active Endpoints, Inc. Page 10 of 15
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.
Copyright © 2011, Active Endpoints, Inc. Page 11 of 15
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.
Copyright © 2011, Active Endpoints, Inc. Page 12 of 15
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.
Copyright © 2011, Active Endpoints, Inc. Page 13 of 15
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.
Copyright © 2011, Active Endpoints, Inc. Page 14 of 15
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.
Copyright © 2011, Active Endpoints, Inc. Page 15 of 15
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].