The work described in this and related documents is aimed at a set of standards for the transport of SOAP messages over JMS []. The main purpose is to ensure interoperability between the implementations of different Web services vendors. This will also enable customers to implement their own Web services for part of their infrastructure, and to have this interoperate with vendor provided Web services. The main audience will be implementers of Web services stacks; in particular people who wish to extend a Web services stack with an implementation of SOAP/JMS. This will enable them to write a SOAP/JMS implementation that will interoperate with other SOAP/JMS implementations, and that will not be dependent on any specific JMS implementation.

A motivational example is a customer who has different departments that use Web services infrastructure from two different vendors, VendorA and VendorB. The customer has a need for reliable Web services interaction between the departments. Where both these vendors provide support for SOAP/JMS according to this standard, it ought be possible for a client running using VendorA to interoperate with a service using VendorB.

The standards will also be of interest to providers of Web services intermediary services such as routing gateways; or SOAP/HTTP to SOAP/JMS gateways. We do not discuss any details of how such gateways might be designed and configured, but adherence to the standard will help the gateway ensure proper interoperation with SOAP/JMS clients and services.

The documents cover three major areas.

Note that the URI specification is in a separate document.

It is important to stress what this standard does NOT provide.

This document specifies how SOAP binds to a messaging system that supports JMS. Binding is specified for both SOAP 1.1 [] and SOAP 1.2 [] using the SOAP 1.2 Protocol Binding Framework.

The approach taken for this specification is to model it on the binding specifications that have been created for SOAP 1.2. The first of these was for a SOAP HTTP Binding, described in section 7, SOAP HTTP binding, []. A second binding for Email [] is also available.

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [].

Parenthetic remarks about fault subcodes are mentioned throughout the document where a conformance issue could result in an error. The section discusses the treatment of these subcodes.

Assertions in this specification are marked by a dagger symbol (†) at the end of a sentence. Each assertion has been assigned a unique identifier that consists of a descriptive textual prefix and a unique numeric suffix. The numeric suffixes are assigned sequentially and never reused so there could be gaps in the sequence.

The assertions and their identifiers are summarized in section .

This specification defines two features, each of which has conformance criteria associated with it. A conforming implementation MUST work with JMS.

This section covers the SOAP/JMS binding, and implicitly the JMS calls that need to be made. One might think of the JMS calls as the SOAP/JMS message format. This is almost correct, but not completely. JMS is strictly an API and does not define a message format. Also, this document covers how the SOAP/JMS implementation connects to the JMS service and selects the appropriate destination.

This part covers details such as how JMS connections and destinations are handled. It also covers the message content, including how properties and headers such as priority, soapAction and targetService are handled within the SOAP/JMS implementation.

There are a number of properties that affect how the binding behaves. The following properties are grouped into related sets.

Some of the properties are optional. Properties can be obtained from a number of sources. If a given property is specified in more than one of these, the following list specifies the precedence: the first MUST be used in preference to the second.

If a given property is specified more than once in the JMS URI the last instance of the property MUST be used.

Security, and in particular authentication, is a critical concern in most if not all environments where this binding will be utilized. There are at least two places where authentication might need to occur — 1) authenticating to the registry (i.e. JNDI) where JMS Destinations are located, and 2) authenticating to the JMS system itself. Credentials such as usernames and passwords might be required to access directories and to obtain JMS Connections from ConnectionFactories. This specification does not mandate how an implementation might obtain these credentials, although typically they can be available as API parameters, environment variables, or in thread context storage.

Implementers of this binding are encouraged to consider the most appropriate way to expose authentication functionality to their users such that it meshes smoothly with the models exposed by their environments.

The contents of the JMS Message body MUST be the SOAP payload as a JMS BytesMessage or TextMessage. While the requesting node can support either BytesMessage or TextMessage, the receiving node MUST support both BytesMessage and TextMessage. If the message is formatted as a JMS BytesMessage, then the sender and receiver MUST use the writeBytes() and readBytes() methods, respectively. A fault MUST be generated with subcode unsupportedJMSMessageFormat when the arriving message format is not BytesMessage or TextMessage.

After being decoded according to the contentEncoding property, the bytes or characters of the JMS Message payload correspond to the MIME format as indicated by the definition of the contentType property. In this way, the SOAP node determines the proper formatting of the SOAP payload irrespective of the underlying JMS message type, and specifies an appropriate value for the contentType property which describes it to the receiving SOAP node. Specifically, if the payload is formatted as a MIME multipart message, then the first byte or character encountered in the JMS Message body MUST be the start of the MIME boundary for the start of the first part — what MIME Part One [] section 2.5 calls a "Body Part". If the message is formatted as "text/xml" or "application/soap+xml", then the first byte or character of the JMS Message body MUST be the start of a conforming XML document.

In the case of SOAP 1.1 there is no formal specification of Message Exchange Patterns. A conforming SOAP-JMS Binding instance MUST support both the generic "request/response" and "one-way" patterns as specified in this document.

In the case of SOAP 1.2 a conforming SOAP-JMS Binding instance MUST support the following message exchange patterns:

There are tables of JMS properties, and explanations of their values, in the remainder of this section. Note that only the relevant properties (i.e. ones affected by this specification) have been included — other properties will continue to follow the normal JMS specification. For instance, the JMSMessageID header will be present on all messages, and automatically generated by the underlying JMS implementation.

For binding instances using the Request-Response Message Exchange Pattern:

The remainder of this section consists of descriptions of the MEP state machine. In the state descriptions following, the states are defined as values for the property http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/State.

Failure reasons as specified in the tables represent values of the property http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason - their values are qualified names. If an implementation enters the "Fail" state, the http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason property will contain the value specified for the particular transition.

The SOAP One-way MEP defines properties for the exchange of a SOAP/JMS message which does not solicit a response. For JMS messages sent to a Queue destination this MEP results in a SOAP message which will be received by zero or one receiver. For JMS messages sent to a Topic destination this MEP results in SOAP message(s) which will be received by zero, one, or many receivers.

This message exchange pattern is identified by the URI http://www.w3.org/2006/08/soap/mep/one-way/.

For binding instances conforming to this specification:

The remainder of this section consists of descriptions of the MEP. Failure reasons represent values of the property http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason — their values are qualified names. If a MEP instance terminates with a fault, then the http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason property will contain an value identifying the fault.

The SOAP fault subcodes listed throughout this document, and consolidated here, include:

The above subcodes are the local name in the soapjms namespace, appearing, for example, as soapjms:malformedRequestURI.

In SOAP 1.2, the subcodes above are used as-is in the env:Value element of the env:Subcode for a SOAP Fault. The following shows an example of a SOAP 1.2 Fault payload with the contentTypeMismatch subcode:

This specification does not mandate any particular text for the env:Text child element of the env:Reason element.

The SOAP 1.1 specification does not support subcodes directly. In that scenario, the faultcode element uses a QName that matches the subcode for SOAP 1.2. The faultstring element can contain textual fault information. The same error as above, shown in SOAP 1.1:

These next sections describe how to indicate the use of SOAP over JMS in WSDL. We begin with complete examples, and then describe the individual pieces and parts in the sections which follow.

The section above contains the actual rules by which SOAP messages are sent and received using JMS. This section indicates how WSDL can be used to indicate the use and control the operation of that binding.

For general information on extending SOAP bindings in WSDL, please refer to section 3, SOAP Binding, . For information about accepted SOAP 1.2 bindings, see [].

This section is normative.

This section describes the optional feature: soapjms:WSDL11 [&nsuri;WSDL11]. To focus on the salient details, all of the WSDL examples in this section show only a portion of a WSDL file in question.

The XML elements jndiConnectionFactoryName, jndiInitialContextFactory, jndiURL, deliveryMode, priority, timeToLive, and replyToName, in the soapjms namespace, MUST be supported when used in the context of the WSDL service, port, and binding elements. This specification does not define any use outside of those elements.