You can write a Web Services Description Language (WSDL)
extension that enables your Web Services Invocation Framework (WSIF)
service to access a SOAP service that uses the Java™ Message Service (JMS) as its transport
mechanism.
Before you begin
This topic assumes that you chose and configured a JMS provider
when you installed WebSphere® Application
Server (either the default messaging provider, or another provider
such as the WebSphere MQ
messaging provider). If not, do so now as described in
Choosing a messaging provider.
About this task
If a SOAP message contains only XML, it can be carried
on the Java Message Service
(JMS) transport mechanism with the JMS message body type TextMessage.
The SOAP message, including the SOAP envelope, is wrapped with a JMS
message and put on the appropriate queue. The container receives the
JMS message and removes the SOAP message to send to the client.
Use
the following procedure, and associated code fragments, to help you
to write the Web Services Description Language (WSDL) extension that
enables your WSIF service to access a SOAP over JMS service.
Note: You
can also use this procedure as a guide to writing the WSDL binding
extension for SOAP over HTTP, because the SOAP over JMS binding is
almost identical to the SOAP over HTTP binding.
Procedure
- Select 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"/>
- Set the JMS address.
Note: See also the alternative
method for specifying the JMS address that is given in the next step.
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 by 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">
<jms:propertyValue name="targetService" type="xsd:string"
value="StockQuoteServicePort"/>
</jms:address>
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 runtime environment.
The optional
attributes initialContextFactory and jndiProviderURL can
only be omitted if the runtime environment has a default Java Naming and Directory Interface (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.
The value attribute of the targetService <jms:propertyValue> element
is the name of the port component for the target service as defined
in the <port-component-name> element of the webservices.xml file
for the target service.
- Set the JMS address (alternative method).
For
the SOAP over JMS provider you can instead specify the JMS address
using the <soap:address> tag in the following format:
jms:/[queue|topic]?<property>=<value>&<property>=<value>&...
where
the specification of
queue or
topic corresponds
to the JMS address
destinationStyle attribute.
Table 1. Properties that are valid for use with
the <soap:address> tag. Column 1 specifies the property
name, column 2 describes the property, and column 3 specifies the
corresponding JMS address value.Property name |
Property description |
Corresponding JMS address value |
destination |
The JNDI name of the destination queue or topic |
jndiDestinationName |
connectionFactory |
The JNDI name of the connection factory. |
jndiConnectionFactory |
targetService |
The name of the port component of the target
service |
targetService jms:propertyValue within jms:address |
JNDI-related properties (optional): |
initialContextFactory |
The name of the initial context factory. |
initialContextFactory |
jndiProviderURL |
The JNDI provider URL |
jndiProviderURL |
JMS-related properties (optional): |
deliveryMode |
An indication as to whether the request message
should be persistent or not. The valid values are DeliveryMode.NON_PERSISTENT
(default) and DeliveryMode.PERSISTENT |
JMSDeliveryMode |
password |
The password to be used to gain access to the
connection factory. |
JMSPassword |
priority |
The JMS priority associated with the request
message. Valid values are 0 to 9. The default value is 4. |
JMSDeliveryMode |
replyTo |
The JNDI destination queue to which reply messages
should be sent. |
JMSReplyTo |
timeToLive |
The lifetime (in milliseconds) of the request
message. A value of 0 indicates an infinite lifetime. |
JMSTimeToLive |
userid |
The userid to be used to gain access to the
connection factory. |
JMSUserid |
Here is an example of this format:
<jms:address>
format:
<wsdl:port name="StockQuoteServicePort"
binding="sqi:StockQuoteSoapJMSBinding">
<jms:address destinationStyle="queue"
jndiConnectionFactoryName="myQCF"
jndiDestinationName="myQ"
initialContextFactory="com.ibm.NamingFactory"
jndiProviderURL="iiop://something:900/">
<jms:propertyValue name="targetService"
type="xsd:string"
value="StockQuoteServicePort"/>
</jms:address>
</wsdl:port>
<soap:address> format:
<wsdl:port name="StockQuoteServicePort"
binding="sqi:StockQuoteSoapJMSBinding">
<soap:address location="jms:/queue?connectionFactory=myQCF&destination
=myQ&initialContextFactory=com.ibm.NamingFactory&jndiProviderURL
=iiop://something:900/&targetService=StockQuoteServicePort" />
</wsdl:port>
- Set 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.
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:jms="http://schemas.xmlsoap.org/wsdl/jms/"
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/">
<jms:propertyValue name="targetService"
type="xsd:string"
value="StockQuoteServicePort"/>
</jms:address>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>