Monday, August 19, 2013

Soap over JMS using TIBCO BusinessWorks

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.
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
 -- 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 




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





9 comments:

  1. Tibco BW/EMS Online Training
    www.21cssindia.com/courses/tibco-bw-ems-online-training-163.html
    Tibco BW/EMS online training institute in India, Tibco BW/EMS online training institute in murlinagar, online training in Tibco BW/EMS , Tibco BW/EMS online ...

    ReplyDelete
  2. Thanks for sharing such a interesting post about TIBCO Training. Keep posting like this and increase your viewers.

    ReplyDelete