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.
Supported configurations: WebSphere® Application Server
Version 7.0 introduces support for 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 Java API for XML-based RPC (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. sptcfg
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 you need to provide implementations for the client or server components.
Also, you need to make sure that the implementations are interoperable
with the client and server components provided by the Web services
engine in WebSphere Application Server.
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.
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.
bprac
- SOAPJMS_requestIRI: You must set this property
to the JMS endpoint URL associated with the request.
Note: In the W3C SOAP over Java Message Service 1.0
Specification, this property name is changed to SOAPJMS_requestURI.
- 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: You 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 that is used for the reply
message. The JMS message setJMSReplyTo method is
used to specify the queue. You 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
...