SOAP over Java™ Message Service 1.0

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

[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

[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

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

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

[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 [SwA] or MTOM [SOAP11-MTOM] [SOAP12-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 [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 at Autodetection of Character Encodings from [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]

[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.3.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 [JMS IRI Scheme]. In particular, this section describes how the properties above are used in the IRI. 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.3.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.6.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.7.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 6.2 Request-Response Message Exchange Pattern. 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.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 6.2 Request-Response Message Exchange Pattern. The following subsections describe each state in more detail and apply to both SOAP 1.1 and SOAP 1.2 until stated otherwise.

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

2.10.1 SOAP Request without attachments

The IRI:

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

will become:

The JMS Message header:

The JMS Message properties:

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

1    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
2       xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
3       xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
4       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
5      <soapenv:Body soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
6        <postMessage><ngName xsi:type="xsd:string">news.current.events</ngName>
7          <msg xsi:type="xsd:string">This is a sample news item.</msg>
8        </postMessage>
9      </soapenv:Body>
10   </soapenv:Envelope>

2.10.2 SOAP Request with attachments

The JMS Message header:

The JMS Message properties:

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

0
1    ----Part_1092086011970
2    Content-Type: text/xml; charset=UTF-8
3    Content-Transfer-Encoding: binary
4    Content-Id: <945414389.1092086011970>
5
6    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
7       xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
8       xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
9       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
10      <soapenv:Body soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
11       <postMessage><ngName xsi:type="xsd:string">news.current.events</ngName>
12         <msg xsi:type="xsd:string">This is a sample news item.</msg>
13       </postMessage>
14     </soapenv:Body>
15   </soapenv:Envelope>
16   ----Part_1092086011970
17   Content-Type: image/jpeg
18   Content-Transfer-Encoding: binary
19   Content-Id: <jpegImageRequest=81380956150.1092086011880>
20
21   [n lines omitted]
21+n ----Part_1092086011970--
22+n

3.4.1 Example

The [WSDL 1.1] Specification includes 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 <soap:binding>, and lines 17-22 show the extension properties in the <soap:binding>.

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

1     <binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">
2        <wsdl11soap11:binding style="document" 
                transport="http://schemas.xmlsoap.org/soap/http"/>
3         <operation name="GetLastTradePrice">
4            <wsdl11soap11:operation soapAction="http://example.com/GetLastTradePrice"/>
5           <input>
6               <wsdl11soap11:body use="literal"/>
7            </input>
8           <output>
9               <wsdl11soap11:body use="literal"/>
10          </output>
11        </operation>
12    </binding>
13
14   <binding name="StockQuoteSoapJMSBinding" type="tns:StockQuotePortType" 
              xmlns:soapjms="*placeholder*">
15       <wsdl11soap11:binding style="document" 
              transport="http://www.soapjms.org/2007/08/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       <operation name="GetLastTradePrice">
25         <wsdl11soap11:operation soapAction="http://example.com/GetLastTradePrice"/>
26         <input>
27             <wsdl11soap11:body use="literal"/>
28         </input>
29         <output>
30             <wsdl11soap11:body use="literal"/>
31          </output>
32       </operation>
33   </binding>
34
35   <service name="StockQuoteService">
36       <documentation>My first service</documentation>
37       <port name="StockQuotePort" binding="tns:StockQuoteSoapBinding">
38           <wsdl11soap11:address location="http://example.com/stockquote"/>
39       </port>
40       <port name="StockQuotePort_jms" binding="tns:StockQuoteSoapJMSBinding">
41           <wsdl11soap11:address location="jms:jndi:myQueue?targetService=stockquote"/>
42       </port>
43   </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 Transport Identification

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

Example:

<wsdl11soap11:binding style="document" 
                 transport="http://www.soapjms.org/2007/08/soap/bindings/JMS/"/>

3.4.3 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

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 wsdl:service, and it is then implied for all of the contained wsdl: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.

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

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

3.4.5 Specifying Properties Via the JMS URI

Some of the above information can be put in the IRI. (See [JMS IRI Scheme]) 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 Extension for SOAP 1.2]

Properties expressed in the IRI override any values set in the markup as described above.

Example:

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

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.