Copyright © Cloud Software Group, Inc. All Rights Reserved

SOAP Messages Over the JMS Transport

The HTTP transport does not provide guaranteed message delivery. The SOAP protocol is not specific to any transport, so SOAP messages in theory can be bound to any transport. JMS provides a highly reliable transport that can guarantee message delivery. TIBCO ActiveMatrix BusinessWorks supports sending and receiving SOAP messages over the HTTP and JMS transports.

As of Release 5.3.0, there is no standard specification for SOAP messages over JMS. TIBCO has proposed a specification with the following features:

•	One-way and request/response operations

•	Thee support is based on SOAP 1.1, SOAP 1.2, and WSDL 1.1

What's in the JMS Message

The following sections describe the content of the JMS message containing a SOAP request.

JMS Header

Table 10 describes the JMS Message Headers and Properties.

Table 10 JMS Message Headers and Properties for SOAP messages

JMS Message Headers and Properties	Description
TIBCO Compliant
Content_Type	This header must be one of the following: • application/xml for SOAP 1.1 or SOAP 1.2 without attachments • multipart/related for SOAP 1.1 or SOAP 1.2 Note: Content type parameters are also allowed, for example, charset=utf-8.
Mime_Version	Must be the string "1.0".
SoapAction	SOAPAction value as defined in the WSDL.
JMSDestination	This contains the destination name.
JMSReplyTo	This contains the reply to address to be used by service provider to return data. Currently, only temporary queues can be used for reply messages.
JMSMessageID	This contains a message ID generated by the JMS provider.
W3C SOAP Over JMS 1.0 Specification
SOAPJMS_targetService	This contains the Target Service value as defined in the WSDL.
SOAPJMS_bindingVersion	Must be the string "1.0"
SOAPJMS_contentType	This contains the format of the message sent.
SOAPJMS_soapAction	This contains the SOAPJMS_soapAction value as defined in the WSDL
SOAPJMS_isFault(boolean)	This contains the value of the SOAP JMS Fault.
SOAPJMS_requestURI	This contains the value of the location.

 

JMS Body

The JMS message body contains a binary representation of the actual SOAP message. Below is an example of a SOAP message.

 

<?xml version="1.0" encoding="UTF-8"?>

   <SOAP-ENV:Envelope xmlns:SOAP-ENV=

         "http://schemas.xmlsoap.org/soap/envelope/">

      <SOAP-ENV:Body SOAP-ENV:encodingStyle=

            "http://schemas.xmlsoap.org/soap/encoding/">

         <ns0:getCatalog xmlns:xs=

               "http://www.w3.org/2001/XMLSchema"

            xmlns:soap-enc=

               "http://schemas.xmlsoap.org/soap/encoding/"

            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

            xmlns:ns0="http://InputMessageNamespace"/>

      </SOAP-ENV:Body>

      </SOAP-ENV:Envelope>

WSDL Extensions

The following sections describe extensions to the WSDL standard to support the JMS protocol.

WSDL Binding

TIBCO Standard

The WSDL Binding for SOAP Over JMS varies only slightly from the SOAP Over HTTP binding. The transport attribute under soap:binding indicates that JMS is being used. The attribute must have the value: http://www.tibco.com/namespaces/ws/2004/soap/binding/JMS.

For example:

 

<soap:binding style="document"

   transport="http://www.tibco.com/namespaces/ws/2004/soap/binding/JMS"/>

In addition to the soap:binding transport information, there must be a JMS binding element that describe the message type used for transmission. Currently, the only supported message types are ByteMessage and TextMessage. This looks like the following:

 

<jms:binding messageFormat="bytes"/>

An example of the complete WSDL binding section is show below.

 

<wsdl:binding name="RetailJMSBinding" type="tns:RetailerPortType">

   <soap:binding style="document" transport=

            "http://www.tibco.com/namespaces/ws/2004/soap/binding/JMS"/>

   <jms:binding messageFormat="bytes"/>

   <wsdl:operation name="getCatalog">

      <wsdl:documentation>The operation has no documentation</wsdl:documentation>

      <soap:operation style="document" soapAction="RetailGetCatalog"/>

      <wsdl:input>

         <soap:body use="encoded"

            encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"

            namespace="http://InputMessageNamespace" parts=""/>

      </wsdl:input>

      <wsdl:output>

         <soap:body use="encoded"

            encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"

            namespace="http://OutputMessageNamespace" parts="return"/>

      </wsdl:output>

   </wsdl:operation>

   </wsdl:binding>

W3C SOAP Over JMS 1.0 Compliance

When the service is W3C SOAP Over JMS 1.0 compliant, the transport attribute under soap:binding has the value : http://www.w3.org/2010/soapjms/.

For example:

<soap:binding style="rpc" transport="http://www.w3.org/2010/soapjms/"/>

Additionally the JNDI namespace in WSDL is also http://www.w3.org/2010/soapjms/

An example of the complete WSDL binding section with W3C SOAP Over JMS 1.0 specification is as follows.

 

<wsdl:binding name="RetailJMSBinding" type="tns:RetailerPortType">

   <soap:binding style="document" transport=

            "http://www.w3.org/2010/soapjms/"/>

   <jms:binding messageFormat="bytes"/>

   <wsdl:operation name="getCatalog">

      <wsdl:documentation>The operation has no documentation</wsdl:documentation>

      <soap:operation style="document" soapAction="RetailGetCatalog"/>

      <wsdl:input>

         <soap:body use="encoded"

            encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"

            namespace="http://InputMessageNamespace" parts=""/>

      </wsdl:input>

      <wsdl:output>

         <soap:body use="encoded"

            encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"

            namespace="http://OutputMessageNamespace" parts="return"/>

      </wsdl:output>

   </wsdl:operation>

   </wsdl:binding>

 

WSDL Service

TIBCO Standard

The service section of the WSDL also contains extensions to support SOAP over JMS. The extension is defined with the following form where '?' means optional.

 

<wsdl:service>

   <jndi:context />?

   <jms:connectionFactory />?

   <wsdl:port>

      <jndi:context />?

      <jms:connectionFactory />?

      <jms:targetAddress />

   </wsdl:port>

</wsdl:service>

In this definition, both jndi:context and jms:connectionFactory elements can possibly appear at two locations and they must appear at least once. When they appear under wsdl:service, the definition applies to all ports inside the service. When they appear under wsdl:port, the definition applies to only that port and it overrides the definitions that appear at the service level if it exists. If they do not appear at the service level, then each port must define them.

The jms:connectionFactory element is the JMS connection factory name that is used to connect with JMS service, using the JNDI context supplied in the jndi:context element. Below is an example of using TIBCO Enterprise Message Service as the JMS provider.

 

<jms:connectionFactory>QueueConnectionFactory

</jms:connectionFactory>

In a simple configuration, the jms:connectionFactory is the same for both the Service Provider and the Service Clients. However, both provider and clients can use different connection factories, provided that they all create connections to the same JMS provider instance.

The jms:targetAddress element contains address information which the service provider is going to listen for messages. Below is an example of using TIBCO Enterprise Message Service as the JMS provider with a queue name of MyQueue.

 

<jms:targetAddress destination="queue">MyQueue</jms:targetAddress>

The jndi:context element holds one or more jndi:property elements. Each of the jndi:property elements describes a JNDI name/value pair. For example,

 

<jndi:context>

   <jndi:property name="java.naming.factory.initial"

        type="java.lang.String">

         com.tibco.tibjms.naming.TibjmsInitialContextFactory

   </jndi:property>

   <jndi:property name="java.naming.provider.url"

         type="java.lang.String">

         tibjmsnaming://localhost:7222

   </jndi:property>

</jndi:context>

MimePar

W3C SOAP Over JMS 1.0 Complaint

With W3C Compliance the jndi:property elements described in the JNDI name and pair value are dispalyed as :

 

<jms:jndiInitialContextFactory>com.tibco.tibjms.naming.TibjmsInitialContextFactory</jms:jndiInitialContextFactory>

<jms:jndiURL>tibjmsnaming://localhost:7222</jms:jndiURL>

Query Parameters

With W3C SOAP Over JMS 1.0 compliance, property names are displayed as query parameters with the value of SOAPJMS_requestURI within the WSDL ( attribute location and under <soap:address>) binding . They are supported in the client activities when referring to concrete WSDLs.

Property Names	Description
deliveryMode	JMS property for sending message
Priority	JMS property for sending message
timeToLive	JMS property for sending message
jndiConnectionFactoryName	Jndi property for connection factory name
jndiInitialContextFactory	Jndi property for Initial Context Factory name
jndiURL	Jndi property for JNDI connection
targetService	Property to dispatch the request

Fault Codes

Additional fault codes are introduced with the W3C SOAP Over JMS 1.0 compliance. The following table lists the fault codes.

Error Fault	Condition
mismatchedSoapAction	If using SOAP 1.2, and the SOAPJMS_contentType property has an action parameter, and its value does not match with SOAPJMS_soapAction value.
missingContentType	If SOAPJMS_contentType property is missing.
missingRequestURI	If SOAPJMS_requestURI property is missing.
missingTargetService	If mentioned in WSDL and SOAPJMS_targetService property is missing.
targetServiceNotAllowedInRequestURI	If targetService parameter is included in the SOAPJMS_requestURI.
unrecognizedBindingVersion	if the value of the SOAPJMS_bindingVersion property does not match the fixed value 1.0.

Copyright © Cloud Software Group, Inc. All Rights Reserved