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

[ 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

[ 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() );
    jmsMessage.setStringProperty("SOAPJMS_requestURI", requestURI.toString() );
  }
}
	    	

2.2.4 Binding of Properties to URI

2.2.5 Other Properties

2.4.1 Considerations For Using TextMessage

• 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

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>

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

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>