SOAP Over JMS without using WSDL Approach inTIBCO BW

Background

Web Service is increasingly popular and SOAP is rapidly becoming the standard protocol for accessing Web Services as well as to implement SOA focussed solutions.

Since SOAP is a specification for using XML documents as messages, it doesn’t provide guidelines for using transport specification. Due to that there have been interoperability issues in implementation of SOAP standard. Though HTTP is the widely used as transport protocol, but it has limitation on reliability so mission critical data kept under risk.

JMS is another messaging standard and currently getting familiar due to multiple reasons such as reliability, open standard and ease to secure etc. As of now no standard available to us to send / receive SOAP messages over JMS transport.

W3C published a specification for SOAP over JMS (SOAP over JMS RC1 1.0). The objective was to standardise the SOAP/JMS binding.

However vendors are yet to fully adapt this specification. At present the vendors like TIBCO implement their own standard which is most of the time causes interoperability.

The purpose of the document is to provide the overview of W3C specification and how can it be implemented using TIBCO.

SOAP over JMS – Overview

This section will give you the high level overview of standards proposed in SOAP over JMS RC0.1 Also provides the recommendation for using JMS IRI to define JMS bindings.

As part of this standard, two message specifications (JMS bindings) has been recommended, those are,

1. Standard JMS message with SOAP envelope

2. WSDL with JMS bindings

Also two Message Exchange Pattern (MEP) s has been considered, ie,

· Request-Response

· One Way

Standard JMS message with SOAP envelope

This specification recommends that send the XML payload within the SOAP envelope as body of the standard JMS message and include SOAP properties with standard JMS properties.

Envelope is the container of SOAP message. It contains encodingStyle attribute, header, body, Fault and some additional attributes which can be used to for special purposes depending upon the application need.

To send the error /exception of the SOAP service, SOAP fault needs to be used.

Find below the list of properties for SOAP over JMS transport as per this specification,

JMS Message Header
JMSDeliveryMode	the value of the deliveryMode property or not set if not specified
JMSExpiration	calculated from the value of the timeToLive property or not set if not specified
JMSPriority	the value of the priority property or not set if not specified
JMSDestination	derived from the destinationName property
JMSReplyTo	if the replyToName property is specified, this is the JMS Destination object derived from that name.. Otherwise the implementation must determine the reply queue, and use the JMS Destination object which represents that queue; the queue may be a temporary queue generated as described in the JMS specification
JMS Message properties (other properties)
SOAPJMS_requestIRI	this is derived from the requestIRI property
SOAPJMS_bindingVersion	this is copied from the bindingVersion property
SOAPJMS_soapAction	the value of the soapAction property or not set if not specified
SOAPJMS_targetService	the value of the targetService property or not set if not specified
SOAPJMS_contentType	Inferred from the SOAP Envelope and presence of attachments.
SOAPJMS_soapMEP	http://www.w3.org/2003/05/soap/mep/request-response/ -- determined by requesting SOAP node

JMS Message Body
body	A SOAP envelope is serialized according to the media type specified in the JMS Message property SOAPJMS_contentType

WSDL with JMS bindings

In general, WSDL is widely used for web services. This specification extends the SOAP JMS binding in WSDL.

Few key points are,

Soap:binding element introduce a new URL for JMS binding ( http://www.example.org/2006/06/soap/bindings/JMS)
Soap:operation element of WSDL specification disallows soapActioon attribute in non-HTTP bindings. But this specification supersedes that, and allows the use of soapAction in the soap:operation element for SOAP/JMS bindings
Specifying properties via the JMS IRI. The IRI can represented as the location attribute on the soap:address element.

Implementation using TIBCO BusinessWorks

TIBCO has provided the implementation of SOAP over JMS by configuring SOAP Event Source palette & WSDL activities to define the SOAP message & define the JMS properties.

But it has got a limitation of addition of other JMS properties such as replytoQueue, Target service etc in WSDL as suggested in the W3C specification.

The other available option to implement the new SOAP over JMS standard using TIBCO product suite is by using JMS palette.

This document details this approach and critical configuration factors.

Instead of using standard SOAP palettes provided by TIBCO, JMS palettes are configured to send (JMS Queue/Topic Sender) and to receive (JMS Queue / Topic Receiver) the message.
A JMS application properties palette is used to configure the SOAP properties (as detailed below).
A SOAP message contains JMS Header, SOAP Properties along with standard JMS properties and SOAP envelope which is body of the message.
From client side, any given request is rendered as SOAP message and placed at destination. JMS provider will send the message to relevant destination which will be picked up the receiver(s).
At the server side the SOAP message will be parsed and based on the SOAP action property and message processing is performed.
The message exchange pattern (MEP) is checked at the server side whether to send the response back to the client.

The following sections detail the detailed BW processes configuration. The main processes are

Service Consumer
Service Provider

Service Consumer (Client):

The Service Consumer process outlined above makes a SOAP over JMS request and waits for response be it successful or resulting in a fault. The caller of the process must supply the payload of the request, the name of the SOAP operation to invoke and a time-out if required. The Make SOAP Request process will then render the request in a SOAP Envelope and send the request JMS message to a previously configured queue. Once the request is sent, the process will wait for a response message to be sent on a pre-configured /temporary queue. If no response is received within the time specified as a time-out in the process

call an error will be thrown.

The request response can be done by using

‘Send Request’ and ‘Wait for JMS Queue’ activity to receive the response from a static queue
‘Send Request’ and ‘Get JMS Queue Message’ activity to receive the response from a static queue
‘JMS Queue Requester activity to receive the response from temporary queue.

This example is developed using the Wait for JMS message activity to receive the response. JMS Requester activity can also be used for the request response scenarios. (while writing this document, both Wait for JMS and JMS Requester activity has open issue with static queues, ie, in case of static queues with multiple receivers the response is being picked up by wrong consumer).

When a response is received, the envelope is parsed and the payload extracted. The SOAPJMS_isFault property is checked to see if the payload is an actual response of a fault indicating some problem in the processing of the request. If it is a successful response the data is returned to the caller of the process as a BW any type, which must then be coerced into the expected schema by the caller.

If a fault was returned the payload is converted in to a BW Error and thrown for the caller to deal with.

Service Provider:

The Service Provider process contains a Process Starter (JMS Queue Receiver) that triggers when a JMS message is received on a given queue. Once the message is received and the process instance started, the payload of the message will be parsed and the SOAP Operation determined. The body of the message is passed to a dynamic process call which uses the SOAP Operation field to determine which actual process to call.

All processing of the message takes place in the dynamically called process and it will either return a payload for the response message, a SOAP fault thrown as an error or another error – typically a BW exception caused by some environmental problem. These last types of error should in general be caught and converted into a SOAP Fault, if not this process will catch any unexpected errors, and generate a generic Fault response for them.

Whether the processing of the request was a success or a failure, a response message will be built and sent on a JMS queue specified by the JMSReplyTo message header of the request that started the process. In case of client application requires the response in temporary queue the JMSReplyTo property of request kept as empty by the client.

Note: Because the Queue Receiver Process Starter has to be configured to listen to a given queue one of these processes will have to be implemented for each different queue

Render Fault

The Render Fault process is a small utility process that encapsulates an issue with generating QNames data type for fault element from a BW Mapper activity. The Schema for SOAP Faults uses a QName type element to contain the faultcode of the Fault message. QNames requires that a namespace with a prefix is added to the resulting XML document and that the qname refers to that namespace through the prefix. This is handled by the XSLT used in the Transform XML activity. As the Transform XML activities requires input and output to be in the same representation (here binary) a renderer activity converts the input data from an XML tree to the binary representation. Finally the resulting binary XML document is parsed and validated against the SOAP Envelope XSD. Functionally this step is superfluous, but it insures against difficult to diagnose errors where a SOAP/JMS service returns invalid Fault responses.

SOAP/JMS Headers and Properties

The SOAP over JMS draft standard proscribes how to use the JMS header and properties when transporting SOAP messages over JMS. The table below outlines which headers and properties used:

*Header*	*Requests*	*Responses*
JMSDestination	Set by BW	Set by BW
JMSDeliveryMode	“NON_PERSISTENT”	“NON_PERSISTENT”
JMSExpiration	Set to 2x the time-out of the request	Set to 2x the time-out of the request
JMSPriority	“4” – default value in BW	“4” – default value in BW
JMSTimestamp	Set by EMS Server	Set by EMS Server
JMSType	Set by BW	Set by BW
JMSReplyTo	Specified by caller	N/A
JMSMessageID	Assigned by EMS Server	Assigned by EMS Server
JMSCorrelationID	Not set	Copied from request
JMSRedelivered	Set by EMS Server	Set by EMS Server

*Property*	*Requests*	*Responses*
SOAPJMS_soapAction	Specified by caller	N/A
SOAPJMS_bindingVersion	“1.0”	“1.0”
SOAPJMS_contentType	“text/xml;charset=utf-8”	“text/xml;charset=utf-8”
SOAPJMS_targetService	N/A	N/A
SOAPJMS_isFault	N/A	Boolean – true iff Fault
SOAPJMS_requestIRI	“jms:” + <RequestQueueName>	Copied from request
SOAPJMS_soapMEP	“http://www.w3.org/2003/05/soap/mep/request-response/”

As the value of the SOAPJMS_contentType property indicates, the XML payload of the SOAP/JMS message should be encoded in UTF-8 and the JMS message body should be a Bytes type message.

Recommended Configuration:

Message Type - Bytes Message

Delivery Mode - Non Persistant for Queue Messages in case of Request / Response case; Persistant for Topic messages

JMS Expiration - Depending upon the application requirements (Do not set Zero)

Priority - Use Default (4)

Acknowledge Mode – Client acknowledgment