You can use the SOAP over Java Message
Service (JMS) transport protocol as an alternative to SOAP over HTTP
for communicating SOAP messages between clients and servers.
Before you begin
A Web service must be implemented as an enterprise bean
for accessibility through the JMS transport.
About this task
New feature: WebSphere® Application Server
Version 7.0 introduces support for an emerging industry standard SOAP
over JMS protocol. The SOAP over JMS specification provides a standard
set of interoperability guidelines for using a JMS-compliant transport
with SOAP messages to enable interoperability between the implementations
of different vendors. Using this standard, a mixture of client and
server components from different vendors can interoperate when exchanging
SOAP request and response messages over the JMS transport for both Java API for XML Web Services (JAX-WS) and Java API for XML-based RPC (JAX-RPC) Web services.
By using the JMS transport, your enterprise beans based Web service
clients and servers can communicate through JMS queues and topics
instead of through HTTP connections. newfeat
Deprecated feature: In earlier versions of the application server,
an IBM® proprietary SOAP over JMS protocol was supported
for Java API for XML-based RPC (JAX-RPC) applications.
In WebSphere Application Server 7.0, this
proprietary SOAP over JMS protocol is now deprecated in favor of an
emerging industry standard SOAP over JMS protocol. You can use the IBM proprietary
SOAP over JMS protocol with your Java API
for XML Web Services (JAX-WS) or JAX-RPC Web services; however, take
advantage of the emerging standard SOAP over JMS protocol. If your
client application invokes enterprise beans-based Web services that
are supported by an earlier version of the WebSphere Application
Server, you must continue to use the IBM proprietary
SOAP over JMS protocol to access those Web services. depfeat
The
benefits of using JMS include:
- Reliable messaging transport for communicating request and response
messages.
- Flexible one-way requests for clients and servers. For example,
the server does not have to be active when the client sends the one-way
request. Simultaneous one-way requests can be sent to multiple servers
through the use of a topic.
- Synchronous two-way requests are supported for both Java API for XML-Based Web Services (JAX-WS)
and Java API for XML-based RPC (JAX-RPC) clients.
- Asynchronous requests are supported for JAX-WS clients.
The SOAP over JMS specification
defines a JMS endpoint URI syntax for specifying JMS destinations.
A JMS endpoint URL is used to access JAX-WS or JAX-RPC Web services
with the JMS transport. This URL specifies the JMS destination and
connection factory, as well as the port component name for the Web
service request. This endpoint URL is similar to the HTTP endpoint
URL, which specifies the host and port as well as the context root
and port component name.
Procedure
- Develop the enterprise bean that you intend to use as your
service implementation bean.
- Develop Java artifacts for JAX-WS applications.
Although a Web Services Description Language (WSDL) file is
typically optional when developing a JAX-WS service implementation
bean, it is required if your JAX-WS endpoints are exposed using the
SOAP over JMS transport and you are publishing your WSDL file. Therefore,
if you are developing JAX-WS Web services using the bottom-up approach,
use the wsgen tool to generate a WSDL file from
your JAX-WS implementation bean, and then package the WSDL file along
with any associated schema files with your application.
- Modify your WSDL file so that the ports that are accessible
using the SOAP over JMS transport have an endpoint location URL that
starts with the jms: prefix. For
example:
<service name="MyService">
<port name="MyJMSPort" binding="tns:MyJMSPortBinding">
<soap:address location="jms:my_actual_endpoint_URL"/>
</port>
</service>
Using the jms: prefix enables the
WSDL publisher to identify the MyJMSPort port
as a JMS port, and a JMS-style endpoint location URL is used when
publishing the WSDL.
- Assemble the enterprise beans.
- Assemble
a JAR file that is enabled for Web services from an enterprise bean.
You can assemble the artifacts that are required to enable the
enterprise beans module for Web services into a Java archive
(JAR) file.
- Assemble
a Web services-enabled enterprise bean JAR file into an enterprise
archive (EAR) file. You can assemble the artifacts
that are required to enable the Web services-enabled JAR file into
an EAR file.
- Enable the enterprise beans-based endpoints by using the endptEnabler command.
Use the -transport jms option to request that
the endptEnabler command create a message-driven
bean (MDB) listener for each Enterprise JavaBeans (EJB)
JAR file that contains Web services implementation beans. This message-driven
bean serves as a listener for requests that are associated with the
Web service endpoints contained in the EJB JAR file.
- Decide on the names and the types of the JMS objects that
your application uses.
Before you install your application,
you need to:
- Decide whether your Web service receives requests from a queue
or a topic.
- Decide whether to use a secure destination or a nonsecure destination.
- Decide the names for your queues and topics, connection factory
and activation specification.
Use the following guidelines for deciding JMS
object names and types. In typical situations, you can use a queue
for receiving Web services requests.
- Queue
- A queue receive all types of requests. Valid requests include
one-way, two-way, and synchronous. Asynchronous requests are only
valid with JAX-WS Web services.
- A queue is used only by a single EJB JAR file for receiving the
requests for Web services endpoints contained within that EJB JAR
file.
- Topic
- A topic is used to receive only one-way requests.
- You can share a topic among multiple EJB JAR files. Each request
message that is sent to a topic is processed by each of the MDB listeners
that are configured to listen on that topic. This means that each
request message is processed by each EJB JAR file associated with
that specific topic.
The following example describes a typical configuration
for a single EJB JAR file containing Web services endpoints:
- Suppose the EJB JAR file is StockQuoteEJB.jar and contains one
or more Web services endpoints related to the StockQuote service.
- You have a single queue, StockQuote_Q, with the JNDI name, jms/StockQuote_Q,
that is used to receive requests.
- You have a connection factory, StockQuote_CF, with JNDI name, jms/StockQuote_CF,
that can be used by clients to connect to the JMS provider.
- You also have a connection factory, StockQuote_ReplyCF, with JNDI
name, jms/StockQuote_ReplyCF, that is used by the
MDB listener for the EJB JAR file to connect to the JMS provider when
sending reply messages.
- You have an activation specification, StockQuote_AS, with JNDI
name, jms/StockQuote_AS, that is used to associate
the StockQuoteEJB.jar's MDB listener with the queue named StockQuote_Q.
- Define the JMS
administered objects.
After you decide on the
names and types of the JMS objects, use the administrative console
or the wsadmin scripting tool to define the JMS
objects. There are multiple ways to administer JMS resources depending
on what type of JMS provider is being used. Read about choosing a
messaging provider to learn more about administering JMS resources.
- Deploy the
Web services application.
During the installation
process you are prompted for two types of information for each enterprise
bean JAR file that is enabled for Web services and is contained in
your EAR file:
- The JNDI name of the connection factory that is used by the MDB
listener to use for sending reply messages.
If your Web service
contains two-way operations, the MDB listener that is defined by the endptEnabler command
needs to access a queue connection factory to add a reply message
to the reply queue. The MDB listener uses a resource environment
reference of java:comp/env/jms/WebServicesReplyQCF.
Therefore, during the application installation process, you must provide
the actual JNDI name of the connection factory for the MDB listener
to use for that Web service. Using the previous example, the JNDI
name is jms/StockQuote_ReplyCF.
- The name of the activation specification for the MDB listener
to use.
An activation specification is an object that is used
to associate a JMS connection factory with a JMS destination (queue
or topic). When deployed, an MDB is configured with the correct activation
specification so that messages from the queue or topic are properly
delivered to the MDB. During deployment, you can modify the name of
the activation specification that is associated with each MDB listener.
The activation specification name contained in the input EAR file
is displayed as a default value. If you specify the correct activation
specification name to the endptEnabler command,
you can accept the default value. Otherwise, enter the correct activation
specification name.
- Decide whether to use the new industry standard SOAP over
JMS protocol or the IBM proprietary SOAP/JMS protocol.
Best practice: It is a best practice to use
the industry standard SOAP/JMS protocol. The IBM proprietary
SOAP/JMS protocol has been deprecated with this release. However,
if your application needs to interoperate with previous versions of
the product, then use the proprietary protocol.
bprac
- (Optional) Configure
endpoint URL information for JMS bindings.
Use
the administrative console to configure a JMS endpoint URL prefix
that you can associate with each EJB JAR module in your application.
The WSDL publisher uses this partial URL string to produce the actual
JMS URL for each port component that is defined in the enterprise
bean JAR file. The clients that need to invoke the Web service can
use the published WSDL file.
Perform this step only if you
are publishing the WSDL file for your application.
- (Optional) Publish
the WSDL file for your application.
Publishing
the WSDL file, this produces WSDL documents that you can use to develop
your client applications. The publishing process produces fully-resolved
endpoint location URLs within the WSDL files.
Perform this
step only if the published WSDL files are needed to develop your client
applications.
Results
You have a Web service that is configured to use SOAP over
JMS to transport the requests.
What to do next
Develop a Web services client.