SOAP over Java™ Message Service 1.0

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]).

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.

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. ^†

[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.^†

[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

• If specified, must be used in accordance to this description.^†

[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

• If specified, must be used in accordance to this description.^†

[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

• If specified, must be used in accordance to this description.^†

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. ^†

[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.^†

[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.^†

[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: pse	20080610
todo Do(should) 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: pse	20080521
Is this 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.^†]

[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.^†]

[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: pse	20080521
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.^†

[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.^†]

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.

[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).^†]

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.^†

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.

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.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.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.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.

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.)

3.4.1 Example

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>.

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.^†

<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.^†

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.^†

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.

<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".^†

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]^†

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

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

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.