SOAP over Java™ Message Service 1.0

Editors' copy $Date: 2008-05-01 19:16:48 $ @@ @@@@ @@@@

This version:
soapjms.html
Latest version:
http://dev.w3.org/cvsweb/~checkout~/2008/ws/soapjms/soapjms.html?content-type=text/html;charset=utf-8
Editor:
Jabba Desilijic Tiure, Criminal

Abstract

This document specifies how SOAP should bind to a messaging system that supports the Java™ Message Service (JMS) [Java Message Service]. Binding is specified for both SOAP 1.1 [SOAP 1.1] and SOAP 1.2 [SOAP 1.2 Messaging Framework] using the SOAP 1.2 Protocol Binding Framework.

Status of this Document

This document is an editors' copy that has no official standing.

Table of Contents

1. Introduction
    1.1 Background
    1.2 Out of Scope
    1.3 Context
    1.4 Notational Conventions
        1.4.1 XML Namespaces
    1.5 Conformance
2. The SOAP/JMS Underlying Protocol Binding
    2.1 Introduction
    2.2 Properties Affecting Binding
        2.2.1 Connection to a destination
        2.2.2 JMS Message Header properties
        2.2.3 JMS Message properties
        2.2.4 Binding of Properties to IRI
        2.2.5 Other Properties
    2.3 Authentication for SOAP/JMS
    2.4 The JMS Message Body
    2.5 Supported Message Exchange Patterns
        2.5.1 Support for Topic destinations
    2.6 Request-Response MEP
        2.6.1 Behaviour of Requesting SOAP Node
            2.6.1.1 Init
            2.6.1.2 Requesting
            2.6.1.3 Sending + Receiving
            2.6.1.4 Success and Fail
        2.6.2 Behaviour of Responding SOAP Node
            2.6.2.1 Init
            2.6.2.2 Receiving
            2.6.2.3 Receiving + Sending
            2.6.2.4 Success and Fail
    2.7 One-way Message Exchange Pattern
        2.7.1 Behaviour of Sending SOAP Node
        2.7.2 Behaviour of Receiving SOAP Node
    2.8 Faults
3. WSDL Usage
    3.1 Overview
    3.2 WSDL 1.1 Extensions Overview
    3.3 WSDL 2.0 Extensions Overview
    3.4 WSDL 1.1 Extensions Detail
        3.4.1 Example
        3.4.2 WSDL 1.1 Transport Identification
        3.4.3 WSDL 1.1 SOAP Action
        3.4.4 Specifying Properties In WSDL 1.1
        3.4.5 Specifying Properties Via the JMS IRI
    3.5 WSDL 2.0 Extensions Detail
    3.6 Properties
        3.6.1 Relationship to WSDL 2.0 Component Model
            3.6.1.1 Precedence

Appendices

A. References
B. SOAP/JMS Underlying Protocol Binding Examples (Non-Normative)
    B.1 SOAP Request without attachments
    B.2 SOAP Request with attachments
C. Acknowledgements (Non-Normative)
D. Change Log (Non-Normative)


1. Introduction

1.1 Background

The work described in this and related documents is aimed at a set of standards for the transport of SOAP messages over JMS [Java Message Service]. The main purpose is to ensure interoperability between the implementations of different Web services vendors. It should 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. It should 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 should 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 should 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.

  • The JMS calls that must be made to construct and interpret SOAP/JMS messages in 2. The SOAP/JMS Underlying Protocol Binding.

    Editorial note: pse20080521
    Note that we never actually specify JMS calls in our documentation. Do we want to add "must be implicitly made". Later on we mention "implicitly"
  • The WSDL binding that may be used to describe SOAP/JMS services in 3. WSDL Usage.

  • The IRI specification for JMS endpoints [URI Scheme for JMS] to be used by SOAP/JMS implementations (and potentially in other areas where a JMS IRI is required).

    Editorial note: pse20080521
    Minor Is "to be" weak? Is "that must be" better?.

Note that the IRI specification is in a separate document.

1.2 Out of Scope

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

  • It does NOT provide any mechanism for interoperation between two different JMS providers. In the example above, VendorA and VendorB are different providers of a Web services infrastructure, but the customer must still use a single implementation of JMS at both client and service side.

  • It does NOT define any (wire) format for SOAP/JMS messages.

    Editorial note: pse20080521
    Testing Angle: So, unlike other standards that specify wire-format and that validate conformance by intermediarys e.g. TCP proxys for WS-I SOAP/HTTP, we need to have some kind of facade/interceptor at the JMS level probably at the points in which messages are published and consumed - i.e. send, receive, onMessage listener at which to record and verify the interractions and properties.
  • It does NOT define how the Web services themselves will be presented to the application programmer. For example, it does not describe how the programmer will characterise a one-way message.

1.3 Context

This document specifies how SOAP should bind to a messaging system that supports the Java™ Message Service (JMS) [Java Message Service]. Binding is specified for both SOAP 1.1 [SOAP 1.1] and SOAP 1.2 [SOAP 1.2 Messaging Framework] 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, [SOAP 1.2 Part 2: Adjuncts]. A second binding for Email [SOAP 1.2 Email Binding] is also available.

1.4 Notational Conventions

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 [IETF RFC 2119].

Parenthetic remarks about fault subcodes are mentioned throughout the document where a conformance issue may result in a error. How these subcodes should be treated is dealt with in the section "Faults".

1.4.1 XML Namespaces

This specification uses a number of namespace prefixes throughout; they are listed in Table 1-1. Properties are named with XML qualified names. Property values are determined by the Schema type of the property, as defined in the specification which introduces the property. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see [XML Namespaces]).

Table 1-1. Prefixes and Namespaces used in this specification
PrefixNamespaceSpecification
soapjmshttp://www.w3.org/@@@@/@@/soapjmsDefined by this specification
xsd http://www.w3.org/2001/XMLSchema [XML Schema Structures]
wsdl11http://schemas.xmlsoap.org/wsdl/[WSDL 1.1]
wsdl20http://www.w3.org/ns/wsdl[WSDL 2.0 Core Language]
wsoaphttp://www.w3.org/ns/wsdl/soap[WSDL 2.0 Adjuncts]
wsdl11soap11http://schemas.xmlsoap.org/wsdl/soap/[WSDL 1.1]
wsdl11soap12http://schemas.xmlsoap.org/wsdl/soap12/[WSDL 1.1 for SOAP 1.2]

The binding defined by this specification is identified by the XML namespace URI [XML Namespaces] http://www.w3.org/@@@@/@@/soapjms.

It is the intent of the W3C SOAP JMS Binding Working Group that the SOAP over Java™ Message Service 1.0 XML namespace URI will not change arbitrarily with each subsequent revision of the corresponding XML Schema documents as the specifications transition through Candidate Recommendation, Proposed Recommendation and Recommendation status. However, should the specifications revert to Working Draft status, and a subsequent revision, published as a WD, CR or PR draft, results in non-backwardly compatible changes from a previously published WD, CR or PR draft of the specification, the namespace URI will be changed accordingly.

Editorial note: plh20080501
The above paragraph will need to be removed for the publication of the Recommendation.

1.5 Conformance

A conforming implementation MUST implement the requirements as specified in 2. The SOAP/JMS Underlying Protocol Binding. To the extent required by that section, conforming implementations MUST support the [URI Scheme for JMS], specifically the syntax manipulations required therein.

Editorial note: pse20080521
2 strong assertions.
A conforming implementation MAY implement the requirements in 3. WSDL Usage portion of this document, and if it does so, it MUST fully support the JMS IRI scheme, including its syntax, and the implications for invoking JMS related APIs.
Editorial note: pse20080521
So this is an optional section for our test suite. It's not spelt out what "support" means - e.g. I suspect the first answer is the ability to consume WSDL a SOAP/JMS WS Client. The ability to publish these WSDLs if that's what your framework claims testable is next. Todo check WSDL2.0 precedent

2. The SOAP/JMS Underlying Protocol Binding

2.1 Introduction

This section covers the SOAP/JMS binding, and implicitly the JMS calls that must be made. Many people may 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 should be handled. It also covers the message content, including how properties and headers such as priority, soapAction and targetService should be handled within the SOAP/JMS implementation.

2.2 Properties Affecting Binding

There are a number of properties that affect how the binding behaves. The following properties are grouped into related sets. A conforming implementation must support all these properties.

Editorial note: pse20080521
Strong assertion.

Properties can be obtained from a number of sources:

  • The JMS IRI (which may be specified in the WSDL, programmatically, on the command line etc.);

  • WSDL elements or attributes (in addition to the endpoint IRI), and;

  • The environment (for example local program variables, system environment variables etc).

If a property is specified in more than one of these places then a property in the Environment will be used in preference to one specified in WSDL that will itself be used in preference to the JMS IRI.
Editorial note: pse20080521
Strong assertions. Testable. What does the last sentence mean ?
If the property is specified more than once on the JMS IRI the last instance of the property will be used.

Editorial note: pse20080521
Strong assertion. Testable

2.2.1 Connection to a destination

Since the underlying JMS IRI scheme defines an open-ended scheme for identifying and connecting to destination, it is not possible to enumerate all the ways that connection information may be set. However, in the interest of specifying context information such as JNDI connection properties in such a way that they can apply to multiple services or endpoints, this specification enumerates specific properties.

[Definition: soapjms:lookupVariant ](xsd:string)
  • Specifies the technique to use for looking up the given destination name.

  • Must be specified in the JMS IRI, as the jms-variant portion of the syntax.

    Editorial note: pse20080521
    Strong assertion. Testable.
[Definition: soapjms:destinationName ] (xsd:string)
  • Specifies the name of the destination, for lookup as per the lookupVariant. If the variant is "jndi", this is the Java Naming and Directory Interface (JNDI) name of the destination (queue or topic). If the variant is "context", then the name is discovered via application context.

  • MUST be specified in JMS IRI, as the jms-dest portion of the syntax.

    Editorial note: pse20080521
    Strong assertion. Testable.
[Definition: soapjms:jndiConnectionFactoryName ] (xsd:string)
  • Specifies the JNDI name of the connection factory.

  • an optional property

  • MAY be specified in JMS IRI, WSDL, or somewhere else in the environment

    Editorial note: pse20080521
    Optional property. Implied assertion is that if specified, then the use of the property is as specificed above. Testable.
[Definition: soapjms:jndiInitialContextFactory ] (xsd:string)
  • Specifies the fully qualified Java class name of the InitialContextFactory to use. This is mapped to the javax.naming.Context.INITIAL_CONTEXT_FACTORY property to be set in the HashMap sent to an InitialContext constructor.

  • an optional property

  • MAY be specified in JMS IRI, WSDL, or somewhere else in the environment

Editorial note: pse20080521
Optional property, etc Testable
[Definition: soapjms:jndiURL ] (xsd:anyURI)
  • Specifies the JNDI provider URL, which is mapped to the java.naming.provider.url property to be set in the HashMap sent to an InitialContextconstructor.

  • an optional property

  • MAY be specified in JMS IRI, WSDL, or somewhere else in the environment

Editorial note: pse20080521
Optional property, etc. Testable

2.2.2 JMS Message Header properties

This set of properties provide information that will set the values of corresponding JMS Header fields. This specification assumes that the JMS provider validates the values set for the respective message header properties, rather than being explicitly constrained by this specification.

[Definition: soapjms:deliveryMode] (xsd:string)
  • indicates whether the request message is persistent or not. The valid values are "PERSISTENT" and "NONPERSISTENT". The default value is "PERSISTENT" (defaulted by JMS)

  • optional in IRI, optional in WSDL, optional in environment

  • if specified MUST appear in the JMS message in the header named JMSDeliveryMode. If the value of this property is "PERSISTENT" then the JMSDeliveryMode integer value must be set to DeliveryMode.PERSISTENT. If the value of this property is "NONPERSISTENT" then the JMSDeliveryMode integer value must be set to DeliveryMode.NONPERSISTENT.

Editorial note: pse20080521
Optional property. Strong assertions on how the JMS Message property is assigned and defaults. Testable
[Definition: soapjms:timeToLive] (xsd:long)
  • the lifetime, in milliseconds, of the request message. A value of 0 indicates an infinite lifetime. The default value is 0 (defaulted by JMS).

  • optional in IRI, optional in WSDL, optional in environment.

  • if specified, this is used to generate the value of the JMS header JMSExpiration.

    Editorial note: pse20080521
    Optional property. Strong assertions on how the JMS Message property is assigned and defaults(I suppose that if the default is wrong it could be a JMS provider defect or a SOAP/JMS provider defect. Testable
[Definition: soapjms:priority] (xsd:int)
  • the JMS priority associated with the request message. Valid values are integers between 0 (lowest priority) and 9 (highest priority). The default value is 4 (defaulted by JMS).

  • optional in IRI, optional in WSDL, optional in environment

  • if specified MUST appear in the JMS message in the header named JMSPriority.

Editorial note: pse20080521
Optional property. Strong assertions on how the JMS Message property is assigned and defaults. Testable
[Definition: soapjms:replyToName] (xsd:string)
  • Specifies the name of the destination to which a response message should be sent. If the replyToName property has a value it is used to lookup a destination using the lookupVariant. If the variant is "jndi", this is the Java Naming and Directory Interface (JNDI) name of the destination (queue or topic). If the variant is "context", then the name is discovered via application context.

  • optional in IRI, optional in WSDL, optional in environment

  • if specified, this is used to derive the value to be used in the JMS header JMSReplyTo

Editorial note: pse20080521
We have to test all the variants just like the original request. todo Do we mandate that JMSReplyTo is only for 2-Way MEPS

2.2.3 JMS Message properties

[Definition: soapjms:targetService] (xsd:string)
  • Used by the service implementation to dispatch the service request.

  • optional in IRI

  • if specified MUST appear in the JMS message in the JMS property named SOAPJMS_targetService.

Editorial note: pse20080521
Optional property. Strong assertion on how the JMS Message property is assigned. Testable
[Definition: soapjms:bindingVersion] (xsd:string)
  • Specifies the version of SOAP JMS binding that is being used.

  • fixed value "1.0" in the implementation, MUST appear in a JMS property named SOAPJMS_bindingVersion. [Definition: Fault subcode unrecognizedBindingVersion if the value of this property does not match the fixed value.]

Editorial note: pse20080521
2 strong statements. Testable
[Definition: soapjms:contentType] (xsd:string)

Note that the contentType value also indicates the MIME type of the primary message payload. This message property, then, identifies whether the message payload uses SOAP 1.1, SOAP 1.2, SOAP Messages With Attachments [SOAP Messages with Attachments] or MTOM [SOAP 1.1 Binding for MTOM 1.0] [SOAP MTOM] as the primary payload.

  • Describes the content of the SOAP message, this has the same values as the MIME Content-Type specified for a SOAP message over HTTP [IETF RFC 2045].

  • If the value of the property is text/xml or application/soap+xml, a charset parameter may be present; if the value of the property is multipart/related, a type parameter may be present.

  • if the charset parameter is specified it is checked to ensure that it matches the encoding value from the supplied XML. If there is a mismatch then a fault is generated. [Definition: Use fault subcode contentTypeMismatch in the event that the values do not match.]

  • if no charset parameter is supplied the charset MUST be inferred using the rules defined in appendix F, Autodetection of Character Encodings , [XML 1.0].

  • the type parameter MUST reflect the value specified in the Content-type part header for the first part (the SOAP body, so text/xml or application/xop+xml).

  • MUST appear in the JMS message in the JMS property named SOAPJMS_contentType. [Definition: Use fault subcode missingContentType if the SOAPJMS_contentType property is missing.]

Editorial note: pse20080521
Several strong statements. Potentially a lot of testing. todo Do we need statements on minimal support for UTF-8. UTF-16, ByteOrderMark etc etc
[Definition: soapjms:soapAction] (xsd:anyURI)
  • as with SOAP/HTTP

  • optional in WSDL, optional in environment

  • if specified MUST appear in the JMS message in the JMS property named SOAPJMS_soapAction

  • if using SOAP 1.2, and the contentType property has an action parameter, that parameter value MUST match this SOAPJMS_soapAction value. [Definition: Use fault subcode mismatchedSoapAction if the SOAP 1.2 action does not match]

Editorial note: pse20080521
Several strong statements. Testable
[Definition: soapjms:isFault] (xsd:boolean)
  • This property indicates whether a SOAP/JMS message is a fault. For senders, this property should be set to true when responding with a SOAP fault. When this property is true, the sending software should include a JMS property named SOAPJMS_isFault with a value of 1.

  • For receivers, this property is derived from the JMS property named SOAPJMS_isFault — if present and containing a value of 1, the value of soapjms:isFault is true. If omitted, or present with a value of 0, the value of soapjms:isFault is false.

Editorial note: pse20080521
Strong assertions. Testable
[Definition: soapjms:requestIRI] (xsd:string)
  • Specifies the JMS IRI of the service. The client MUST create this property which is derived from the supplied IRI. The client MUST remove the targetService query parameter if specified; SHOULD remove JMS Message Header properties; and MAY remove other query parameters (for example client security related properties).

  • a required property

  • MUST appear in the JMS message in the JMS property named SOAPJMS_requestIRI. [Definition: Use fault subcode missingRequestIRI if the SOAPJMS_requestIRI is missing from the message.]

Editorial note: pse20080521
Strong assertions. Testable

2.2.4 Binding of Properties to IRI

Implementations of this specification need to allow for the setting of the above properties. Some properties, as mentioned above can be inferred from context, or provided by the application environment. Some might be put into WSDL. In many cases, it is desirable to represent those properties as part of a URL-like representation. To conform to the latest enhancements to support internationalization, this specification references the [URI Scheme for JMS]. In particular, this section describes how the properties above are used in the IRI [IETF RFC 3987]. Note that the IRI scheme also defines query parameters, and where the query parameter names are the same, the same meaning is intended here.

For brevity, properties are shown without the SOAPJMS prefix. The "IRI representation" column describes how the property is carried in the IRI. The "Client treatment" column describes how the property should be treated in the process of forming the soapjms:requestIRI property. There are three options for this column:

  • As-is — the client SHOULD leave the information in the IRI as is.

  • Should exclude — the client SHOULD exclude the information from the generated requestIRI .

  • Must exclude — the client MUST not include the information in the generated requestIRI.

Table 2-1. Binding of Properties to IRI
Specification PropertyIRI RepresentationClient Treatment
deliveryMode as deliveryMode query parameterShould exclude
destinationNameas jms-dest portion of IRI syntax As-is
jndiConnectionFactoryName as jndiConnectionFactoryName query parameterShould exclude
jndiInitialContextFactory as jndiInitialContextFactory query parameterShould exclude
jndiURL as jndiURL query parameterShould exclude
replyToName as replyToName query parameterMust exclude
priority as priority query parameterShould exclude
targetService as targetService query parameterMust exclude
timeToLive as timeToLive query parameterShould exclude

Editorial note: pse20080521
Lots of must statements as to what is left-over in the requestIRI by the client side. Lots of statements on how the IRI representation maps to properties. Testable on these 2 levels

[Definition: Use fault subcode malformedRequestIRI when the IRI violates the expected syntax.]. [Definition: Use fault subcode targetServiceNotAllowedInRequestIRI when targetService parameter is included in the requestIRI).]

Editorial note: pse20080521
2 strong statements. Testable

2.2.5 Other Properties

It is possible to specify other properties on the IRI but they do not affect processing. Any such properties will be included in the JMS Message property requestIRI unless explicitly removed by the client.

Editorial note: pse20080521
Untestable ? Do we mean this ?

2.3 Authentication for SOAP/JMS

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 may 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 may be required to access directories and to obtain JMS Connections from ConnectionFactories. This specification does not mandate how an implementation should obtain these credentials, although typically they may be available as API parameters, environment variables, or in thread context storage.

Implementers of this binding should consider how to most appropriately expose authentication functionality to their users in a way that meshes smoothly with the models exposed by their environments.

Note:

Although technically possible, the specification of userid and/or password related properties in the IRI is not recommended.

Editorial note: pse20080521
Untestable?

2.4 The JMS Message Body

The contents of the JMS Message body MUST be the SOAP payload as a JMS BytesMessage. [Definition: Use fault subcode unsupportedJMSMessageFormat when the arriving message format is not supported by the application.]. The encoding will depend on whether the payload is simply a SOAP Envelope or whether there are any attachments, and the JMS "Content-type" header (section 3.3) will reflect this appropriately.

Editorial note: plh20080501
"section 3.3" (in paragraph above) doesn't seem to lead to the right place?!?
Editorial note: pse20080521
Strong assertions. Testable

In the case of a message without any attachments, the JMS Message Body will contain the properly encoded bytes of the XML SOAP message, and nothing else. In this case the Content-type will be "text/xml" (for SOAP 1.1) or "application/soap+xml" (for SOAP 1.2).

Editorial note: pse20080521
Strong assertions. Testable

In the case that there are attachments, the JMS Message Body will contain a multipart MIME message. The first thing encountered in byte stream MUST be the MIME boundary for the start of the first part — what MIME Part One [IETF RFC 2045] section 2.5 calls a "Body Part". The message will be encoded using SOAP Messages with Attachments [SOAP Messages with Attachments] or XOP [SOAP 1.1 Binding for MTOM 1.0] [SOAP MTOM], in either case with a Content-type of "multipart/related".

Editorial note: pse20080521
Strong assertions. Testable

2.5 Supported Message Exchange Patterns

An instance of a binding to JMS conforming to this binding specification MUST support the following message exchange patterns:

  • Request-Response

  • One-way

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

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 and in the case of SOAP 1.1 are specified in this document. Relevant information on how SOAP 1.1 should bind to HTTP is specified in that specification [SOAP 1.1].

Editorial note: pse20080521
Strong assertions. Testable. "should bind to HTTP" is this relevant?

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.

2.5.1 Support for Topic destinations

Topics may be used as destinations for SOAP messages over JMS. However, due to the potential complexities around how topics might interact with message-exchange patterns, this specification provides no guidelines as to how that message exchange might work. In particular, the "request-response" exchange clearly means something different when an unknown number of responses might be received. Even the "one-way" exchange over a JMS topic differs in subtle ways from the same exchange over HTTP, including the fundamental question of whether the message is received at all, by any listeners.

Editorial note: pse20080521
Testing optional - 1-ways perhaps

For these reasons, implementers and clients of this specification are advised to use caution when dealing with JMS topics. We strongly encourage implementers to carefully document their choices around the use and support of topic destinations.

2.6 Request-Response MEP

The http://www.w3.org/2003/05/soap/mep/request-response/ message pattern is described in section 6.2, Request-Response Message Exchange Pattern, [SOAP 1.2 Part 2: Adjuncts].

For binding instances conforming to this specification:

  • A SOAP Node instantiated at the JMS interface (sending and receiving) may take on the role (i.e. the property http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role) of RequestingSOAPNode.

    Editorial note: pse20080521
    "sending and receiving" confuses - omit ? Same comment below.
  • A SOAP Node instantiated at the JMS interface (sending and receiving) may take on the role (i.e. the property http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role) of RespondingSOAPNode.

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.

2.6.1 Behaviour of Requesting SOAP Node

The overall flow of the behaviour of a Requesting SOAP Node follows the outline state machine description contained in section 6.2, Request-Response Message Exchange Pattern, [SOAP 1.2 Part 2: Adjuncts]. The following subsections describe each state in more detail and apply to both SOAP 1.1 and SOAP 1.2 until stated otherwise.

2.6.1.1 Init

In the "Init" state, a JMS request is formulated and transmission of the request is initiated. The message must be created as a JMS BytesMessage as per section 4 above. A number of the message header properties are implicitly created by the use of the JMS api, the following table specifies how the properties described earlier explicitly affect the message constructed.

Editorial note: plh20080501
"section 4" (in paragraph above) doesn't seem to lead to the right place?!?
Table 2-2. Init State Values
FieldValue Set by Conforming Client
JMS Message Header
JMSDeliveryModethe value of the deliveryMode property or not set if not specified
JMSExpirationcalculated from the value of the timeToLive property or not set if not specified
JMSPrioritythe value of the priority property or not set if not specified
JMSDestinationderived from the destinationName property
JMSReplyToif the replyToName property is specified, this is the JMS Destination object derived from that name. Otherwise the implementation must determine the reply queue, and use the JMS Destination object which represents that queue; the queue may be a temporary queue generated as described in the JMS specification.
JMS Message properties
SOAPJMS_requestIRIthis is derived from the requestIRI property
SOAPJMS_bindingVersionthis is copied from the bindingVersion property
SOAPJMS_soapActionthe value of the soapAction property or not set if not specified
SOAPJMS_targetServicethe value of the targetService property or not set if not specified
SOAPJMS_contentTypeinferred from the SOAP Envelope and presence of attachments
JMS Message Body
bodyA SOAP envelope is serialized according to the media type specified in the JMS Message property SOAPJMS_contentType

Editorial note: pse20080521
Strong assertions. Testable..
2.6.1.2 Requesting

In the "Requesting" state, sending of the request continues while waiting for the start of the correlated response message. A correlated response message is one where the value of the JMSCorrelationID header field is the same as the value of the JMSMessageID of the request message. The response message will be received on the JMS Destination specified in the JMSReplyTo header above, and that Destination is where implementations should be listening.

Editorial note: pse20080521
Strong assertion that JMSCorrelationID is required.

If a correlated response message is received then a transition to "Sending + Receiving" is made.

If, for whatever reason (for example a timeout), no correlated response message is received then a failure reason receptionFailure is set and a transition to "Fail" is made.

Editorial note: pse20080521
Strong assertion. In practice the JMS receive call gets a timeout. Testable
2.6.1.3 Sending + Receiving

Receive a correlated message body that is assumed to contain a SOAP envelope serialised according to the rules for carrying a SOAP message in the media type specified in the JMS Message property SOAPJMS_contentType.

If a well formed response message is received a transition to "Success" is made.

Editorial note: pse20080521
Strong assertion about well formed. Testable.
2.6.1.4 Success and Fail

"Success" and "Fail" are the terminal states of the Request-Response MEP. Control over the message exchange context returns to the local SOAP node.

Editorial note: pse20080521
Strong assertion. Testable.

2.6.2 Behaviour of Responding SOAP Node

The overall flow of the behaviour of a Responding SOAP Node follows the outline state machine description contained in section 6.2, Request-Response Message Exchange Pattern, [SOAP 1.2 Part 2: Adjuncts]. The following subsections describe each state in more detail and apply to both SOAP 1.1 and SOAP 1.2 until stated otherwise.

2.6.2.1 Init

Receive and validate the inbound request message.

If a well formed request message is received a transition to the local SOAP node is made followed by a transition to the "Receiving" state.

If a malformed request message is received a transition to "Fail" is made.

2.6.2.2 Receiving

Waiting for Response Message to become available in Message Exchange Context as a result of processing the Request Message (note Request Message fully received on exit from Init state).

2.6.2.3 Receiving + Sending

Completing Request Message reception and Response Message transmission. (Response Message sent on exit from Receiving State).

The JMS request is formulated and transmission of the response is initiated. The message must be created as a JMS BytesMessage. A number of the message header properties are implicitly created by the use of the JMS api, the following table specifies how the properties described earlier explicitly affect the message constructed. The message MUST be sent to the JMS Destination in the JMSReplyTo header of the Request Message. The value of the JMSCorrelationID header field MUST be set to the same as the value of the JMSMessageID of the request message.

Table 2-3. Receiving + Sending State Values
FieldValue Set by Conforming Client
JMS Message Header
JMSDeliveryModethis SHOULD be the same as that specified on the request
JMSExpirationthis is derived from the request. It is up to the responding node to decide whether to degrade for processing time.
JMSPrioritythis is copied from the request
JMSCorrelationIDthis is copied from the request JMSMessageID
JMSDestinationthis is copied from the JMSReplyTo property in the request
JMS Message properties
SOAPJMS_requestIRIthis is copied from the requestIRI property in the request message
SOAPJMS_bindingVersionthis is copied from the bindingVersion property
SOAPJMS_contentTypeinferred from the SOAP Envelope and presence of attachments.
JMS Message Body
bodyA SOAP envelope is serialized according to the media type specified in the JMS Message property SOAPJMS_contentType.

Editorial note: pse20080521
Strong assertions. Testable..

If a response message is successfully sent a transition to the "Success" state is made.

If there is a failure to send a response message then failure reason transmissionFailure is set and a transition to "Fail" is made.

2.6.2.4 Success and Fail

"Success" and "Fail" are the terminal states for the Request-Response MEP. From the point-of-view of the local node this message exchange has completed.

2.7 One-way Message Exchange Pattern

The SOAP One-way MEP [SOAP 1.2 Part 3: 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 may be received by zero or one receiver. For JMS messages sent to a Topic destination this MEP results in SOAP message(s) which may 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:

  • A SOAP Node instantiated at the sending JMS interface may take on the role (i.e. the property http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role, defined in Table 2, Property definitions supporting the description of MEPs), of SendingSOAPNode.

  • A SOAP Node instantiated at the receiving JMS interface takes on the role (i.e. the property http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role) of ReceivingSOAPNode.

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 an fault, then the http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason property will contain an value identifying the fault.

2.7.1 Behaviour of Sending SOAP Node

The sending node MUST formulate a JMS request, make it available in the http://www.w3.org/2003/05/soap/mep/OutboundMessage property, and send it to the destination identified by http://www.w3.org/2003/05/soap/mep/ImmediateDestination.

The message must be created as a JMS BytesMessage as per section 4 above. A number of the message header properties are implicitly created by the use of the JMS API, the following table specifies how the properties described earlier explicitly affect the message constructed.

If the Sender receives a message transmission failure, then the http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason property is set to transmissionFailure and the message exchange is terminated with a fault.

Editorial note: pse20080521
Strong assertion. I'm familiar with the SOAP1.1 1-way can a SOAP 1.2 1-way return faults to the client, or is it fire and forget
Table 2-4. Sending SOAP Node Values
FieldValue Set by Conforming Client
JMS Message Header
JMSDeliveryModethe value of the deliveryMode property or not set if not specified
JMSExpirationcalculated from the value of the timeToLive property or not set if not specified
JMSPrioritythe value of the priority property or not set if not specified
JMSDestinationderived from the destinationName property
JMS Message properties
SOAPJMS_requestIRIthis is derived from the requestIRI property
SOAPJMS_bindingVersionthis is copied from the bindingVersion property
SOAPJMS_soapActionthe value of the soapAction property or not set if not specified
SOAPJMS_targetServicethe value of the targetService property or not set if not specified
SOAPJMS_contentTypeinferred from the SOAP Envelope and presence of attachments.
JMS Message Body
bodyA SOAP envelope is serialized according to the media type specified in the JMS Message property SOAPJMS_contentType.

Editorial note: pse20080521
Strong assertions. Testable..

2.7.2 Behaviour of Receiving SOAP Node

A receiving node MUST validate an inbound message, and if it determines that the message is successfully received, it MUST populate http://www.w3.org/2003/05/soap/mep/InboundMessage with the received message. It MUST then process the message in http://www.w3.org/2003/05/soap/mep/InboundMessage

If the Receiving SOAP Node receives a message receipt failure, or the inbound message is not valid then the http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason property MAY be set to transmissionFailure. The message exchange should terminate, and control over the message exchange context should return to the local SOAP node. (Note, however, that in many cases where receipt is unsuccessful, information identifying the message or its sender may be unreliable, in which case there may be little if any value in reflecting a message-specific fault.)

Editorial note: pse20080521
Untestable?

2.8 Faults

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

Editorial note: pse20080521
No strong assertions here about whether they are required. Do we need assertions ? Implied assertion could be that under failure conditions X,Y,Z faults A,B,C are produced. Testable.

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

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:

Example 2-1. SOAP 1.2 Fault payload with the contentTypeMismatch subcode

<env:Envelope
   xmlns:env="http://www.w3.org/2003/05/soap-envelope"
   xmlns:soapjms="http://www.w3.org/@@@@/@@/soapjms"
   xmlns:xml="http://www.w3.org/XML/1998/namespace">
 <env:Body>
  <env:Fault>
   <env:Code>
     <env:Value>env:Sender</env:Value>
     <env:Subcode>
      <env:Value>soapjms:contentTypeMismatch</env:Value>
     </env:Subcode>
   </env:Code>
   <env:Reason>
     <env:Text xml:lang="en">The content type of the JMS payload does 
                             not match the XML.</env:Text>
   </env:Reason>
   <env:Detail>
     <m:MaxTime>P5M</m:MaxTime>
   </env:Detail>    
  </env:Fault>
 </env:Body>
</env:Envelope>

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 detail element should have a single child element with the namespace and local name of that matches the subcode for SOAP 1.2. The same error as above, shown in SOAP 1.1:

Example 2-2. SOAP 1.1 Fault payload with the contentTypeMismatch subcode

<env:Envelope
     xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Body>
       <env:Fault>
           <faultcode>SOAP-ENV:Client</faultcode>
           <faultstring>Client Error</faultstring>
           <detail>
               <soapjms:contentTypeMismatch 
                  xmlns:soapjms="http://www.w3.org/@@@@/@@/soapjms" />
           </detail>
       </env:Fault>
   </env:Body>
</env:Envelope>

An implementation MAY choose to put a textual description as the contents of the element within the detail section. A portion of the above example with this change follows:

<env:detail>
   <soapjms:contentTypeMismatch 
        xmlns:soapjms="http://www.w3.org/@@@@/@@/soapjms">
     The content type of the JMS payload does not match the XML.
   </soapjms:contentTypeMismatch>
</env:detail>
Editorial note: pse20080521
These look like standard SOAP fault formatting details.All Testable

3. WSDL Usage

3.1 Overview

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 associated SOAP Underlying Transport Binding above contains the actual rules by which SOAP messages are sent and received using the Java Message Service. 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 section 3, SOAP Binding, WSDL 1.1. For information about accepted SOAP 1.2 bindings, see WSDL 1.1 for SOAP 1.2. For information about SOAP bindings in WSDL 2.0 see [WSDL 2.0 Adjuncts].

3.2 WSDL 1.1 Extensions Overview

  • The transport attribute of the wsdl11soap11:binding or wsdl11soap12:binding element gets a new URL reflecting a JMS transport.

  • Allows use of SOAPAction header, even though it is explicitly disallowed by WSDL specification.

  • Defines how to set various properties to control the behavior (connection parameters, runtime setting) of the binding.

  • Locates the service using a JMS IRI.

3.3 WSDL 2.0 Extensions Overview

  • The wsoap:protocol attribute of the binding element gets a new URL reflecting a JMS transport.

  • Defines how to set various properties to control the behavior (connection parameters, runtime setting) of the binding.

  • Locates the service using a JMS IRI.

3.4 WSDL 1.1 Extensions Detail

3.4.1 Example

Note:

This section is non-normative.

The [WSDL 1.1] specification includes in section 1.2, WSDL Document Example, the example Example 1 SOAP 1.1 Request/Response via HTTP.

The following example illustrates a new service description which assumes the original service available over HTTP is also made available over JMS.

Lines 14-33 are a new binding for specifying that JMS is to be used, line 15 shows the transport URI in <wsdl11soap11:binding>, and lines 17-22 show the extension properties in the <wsdl11soap11:binding>.

Lines 40-42 are also additions to specify the location at which this new implementation exists. Line 41 shows the JMS IRI Scheme jms: in the <wsdl11soap11::address>.

Example 3-1. WSDL 1.1 JMS Binding

1     <wsdl11:binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">
2        <wsdl11soap11:binding style="document" 
                transport="http://schemas.xmlsoap.org/soap/http"/>
3         <wsdl11:operation name="GetLastTradePrice">
4            <wsdl11soap11:operation soapAction="http://example.com/GetLastTradePrice"/>
5           <wsdl11:input>
6               <wsdl11soap11:body use="literal"/>
7            </wsdl11:input>
8           <wsdl11:output>
9               <wsdl11soap11:body use="literal"/>
10          </wsdl11:output>
11        </wsdl11:operation>
12    </wsdl11:binding>
13
14   <wsdl11:binding name="StockQuoteSoapJMSBinding" type="tns:StockQuotePortType" 
              xmlns:soapjms="http://www.w3.org/@@@@/@@/soapjms">
15       <wsdl11soap11:binding style="document" 
              transport="http://www.w3.org/@@@@/@@/soapjms"/>
16
17       <!-- We want this binding to use a particular CF class -->
18       <soapjms:jndiConnectionFactoryName>
19         sample.jms.ConnectionFactory
20       </soapjms:jndiConnectionFactoryName>
21       <!-- Specify PERSISTENT delivery mode -->
22       <soapjms:deliveryMode>PERSISTENT</soapjms:deliveryMode>
23
24       <wsdl11:operation name="GetLastTradePrice">
25         <wsdl11soap11:operation soapAction="http://example.com/GetLastTradePrice"/>
26         <wsdl11:input>
27             <wsdl11soap11:body use="literal"/>
28         </wsdl11:input>
29         <wsdl11:output>
30             <wsdl11soap11:body use="literal"/>
31          </wsdl11:output>
32       </wsdl11:operation>
33   </wsdl11:binding>
34
35   <wsdl11:service name="StockQuoteService">
36       <wsdl11:documentation>My first service</wsdl11:documentation>
37       <wsdl11:port name="StockQuotePort" binding="tns:StockQuoteSoapBinding">
38           <wsdl11soap11:address location="http://example.com/stockquote"/>
39       </wsdl11:port>
40       <wsdl11:port name="StockQuotePort_jms" binding="tns:StockQuoteSoapJMSBinding">
41           <wsdl11soap11:address location="jms:jndi:myQueue?targetService=stockquote"/>
42       </wsdl11:port>
43   </wsdl11:service>

The key points to notice are:

  • The transport URI in <wsdl11soap11:binding> (line 15)

  • The jms: IRI in the <wsdl11soap11:address> (line 41)

  • The extension properties in the <wsdl11soap11:binding> (lines 17-22)

3.4.2 WSDL 1.1 Transport Identification

The wsdl11soap11:binding element has a transport attribute. The developer indicates the use of the SOAP/JMS binding by putting http://www.w3.org/@@@@/@@/soapjms as the value of the transport.

Editorial note: pse20080521
Strong assertion. Testable.

Example 3-2. SOAP 1.1 Binding for WSDL 1.1 Transport Identification

<wsdl11soap11:binding style="document" 
                 transport="http://www.w3.org/@@@@/@@/soapjms"/>

3.4.3 WSDL 1.1 SOAP Action

The wsdl11soap11:operation portion of the WSDL specification explicitly disallows use of the soapAction attribute in non-HTTP bindings. This specification supersedes that requirement, and allows the use of soapAction in the wsdl11soap11:operation element for SOAP/JMS bindings. This value corresponds to the property soapAction.

Editorial note: pse20080521
Strong assertion. Testable.

3.4.4 Specifying Properties In WSDL 1.1

Various JMS properties described in the SOAP/JMS binding specification may be set in three places in the WSDL — the binding, the service, and the port. Values specified at the service will propagate to all ports/endpoints. Values specified at the binding will propagate to all ports/endpoints using that binding. For example, the jndiInitialContextFactory may be indicated for a wsdl11:service, and it is then implied for all of the contained wsdl11:port elements.

Editorial note: pse20080521
Strong assertions on where properties can appear. Testable.

If a property is specified at multiple levels, the most specific setting will take precedence (port first, then service, then binding). In the following example, notice the timeToLive property — for the quickPort port, the value will be 10 (specified at the port level). For the slowPort port, the value will be 100 (specified at the service level). The setting in the binding is, in this example, always overridden.

Editorial note: pse20080521
Strong assertions on precedence. Testable.

Example 3-3. Specifying Properties in WSDL 1.1

<wsdl11:binding name="exampleBinding">
  ...
  <soapjms:timeToLive>200</soapjms:timeToLive>
</wsdl11:binding>

<wsdl11:service name="exampleService">
  <soapjms:jndiInitialContextFactory>
    com.example.jndi.InitialContextFactory
  </soapjms:jndiInitialContextFactory>
  <soapjms:timeTolive>100</soapjms:timeToLive>
  ...
  <wsdl11:port name="quickPort" binding="tns:exampleBinding">
    ...
    <soapjms:timeToLive>10</soapjms:timeToLive>
  </wsdl11:port>
  <wsdl11:port name="slowPort" binding="tns:exampleBinding">
    ...
  </wsdl11:port>
</wsdl11:service>

3.4.5 Specifying Properties Via the JMS IRI

Some of the above information can be put in the IRI [URI Scheme for JMS]. When expressing properties from the SOAP/JMS binding in the IRI, you do not need the namespace prefix — just use the property name, such as "priority".

Editorial note: pse20080521
Assertion about optional namespace. Testable.

This IRI, in turn, is represented as the location attribute on the <wsdl11soap11:address> element. Note that with SOAP 1.2, the same pattern applies, although the "soap" prefix corresponds to the SOAP 1.2 binding namespace http://schemas.xmlsoap.org/wsdl/soap12/ as established by [WSDL 1.1 for SOAP 1.2]

Editorial note: pse20080521
Assertion on where the IRI can appear. Testable.

Properties expressed in the IRI [IETF RFC 3987] override any values set in the markup as described above.

Editorial note: pse20080521
Strong assertion. Testable.

Example 3-4. Specifying WSDL 1.1 Properties Via the JMS IRI

<wsdl11:port .... >
       <wsdl11soap11:address location="jms:jndi:destinationName?targetService=service1"/> 
</wsdl11:port>

3.5 WSDL 2.0 Extensions Detail

Section 3.4 WSDL 1.1 Extensions Detail illustrates how a service originally available over HTTP is made available over JMS using WSDL 1.1. This section illustrates how to indicate the configuration for using SOAP over JMS with WSDL 2.0

(01) <wsdl20:binding
(02)    name="StockQuoteSoapJMSBinding" interface="tns:StockQuoteInterface" 
(03)    type="http://www.w3.org/2006/01/wsdl/soap"
(04)    wsoap:protocol="http://www.w3.org/@@@@/@@/soapjms"
   xmlns:soapjms="http://www.w3.org/@@@@/@@/soapjms">
(05)   
(06)   <!-- We want this binding to use a particular CF class -->
(07)   <soapjms:jndiConnectionFactoryName>
(08)     sample.jms.ConnectionFactory
(09)   </soapjms:jndiConnectionFactoryName>
(10)   <!-- Specify PERSISTENT delivery mode -->
(11)   <soapjms:deliveryMode>PERSISTENT</soapjms:deliveryMode>
(12) </wsdl20:binding>
(13) 
(14) <wsdl20:service name="StockQuoteService" interface="tns:StockQuoteInterface">
(15)   <wsdl20:documentation>My first service</wsdl20:documentation>
(16)   <wsdl20:endpoint name="SOAPHTTP" binding="tns:StockQuoteSoapHTTPBinding"
(17) 	    address="http://example.com/stockquote"/>
(18)   <wsdl20:endpoint name="JMS" binding="tns:StockQuoteSoapJMSBinding"
(19) 	    address="jms:jndi:myQueue/stockquote"/>
(20) </wsdl20:service>

Line 4 shows the protocol URI in the wsoap:protocol attribute of the <binding>, which indicates that this SOAP over JMS binding is in use.

Lines 7-11 show the use of WSDL 2.0 extension elements to set some of the properties of the connection. In this case, you see the <soapjms:jndiConnectionFactoryName> and <soapjms:deliveryMode> elements defining the values for the jndiConnectionFactoryName and deliveryMode properties. More generally, each allowed property may be expressed as a WSDL 2.0 extension element, typed appropriately for that property's value space. For example, on line 11 above, <soapjms:deliveryMode> is of type xsd:string. This XML representation then surfaces in the WSDL 2.0 Component Model (see next section) as an extension property.

Editorial note: pse20080521
Testable

Lines 18-19 are also additions to specify the location at which this new implementation exists. Line 19 showing the JMS IRI Scheme jms: in the address attribute of the <endpoint> element. As with the WSDL 1.1 binding, you may also set connection properties in the IRI.

Editorial note: pse20080521
Testable

3.6 Properties

Table 3-1 lists the SOAP/JMS properties which are declarable in WSDL documents.

Table 3-1. SOAP/JMS properties which are declarable in WSDL 1.1 and WSDL 2.0 documents
Property localNameValid WSDL Locations
jndiConnectionFactoryNameservice, port/endpoint, binding
jndiInitialContextFactoryservice, port/endpoint, binding
jndiURLservice, port/endpoint, binding
deliveryModeservice, port/endpoint, binding
priorityservice, port/endpoint, binding
timeToLiveservice, port/endpoint, binding
replyToNameservice, port/endpoint, binding
soapActionbinding operation

Editorial note: pse20080521
Testable

3.6.1 Relationship to WSDL 2.0 Component Model

WSDL 2.0 is described abstractly in terms of a component model. Extensions such as the SOAP/JMS binding extend the predefined components with new properties and/or components.

For this specification, each property in the table above adds a WSDL Component Model Property with the same name to the containing WSDL 2.0 component. For instance, if the <deliveryMode> extension element appeared underneath the <service> element in a WSDL 2.0 description, it would result in a deliveryMode property added to the Service component.

Editorial note: pse20080521
Testable as per above

3.6.1.1 Precedence

Since the same property can be specified in multiple places, we need precedence rules, and in fact they are exactly as specified in section 3.4.4 Specifying Properties In WSDL 1.1. The most-specific setting overrides less-specific ones, so endpoint wins over service, which wins over binding. For a particular interaction, you may search for a given property on the Endpoint component, then Service, then Binding, taking whichever value you find first.

Editorial note: pse20080521
Strong assertions. Testable

A. References

[IETF RFC 2045]
Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies, N. Freed, N. Borenstein, Authors. Internet Engineering Task Force, November 1996. Available at http://www.ietf.org/rfc/rfc2045.txt.
[IETF RFC 2119]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, Author. Internet Engineering Task Force, March 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.
[IETF RFC 3987]
Internationalized Resource Identifiers (IRIs) , M. Duerst and M. Suignard, Authors. Internet Engineering Task Force, January 2005. Available at http://www.ietf.org/rfc/rfc3987.txt.
[Java Message Service]
Java Message Service (JMS) 1.1, M. Hapner, et. al., Authors. Sun Microsystems, Inc., 12 April 2002. Available at http://java.sun.com/products/jms/docs.html
[URI Scheme for JMS]
URI Scheme for Java™ Message Service 1.0, D. Xiao, R. Merrick, P. Easton, and D. Rokicki, Authors. Internet Engineering Task Force, 22 April 2008. Available at http://www.ietf.org/internet-drafts/draft-merrick-jms-iri-03.txt
[SOAP Messages with Attachments]
SOAP Messages with Attachments, John Barton, Satish Thatte, and Henrik Frystyk Nielsen, Authors. Hewlett Packard Labs, Microsoft Corporation, 11 December 2000. Available at http://www.w3.org/TR/SOAP-attachments
[SOAP 1.1 Binding for MTOM 1.0]
SOAP 1.1 Binding for MTOM 1.0, Dimitar Angelov, et. al., Authors. International Business Machines Corporation, Microsoft Corporation, Inc., Oracle Corp. and SAP AG, 5 April 2006. Available at http://www.w3.org/Submission/soap11mtom10/
[SOAP MTOM]
SOAP Message Transmission Optimization Mechanism, N. Mendelsohn, M. Nottingham, and H. Ruellan, Editors. World Wide Web Consortium, W3C Recommendation, 25 January 2005. This version of SOAP Message Transmission Optimization Mechanism is http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/. The latest version of the "SOAP Message Transmission Optimization Mechanism" document is available from http://www.w3.org/TR/soap12-mtom/.
[SOAP 1.2 Email Binding]
SOAP Version 1.2 Email Binding, Highland Mary Mountain, Jacek Kopecky, Stuart Williams, Glen Daniels, and Noah Mendelsohn, Authors. World Wide Web Consortium, 3 July 2002. Available at http://www.w3.org/TR/2002/NOTE-soap12-email-20020703
[SOAP 1.1]
Simple Object Access Protocol (SOAP) 1.1, D. Box, et al, Editors. DevelopMentor, International Business Machines Corporation, Lotus Development Corporation, Microsoft, and UserLand Software, 8 May 2000. Available at http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.
[SOAP 1.2 Messaging Framework]
SOAP Version 1.2 Part 1: Messaging Framework, M. Gudgin, M. Hadley, N. Mendelsohn, J-J. Moreau, H. Frystyk Nielsen, Editors. World Wide Web Consortium, 24 June 2003, revised 27 April 2007. This version of the SOAP Version 1.2 Part 1: Messaging Framework Recommendation is http://www.w3.org/TR/2007/REC-soap12-part1-20070427/. The latest version of SOAP Version 1.2 Part 1: Messaging Framework is available at http://www.w3.org/TR/soap12-part1/.
[SOAP 1.2 Part 2: Adjuncts]
SOAP Version 1.2 Part 2: Adjuncts (Second Edition), M. Gudgin, et al., Editors. World Wide Web Consortium, 24 June 2006, revised 27 April 2007. This version of the "SOAP Version 1.2 Part 2: Adjuncts (Second Edition)" Recommendation is http://www.w3.org/TR/2007/REC-soap12-part2-20070427/. The latest version of "SOAP Version 1.2 Part 2: Adjuncts" is available at http://www.w3.org/TR/soap12-part2/.
[SOAP 1.2 Part 3: One-Way MEP]
SOAP 1.2 Part 3: One-Way MEP, David Orchard, Author. World Wide Web Consortium, 2 July 2007. Available at http://www.w3.org/TR/2007/NOTE-soap12-part3-20070702/
[WSDL 1.1]
Web Services Description Language (WSDL) 1.1, E. Christensen, et al, Authors. Ariba, International Business Machines Corporation, and Microsoft, 15 March 2001. Available at http://www.w3.org/TR/2001/NOTE-wsdl-20010315.
[WSDL 1.1 for SOAP 1.2]
WSDL 1.1 Binding Extension for SOAP 1.2, D. Angelov, et al, Authors. International Business Machines Corporation, Microsoft Corporation, Inc., Oracle Corp. and SAP AG, 5 April 2006.  Available at http://www.w3.org/Submission/2006/SUBM-wsdl11soap12-20060405/.
[WSDL 2.0 Core Language]
Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language, R. Chinnici, J. J. Moreau, A. Ryman, S. Weerawarana, Editors. World Wide Web Consortium, 26 June 2007. This version of the WSDL 2.0 specification is http://www.w3.org/TR/2007/REC-wsdl20-20070626/. The latest version of WSDL 2.0 is available at http://www.w3.org/TR/wsdl20/.
[WSDL 2.0 Adjuncts]
Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts, R. Chinnici, H. Haas, A. Lewis, J-J. Moreau, D. Orchard, S. Weerawarana, Editors. World Wide Web Consortium, 26 June 2007. This version of the "Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts" Recommendation is available at http://www.w3.org/TR/2007/REC-wsdl20-adjuncts-20070626. The latest version of "Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts" is available at http://www.w3.org/TR/wsdl20-adjuncts.
[XML 1.0]
Extensible Markup Language (XML) 1.0 (Fourth Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, and François Yergeau, Editors. World Wide Web Consortium, 10 February 1998, revised 16 August 2006. This version of the XML 1.0 Recommendation is http://www.w3.org/TR/2006/REC-xml-20060816. The latest version of XML 1.0 is available at http://www.w3.org/TR/REC-xml.
[XML Namespaces]
Namespaces in XML 1.0, T. Bray, D. Hollander, A. Layman, and R. Tobin, Editors. World Wide Web Consortium, 14 January 1999, revised 16 August 2006. This version of the Namespaces in XML Recommendation is http://www.w3.org/TR/2006/REC-xml-names-20060816/. The latest version of Namespaces in XML is available at http://www.w3.org/TR/REC-xml-names.
[XML Schema Structures]
XML Schema Part 1: Structures Second Edition, H. Thompson, D. Beech, M. Maloney, and N. Mendelsohn, Editors. World Wide Web Consortium, 2 May 2001, revised 28 October 2004. This version of the XML Schema Part 1 Recommendation is http://www.w3.org/TR/2004/REC-xmlschema-1-20041028. The latest version of XML Schema Part 1 is available at http://www.w3.org/TR/xmlschema-1.
[XML Schema Datatypes]
XML Schema Part 2: Datatypes Second Edition, P. Byron and A. Malhotra, Editors. World Wide Web Consortium, 2 May 2001, revised 28 October 2004. This version of the XML Schema Part 2 Recommendation is http://www.w3.org/TR/2004/REC-xmlschema-2-20041028. The latest version of XML Schema Part 2 is available at http://www.w3.org/TR/xmlschema-2.

B. SOAP/JMS Underlying Protocol Binding Examples (Non-Normative)

The JMS message consists of three parts, the first of these is the Message Header that contains a set of fields defined in the JMS specification, the second part is a set of properties that represent optional header fields the last part is the Message Body.

Example B-1. JMS IRI

jms:jndi:news?targetService=current-affairs
        &jndiConnectionFactory=SOAPJMSFactory
        &deliveryMode=PERSISTENT
        &priority=8
        &replyToName=interested
        &userprop=mystuff

B.1 SOAP Request without attachments

The IRI in Example B-1 will become:

Table B-1. JMS Message Header Values
Fieldvaluecomments
JMSMessage classjms_bytesa fixed value
JMSTypenull
JMSDeliveryMode2
JMSExpiration0
JMSPriority8
JMSMessageIDID:d438e0000001
JMSTimestamp1092110476167
JMSCorrelationIDnull
JMSDestinationA Destination objectresolved by JNDI from the destination name news
JMSReplyToA Destination objectresolved by JNDI from the destination name interested
JMSRedeliveredfalse

Table B-2. JMS Message Properties Values
Fieldvaluecomments
SOAPJMS_bindingVersion1.0
SOAPJMS_targetServicecurrent-affairsthis is derived from the targetService property
SOAPJMS_requestIRIjms:jndi:news?userprop=mystuffthis is derived from the requestIRI property
SOAPJMS_contentTypeapplication/soap+xmlinferred from the SOAP Envelope and absence of attachments. In this case it is SOAP 1.2

The following represents a human readable version of the JMS message body:

Example B-2. Representation of a JMS SOAP 1.2 Request without attachments

<env:Envelope
      xmlns:env="http://www.w3.org/2003/05/soap-envelope" 
      xmlns='http://example.org/MyApplication'
      xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <env:Body env:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
       <postMessage>
         <ngName xsi:type="xsd:string">news.current.events</ngName>
         <msg xsi:type="xsd:string">This is a sample news item.</msg>
       </postMessage>
    </env:Body>
</env:Envelope>

B.2 SOAP Request with attachments

The IRI in Example B-1 will become:

Table B-3. JMS Message Header Values
Fieldvaluecomments
JMSMessage classjms_bytesa fixed value
JMSTypenull
JMSDeliveryMode2
JMSExpiration0
JMSPriority8
JMSMessageIDID:d438e0000001
JMSTimestamp1092110476167
JMSCorrelationIDnull
JMSDestinationA Destination object resolved by JNDI from the destination name news
JMSReplyToA Destination object resolved by JNDI from the destination name interested
JMSRedeliveredfalse

Table B-4. JMS Message Properties Values
Fieldvaluecomments
SOAPJMS_bindingVersion1.0
SOAPJMS_targetServicecurrent-affairsderived from the targetService property
SOAPJMS_requestIRIjms:jndi:news?userprop=mystuffderived from the requestIRI property
SOAPJMS_contentTypemultipart/related type="application/xop+xml"; boundary="--MIME_boundary"inferred from the SOAP Envelope and presence attachments. In this case it is SOAP 1.2

The following represents a human readable version of the JMS message body:

Example B-3. Representation of a JMS SOAP 1.2 Request with attachments

MIME-Version: 1.0
Content-Type: Multipart/Related;boundary=MIME_boundary;
    type="application/xop+xml";
    start="<945414389.1092086011970>";
    startinfo="application/soap+xml"

--MIME_boundary
Content-Type: application/xop+xml; 
    charset=UTF-8; 
    type="application/soap+xml"
Content-Transfer-Encoding: 8bit
Content-ID: <945414389.1092086011970>

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" 
  xmlns:xop='http://www.w3.org/2004/08/xop/include' 
  xmlns='http://example.org/MyApplication'
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:xmlmime="http://www.w3.org/2005/05/xmlmime"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <env:Body env:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
    <postMessage>
      <ngName xsi:type="xsd:string">news.current.events</ngName>
      <msg xsi:type="xsd:string">This is a sample news item.</msg>
      <photo xmlmime:contentType='image/png'><xop:Include 
        href='cid:http://example.org/photo.png'/></photo>
    </postMessage>
  </env:Body>
</env:Envelope>
--MIME_boundary
Content-Type: image/png
Content-Transfer-Encoding: binary
Content-Id: <http://example.org/photo.png>

[n lines omitted]
--MIME_boundary

C. Acknowledgements (Non-Normative)

This document is the work of the W3C SOAP-JMS Binding Working Group.

Members of the Working Group are (at the time of writing, and by alphabetical order): Phil Adams (IBM Corporation), Glen Daniels (WSO2), Peter Easton (Progress Software), Mark Hapner (Sun Microsystems, Inc.), Eric Johnson (TIBCO Software, Inc.), Yves Lafon (W3C/ERCIM), Philippe Le Hégaret (W3C/MIT), Amelia Lewis (TIBCO Software, Inc.), Bhakti Mehta (Sun Microsystems, Inc.), Roland Merrick (IBM Corporation), Mark Phillips (IBM Corporation), Derek Rokicki (Software AG).

Previous members of the Working Group were: Dongbo Xiao.

The people who have contributed to discussions on public-soap-jms@w3.org are also gratefully acknowledged.

The original contributors to the SOAP over Java™ Message Service 1.0 W3C Member Submission: Phil Adams (IBM); Glen Daniels (WSO2); Peter Easton (Progress Software); Tim Frank (Software AG); Lei Jin (BEA Systems, Inc.); Eric Johnson (TIBCO Software Inc.); Vinod Kumar (BEA Systems, Inc.); Amelia A. Lewis (TIBCO Software Inc.); David Orchard (BEA Systems, Inc.); Roland Merrick (IBM); Mark Phillips (IBM); Stephen Todd (IBM); Dongbo Xiao (BEA Systems, Inc.) and Prasad Yendluri (Software AG).

D. Change Log (Non-Normative)

DateEditorDescription
2008-05-01plehegar Using latest version for WSDL 2.0 references
2008-05-01plehegar Added support for CVS changelog
2008-05-01plehegar Moved section 2.9 into non-normative appendix. Updated the references section (now normative). Added table and example headers. Fixed/added bibref. Using SOAP 1.2 instead of SOAP 1.1 in example. Added XML Namespaces section.
2008-04-22plehegar New