Web services SOAP/JMS protocol

Web services SOAP/JMS protocol

+
Search Tips | Advanced Search

Overview

The Web services engine supports the use of a JMS-compliant messaging transport as an alternative to HTTP for communicating SOAP messages between clients and servers.
You can use SOAP/JMS if provide implementations for the client or server components, and need to make sure that the implementations are interoperable with the client and server components provided by the Web services engine in WAS.

Client responsibilities

The client component is responsible for sending SOAP request messages and receiving SOAP response messages while adhering to the following protocol constraints:

The client must use either a JMS TextMessage, for example, javax.jms.TextMessage, or a BytesMessage, for example, javax.jms.BytesMessage, to transmit the SOAP request message to the server. If the request message contains attachments, a BytesMessage must be used. If the request message does not contain attachments, the client can use a TextMessage or a BytesMessage. The WebSphere product client implementation uses only a BytesMessage for the request message due to the potential need to transmit attachments.

The client must set the following properties on the JMS request message before sending the message to the destination queue or topic:

contentType This property is similar to the Content-Type header found in an HTTP message and is used to describe the content type of the message. A text-only SOAP message, for example, a message with no attachments, is written as follows:
text/xml; charset="UTF-8"

The contentType property in a SOAP request message that contains attachments must be set as follows:
multipart/related; type="text/xml"; start="<...content-id of first part...>"
This example represents a multi-part message, where the first part is of type "text/xml" that contains the SOAP message. The other parts of the multi-part message contain various attachments. The HTTP 1.1 specification contains more information about the Content-Type header.
enableTransaction Set this optional property to true on the outgoing SOAP/JMS request message if the server component should process the Web service request under the same transaction that was used to receive the message from the destination queue or topic. The client component should only set this property to true for a one-way request to avoid synchronization problems that can occur with a two-way Web service request. If this property is not set or is set to the default value of false, then the server will suspend the transaction that was used to receive the request message from the destination queue or topic prior to invoking the Web services engine to process the request.
endpointURL This property must be set to the JMS endpoint URL associated with the request.
soapAction This optional property is set on an outgoing SOAP/JMS request message to indicate the soapAction value associated with the Web services request. This property is similar to the SOAPAction HTTP header used when transporting Web service requests over an HTTP transport. The value of the soapAction property is a URI identifying the intent of the SOAP request. If the soapAction property is specified, it is used by the server component to determine the target of the request. The SOAP specification places no restrictions on the format or specificity of the URI or that it is resolvable. Typically, this property is set to the soapAction value from the WSDL document.
targetService This property must be set to the targetService property value that is found in the JMS-style endpoint location URL for the request. This value is used by the server component to determine the port component in the target when dispatching the request.
transportV This property indicates the version number of the protocol used by the client and server. Set the value to 1 (one).

If the SOAP request message represents a two-way request, the client component must set the JMS message’s replyTo property to specify the queue that is used for the reply message. The JMS message’s setJMSReplyTo method is used for this. It can be beneficial to configure a permanent replyTo queue on the client to prevent the client from having to set the JMS message’s replyTo property each time a Web service request is made.

If the SOAP request message represents a one-way request, the client component must not set the JMS message’s replyTo property.

The client component must be prepared to handle a reply message that is a BytesMessage or a TextMessage, regardless of the type of JMS message used to transmit the SOAP request. The WebSphere product implementation of the server component responds with the same type of JMS message that is received from the client, unless the response contains attachments and a BytesMessage must be used.

The client component can assume that the reply message correlation ID matches the original request message ID.

Server responsibilities
The server component is responsible for receiving the SOAP request messages and sending the SOAP response messages while adhering to the following protocol constraints:

The server must be prepared to receive a TextMessage or a BytesMessage. If the request contains attachments, a ByteMessage must be used. The WebSphere product implementation of the server component responds in kind when sending the reply message back to the client, unless the response contains attachments and a BytesMessage is used.

The server component must process the SOAP request properly to produce an appropriate SOAP reply message.

The server component must send a reply message back to the client only if the JMS request message’s replyTo property is set.

The server component must set the following properties in the JMS reply message before sending the message to the replyTo queue:

contentType See the description for this property in the client responsibilities section in this article.

The correlation ID of the JMS reply message should be set to the message ID of the original JMS request message. This is done by calling the JMS message’s setJMSCorrelationID method.
transportVersion This property indicates the version number of the protocol used by the client and server. Set the value to 1 (one).

Example: SOAP request without attachments

The following example displays the results from calling the JMS message’s toString method for a request message without attachments:
JMSMessage class: jms_bytes
JMSType:          null
JMSDeliveryMode:  2
JMSExpiration:    0
JMSPriority:      4
JMSMessageID:     ID:d438eebf04cb124aa25c5821110a134f0000000000000001
JMSTimestamp:     1092110476167
JMSCorrelationID: null
JMSDestination:   topic://NewsGroupTopic?topicSpace=FvtTopicSpace
JMSReplyTo:       null
JMSRedelivered:   false
JMS_IBM_System_MessageID: 6B6765B36943A18C_11000001 transportVersion: 1
JMSXUserID: targetService: NGConsumerJMS
JMSXAppID: Service Integration Bus endpointURL: jms:/topic?destination=jms/NewsGroupTopic&connectionFactory;=jms/NewsGroupTCF&targetService;=NGConsumerJMS
 contentType: text/xml; charset=utf-8
3c736f6170656e763a456e76656c6f706520786d6c6e733a736f6170656e763d22687474703a2f2f
736368656d61732e786d6c736f61702e6f72672f736f61702f656e76656c6f70652f2220786d6c6e
...
 
JMSMessage class: jms_bytes
JMSType:          null
JMSDeliveryMode:  2
JMSExpiration:    0
JMSPriority:      4
JMSMessageID:     ID:d438eebf04cb124aa25c5821110a134f0000000000000001
JMSTimestamp:     1092110476167
JMSCorrelationID: null
JMSDestination:   topic://NewsGroupTopic?topicSpace=FvtTopicSpace
JMSReplyTo:       null
JMSRedelivered:   false
JMS_IBM_System_MessageID: 6B6765B36943A18C_11000001 transportVersion: 1
JMSXUserID: targetService: NGConsumerJMS
JMSXAppID: Service Integration Bus endpointURL: jms:/topic?destination=jms/NewsGroupTopic&connectionFactory;
  =jms/NewsGroupTCF&targetService;=NGConsumerJMS
 contentType: text/xml; charset=utf-8
3c736f6170656e763a456e76656c6f706520786d6c6e733a736f6170656e763d22687474703a2f2f
736368656d61732e786d6c736f61702e6f72672f736f61702f656e76656c6f70652f2220786d6c6e
...
The following SOAP V1.1 example displays the payload from the previous message example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<postMessage><ngName xsi:type="xsd:string">news.current.events</ngName>
<msg xsi:type="xsd:string">This is a sample news item.</msg>
</postMessage>
</soapenv:Body>
</soapenv:Envelope>
Example: SOAP request with attachments
The following example displays the results from calling the JMS message’s toString method for a request message with attachments:
JMSMessage class: jms_bytes
JMSType:          null
JMSDeliveryMode:  1
JMSExpiration:    1092086312310
JMSPriority:      4
JMSMessageID:     ID:4bb64ed64e7d813d59ba5fec110a134f0000000000000001
JMSTimestamp:     1092086012310
JMSCorrelationID: null
JMSDestination:   queue://Logger_Q
JMSReplyTo:       queue://_Q_6B6765B36943A18C_00000385
JMSRedelivered:   false
JMS_IBM_System_MessageID: 6B6765B36943A18C_10000001 transportVersion: 1
JMSXUserID: targetService: WSLoggerJMS
JMSXAppID: Service Integration Bus endpointURL: jms:/queue? destination=jms/Logger_Q&connectionFactory=jms/Logger_CF&targetService=WSLoggerJMS contentType: multipart/related; type="text/xml";  start="<945414389.1092086011970.IBM.WEBSERVICES@myhost1>";      boundary="----=_Part_0_247953397.1092086011970"
0d0a2d2d2d2d2d2d3d5f506172745f305f3234373935333339372e31303932303836303131393730
0d0a436f6e74656e742d547970653a20746578742f786d6c3b20636861727365743d5554462d380d
...
The following displays the payload from the previous message example:
Content-Type: multipart/related; type="text/xml"; start="<945414389.1092086011970.IBM.WEBSERVICES@myhost1>"; boundary="----=_Part_0_247953397.1092086011970"

 

------=_Part_0_247953397.1092086011970
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: binary
Content-Id: <945414389.1092086011970.IBM.WEBSERVICES@myhost1>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<p499:InternationalizationContext soapenv:mustUnderstand="0"
  xmlns:p499="http://www.ibm.com/webservices/InternationalizationContext">
<Locales>
  <Locale>
    <LanguageCode>en</LanguageCode>
    <CountryCode>US</CountryCode>
  </Locale>
</Locales>
<TimeZoneId>America/Chicago</TimeZoneId>
</p499:InternationalizationContext>
</soapenv:Header>
<soapenv:Body>
  <sendJpegImage/>
</soapenv:Body>
<soapenv:Envelope>
------=_Part_0_247953397.1092086011970
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
Content-ID: <jpegImageRequest=81380956150.1092086011880.IBM.WEBSERVICES@myhost1>
<...contents of jpeg image file...>
SOAP response
The following example displays the results from calling the JMS message’s toString method for a SOAP reply message:
JMSMessage class: jms_bytes
JMSType:          null
JMSDeliveryMode:  2
JMSExpiration:    0
JMSPriority:      4
JMSMessageID:     null
JMSTimestamp:     0
JMSCorrelationID: ID:cdddb857f078a266eb9a972f110a134f0000000000000001
JMSDestination:   null
JMSReplyTo:       null
JMSRedelivered:   false contentType:
  multipart/related;
  type="text/xml"; 
  start="<961368106530.1092112854745.IBM.WEBSERVICES@yackerjr>";
  boundary="----=_Part_0_1655006754.1092112854745"
0d0a2d2d2d2d2d2d3d5f506172745f305f313635353030363735342e313039323131323835343734
350d0a436f6e74656e742d547970653a20746578742f786d6c3b20636861727365743d5554462d38
...
Review the API documentation for a complete list of APIs. You can also review several articles about the development of Web services at Web services: Resources for learning.

Related tasks
Use the JMS API to transport JAX-RPC Web services requests
Configure a permanent replyTo queue for JAX-RPC Web services using SOAP over JMS

contentType	This property is similar to the Content-Type header found in an HTTP message and is used to describe the content type of the message. A text-only SOAP message, for example, a message with no attachments, is written as follows: text/xml; charset="UTF-8" The contentType property in a SOAP request message that contains attachments must be set as follows: multipart/related; type="text/xml"; start="<...content-id of first part...>" This example represents a multi-part message, where the first part is of type "text/xml" that contains the SOAP message. The other parts of the multi-part message contain various attachments. The HTTP 1.1 specification contains more information about the Content-Type header.
enableTransaction	Set this optional property to true on the outgoing SOAP/JMS request message if the server component should process the Web service request under the same transaction that was used to receive the message from the destination queue or topic. The client component should only set this property to true for a one-way request to avoid synchronization problems that can occur with a two-way Web service request. If this property is not set or is set to the default value of false, then the server will suspend the transaction that was used to receive the request message from the destination queue or topic prior to invoking the Web services engine to process the request.
endpointURL	This property must be set to the JMS endpoint URL associated with the request.
soapAction	This optional property is set on an outgoing SOAP/JMS request message to indicate the soapAction value associated with the Web services request. This property is similar to the SOAPAction HTTP header used when transporting Web service requests over an HTTP transport. The value of the soapAction property is a URI identifying the intent of the SOAP request. If the soapAction property is specified, it is used by the server component to determine the target of the request. The SOAP specification places no restrictions on the format or specificity of the URI or that it is resolvable. Typically, this property is set to the soapAction value from the WSDL document.
targetService	This property must be set to the targetService property value that is found in the JMS-style endpoint location URL for the request. This value is used by the server component to determine the port component in the target when dispatching the request.
transportV	This property indicates the version number of the protocol used by the client and server. Set the value to 1 (one).

contentType	See the description for this property in the client responsibilities section in this article. The correlation ID of the JMS reply message should be set to the message ID of the original JMS request message. This is done by calling the JMS message’s setJMSCorrelationID method.
transportVersion	This property indicates the version number of the protocol used by the client and server. Set the value to 1 (one).