SOAP over JMS protocol

WAS v8.5 > Reference > Developer detailed usage information
SOAP over JMS protocol

SOAP over JMS-compliant messaging transport is an alternative to HTTP for communicating SOAP messages between clients and servers. A mixture of client and server components from different vendors can interoperate when exchanging SOAP request and response messages over the JMS transport for both JAX-WS and JAX-RPC web services. Enterprise beans can communicate through JMS queues and topics instead of through HTTP connections..
The client component is responsible for sending SOAP request messages and receiving SOAP response messages while adhering to the following protocol constraints:

To transmit the SOAP request message to the server, the client must use either...

javax.jms.BytesMessage
javax.jms.TextMessage

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

SOAPJMS_contentType Similar to the Content-Type header found in an HTTP message. Describes the content type of the message. A text-only SOAP message, for example, a message with no attachments, has the following value...
text/xml; charset="UTF-8"

For a SOAP message containing attachments...
multipart/related; type="text/xml"; start="<...content-id_of_first_ part...>"

The first part of this multi-part message is type text/xml, and contains the SOAP envelope. The other parts of the multipart message contain various attachments.
enableTransaction Optional. Set true on an outbound JMS request message to have server process the web service request under the same transaction used to receive the message from the destination queue or topic. This property is an IBM extension to the SOAP over JMS specification. For client components, to avoid synchronization problems that can occur with two-way synchronous web service requests, only set this property to true for one-way or two-way asynchronous requests If not set or is set to default of false, the server suspends the transaction used to receive the request message from the destination queue or topic prior to invoking the web services engine to process the request.
SOAPJMS_requestURI Set this property to the JMS endpoint URL associated with the request.
SOAPJMS_soapAction Optional property set on an outbound JMS request message to indicate the soapAction value associated with the web services request. 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 SOAPJMS_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 nor does the specification require the URI is resolvable.
Typically, this property is set to the soapAction value from the WSDL document.
SOAPJMS_targetService Set this property on an outbound JMS request message. The value must match the targetService property value found in the JMS endpoint URL for the request. Used by the server component to determine the port component to which the request is dispatched.
SOAPJMS_bindingVersion Version number of the protocol used by the client and server. Set the value to 1.0.

If the request message represents a two-way request, meaning that a reply is expected, the client component must set the JMS message JMSReplyTo property to specify the queue used for the reply message. The JMS message setJMSReplyTo method is used to specify the queue. We can benefit from configuring a permanent reply queue on the client to prevent the client from having to create a temporary queue each time a web service request is made. Read about configuring a permanent reply queue for web services using SOAP over JMS to learn more about creating this special queue.
If the SOAP request message represents a one-way request, meaning that a reply message is not expected, the client component must not set the JMS message JMSReplyTo property.

The client component can assume that a reply message is a JMS BytesMessage object.

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

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 component can expect to receive a JMS BytesMessage. If something other than a BytesMessage is received by the server component, then a fault with the subcode, unsupportedJMSMessageFormat, is returned to the client if a reply is expected.

The server component can expect to receive a javax.jms.BytesMessage object or a javax.jms.TextMessage object. If something other than a BytesMessage or TextMessage is received by the server component, then a fault with the subcode, unsupportedJMSMessageFormat, is returned to the client if a reply is expected.

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 JMSReplyTo property is set. The JMS message getJMSReplyTo method is used to retrieve the JMSReplyTo property value from the JMS message. This property value indicates the reply destination.

When sending a reply message, the server component must use the same message type as the request. If the request was received as a BytesMessage, the reply must be sent as a BytesMessage. Similarly, if the request was received as a TextMessage, the reply must be sent as a TextMessage.
The server component must set the following properties in the JMS reply message before sending the message to the reply queue:

SOAPJMS_contentType Content type of the message.
correlation ID Set the correlation ID property of the JMS reply message to the message ID of the original JMS request message. This correlation is done by calling the JMS message setJMSCorrelationID method.
SOAPJMS_bindingVersion Version number of the protocol used by the client and server. Set the value to 1.0.

The following example displays the results from calling the JMS message toString method for a request message without attachments:
  JMSMessage class: jms_bytes
  JMSType:          null
  JMSDeliveryMode:  2
  JMSExpiration:    0
  JMSPriority:      4
  JMSMessageID:     null
  JMSTimestamp:     -1
  JMSCorrelationID: null
  JMSDestination:   null
  JMSReplyTo:       queue://_Q_7D6C2035383215AB00000000000F4241?busName=WsFvtBus
  JMSRedelivered:   false
    JMS_IBM_MsgType: 1
    SOAPJMS_contentType: text/xml; charset=UTF-8
    SOAPJMS_targetService: MaelstromWsEndpoint
    SOAPJMS_requestIRI: jms:jndi:jms/MyRequestQueue?jndiConnectionFactoryName=jms/MyConnFactory&targetService=MyPort1
    SOAPJMS_soapAction: "getQuote"
    SOAPJMS_bindingVersion: 1.0 3c3f786d6c2076657273696f6e3d22312e302220656e636f64696e673d227574662d38223f3e3c73
6f6170656e763a456e76656c6f706520786d6c6e733a736f6170656e763d22687474703a2f2f7363
68656d61732e786d6c736f61702e6f72672f736f61702f656e76656c6f70652f2220786d6c6e733a
7873643d22687474703a2f2f7777772e77332e6f72672f323030312f584d4c536368656d61222078
...
The following example displays the results from calling the JMS message toString method for a request message with attachments:
  JMSMessage class: jms_bytes
  JMSType:          null
  JMSDeliveryMode:  2
  JMSExpiration:    0
  JMSPriority:      4
  JMSMessageID:     null
  JMSTimestamp:     -1
  JMSCorrelationID: null
  JMSDestination:   null
  JMSReplyTo:       queue://_Q_F0940794C5CC2F84000000000044AA21?busName=WsFvtBus
  JMSRedelivered:   false
    JMS_IBM_MsgType: 1
    SOAPJMS_contentType: multipart/related; 
  boundary=MIMEBoundaryurn_uuid_B6BAFEADB1886ADC241205525550237; 
  type="text/xml"; start="<0.urn:uuid:B6BAFEADB1886ADC241205525550238@apache.org>"
    SOAPJMS_targetService: MaelstromWsEndpoint
    SOAPJMS_requestIRI: jms:jndi:jms/WebSvcsJMSQ?jndiConnectionFactoryName=
   jms/WebSvcsJMS_CF&targetService=MaelstromWsEndpoint
    SOAPJMS_soapAction: attachment
    SOAPJMS_bindingVersion: 1.0 2d2d4d494d45426f756e6461727975726e5f757569645f4236424146454144423138383641444332
34313230353532353535303233370d0a436f6e74656e742d547970653a20746578742f786d6c3b20
636861727365743d5554462d380d0a436f6e74656e742d5472616e736665722d456e636f64696e67
3a20386269740d0a436f6e74656e742d49443a203c302e75726e3a757569643a4236424146454144
4231383836414443323431323035353235353530323338406170616368652e6f72673e0d0a0d0a3c
736f6170656e763a456e76656c6f706520786d6c6e733a736f6170656e763d22687474703a2f2f73
6368656d61732e786d6c736f61702e6f72672f736f61702f656e76656c6f70652f2220786d6c6e73
3a7873643d22687474703a2f2f7777772e77332e6f72672f323030312f584d4c536368656d612220
786d6c6e733a7873693d22687474703a2f2f7777772e77332e6f72672f323030312f584d4c536368
656d612d696e7374616e63652220786d6c6e733a736f6170656e633d22687474703a2f2f73636865
...
The following example displays the results from calling the JMS message 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
...
Related concepts:

Differences in SOAP versions

Related

Use SOAP over JMS to transport web services
Configure a permanent reply queue for web services using SOAP over JMS

Reference:

JMS endpoint URL syntax
Web services specifications and APIs

Related information:

SOAP over Java Message Service specification

+
Search Tips | Advanced Search

SOAPJMS_contentType	Similar to the Content-Type header found in an HTTP message. Describes the content type of the message. A text-only SOAP message, for example, a message with no attachments, has the following value... text/xml; charset="UTF-8" For a SOAP message containing attachments... multipart/related; type="text/xml"; start="<...content-id_of_first_ part...>" The first part of this multi-part message is type text/xml, and contains the SOAP envelope. The other parts of the multipart message contain various attachments.
enableTransaction	Optional. Set true on an outbound JMS request message to have server process the web service request under the same transaction used to receive the message from the destination queue or topic. This property is an IBM extension to the SOAP over JMS specification. For client components, to avoid synchronization problems that can occur with two-way synchronous web service requests, only set this property to true for one-way or two-way asynchronous requests If not set or is set to default of false, the server suspends the transaction used to receive the request message from the destination queue or topic prior to invoking the web services engine to process the request.
SOAPJMS_requestURI	Set this property to the JMS endpoint URL associated with the request.
SOAPJMS_soapAction	Optional property set on an outbound JMS request message to indicate the soapAction value associated with the web services request. 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 SOAPJMS_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 nor does the specification require the URI is resolvable. Typically, this property is set to the soapAction value from the WSDL document.
SOAPJMS_targetService	Set this property on an outbound JMS request message. The value must match the targetService property value found in the JMS endpoint URL for the request. Used by the server component to determine the port component to which the request is dispatched.
SOAPJMS_bindingVersion	Version number of the protocol used by the client and server. Set the value to 1.0.

SOAPJMS_contentType	Content type of the message.
correlation ID	Set the correlation ID property of the JMS reply message to the message ID of the original JMS request message. This correlation is done by calling the JMS message setJMSCorrelationID method.
SOAPJMS_bindingVersion	Version number of the protocol used by the client and server. Set the value to 1.0.