SOAP over JMS protocol

The Web services engine supports the use of an emerging industry standard SOAP over JMS-compliant messaging transport as an alternative to HTTP for communicating SOAP messages between clients and servers.

Supported configurations: WAS Version 7.0 introduces support for an emerging industry standard SOAP over JMS protocol. The SOAP over JMS spec provides a standard set of interoperability guidelines for using a JMS-compliant transport with SOAP messages to enable interoperability between the implementations of different vendors. Using this standard, 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. By using the JMS transport, the enterprise beans based Web service clients and servers can communicate through JMS queues and topics instead of through HTTP connections. sptcfg

IBM and other vendors have been working on the proposed SOAP over JMS spec since 2005. The specification has been submitted to W3C and a working group is established. The current member submission of this draft spec was jointly published in October, 2007. Refer to the SOAP over JMS specification for details of this industry standard.

This page provides a summary of the emerging industry-standard SOAP over JMS protocol. Use this SOAP over JMS transport protocol to provide implementations for the client or server components. Also, we 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 a BytesMessage, for example, javax.jms.BytesMessage, to transmit the SOAP request message to the server.

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

  • SOAPJMS_contentType: 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, has the following value set for this JMS message property:

    text/xml; charset="UTF-8"
    

    For a SOAP message containing attachments, use the following code to set the SOAPJMS_contentType property on the JMS message:

    multipart/related; type="text/xml"; start="<...content-id_of_first_ part...>" 
    

    This example represents a multipart message, where the first part is of type text/xml and contains the SOAP envelope. The other parts of the multipart message contain various attachments. The HTTP 1.1 spec contains more information about the Content-Type header.

  • enableTransaction: Set this optional property to true on an outbound JMS request message if we want the server component to process the Web service request under the same transaction that was used to receive the message from the destination queue or topic.

    Best practice: For client components, only set this property to true for one-way or two-way asynchronous requests to avoid synchronization problems that can occur with two-way synchronous Web service requests. If this property is not set or is set to the default value of false, the server suspends 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

  • SOAPJMS_requestIRI: Set this property to the JMS endpoint URL associated with the request.

  • SOAPJMS_soapAction: This optional property is set on an outbound JMS request message to indicate the soapAction value associated with the Web services request. 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 SOAPJMS_soapAction property is specified, it is used by the server component to determine the target of the request. The SOAP spec places no restrictions on the format or specificity of the URI nor does the specification require that 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, and the value must match the targetService property value that is found in the JMS endpoint URL for the request. This value is used by the server component to determine the port component to which the request is dispatched.

  • SOAPJMS_bindingVersion: Indicates the 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 that the reply message correlation ID matches the message ID of the original request message.

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

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

  • SOAPJMS_contentType: Is used to describe the content type of the message. See the description for this property in the client responsibilities section in this topic.

  • 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: Indicates the version number of the protocol used by the client and server.

    Set the value to 1.0.

Example: SOAP request without attachments

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

Example: SOAP request with attachments

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

SOAP response

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 tasks

Use SOAP over Java Message Service to transport Web services
Set a permanent reply queue for Web services using SOAP over JMS

 

Related

JMS endpoint URL syntax
Web services specifications and APIs

 

Related information

SOAP over Java Message Service specification