+

Search Tips   |   Advanced Search

Use SOAP over JMS to transport web services

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.

A web service must be implemented as an enterprise bean for accessibility through the JMS transport.

This product supports 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 JAX-WS and Java API for XML-based RPC (JAX-RPC) web services. By using the JMS transport, the enterprise beans based web service clients and servers can communicate through JMS queues and topics instead of through HTTP connections.

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 and later, this proprietary SOAP over JMS protocol is now deprecated in favor of an emerging industry standard SOAP over JMS protocol. Use the IBM proprietary SOAP over JMS protocol with the JAX-WS or JAX-RPC web services; however, take advantage of the emerging standard SOAP over JMS protocol. If wer client application invokes enterprise beans-based web services that are supported by an earlier version of the WAS, you must continue to use the IBM proprietary SOAP over JMS protocol to access those web services. depfeat

The benefits of using JMS include:

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.

  1. Develop the enterprise bean that you intend to use as your service implementation bean.

  2. For JAX-WS applications, add the @BindingType annotation to the endpoint implementation class and specify the SOAP over JMS binding id for the endpoint. For example: 
    @WebService  @BindingType("http://www.w3.org/2010/soapjms/")
public class MyServiceBeanImpl {
    ...
}

    The @BindingType annotation is used to indicate the protocol (SOAP) and transport (JMS) to be used when sending request and response messages for the endpoint.

  3. Assemble the enterprise beans.

    1. Assemble a JAR file that is enabled for web services from an enterprise bean. We can assemble the artifacts required to enable the enterprise beans module for web services into a JAR file.

    2. Assemble a web services-enabled enterprise bean JAR file into an EAR file. We can assemble the artifacts required to enable the web services-enabled JAR file into an EAR file.

  4. Enable the enterprise beans-based endpoints using the endptEnabler command. Use the -transport jms option to request that the endptEnabler command create a message-driven bean (MDB) listener for each EJB JAR file containing web services implementation beans. This message-driven bean serves as a listener for requests associated with the web service endpoints contained in the EJB JAR file.

  5. Decide on the names and the types of the JMS objects that the application uses.

    Before you install the application, we need to:

    • Decide whether the 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 the queues and topics, connection factory and activation specification.

    Use the following guidelines for deciding JMS object names and types. In typical situations, we 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.

      • We can share a topic among multiple EJB JAR files. Each request message sent to a topic is processed by each of the MDB listeners 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, 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, 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, used to associate the StockQuoteEJB.jar's MDB listener with the queue named StockQuote_Q.

  6. Define the JMS administered objects.

    After you decide on the names and types of the JMS objects, use the 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.

  7. 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 our EAR file:

    • The JNDI name of the connection factory used by the MDB listener to use for sending reply messages.

      If the web service contains two-way operations, the MDB listener 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, 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 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, we 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 we specify the correct activation specification name to the endptEnabler command, we can accept the default value. Otherwise, enter the correct activation specification name.

  8. 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 the application needs to interoperate with previous versions of the product, then use the proprietary protocol.bprac

    • If we use the industry standard SOAP over JMS protocol, use the Configure endpoint URL information for JMS bindings task to specify a JMS endpoint URL prefix that adheres to the JMS endpoint URI syntax that is associated with the standard; for example:

        jms:jndi:jms/StockQuote_Q&jndiConnectionFactoryName=jms/StockQuote_CF

    • If we use the IBM proprietary SOAP over JMS protocol, use the Configure endpoint URL information for JMS bindings task to specify a JMS endpoint URL prefix that adheres to the IBM proprietary SOAP over JMS protocol; for example:

        jms:/queue?destination=jms/StockQuote_Q&connectionFactory=jms/StockQuote_CF

  9. Optional. Configure endpoint URL information for JMS bindings.

    Use the console to configure a JMS endpoint URL prefix that we can associate with each EJB JAR module in the application. The WSDL publisher uses this partial URL string to produce the actual JMS URL for each port component 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 the application.

  10. Optional. Publish the WSDL file for the application.

    Publishing the WSDL file, this produces WSDL documents that we 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 the client applications.


Results

You have a web service configured to use SOAP over JMS to transport the requests.


What to do next

Develop a web services client.


Related tasks

  • Use the JAX-WS JMS asynchronous response message listener
  • Configure a permanent reply queue for web services using SOAP over JMS
  • Configure a permanent replyTo queue for JAX-RPC web services using SOAP over JMS (deprecated)
  • Invoking web service requests transactionally using SOAP over JMS transport
  • Invoking one-way JAX-RPC web service requests transactionally using the JMS transport (deprecated)
  • Implement web services applications with JAX-WS
  • Implement web services applications with JAX-RPC
  • Implement static JAX-WS web services clients
  • Implement JAX-RPC web services clients
  • Configure endpoint URL information for JMS bindings
  • Choose a messaging provider
  • Task overview: Implement web services applications
  • Enable an EAR file for EJB modules containing web services
  • Making deployed web services applications available to clients

  • SOAP over JMS protocol
  • JMS endpoint URL syntax
  • IBM proprietary SOAP over JMS protocol (deprecated)
  • IBM proprietary JMS endpoint URL syntax (deprecated)
  • endptEnabler command
  • Web services specifications and APIs


    Related information:

    SOAP over Java Message Service specification