Warning:
This wiki has been archived and is now read-only.

SOAP-JMS FAQ

From SOAP-JMS Binding Working Group Wiki
Jump to: navigation, search

Background

What is this FAQ about?

This FAQ answers questions related to the SOAP/JMS binding. That binding provides a means to carry SOAP messages over the Java™ Messaging Service (JMS).

Why is interoperability between JMS providers out-of-scope?

The JMS specification itself only defines a Java Application Programming Interface (API), and does not define any details of how that API translates into information sent via any particular communications mechanism. Different JMS providers perform communications between JMS clients in different ways, and it is unlikely that you'll find two different implementations of the JMS APIs that work together.

As a consequence of this limitation, the SOAP/JMS specification makes no attempt to define a common communications approach for JMS, but rather operates on top of the JMS API.

Specification Details

Does the SOAP/JMS Binding work with Topics?

Yes. Topics may be used as JMS Destinations in conjunction with SOAP/JMS, however caution should be applied. See section 2.5.1 of the specification.

What is the point of the requestURI property?

The specification intends that the requestURI property (which appears on a JMS message as the SOAPJMS_requestURI message property) communicate certain parts of the JMS endpoint location URI used to invoke the service. The server might use this information for dispatching purposes, or for establishing more context for the request. As a result, this property has been included in the SOAP/JMS specification as a required property on a request message.

As an analogy, when using SOAP/HTTP, the client makes a request on a URL, something like http://www.example.com/my/path/to/service?valueX=20&valueY=30. The receiving host can use the query portion of the URL, in this case valueX=20&valueY=30 to further determine dispatching. The requestURI, then, exists to establish a parity between JMS and HTTP.

How does a SOAP/JMS message compare to a SOAP/HTTP message?

A SOAP message can be transmitted in a JMS or HTTP message. The SOAP message can be a simple SOAP envelope or it could be a MIME multi-part message with one of the MIME parts containing the SOAP envelope. For an equivalent SOAP request or response message, the message payload will be the same in either a JMS or an HTTP message.

In addition to the message payload, additional properties are also required in order to provide additional information that further describes the SOAP message. In the case of a JMS mesage, these additional properties will be JMS message properties, and in the case of an HTTP message, the additional properties will be HTTP headers.

So although JMS and HTTP are very different protocols, SOAP/JMS and SOAP/HTTP messages are similar in that they both contain a similar message payload and they both contain additional message properties that provide additional information about the message payload.

What is the point of the targetService property?

The targetService property within a JMS endpoint URI string is used to provide routing information to the SOAP receiving node to assist it in the dispatching of the request. For example, it could specify the name of the port component to be invoked by the SOAP receiving node (i.e. server). Each vendor implementation of the SOAP receiving node may decide whether or not to require the targetService property within a JMS endpoint URI.

Should I use TextMessage or BytesMessage?

Most situations will likely prefer the use of BytesMessage, which the specification recommends. However, the specification allows TextMessage, in case you have a situation that requires the use of human-readable messages (perhaps to facilitate audit logging), or if you need to inter-operate with an existing system that requires TextMessages. Note that implementations using TextMessages will perform worse than corresponding implementations using BytesMessages, particularly with respect to memory use and speed of message serialization/deserialization. Unless you have a good reason to use a TextMessage, you'll be better off if you use a BytesMessage.

Support for Non-Normative Message Exchange Patterns

The SOAP over Java Message Service 1.0 specification requires conformance with the following Message Exchange Patterns (MEP): Request-Response MEP and One-way MEP. Other MEPs, such as Robust In-Only and In-Optional-Out, are considered to be non-normative and are not documented in this specification.

Individual vendors might offer solutions that implement non-normative MEPs. Any such solutions are considered proprietary and may not be interoperable with other vendors.

If one or more vendors wish to introduce new MEPs to the SOAP over Java Message Service 1.0 specification, an extension to the specification should be developed.


Relationship to Other Specifications

Is SOAP/JMS Compatible With WS-I Basic Profile?

The short answer is that the working group is unaware of anything specifically incompatible with the two latest versions of WS-I Basic Profile. Of the four available versions of Basic Profile, version 1.0, and version 1.1 require the use of HTTP as the transport. Therefore, at least the one portion of the specification that deals with HTTP transport is obviously not applicable to SOAP/JMS. The two newer versions of WS-I Basic Profile (1.2 and 2.0) separate out HTTP specific constraints. It does appear, however, that some constraints flagged as specific to HTTP in the 1.2 & 2.0 versions may have analogous constraints when considered in the context of JMS.

Users of SOAP/JMS may want to look at and conform to WS-I Basic Profile where possible, because many of the rules of WS-I Basic Profile facilitate interoperability of different implementations of SOAP. Note, however, that the working group for SOAP/JMS has not attempted to identify which parts of WS-I Basic Profile apply for SOAP/JMS, and does not define what it might mean to "conform where possible". Nor has the group tried to identify portions of Basic Profile flagged as specific to HTTP that might correspond to appropriate and analogous constraints for JMS.

What is the relationship between SOAP/JMS and WS-Addressing?

Web Services Addressing works over any SOAP underlying protocol binding, including SOAP/JMS. Using the SOAP binding of WS-Addressing, behavior is described in terms of the abstract Message Exchange Patterns (MEPs) that a given binding supports. Addressing properties are conveyed in the form of SOAP headers. These properties are distinct from the transport properties specified at the JMS property level.

The SOAP/JMS binding provides both one-way and request-response MEPs. Otherwise the SOAP/JMS binding imposes no constraints on the use of Web Services addressing.

WS-Addressing provides a number of features. Some of these features are useful where the underlying transport lacks equivalent capability. For example, when using SOAP/HTTP without WS-Addressing, response and fault messages can only be returned on the HTTP response. Using WS-Addressing with the wsa:ReplyTo and wsa:FaultTo elements, business logic responses and faults can instead be returned after the initial communications channel has been closed, a so-called "asynchronous" response. This use of WS-Addressing can conserve potentially critical communication resources.

In contrast, the JMS API already decouples the original message from the corresponding response, so using of WS-Addressing to make response and fault return "asynchronous" is likely redundant. Instead, a JMS implementation will simply use the JMSReplyTo message property to indicate where a response or fault should be sent.

WS-Addressing also includes correlation properties. These properties are distinct from the similar sounding JMS message headers and properties. The SOAP/JMS binding does not define any equivalence.

What is the relationship between SOAP/JMS and other WS-* specifications?

WS-ReliableMessaging

WS-ReliableMessaging is not recommended in conjunction with SOAP/JMS since messaging providers that implement the JMS API already provide a reliable message transport. Therefore, the usefulness of WS-ReliableMessaging when also using SOAP/JMS is questionable at best. In fact, some implementations of WS-ReliableMessaging might be limited only to the HTTP transport.

WS-Security

The WS-Security specification defines various forms of SOAP message-level security which are independent from the actual transport (HTTP, JMS, etc.) used to exchange SOAP messages between the web services consumer and provider. Therefore, it is certainly expected that WS-Security can and will be used in conjunction with SOAP/JMS, similar to its use with SOAP over HTTP.

How to register a SOAP/JMS endpoint with UDDI v3.0?

UDDI provides a means to register endpoints for services, and includes a definition for HTTP endpoints. Due to UDDI's open ended design, anyone can define additional "tModels" that establish that an endpoint uses JMS instead of HTTP. However, no standard definition for such a tModel exists.

The working group for SOAP/JMS has concluded that a normative definition for such a tModel is beyond the scope of the charter. However, following the pattern from section 11.3 of the UDDI v.3.0 specification a proposal for a possible tModel follows:

tModel properties

Property Description
Name: w3-org:jms
Descripton: A web service that uses JMS transport
UDDI Key (v3): uddi:w3.org:transport:jms
Categorization: transport

tModel definition

The proposed tModel definition is as follows:

<tModel
 tModelKey="uddi:w3.org:transport:jms">
  <name>w3-org:jms</name>
  <description> A Web service that uses JMS transport</description>
  <overviewDoc>
    <overviewURL useType="text">
      http://www.w3.org/2002/ws/soapjms/wiki/2008-09_FAQ
    </overviewURL>
  </overviewDoc>
  <categoryBag>
    <keyedReference keyName="uddi-org:types:transport"
      keyValue="transport"
      tModelKey="uddi:uddi.org:categorization:types"/>
   </categoryBag>
</tModel>

Of course, to publish the above tModel with the key "uddi:w3.org:transport:jms", as per section 5.2.2 of the UDDI v. 3.0 specification, the tModels for the "key generators" of "uddi:w3.org:keygenerator", and "uddi:w3.org:transport:keygenerator" also need to be published.