Process Developer supports a Java Messaging Service (JMS) invoke handler for invoking endpoints. This means that you can bypass the standard Process Developer 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 Metro 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 Process 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: Looking up a queue using a JNDI Name
<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
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:ReplyTo></wsa:Address>...</wsa:Address>
</wsa:ReplyTo>
<abx:param name="someProperty" value="value"
xmlns:abx="http://www.activebpel.org/bpel/extension" />
</wsa:ReferenceParameters>
Adding a JMS Delivery Options Policy Assertion to a Partner Role
The message sender (partner role) controls the messaging options used for JMS. When Process Server 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 can 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.
|
A text message content is XML text.
A bytes message content is a byte array.
|
|
SOAP the default format. 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.
XML 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 administration console.
|
|
If desired, specify a non-negative integer for a message handling priority. The default value is 0, which means that the default for the provider is used.
JMS defines a 10-level priority value with 0 as the lowest and 9 as the highest. Clients should consider 0-4 as gradients of normal priority and 5-9 as gradients of expedited priority. Priority is set to 4, by default.
|
|
This setting controls whether or not the JMS provider persists messages to storage for all processes. The default is
persistent .
Select
persistent to instruct the JMS provider to ensure that a message is not lost in transit in case of a JMS provider failure. A message sent with this delivery mode is logged to stable storage when it is sent. Note that persistent delivery requires that your JMS provider be configured with storage. Also, there is usually a performance hit with persisting messages.
Select
non-persistent
if desired. This mode does not require any knowledge of how a provider is configured for storage.
|
|
This setting allows you to specify the amount of time an unconsumed message remains on a queue (in milliseconds). If a message will become obsolete after a certain period, you may want to set an expiration time. The destruction of obsolete messages conserves storage and computing resources.
The default setting is 0, which means that the default for the provider is used. Typically, this means that messages never expire and remain on the queue forever.
|
|
In the Process Console, you can add multiple JMS Provider configurations. If you want to use one other than the default, you can specify the Manager name for a JMS Provider that has been configured.
|
Other attributes, such as the correlation id and expiration, can be set dynamically at runtime through a copy operation to the partner endpoint.
A
jmsCorrelationID
correlates response messages for two-way operations. By default, Process Server use the
wsa:MessageID
of the request as the unique correlation Id. You can use the default correlation id with an external consumer, provided that consumer will propagate the
JMSCorrelationID
from the request. If you notice a problem with invoke timeouts, a missing/incorrect correlation id can be the cause.
If the consumer will not propagate the correlation ID from the request, you can set an explicit
jmsCorrelationID
as an override in this policy. Note that using a static value becomes problematic if there could be more than one invoke waiting for a response on the same queue. If responses all use the same correlation id, there is no way to distinguish which response goes where. A workaround for this is to use a temporary queue for receiving responses. If using a temporary queue for responses, a correlation id is not necessary since there will be a unique temporary queue for each request-response pair.
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
jmsManagerID="JMSMessagingManagerName"
jmsMessageType="bytes"
jmsMessageFormat="xml"
jmsPriority="1"
jmsCorrelationID="12345678"
jmsExpiration = "9999999999"/>
</wsp:Policy>
</wsa:EndpointReference>
</partnerRole>
Configuring the Messaging Service in the Process Console
To take advantage of JMS messaging, your Process Server administrator must enable the Messaging Service within the Process Console. See the
Process Console Help
for details.
