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/2008/07/soap/bindings/JMS/.

It is the intent of the W3C SOAP JMS Binding Working Group that the SOAP over Java Message Service 1.0 XML namespace URI will not change arbitrarily with each subsequent revision of the corresponding XML Schema documents as the specifications transition through Candidate Recommendation, Proposed Recommendation and Recommendation status. However, should the specifications revert to Working Draft status, and a subsequent revision, published as a WD, CR or PR draft, results in non-backwardly compatible changes from a previously published WD, CR or PR draft of the specification, the namespace URI will be changed accordingly.

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 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 URI, as the jms-variant portion of the syntax. ^†

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

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

• an optional property

• MAY be specified in JMS URI, 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 java.naming.factory.initial property (defined by the constant javax.naming.Context.INITIAL_CONTEXT_FACTORY) to be set in the HashMap sent to an InitialContext constructor.

• an optional property

• MAY be specified in JMS URI, WSDL, or somewhere else in the environment

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

• an optional property

• MAY be specified in JMS URI, WSDL, or somewhere else in the 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.

• An optional property that MAY be specified more than once.

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

• The JNDI property's name MUST be included in the name attribute, its value MUST be included in the value attribute. The value is added as a java.lang.String.

• MAY be specified in JMS URI, WSDL, or somewhere else in the environment

Example: Including the JNDI property com.acme.jndi.enable.tracing for the ACME Corporation JNDI provider

<soapjms:jndiContextParameter name="com.acme.jndi.enable.tracing" value=true" />
 

Example: Including the standard JNDI property java.naming.referral to disable (ignore) JNDI provider referrals.

<soapjms:jndiContextParameter name="java.naming.referral" value="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 SHOULD be sent. If the replyToName property has a value it is used to lookup a destination using the lookupVariant. If the variant is "jndi", this is the Java Naming and Directory Interface (JNDI) name of the destination (queue or topic). If the variant is "queue" or "topic", this refers to the name of a JMS queue.

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

• if specified, this MUST be used to derive the value to be used in the JMS header JMSReplyTo.^†

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

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

• if the variant is "jndi", topicReplyToName is not relevant and MUST be ignored.

• if the replyToName is specified in the URI, WSDL, or environment, topicReplyToName is not relevant and MUST be ignored.

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

• if specified and if relevant, this MUST be used to derive the value to be used in the JMS header JMSReplyTo.^†

import java.naming.Context;
import javax.jms.DeliveryMode;
import javax.jms.Destination;
import javax.jms.Message;
import javax.jms.MessageProducer;
...

class ... {

  // add appropriate error checking for your use....
  public void someMethod(Context ctx, MessageProducer producer, Message jmsMessage,
        String deliveryModeStr, String replyToName, int priority, long timeToLive) {

    // set the delivery mode to the appropriate constant value.
    int deliveryMode = deliveryModeStr.equals("PERSISTENT") 
      ? DeliveryMode.PERSISTENT: DeliveryMode.NON_PERSISTENT;
    jmsMessage.setJMSDeliveryMode( deliveryMode );
   
    // Set the reply destination, first looking it up using JNDI
    Destination replyDestination = ctx.lookup(replyToName);
    jmsMessage.setJMSReplyTo(replyDestination);

    // set the priority on the message.
    jmsMessage.setJMSPriority(priority);

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

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

    // alternately, a bunch of the lines above could be collapsed to:
    // producer.send(jmsMessage, deliveryMode, priority, timeToLive);
 }

} 
 

2.2.3 JMS Message properties

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

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

• optional in URI

• if specified MUST appear in the JMS message in the JMS property named SOAPJMS_targetService.^†

[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 MUST be generated 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 may be present; if the value of the property is multipart/related, a type parameter may be present.

• if the charset parameter is specified it is checked to ensure that it matches the encoding value from the supplied XML. If there is a mismatch then a fault MUST be generated.^† [Definition: Use fault subcode contentTypeMismatch in the event that the values do not match.^†]

• if no charset parameter is supplied the charset MUST be inferred using the rules defined in appendix F, Autodetection of Character Encodings , [XML 1.0].^†

• the contentType parameter MUST reflect the value specified in the Content-type part header for the first part (the SOAP body, so text/xml or application/xop+xml).^†

• MUST appear in the JMS message in the JMS property named SOAPJMS_contentType.^† [Definition: Use fault subcode missingContentType if the SOAPJMS_contentType property is missing.^†]

[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:requestURI] (xsd:string)

• Specifies the JMS URI of the service. The client MUST create this property which is derived from the supplied URI. The client MUST remove the targetService query parameter if specified; SHOULD remove JMS Message Header properties; and MAY remove other query parameters (for example client security related properties).^†

• a required property

• MUST appear in the JMS message in the JMS property named SOAPJMS_requestURI.^† [Definition: Use fault subcode missingRequestURI if the SOAPJMS_requestURI is missing from the message.^†]

 		
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. To conform to the latest enhancements to support internationalization, this specification references the [URI Scheme for JMS]. In particular, this section describes how the properties above are used in the URI [IETF RFC 3987]. Note that the URI scheme also defines query parameters, and where the query parameter names are the same, the same meaning is intended here.

For brevity, properties are shown without the SOAPJMS prefix. The "URI representation" column describes how the property is carried in the URI. The "Client treatment" column describes how the property should be treated in the process of forming the soapjms:requestURI property. There are three options for this column:

• As-is — the client SHOULD leave the information in the URI as is.

• Should exclude — the client SHOULD exclude the information from the generated requestURI .

• Must exclude — the client MUST not include the information in the generated requestURI.

[Definition: Use fault subcode malformedRequestURI when the URI violates the expected syntax.^† ]. [Definition: Use fault subcode targetServiceNotAllowedInRequestURI when targetService parameter is included in the requestURI).^†]

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 may be attractive in some scenarios, there are some considerations that go along with it.

• Since the message is already in text format the "encoding" attribute in the XML header MUST be ignored.

• Messages with attachments will need to use Content-Transfer-Encoding for attachment parts.

• Depending on the range of characters used by the SOAP message, using TextMessage may do more than double the memory requirements to receive a message.

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

Since binary data needs to be encoded to be carried as text, SOAP attachments via a TextMessage have the same concerns as the MIME specification carrying messages over a 7-bit channel [IETF RFC 2045]. The attachments will need to be encoded using one of the Content-Transfer-Encoding options specified by MIME. If the data is truly binary, such as a picture, a base64 encoding might be appropriate.

In typical scenarios, using TextMessage will almost certainly dramatically increase the memory requirements. This happens as a consequence of the JMS API TextMessage.getText(), which returns a Java String. The Java String class uses a UTF-16 representation to represent the data. This in memory representation will generally be larger than the corresponding BytesMessage representation. For example, if the message contains only US-ASCII characters, and is encoded into XML using UTF-8, the Java String representation of the message will take exactly twice as much memory.

The in memory UTF-16 representation, coupled with base64 encoding of an attachment, will consume much more memory than the equivalent BytesMessage payload. To begin with, a base64 conversion yields a ratio of 33% more characters than bytes. Combined with a UTF-16 representation of those characters, the bytes required in memory will be 167% more than the original binary data (an 8/3 ratio). As a consequence, carefully consider any scenarios that use attachments with a TextMessage.

As significant as the concerns around memory consumption may be, the effects on network payload size are more difficult to predict. Since the JMS API does not specify exactly how messages are handled, the effects on network traffic are JMS provider-specific. A JMS provider might be encoding a TextMessage with UTF-8, and may further compress such messages. With these two techniques, the data transferred via network calls may end up being no larger than a corresponding BytesMessage representation, even with attachments. However, only actual monitoring will determine specific effects of specific scenarios. Clients of this specification who are using TextMessage are encouraged to do such monitoring.

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

2.7.1 Behaviour of Sending SOAP Node

The message MUST be created as a JMS BytesMessage or TextMessage as defined in 2.4 The JMS Message Body.^†

The JMSReplyTo header MUST NOT be assigned a value. ^†

If the Sender receives a message transmission failure, then the http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason property is set to transmissionFailure and the message exchange is terminated with a fault.

A number of the message header properties are implicitly created by the use of the JMS API, the following table specifies how the binding properties described earlier explicitly affect the message constructed.^†

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 URI Scheme jms: in the <wsdl11soap11::address>.

1     <wsdl11:binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">
2        <wsdl11soap11:binding style="document" 
                transport="http://schemas.xmlsoap.org/soap/http"/>
3         <wsdl11:operation name="GetLastTradePrice">
4            <wsdl11soap11:operation soapAction="http://example.com/GetLastTradePrice"/>
5           <wsdl11:input>
6               <wsdl11soap11:body use="literal"/>
7            </wsdl11:input>
8           <wsdl11:output>
9               <wsdl11soap11:body use="literal"/>
10          </wsdl11:output>
11        </wsdl11:operation>
12    </wsdl11:binding>
13
14   <wsdl11:binding name="StockQuoteSoapJMSBinding" type="tns:StockQuotePortType" 
              xmlns:soapjms="http://www.w3.org/2008/07/soap/bindings/JMS/">
15       <wsdl11soap11:binding style="document" 
              transport="http://www.w3.org/2008/07/soap/bindings/JMS/"/>
16
17       <!-- We want this binding to use a particular CF class -->
18       <soapjms:jndiConnectionFactoryName>
19         sample.jms.ConnectionFactory
20       </soapjms:jndiConnectionFactoryName>
21       <!-- Specify PERSISTENT delivery mode -->
22       <soapjms:deliveryMode>PERSISTENT</soapjms:deliveryMode>
23
24       <wsdl11:operation name="GetLastTradePrice">
25         <wsdl11soap11:operation soapAction="http://example.com/GetLastTradePrice"/>
26         <wsdl11:input>
27             <wsdl11soap11:body use="literal"/>
28         </wsdl11:input>
29         <wsdl11:output>
30             <wsdl11soap11:body use="literal"/>
31          </wsdl11:output>
32       </wsdl11:operation>
33   </wsdl11:binding>
34
35   <wsdl11:service name="StockQuoteService">
36       <wsdl11:documentation>My first service</wsdl11:documentation>
37       <wsdl11:port name="StockQuotePort" binding="tns:StockQuoteSoapBinding">
38           <wsdl11soap11:address location="http://example.com/stockquote"/>
39       </wsdl11:port>
40       <wsdl11:port name="StockQuotePort_jms" binding="tns:StockQuoteSoapJMSBinding">
41           <wsdl11soap11:address location="jms:jndi:myQueue?targetService=stockquote"/>
42       </wsdl11:port>
43   </wsdl11:service>

The key points to notice are:

• The transport URI in <wsdl11soap11:binding> (line 15)

• The jms: URI in the <wsdl11soap11:address> (line 41)

• The extension properties in the <wsdl11soap11:binding> (lines 17-22)

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/2008/07/soap/bindings/JMS/ as the value of the transport.

<wsdl11soap11:binding style="document" 
                 transport="http://www.w3.org/2008/07/soap/bindings/JMS/"/>

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 MUST take precedence (port first, then service, then binding). ^† In the following example, notice the timeToLive property — for the quickPort port, the value will be 10 (specified at the port level). For the slowPort port, the value will be 100 (specified at the service level). The setting in the binding is, in this example, always overridden.

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

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

3.4.5 Specifying Properties Via the JMS URI

Some of the above information can be put in the URI [URI Scheme for JMS]. When expressing properties from the SOAP/JMS binding in the URI, you do not need the namespace prefix — just use the property name, such as "priority".

This URI, in turn, is represented as the location attribute on the <wsdl11soap11:address> element. Note that with SOAP 1.2, the same pattern applies, although the "soap" prefix corresponds to the SOAP 1.2 binding namespace http://schemas.xmlsoap.org/wsdl/soap12/ as established by [WSDL 1.1 for SOAP 1.2].

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

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