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

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

It is the intent of the W3C SOAP JMS Binding Working Group that the SOAP/JMS 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 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 can 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 URI, as the jms-variant portion of the syntax. ^†

• The jms-variant: jndi MUST be supported.^† [Definition: A fault MUST be generated with subcode unsupportedLookupVariant if the JMS URI specifies a lookupVariant that is not supported by the implementation.^†]

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

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

[Definition: soapjms:jndiConnectionFactoryName ] (xsd:string)

• Specifies the JNDI name of the connection factory.

• optional in URI, optional in WSDL, optional in environment

[Definition: soapjms:jndiInitialContextFactory ] (xsd:string)

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

• optional in URI, optional in WSDL, optional in environment

[Definition: soapjms:jndiURL ] (xsd:anyURI)

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

• optional in URI, optional in WSDL, optional in environment

[Definition: soapjms:jndiContextParameter ] (soapjms:jndiContextParameterType)

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

• A property that can be specified more than once. When determining precedence rules for multiple occurrences of the jndiContextParameter property, the property is not considered to occur more than once unless the name attribute is identical in multiple jndiContextParameter properties.

• Specifies a JNDI property name and value pair to be added to the java.util.Hashtable sent to the InitialContext.

• In XML form the JNDI property's name is defined by the name attribute of the jndiContextParameter element, and the JNDI property value is defined by the value attribute. When indicated in a URI, the name of the JNDI property is derived from dropping the 'jndi-' prefix from any parameter name starting that way, and the value comes from the parameter value. The value is added as a java.lang.String.

• optional in URI, optional in WSDL, optional in environment

Example: Including JNDI context properties in WSDL

<!-- Enable tracing for the ACME Corporation JNDI provider   -->
<soapjms:jndiContextParameter name="com.acme.jndi.enable.tracing" value="true" />

<!-- Include the standard JNDI property to ignore JNDI provider referrals -->
<soapjms:jndiContextParameter name="java.naming.referral" value="ignore" />
 

Example: Including JNDI context properties in URI

jms:jndi:destinationName?jndi-com.acme.jndi.enable.tracing=true&jndi-java.naming.referral=ignore
 

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] (soapjms:deliveryModeType)

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

[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 URI, optional in WSDL, optional in environment.

• if specified, this MUST be used to generate the value of the JMS header JMSExpiration.^†

[Definition: soapjms:priority] (soapjms:priorityType)

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

[Definition: soapjms:replyToName] (xsd:string)

• Specifies the name of the destination to which a response message will 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.^†

[Definition: soapjms:topicReplyToName] (xsd:string)

• Specifies the name of the topic destination to which a response message will be sent.

• as defined by [IETF RFC 6167], the topicReplyToName only makes sense if the URI variant is "queue" or "topic".

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

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 reply destination, first looking it up using JNDI
    Destination replyDestination = ctx.lookup(replyToName);
    jmsMessage.setJMSReplyTo(replyDestination);

    // set the delivery mode to the appropriate constant value.
    int deliveryMode = deliveryModeStr.equals("PERSISTENT") ? DeliveryMode.PERSISTENT: DeliveryMode.NON_PERSISTENT;
    producer.setDeliveryMode( deliveryMode );

    // set the default priority on the producer.
    producer.setPriority(priority);

    // set when the message is set to expire.
    producer.setTimeToLive(timeToLive);

    // and finally, send the message.
    producer.send(jmsMessage);

    // Alternately, instead of changing the producer's default settings, the
    // header properties could be set on a per-message basis by passing them
    // to the MessageProducer.send() method, like so:
    // producer.send(jmsMessage, deliveryMode, priority, timeToLive);
  }  
} 
 

2.2.3 JMS Message properties

[Definition: soapjms:targetService] (xsd:string)

• Used by the service implementation to dispatch the service request.

• optional in URI

• [Definition: if specified MUST appear in the JMS message in the JMS property named SOAPJMS_targetService. Use fault subcode missingTargetService if specified and SOAPJMS_targetService does not appear. ^† ]

[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: A fault MUST be generated with subcode unrecognizedBindingVersion if the value of the soapjms:bindingVersion 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 might be present; if the value of the property is multipart/related, a type parameter might be present.

• [Definition: If the charset parameter is specified, it is checked to ensure that it matches the encoding value from the supplied XML. A fault MUST be generated with subcode contentTypeMismatch if the encoding values do not match.^†]

• The charset parameter is optional and can take the values "utf-8" or "utf-16". If the charset parameter is omitted, the character set rules for freestanding [XML 1.0] apply to the body of the JMS message.

• [Definition: The contentType value MUST appear in the JMS message in the JMS property named SOAPJMS_contentType. A fault MUST be generated with subcode missingContentType if the SOAPJMS_contentType property is missing.^†]

[Definition: soapjms:soapAction] (xsd:anyURI)

• As with SOAP/HTTP

• Optional in WSDL, optional in environment

• [Definition: If specified MUST appear in the JMS message in the JMS property named SOAPJMS_soapAction. Fault subcode missingSoapAction MAY be used if SOAPJMS_soapAction does not appear.^† ]

• [Definition: If using SOAP 1.2, and the contentType property has an action parameter, that parameter value is compared with the SOAPJMS_soapAction value. A fault MUST be generated with fault subcode mismatchedSoapAction if the SOAP 1.2 action does not match the SOAPJMS_soapAction value.^†]

[Definition: soapjms:isFault] (xsd:boolean)

• This property indicates whether a SOAP/JMS message corresponds to a SOAP fault.

• For senders, this property is set to true when responding with a SOAP fault. When this property is true, the sending software MUST set a boolean JMS Message property named SOAPJMS_isFault with a value of true, as in: Message.setBooleanProperty("SOAPJMS_isFault", true). ^†

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

[Definition: soapjms:requestURI] (xsd:string)

• Specifies the JMS URI of the service. The client MUST create the requestURI by taking the supplied URI, leaving the destinationName as-is, and removing the targetService and replyToName query parameters if they are specified. The client SHOULD also remove deliveryMode, jndiConnectionFactoryName, jndiInitialContextFactory, jndiURL, jndiContextParameter, timeToLive, and priority properties. The client MAY remove other query parameters not explicitly mentioned above (for example client security related properties).^†

• A required property

• [Definition: Appears in the JMS message in the JMS property named SOAPJMS_requestURI. A fault MUST be generated with fault subcode missingRequestURI if the SOAPJMS_requestURI property is missing from the message.^†]

• [Definition: A fault MUST be generated with subcode malformedRequestURI when the SOAPJMS_requestURI violates the expected syntax.^† ].

• [Definition: A fault MUST be generated with subcode targetServiceNotAllowedInRequestURI when targetService parameter is included in the SOAPJMS_requestURI). ^† ]

[Definition: soapjms:contentEncoding] (xsd:string)

• Identifies the transformation that has been applied to the message payload body. Contains one of the values defined by IANA for the Content-Coding values of [IANA HTTP PARAMS]. Defaults to "identity" if the property is not present.

• Corresponds to the JMS Message property named SOAPJMS_contentEncoding

• [Definition: If the content encoding is specified, it is checked to ensure that it matches the content encoding values supported. A fault MUST be generated with subcode contentEncodingNotSupported if the encoding values do not match.^†]

• Restriction: the meaning of the property is not defined for composite messages (messages with a Content-Type of "multipart" or "message"), only for discrete messages (Content-Type "application" or "text", for this specification).

 		
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() );
  }
}
	    	
	    	

2.2.4 Binding of Properties to URI

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. In particular, this section describes how the properties above are used in the URI. 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.

2.2.5 Other Properties

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

2.4.1 Considerations For Using TextMessage

While the use of TextMessage might 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 has to 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 might more than double the memory requirements to receive a message.

• The impact on network consumption ought to be measured for particular scenarios and JMS providers.

• Use of the contentEncoding property is not defined, since the underlying message payload is not raw bytes.

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 might 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 could further compress such messages. With these two techniques, the data transferred via network calls could 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.

2.5.1 Support for Topic destinations

Topics can 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

2.6.2 Behaviour of Responding SOAP Node

2.7.1 Behaviour of Sending SOAP Node

The message is 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 shows how the binding properties described earlier explicitly affect the message constructed.

2.7.2 Behaviour of Receiving SOAP Node

The receiving node follows the rules defined in [SOAP 1.2 Part 3: One-Way MEP].

3.3.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 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/2010/soapjms/">
15       <wsdl11soap11:binding style="document" 
              transport="http://www.w3.org/2010/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
                                   &amp;priority=8&amp;replyToName=interested&amp;userprop=mystuff"/>
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)

3.3.2 WSDL 1.1 Transport Identification

For each of SOAP 1.1 and SOAP 1.2, the transport attribute of the wsdl11soap11:binding element, and the wsdl11soap12:binding element, respectively, indicate the transport value. To indicate that this SOAP/JMS binding is in use, the transport attribute MUST be set to the value http://www.w3.org/2010/soapjms/.^†

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

3.3.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.3.4 Specifying Properties In WSDL 1.1

Various JMS properties described in the SOAP/JMS binding specification can be set in four places in the WSDL — the binding, the service, the port, and the URI for the port. Values specified at the service will propagate to all ports. Values specified at the binding will propagate to all ports using that binding. For example, the jndiInitialContextFactory can 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 within the WSDL document, the most specific setting MUST take precedence (URI specified in the address element's location attribute first, then other properties set on the port, 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.3.5 Specifying Properties Via the JMS URI

Some of the above information can be put in the JMS URI. 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 is found as the value of the location attribute on the <wsdl11soap11:address> or <wsdl11soap12:address> element when using SOAP 1.1 and SOAP 1.2, respectively. The value of the location attribute MUST be a URI corresponding to a JMS Destination, and SHOULD be a "jms" scheme URI.^† The characters in the URI need to be encoded ("%20" for space, for example) as per normal URI escaping rules, and the resulting URI needs to be encoded as per normal XML rules ("&" for &) when serialized into an XML attribute.

<wsdl11:port .... >
       <wsdl11soap11:address
location="jms:jndi:destinationName?targetService=service%20Test&amp;priority=5"/>
       
</wsdl11:port>