The SOAP over JMS provider - Writing the WSDL extension

If a SOAP message contains only XML, then it can be carried on the Java Messaging Service (JMS) transport with the JMS message body type TextMessage.

The WSDL binding extension for SOAP over JMS varies only slightly from the SOAP over HTTP binding.

Selecting the SOAP over JMS binding

You set the transport attribute of the <soap:binding> tag to indicate that JMS is used. If you also set the style attribute to rpc Remote(Procedure Call), then the Web Services Invocation Framework (WSIF) assumes that an operation is invoked on the Web service endpoint 

<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/jms"/>

Setting the JMS address

For SOAP over JMS, the <wsdl:port> tag must contain a <jms:address> element. This element provides the information required for a client to connect correctly to the Web service using the JMS programming model. Typically, it is the stubs generated to support the SOAP over JMS binding that act as the JMS client. Alternatively, the Web service client can use the JMS programming model directly.

The <jms:address> element takes this form 

 
<jms:address
    
    destinationStyle="queue"    
    jmsVendorURI="http://ibm.com/ns/mqseries"?
    initialContextFactory="com.ibm.NamingFactory"?
    jndiProviderURL="iiop://something:900/wherever"?
    jndiConnectionFactoryName="orange"
    jndiDestinationName="fred"
/>
where attributes marked with a question mark (?) are optional.

The optional jmsVendorURI attribute is a string that uniquely identifies the JMS implementation. WSIF ignores this URI, which is used by the client developer and perhaps the client implementation to determine if it has access to the correct JMS provider in the client run-time.

The optional attributes initialContextFactory and jndiProviderURL can only be omitted if the run-time has a default JNDI provider configured.

The jndiConnectionFactoryName attribute gives the name of a JMS ConnectionFactory object, which can be looked up within the JNDI context given by the jndiContext attribute. This ConnectionFactory object is used to create a JMS connection to the JMS provider instance that owns the queue. In a simple configuration, the same ConnectionFactory object is used by the server message listener and by the clients. However the server and the clients can use different ConnectionFactory objects, provided that they all create connections to the same JMS provider instance.

Setting the JMS headers and properties

You use the <jms:property> tag to set the JMS headers and properties. This tag maps either a message part, or a literal value, into a JMS property 

<jms:property name="Priority" {part="requestPriority" | value="fixedValue"}/>

If the <jms:property> has a literal value, then it can also be nested within the <jms:address> tag 

<jms:property name="Priority" value="fixedValue" />

This form of the <jms:property> tag is also used in the native JMS binding.

 

Usage Scenario

Here is an example of a WSDL that defines a SOAP over JMS binding 

<!-- Example: SOAP over JMS Text Message -->

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions
           name="StockQuoteInterfaceDefinitions"
        targetNamespace="urn:StockQuoteInterface"
        xmlns:tns="urn:StockQuoteInterface"
        xmlns:xsd="http://www.w3.org/2000/10/XMLSchema"
        xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <wsdl:message name="GetQuoteInput">
        <part name="symbol" type="xsd:string"/>
    </wsdl:message>
    <wsdl:message name="GetQuoteOutput">
        <part name="value" type="xsd:float"/>
    </wsdl:message>

    <wsdl:portType name="StockQuoteInterface">
        <wsdl:operation name="GetQuote">
            <wsdl:input message="tns:GetQuoteInput"/>
            <wsdl:output message="tns:GetQuoteOutput"/>
        </wsdl:operation>
    </wsdl:portType>

    <wsdl:binding name="StockQuoteSoapJMSBinding" type="tns:StockQuoteInterface">
        <soap:binding style="rpc"
                 transport="http://schemas.xmlsoap.org/soap/jms"/>
        <wsdl:operation name="GetQuote">
            <soap:operation soapAction="urn:StockQuoteInterface#GetQuote"/>
            <wsdl:input>
                <soap:body use="encoded" namespace="urn:StockQuoteService"
                         encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use="encoded" namespace="urn:StockQuoteService"
                     encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name="StockQuoteService">
        <wsdl:port name="StockQuoteServicePort" 
                      binding="sqi:StockQuoteSoapJMSBinding">
            <jms:address destinationStyle="queue" 
                     jndiConnectionFactoryName="myQCF"
                     jndiDestinationName="myQ"
                     initialContextFactory="com.ibm.NamingFactory" 
                     jndiProviderURL="iiop://something:900/" />
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

 

See Also

Using the SOAP over JMS provider
The JMS providers - Configuring the client and server