Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is the Candidate Recommentation of the SOAP over Java Message Service 1.0 specification. It has been produced by the SOAP-JMS Binding Working Group, which is part of the W3C Web Services Activity.
This document is based on the W3C Submission SOAP over Java™ Message Service 1.0. A list of changes is available in F Change Log.
A diff-marked version against the previous version of this document is available.
Only two features are marked "at risk", soapjms:WSDL11
and
soapjms:WSDL20
(1.6 Conformance). Both features are optional.
The Working Group started collecting testcases and test assertions, they are compiles in the Test Suite. There is no preliminary implementation report.
The Working Group intend to submit this document for consideration as a W3C Proposed Recommendation after 31 August 2009 having met the following criteria:
At least two implementations have demonstrated interoperability of each feature.
All issues raised during the CR period against this document have received formal responses.
This specification is not describing the way the binding could be used with WSDL 1.1 WSDL 1.1 or WSDL 2.0 WSDL 2.0 Core Language, due to lack of support in the Working Group. As a consequence, the description of how to deal with WSDL 1.1 or 2.0 MEPs will be moved to the Working Group's FAQ.
Please send comments about this document to public-soap-jms@w3.org mailing list (public archive). The review period for this document extends until 31 August 2009.
Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
1 Introduction
1.1 Background
1.2 Out of Scope
1.3 Context
1.4 Notational Conventions
1.4.1 XML Namespaces
1.5 Assertions
1.6 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.2.1 Setting JMS Message Header properties
2.2.3 JMS Message properties
2.2.3.1 Setting JMS Message properties
2.2.4 Binding of Properties to URI
2.2.5 Other Properties
2.3 Authentication for SOAP/JMS
2.4 The JMS Message Body
2.4.1 Considerations For Using TextMessage
2.5 Supported Message Exchange Patterns
2.5.1 Support for Topic destinations
2.6 Request-Response Message Exchange Pattern
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 URI
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
A References
B Schema
C SOAP/JMS Underlying Protocol Binding Examples (Non-Normative)
C.1 SOAP Request without attachments
C.2 SOAP Request with attachments
D Acknowledgements (Non-Normative)
E Assertion Summary (Non-Normative)
F Change Log (Non-Normative)
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.
The WSDL binding that may be used to describe SOAP/JMS services in 3 WSDL Usage.
How SOAP over JMS uses the URI specification for JMS endpoints [URI Scheme for JMS].
Note that the URI specification is in a separate document.
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.
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.
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.
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".
This specification uses a number of namespace prefixes throughout; they are listed in Table Prefixes and Namespaces used in this specification. 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]).
Prefix | Namespace | Specification |
---|---|---|
soapjms | http://www.w3.org/2008/07/soap/bindings/JMS/ | Defined by this specification |
xsd | http://www.w3.org/2001/XMLSchema
| [XML Schema Structures] |
wsdl11 | http://schemas.xmlsoap.org/wsdl/ | [WSDL 1.1] |
wsdl20 | http://www.w3.org/ns/wsdl | [WSDL 2.0 Core Language] |
wsoap | http://www.w3.org/ns/wsdl/soap | [WSDL 2.0 Adjuncts] |
wsdl11soap11 | http://schemas.xmlsoap.org/wsdl/soap/ | [WSDL 1.1] |
wsdl11soap12 | http://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/2008/07/soap/bindings/JMS/
.
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: plh | 20080501 |
The above paragraph will need to be removed for the publication of the Recommendation. |
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 may be gaps in the sequence.
The assertions and their identifiers are summarized in section E Assertion Summary.
This specification defines three features, each of which has conformance criteria associated with it. A conforming implementation MUST work with Java Message Service (JMS) 1.1 [Java Message Service].†
Feature: soapjms:Protocol [http://www.w3.org/2008/07/soap/bindings/JMS/Protocol
]
A conforming implementation MUST implement all the requirements of 2 The SOAP/JMS Underlying Protocol Binding.† Conforming implementations MUST implement all the requirements of [URI Scheme for JMS].†
Feature: soapjms:WSDL11 [http://www.w3.org/2008/07/soap/bindings/JMS/WSDL11
]
Support for WSDL 1.1 is optional and as such an implementation MAY implement it. However, a conforming implementation of this feature MUST implement all the requirements of 3.4 WSDL 1.1 Extensions Detail.†
Feature: soapjms:WSDL20 [http://www.w3.org/2008/07/soap/bindings/JMS/WSDL20
]
Support for WSDL 2.0 is optional and as such an implementation MAY implement it. However, a conforming implementation of this feature MUST implement all the requirements of 3.5 WSDL 2.0 Extensions Detail.†
This section is normative.
This section describes the required feature: soapjms:Protocol [http://www.w3.org/2008/07/soap/bindings/JMS/Protocol
]
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.
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. If the specified property is present then it MUST be processed as specified.
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. †
The environment (for example local program variables, system environment variables etc).
WSDL elements or attributes (including those specified in an endpoint URI within the WSDL). The precedence rules for properties specified in a WSDL document are defined in 3.4.4 Specifying Properties In WSDL 1.1 and 3.4.5 Specifying Properties Via the JMS URI.
If a given property is specified more than once in the JMS URI the last instance of the property MUST be used. †
Since the underlying JMS URI scheme defines an open-ended scheme for identifying and connecting to a 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.
Specifies the technique to use for looking up the given destination name.
MUST be specified in the JMS URI, as the jms-variant
portion of the syntax. †
The jms-variant
: jndi
MUST be supported.†
[Definition: Use fault subcode unsupportedLookupVariant
if the JMS URI specifies a lookupVariant that is not supported by the implementation.†]
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).
MUST be specified in JMS URI, as the jms-dest
portion of the syntax.†
Specifies the JNDI name of the connection factory.
an optional property
MAY be specified in JMS URI, WSDL, or somewhere else in the environment
Specifies the fully qualified Java class name of the
InitialContextFactory
to use. This is mapped to the java.naming.factory.initial
property (defined by the constant javax.naming.Context.INITIAL_CONTEXT_FACTORY
) to be set in
the HashMap
sent to an InitialContext
constructor.
an optional property
MAY be specified in JMS URI, WSDL, or somewhere else in the environment
Specifies the JNDI provider URL, which is mapped to the
java.naming.provider.url
property (defined by the constant
javax.naming.Context.PROVIDER_URL
) to be set in the
HashMap
sent to an InitialContext
constructor.
an optional property
MAY be specified in JMS URI, WSDL, or somewhere else in the environment
Provides mechanism to set additional, arbitrary JNDI environment properties,
other than jndiURL and jndiInitialContextFactory, in the java.util.Hashtable
sent to the
InitialContext constructor for the JNDI provider.
An optional property that MAY be specified more than once.
Specifies a JNDI property name and value pair to be added to the java.util.Hashtable
sent to the
InitialContext.
The JNDI property's name MUST be included in the name
attribute,
its value MUST be included in the value
attribute. The value is added as a
java.lang.String
.
MAY be specified in JMS URI, WSDL, or somewhere else in the environment
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.
indicates whether the request message is persistent or not. The valid values are "PERSISTENT" and "NON_PERSISTENT". The default value is "PERSISTENT" (defaulted by JMS)
optional in URI, 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 "NON_PERSISTENT" then the
JMSDeliveryMode
integer value MUST be set to DeliveryMode.NON_PERSISTENT
.
†
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 URI, optional in WSDL, optional in environment.
if specified, this MUST be used to generate the value of the JMS header JMSExpiration
.†
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 URI, optional in WSDL, optional in environment
if specified MUST appear in the JMS message in the header named JMSPriority
.†
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 "queue" or "topic", this refers to the name of a JMS queue.
optional in URI, optional in WSDL, optional in environment
if specified, this MUST be used to derive the value to be used in the JMS header JMSReplyTo
.†
Specifies the name of the topic destination to which a response message SHOULD be sent.
if the variant is "jndi", topicReplyToName is not relevant and MUST be ignored.
if the replyToName is specified in the URI, WSDL, or environment, topicReplyToName is not relevant and MUST be ignored.
optional in URI, optional in WSDL, optional in environment
if specified and if relevant, this MUST be used to derive the value to be used in the JMS header JMSReplyTo
.†
This section is non-normative and is intended to give an example of how a JMS Message Header property MAY be set.
import java.naming.Context; import javax.jms.DeliveryMode; import javax.jms.Destination; import javax.jms.Message; import javax.jms.MessageProducer; ... class ... { // add appropriate error checking for your use.... public void someMethod(Context ctx, MessageProducer producer, Message jmsMessage, String deliveryModeStr, String replyToName, int priority, long timeToLive) { // set the delivery mode to the appropriate constant value. int deliveryMode = deliveryModeStr.equals("PERSISTENT") ? DeliveryMode.PERSISTENT: DeliveryMode.NON_PERSISTENT; jmsMessage.setJMSDeliveryMode( deliveryMode ); // Set the reply destination, first looking it up using JNDI Destination replyDestination = ctx.lookup(replyToName); jmsMessage.setJMSReplyTo(replyDestination); // set the priority on the message. jmsMessage.setJMSPriority(priority); // set when the message is set to expire. producer.setTimeToLive(timeToLive); // and finally, send the message. producer.send(jmsMessage); // alternately, a bunch of the lines above could be collapsed to: // producer.send(jmsMessage, deliveryMode, priority, timeToLive); } }
Used by the service implementation to dispatch the service request.
optional in URI
if specified MUST appear in the JMS message in the JMS property named SOAPJMS_targetService
.†
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 MUST be generated if the value of the soapjms:bindingVersion property does not match the fixed value.†]
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 MUST be 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 contentType
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.†]
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.†]
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.
Specifies the JMS URI of the service. The client MUST create this property which is derived from the supplied URI. 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_requestURI
.†
[Definition: Use fault subcode missingRequestURI if
the SOAPJMS_requestURI
is missing from the message.†]
This section is non-normative and is intended to give an example of how a JMS Message property MAY be set.
import javax.jms.Message; import javax.mail.internet.ContentType; ... class ... { public void anotherMethod(Message jmsMessage, String targetService, ContentType type, URI requestURI) { jmsMessage.setStringProperty("SOAPJMS_targetService", targetService); // at least for this definition of the binding, the version here is always "1.0" jmsMessage.setStringProperty("SOAPJMS_bindingVersion", "1.0"); // set the content type using the ContentType value already defined by javax.mail. jmsMessage.setStringProperty("SOAPJMS_contentType", type.toString() ); //According to Basic Profile SOAP 1.2 HTTP binding does not use the SOAPAction header //However the soapAction is mandatory with SOAP 1.1 hence setting to empty string jmsMessage.setStringProperty("SOAPJMS_soapAction", ""); // for the first message in an exchange, not a fault1 jmsMessage.setBooleanProperty("SOAPJMS_isFault", false); jmsMessage.setStringProperty("SOAPJMS_requestURI, requestURI.toString() ); } }
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 URI [IETF RFC 3987]. Note that the URI 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 "URI representation" column describes how the property is carried
in the URI. The "Client treatment" column describes how the property
should be treated in the process of forming the
soapjms:requestURI property. There are three options for this
column:
As-is — the client SHOULD leave the information in the URI as is.
Should exclude — the client SHOULD exclude the information from the generated requestURI .
Must exclude — the client MUST not include the information in the generated requestURI.
Specification Property | URI Representation | Client Treatment |
---|---|---|
deliveryMode | as deliveryMode query parameter | SHOULD exclude |
destinationName | as jms-dest portion of URI syntax | As-is |
jndiConnectionFactoryName | as jndiConnectionFactoryName query parameter | SHOULD exclude |
jndiInitialContextFactory | as jndiInitialContextFactory query parameter | SHOULD exclude |
jndiURL | as jndiURL query parameter | SHOULD exclude |
jndiContextParameter | as a query parameter combining the string "jndi-" with the jndiContextParameter's name attribute | SHOULD exclude |
replyToName | as replyToName query parameter | MUST exclude |
priority | as priority query parameter | SHOULD exclude |
targetService | as targetService query parameter | MUST exclude |
timeToLive | as timeToLive query parameter | SHOULD exclude |
[Definition: Use fault subcode malformedRequestURI
when the URI violates the expected syntax.†
]. [Definition: Use fault subcode
targetServiceNotAllowedInRequestURI when targetService
parameter is
included in the requestURI).†]
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 URI is not recommended.
The contents of the JMS Message body MUST be the SOAP payload as a
JMS BytesMessage
or TextMessage
.†
[Definition:
Use fault subcode unsupportedJMSMessageFormat when the arriving message format is not BytesMessage
or TextMessage
.
†].
The formatting of the SOAP payload is determined by the sending SOAP node, and should follow the same pattern as for the SOAP/HTTP binding. Based on the sending node's use of SOAP 1.1 [SOAP 1.1], SOAP 1.2 [SOAP 1.2 Messaging Framework], SOAP Messages with Attachments [SOAP Messages with Attachments], and MTOM [SOAP 1.1 Binding for MTOM 1.0] [SOAP MTOM], the contentType property MUST be set as it would be for SOAP/HTTP, and the message body MUST use the corresponding format.
For example, if the SOAP payload is formatted as a simple SOAP envelope,
the contentType property value MUST be specified as
"text/xml
" for SOAP 1.1 or
"application/soap+xml
" for SOAP 1.2.
On the other hand, if the SOAP payload is formatted as a MIME multipart message,
the contentType property value MUST be specified as
"multipart/related
".
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.
Note also that 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 [IETF RFC 2045] 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.
†
While the use of TextMessage
may be attractive in some scenarios,
there are some considerations that go along with it.
Since the message is already in text format the "encoding" attribute in the XML header MUST be ignored.
Messages with attachments will need to use Content-Transfer-Encoding
for attachment parts.
Depending on the range of characters used by the SOAP message,
using TextMessage
may do more than double the memory requirements to receive a message.
The impact on network consumption must be measured for particular scenarios and JMS providers.
Since binary data needs to be encoded to be carried as text, SOAP
attachments via a TextMessage
have the same concerns as the MIME specification
carrying messages over a 7-bit channel [IETF RFC 2045].
The attachments will need to be encoded using one of the
Content-Transfer-Encoding
options specified by MIME.
If the data is truly binary, such as a picture, a base64 encoding might be appropriate.
In typical scenarios, using TextMessage
will almost
certainly dramatically increase the memory requirements.
This happens as a consequence of the JMS API TextMessage.getText()
,
which returns a Java String.
The Java String class uses a UTF-16 representation to represent the data.
This in memory representation will generally be larger than the
corresponding BytesMessage
representation.
For example, if the message contains only US-ASCII characters,
and is encoded into XML using UTF-8, the Java String representation of
the message will take exactly twice as much memory.
The in memory UTF-16 representation, coupled with base64 encoding of an attachment,
will consume much more memory than the equivalent BytesMessage
payload.
To begin with, a base64 conversion yields a ratio of 33% more characters than bytes.
Combined with a UTF-16 representation of those characters, the bytes required in
memory will be 167% more than the original binary data (an 8/3 ratio).
As a consequence, carefully consider any scenarios that use attachments with a TextMessage
.
As significant as the concerns around memory consumption may be,
the effects on network payload size are more difficult to predict.
Since the JMS API does not specify exactly how messages are handled,
the effects on network traffic are JMS provider-specific.
A JMS provider might be encoding a TextMessage
with UTF-8,
and may further compress such messages.
With these two techniques, the data transferred via network calls
may end up being no larger than a corresponding BytesMessage
representation, even with attachments.
However, only actual monitoring will determine specific effects of specific scenarios.
Clients of this specification who are using TextMessage
are encouraged to do such monitoring.
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:†
http://www.w3.org/2003/05/soap/mep/request-response/
(defined in section 6.2, Request-Response
Message Exchange Pattern,
[SOAP 1.2 Part 2: Adjuncts])
http://www.w3.org/2006/08/soap/mep/one-way/
(defined in
[SOAP 1.2 Part 3: One-Way MEP])
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.†
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.
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.
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.
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 may take on the role
(i.e. the property http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role
)
of RequestingSOAPNode
.
A SOAP Node instantiated at the JMS interface 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.
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 unless stated otherwise.
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
or TextMessage
as defined in 2.4 The JMS Message Body.†
A number of the message header properties are implicitly created by the use of the JMS API, the following table specifies how the binding properties described earlier explicitly affect the message constructed.†
Field | Value Set by Conforming Client |
---|---|
JMS Message Header | |
JMSDeliveryMode | the value of the deliveryMode property or not set if not specified |
JMSExpiration | calculated from the value of the timeToLive property or not set if not specified |
JMSPriority | the value of the priority property or not set if not specified |
JMSDestination | derived from the destinationName property |
JMSReplyTo | if 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_requestURI | this is derived from the requestURI property |
SOAPJMS_bindingVersion | this is copied from the bindingVersion property |
SOAPJMS_soapAction | the value of the soapAction property or not set if not specified |
SOAPJMS_targetService | the value of the targetService property or not set if not specified |
SOAPJMS_contentType | inferred from the SOAP Envelope and presence of attachments |
JMS Message Body | |
body | A SOAP envelope is serialized according to the media type specified in the JMS Message property SOAPJMS_contentType |
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 JMSReplyTo
header MUST be assigned a value.
†
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.
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.
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.
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.
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.
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).
Completing Request Message reception and Response Message transmission. (Response Message sent on exit from Receiving State).
The JMS response is formulated and transmission of the response is initiated.
The Response Message MUST be created
using the same type as the corresponding Request Message, i.e. as a JMS BytesMessage
or TextMessage
.†
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.†
A number of the message header properties are implicitly created by the use of the JMS API, the following table specifies how the binding properties described earlier explicitly affect the message constructed.†
Field | Value Set by Conforming Client |
---|---|
JMS Message Header | |
JMSDeliveryMode | this SHOULD be the same as that specified on the request |
JMSExpiration | this is derived from the request. It is up to the responding node to decide whether to degrade for processing time. |
JMSPriority | this is copied from the request |
JMSCorrelationID | this is copied from the request JMSMessageID |
JMSDestination | this is copied from the JMSReplyTo property in the request |
JMS Message properties | |
SOAPJMS_requestURI | this is copied from the requestURI property in the request message |
SOAPJMS_bindingVersion | this is copied from the bindingVersion property |
SOAPJMS_contentType | inferred from the SOAP Envelope and presence of attachments. |
JMS Message Body | |
body | A SOAP envelope is serialized according to the media type specified in the JMS Message property SOAPJMS_contentType . |
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.
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 a fault, then the
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason
property will contain an value identifying the fault.
The message MUST
be created as a JMS BytesMessage
or TextMessage
as defined in 2.4 The JMS Message Body.†
The JMSReplyTo
header MUST NOT be assigned a value.
†
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.
A number of the message header properties are implicitly created by the use of the JMS API, the following table specifies how the binding properties described earlier explicitly affect the message constructed.†
Field | Value Set by Conforming Client |
---|---|
JMS Message Header | |
JMSDeliveryMode | the value of the deliveryMode property or not set if not specified |
JMSExpiration | calculated from the value of the timeToLive property or not set if not specified |
JMSPriority | the value of the priority property or not set if not specified |
JMSDestination | derived from the destinationName property |
JMS Message properties | |
SOAPJMS_requestURI | this is derived from the requestURI property |
SOAPJMS_bindingVersion | this is copied from the bindingVersion property |
SOAPJMS_soapAction | the value of the soapAction property or not set if not specified |
SOAPJMS_targetService | the value of the targetService property or not set if not specified |
SOAPJMS_contentType | inferred from the SOAP Envelope and presence of attachments. |
JMS Message Body | |
body | A SOAP envelope is serialized according to the media type specified in the JMS Message property SOAPJMS_contentType . |
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.)
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:
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:soapjms="http://www.w3.org/2008/07/soap/bindings/JMS/" 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:
<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/2008/07/soap/bindings/JMS/" /> </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/2008/07/soap/bindings/JMS/"> The content type of the JMS payload does not match the XML. </soapjms:contentTypeMismatch> </env:detail>
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].
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 URI.
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 URI.
This section is normative.
This section describes the optional feature: soapjms:WSDL11 [http://www.w3.org/2008/07/soap/bindings/JMS/WSDL11
]
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 URI Scheme jms:
in the <wsdl11soap11::address>
.
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/2008/07/soap/bindings/JMS/"> 15 <wsdl11soap11:binding style="document" transport="http://www.w3.org/2008/07/soap/bindings/JMS/"/> 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: URI in the <wsdl11soap11:address>
(line 41)
The extension properties in the <wsdl11soap11:binding>
(lines 17-22)
The wsdl11soap11:binding
element has a transport
attribute. The developer
indicates the use of the SOAP/JMS binding by putting
http://www.w3.org/2008/07/soap/bindings/JMS/
as the value
of the transport.
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.
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.
If a property is specified at multiple levels, the most specific
setting MUST 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.
<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>
Some of the above information can be put in the URI [URI Scheme for JMS]. When expressing properties from the SOAP/JMS binding
in the URI, you do not need the namespace prefix — just use the
property name, such as "priority
".
This URI, 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].
Properties expressed in the URI [IETF RFC 3987] MUST override any values set in the markup as described above.†
This section is normative.
This section describes the optional feature: soapjms:WSDL20 [http://www.w3.org/2008/07/soap/bindings/JMS/WSDL20
]
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/2008/07/soap/bindings/JMS/" xmlns:soapjms="http://www.w3.org/2008/07/soap/bindings/JMS/"> (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.
Lines 18-19 are also additions to specify the location at
which this new implementation exists. Line 19 showing the JMS
URI 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 URI.
Table SOAP/JMS properties which are declarable in WSDL 1.1 and WSDL 2.0 documents lists the SOAP/JMS properties which are declarable in WSDL documents.
Property localName | Valid WSDL Locations |
---|---|
jndiConnectionFactoryName | service, port/endpoint, binding |
jndiInitialContextFactory | service, port/endpoint, binding |
jndiURL | service, port/endpoint, binding |
deliveryMode | service, port/endpoint, binding |
priority | service, port/endpoint, binding |
timeToLive | service, port/endpoint, binding |
replyToName | service, port/endpoint, binding |
soapAction | binding operation |
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.
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.
<?xml version="1.0" encoding="utf-8"?> <xs:schema targetNamespace="http://www.w3.org/2008/07/soap/bindings/JMS/" xmlns:soapjms="http://www.w3.org/2008/07/soap/bindings/JMS/" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:complexType name="jndiContextParameterType"> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="name" type="xs:string" use="required"/> <xs:attribute name="value" use="required"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:minLength value="1"/> </xs:restriction> </xs:simpleType> </xs:attribute> </xs:extension> </xs:simpleContent> </xs:complexType> <xs:simpleType name="deliveryModeType"> <xs:restriction base="xs:string"> <xs:enumeration value="PERSISTENT"/> <xs:enumeration value="NON_PERSISTENT"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="priorityType"> <xs:restriction base="xs:int"> <xs:minInclusive value="0"/> <xs:maxInclusive value="9"/> </xs:restriction> </xs:simpleType> <xs:element name="jndiContextParameter" type="soapjms:jndiContextParameterType"/> <xs:element name="jndiConnectionFactoryName" type="xs:string"/> <xs:element name="jndiInitialContextFactory " type="xs:string"/> <xs:element name="jndiURL" type="xs:anyURI"/> <xs:element name="deliveryMode" type="soapjms:deliveryModeType"/> <xs:element name="priority" type="soapjms:priorityType"/> <xs:element name="timeToLive" type="xs:long"/> <xs:element name="replyToName" type="xs:string"/> </xs:schema>
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.
jms:jndi:news?targetService=current-affairs &jndiConnectionFactory=SOAPJMSFactory &deliveryMode=PERSISTENT &priority=8 &replyToName=interested &userprop=mystuff
The URI in Example JMS URI will become:
Field | value | comments |
---|---|---|
JMSMessage class | jms_bytes | a fixed value |
JMSType | null | |
JMSDeliveryMode | 2 | |
JMSExpiration | 0 | |
JMSPriority | 8 | |
JMSMessageID | ID:d438e0000001 | |
JMSTimestamp | 1092110476167 | |
JMSCorrelationID | null | |
JMSDestination | A Destination object | resolved by JNDI from the destination name news |
JMSReplyTo | A Destination object | resolved by JNDI from the destination name interested |
JMSRedelivered | false |
Field | value | comments |
---|---|---|
SOAPJMS_bindingVersion | 1.0 | |
SOAPJMS_targetService | current-affairs | this is derived from the targetService property |
SOAPJMS_requestURI | jms:jndi:news?userprop=mystuff | this is derived from the requestURI property |
SOAPJMS_contentType | application/soap+xml | inferred 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:
<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>
The URI in Example JMS URI will become:
Field | value | comments |
---|---|---|
JMSMessage class | jms_bytes | a fixed value |
JMSType | null | |
JMSDeliveryMode | 2 | |
JMSExpiration | 0 | |
JMSPriority | 8 | |
JMSMessageID | ID:d438e0000001 | |
JMSTimestamp | 1092110476167 | |
JMSCorrelationID | null | |
JMSDestination | A Destination object | resolved by JNDI from the destination name news |
JMSReplyTo | A Destination object | resolved by JNDI from the destination name interested |
JMSRedelivered | false |
Field | value | comments |
---|---|---|
SOAPJMS_bindingVersion | 1.0 | |
SOAPJMS_targetService | current-affairs | derived from the targetService property |
SOAPJMS_requestURI | jms:jndi:news?userprop=mystuff | derived from the requestURI property |
SOAPJMS_contentType | multipart/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:
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
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), Peter Easton (Progress Software), Mark Hapner (Sun Microsystems, Inc.), Eric Johnson (TIBCO Software, Inc.), Yves Lafon (W3C), Amelia Lewis (TIBCO Software, Inc.), Bhakti Mehta (Sun Microsystems, Inc.), Roland Merrick (IBM Corporation), Mark Phillips (IBM Corporation), Derek Rokicki (Software AG), Nathan Sowatskey (Cisco).
Previous members of the Working Group were: Glen Daniels, Philippe Le Hégaret, 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).
This appendix summarizes assertions made by this specification. Each assertion is assigned a unique identifier.
Id | Assertion |
---|---|
Conformance-1000 | A conforming implementation MUST work with Java Message Service (JMS) 1.1 [Java Message Service]. |
Conformance-1001 | A conforming implementation MUST implement all the requirements of 2 The SOAP/JMS Underlying Protocol Binding. |
Conformance-1002 | Conforming implementations MUST implement all the requirements of [URI Scheme for JMS]. |
Conformance-1003 | Support for WSDL 1.1 is optional and as such an implementation MAY implement it. However, a conforming implementation of this feature MUST implement all the requirements of 3.4 WSDL 1.1 Extensions Detail. |
Conformance-1004 | Support for WSDL 2.0 is optional and as such an implementation MAY implement it. However, a conforming implementation of this feature MUST implement all the requirements of 3.5 WSDL 2.0 Extensions Detail. |
Protocol-2001 | 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. |
Protocol-2002 | If a given property is specified more than once in the JMS URI the last instance of the property MUST be used. |
Protocol-2003 | (lookupVariant)
MUST be specified in the JMS URI, as the jms-variant portion of the syntax. |
Protocol-2004 | (destinationName) MUST be specified in JMS URI, as the jms-dest portion of the syntax. |
Protocol-2005 | (deliveryMode)
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 "NON_PERSISTENT" then the
JMSDeliveryMode integer value MUST be set to DeliveryMode.NON_PERSISTENT .
|
Protocol-2006 | (timeToLive) if specified, this MUST be used to generate the value of the JMS header JMSExpiration . |
Protocol-2007 | (priority) if specified MUST appear in the JMS message in the header named JMSPriority . |
Protocol-2008 | (replyToName) if specified, this MUST be used to derive the value to be used in the JMS header JMSReplyTo . |
Protocol-2009 | (targetService) if specified MUST appear in the JMS message in the JMS property named SOAPJMS_targetService . |
Protocol-2010 | (bindingVersion) fixed value "1.0" in the implementation, MUST appear in a JMS property named SOAPJMS_bindingVersion . |
Protocol-2011 | Fault subcode unrecognizedBindingVersion MUST be generated if the value of the soapjms:bindingVersion property does not match the fixed value. |
Protocol-2012 | (contentType) 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 MUST be generated. |
Protocol-2013 | Use fault subcode contentTypeMismatch in the event that the values do not match. |
Protocol-2014 | 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]. |
Protocol-2015 | the contentType 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). |
Protocol-2016 | (contentType) MUST appear in the JMS message in the JMS property named SOAPJMS_contentType . |
Protocol-2017 | Use fault subcode missingContentType
if the SOAPJMS_contentType property is missing. |
Protocol-2018 | (soapAction) if specified MUST appear in the JMS message in the JMS property named SOAPJMS_soapAction . |
Protocol-2019 | if using SOAP 1.2, and the contentType
property has an action parameter, that parameter value MUST match this
SOAPJMS_soapAction value. |
Protocol-2020 | (soapAction) Use fault subcode
mismatchedSoapAction if the SOAP 1.2 action does not
match. |
Protocol-2021 | Specifies the JMS URI of the service. The client MUST create this property which is derived from the supplied URI. 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). |
Protocol-2022 | (requestURI) MUST appear in the JMS message in the JMS property named SOAPJMS_requestURI . |
Protocol-2023 | Use fault subcode missingRequestURI if
the SOAPJMS_requestURI is missing from the message. |
Protocol-2024 | Binding of Properties to URI |
Protocol-2025 | Use fault subcode malformedRequestURI when the URI violates the expected syntax. |
Protocol-2026 | Use fault subcode
targetServiceNotAllowedInRequestURI when targetService parameter is
included in the requestURI). |
Protocol-2027 | The contents of the JMS Message body MUST be the SOAP payload as a
JMS BytesMessage or TextMessage . |
Protocol-2028 |
Use fault subcode unsupportedJMSMessageFormat when the arriving message format is not BytesMessage or TextMessage .
|
Protocol-2029 | Note also that 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 [IETF RFC 2045] section 2.5 calls a "Body Part". |
Protocol-2030 |
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.
|
Protocol-2031 | An instance of a binding to JMS conforming to this binding specification MUST support the following message exchange patterns: |
Protocol-2032 | In the case of SOAP 1.2 a conforming SOAP-JMS Binding instance MUST support the following message exchange patterns: |
Protocol-2033 | 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. |
Protocol-2034 | (request-response MEP - requesting node) The message MUST be created as a JMS
BytesMessage or TextMessage as defined in 2.4 The JMS Message Body. |
Protocol-2035 | (request-response MEP - requesting node during init) the following table specifies how the binding properties described earlier explicitly affect the message constructed. |
Protocol-2036 | The Response Message MUST be created
using the same type as the corresponding Request Message, i.e. as a JMS BytesMessage or TextMessage . |
Protocol-2037 | The message MUST be sent to the JMS Destination in the
JMSReplyTo header of the Request Message. |
Protocol-2038 | The value of the
JMSCorrelationID header field MUST be set to the same as the
value of the JMSMessageID of the request message. |
Protocol-2039 | (request-response MEP - responding node during receiving and sending) the following table specifies how the binding properties described earlier explicitly affect the message constructed. |
Protocol-2040 | (one-way MEP - sending node) The message MUST
be created as a JMS BytesMessage or TextMessage as defined in 2.4 The JMS Message Body. |
Protocol-2041 | (One-way MEP - sending node) the following table specifies how the binding properties described earlier explicitly affect the message constructed. |
Protocol-2050 |
The JMSReplyTo header MUST be assigned a value.
|
Protocol-2051 |
The JMSReplyTo header MUST NOT be assigned a value.
|
Protocol-2060 | (lookupVariant)
The jms-variant : jndi
MUST be supported. |
Protocol-2070 | (topicReplyToName) if specified and if relevant, this MUST be used to derive the value to be used in the JMS header JMSReplyTo . |
Protocol-2071 | Use fault subcode unsupportedLookupVariant if the JMS URI specifies a lookupVariant that is not supported by the implementation. |
WSDLUsage-3001 | 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. |
WSDLUsage-3002 | If a property is specified at multiple levels, the most specific setting MUST take precedence (port first, then service, then binding). |
WSDLUsage-3003 | Properties expressed in the URI [IETF RFC 3987] MUST override any values set in the markup as described above. |
WSDLUsage-3004 | SOAP/JMS properties which are declarable in WSDL 1.1 and WSDL 2.0 documents |
Date | Editor | Description |
---|---|---|
2009-05-06 | rmerric | change section heading from Request-Response MEP to Request-Response Message Exchange Pattern as per derek suggestion that we be consistent with One-way Message Exchange Pattern |
2009-05-06 | rmerric | change how assertions Protocol-2035, Protocol-2039, and Protocol-2041 appear in the assertion summary. |
2009-05-05 | rmerric | Improve summary text for assertions Protocol-34 & Protocol-40 |
2009-05-05 | rmerric | remove assertion Protocol-2042 that is a duplicate of its constituent parts |
2009-04-29 | rmerric | mark usage of rfc2119 terms where required, tweak assertions so that the assertion summary is clearer. |
2009-04-28 | rmerric | expand scope of text inside assertions 1003 and 1004. |
2009-04-23 | rmerric | fix syntax error in example "Setting JMS Message Header properties" |
2009-04-16 | rmerric | ACTION-82 apply agreed changes to contentType |
2009-04-14 | padams2 | Added new fault subcode: unsupportedLookupVariant |
2009-04-14 | rmerric | editorial tweak to previous precedence change |
2009-04-08 | rmerric | clarify precedence rules for binding properties |
2009-03-25 | rmerric | change NONPERSISTENT to NON_PERSISTENT |
2009-03-23 | peaston | Clarify the wording and scope of the jndiContext Parameter property |
2009-03-19 | rmerric | tweak wording for topicReplyToName |
2009-03-19 | rmerric | add topicReplytoName definition |
2009-02-10 | padams2 | Added myself as an editor |
2009-02-10 | padams2 | Minor wording change re: use of java naming-related properties (Action-61) |
2009-01-29 | rmerric | make support for lookupVariant = jndi required. Response to Last Call comment LC03. |
2009-01-29 | rmerric | Add support for JMS 1.1 to conformance criteria. Response to Last Call comment LC02. |
2008-11-18 | rmerric | point to November draft of URI Scheme |
2008-11-12 | rmerric | add precedence question to status section. |
2008-10-29 | rmerric | add note about handling of precedence. more minor typos. |
2008-10-29 | rmerric | create named types in schema and use them in "Properties affecting binding" |
2008-10-29 | rmerric | remove references to the obsolete "context" variant +fix two minor typos |
2008-10-22 | rmerric | Remove Editor Note |
2008-10-22 | rmerric | add jndiContextParameter |
2008-10-22 | rmerric | Add XML Schema as an appendix |
2008-10-15 | rmerric | simplify conformance criteria for JMS URI support |
2008-10-15 | rmerric | clarify fault: unsupportedJMSMessageFormat |
2008-10-14 | rmerric | correct feature URIs |
2008-10-14 | rmerric | change conformance criteria |
2008-10-09 | padams2 | Modified soapjms.xml with minor edits related to TextMessage. |
2008-10-09 | rmerric | fix rfc2045 reference |
2008-10-09 | rmerric | Add support for TextMessage and considerations for use of said type. |
2008-08-18 | bmehta | Made changes to the spec to show snippets in JMS Message Header and Message properties based on code shown by Eric |
2008-07-29 | rmerric | add examples of how to set message properties |
2008-07-23 | ylafon | <p> were out of balance as a block level element was in the middle |
2008-07-23 | rmerric | Remove Java TM |
2008-07-17 | rmerric | Added a non-normative code snippet to DeliveryMode |
2008-07-14 | plehegar | Fixed language information |
2008-07-11 | rmerric | editorial nits before FPWD |
2008-06-25 | rmerric | make valid as well as well-formed! |
2008-06-25 | rmerric | MUST & MUST NOT for JMSReplyTo |
2008-06-25 | rmerric | Editorial changes identified by Eric and Peter |
2008-06-23 | rmerric | fix pointer to IETF JMS URI spec |
2008-06-22 | bmehta | Fixed some places where I missed the iri |
2008-06-22 | bmehta | Updated with changes based on discussions in meetings and Eric's feedback |
2008-06-12 | peaston | Add support for assertion markups |
2008-06-10 | rmerric | add the authors as a test |
2008-05-01 | plehegar | Using latest version for WSDL 2.0 references |
2008-05-01 | plehegar | Added support for CVS changelog |
2008-05-01 | plehegar | 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-22 | plehegar | New |