Network Deployment (Distributed operating systems), v8.0 > Reference > Developer detailed usage information
SOAP over JMS protocol
The web services engine supports the use of an emerging industry standard SOAP over Java Message Service (JMS)-compliant messaging transport as an alternative to HTTP for communicating SOAP messages between clients and servers.
This product supports an emerging industry standard SOAP over JMS protocol. The SOAP over JMS specification 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 Java API for XML Web Services (JAX-WS) and JAX-RPC web services. By using the JMS transport, your enterprise beans based web service clients and servers can communicate through JMS queues and topics instead of through HTTP connections.
IBM and other vendors have been working on the proposed SOAP over JMS specification since 2005. The specification has been submitted to W3C and a working group is established. The current member submission of this draft specification was jointly published in October, 2007. Refer to the SOAP over JMS specification for details of this industry standard.
This topic provides a summary of the emerging industry-standard SOAP over JMS protocol. Use this SOAP over JMS transport protocol if provide implementations for the client or server components. Also, 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 javax.jms.BytesMessage object or a javax.jms.TextMessage object 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: 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, 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 specification contains more information about the Content-Type header.- enableTransaction: Set this optional property to true on an outbound JMS request message if you 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. This property is an IBM extension to the SOAP over JMS specification.
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_requestURI: We must 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. 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 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 that the URI is resolvable. Typically, this property is set to the soapAction value from the WSDL document.
- SOAPJMS_targetService: We must 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: This property 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 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: This property 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: This property 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 ...
Differences in SOAP versions
Use SOAP over JMS to transport web services
Configure a permanent reply queue for web services using SOAP over JMS
Related
JMS endpoint URL syntax
Web services specifications and APIs
SOAP over JMS specification