Use the Java Messaging Service to transport Web services requests

WAS offers support for using a Java Messaging Service (JMS) transport layer, in addition to the existing HTTP transport. Using JMS transport allows your Web service clients and servers to communicate through JMS queues and topics instead of HTTP connections. One-way and synchronous two-way requests are supported.

Note that A Web service must be implemented as an enterprise JavaBean (EJB) to be accessed through the JMS transport.

The benefits of using JMS as an alternative to HTTP, include:

To use JMS as a transport for Web services requests...

  1. Add a JMS binding and a SOAP address to the Web Services Description Language (WSDL) file. The WSDL file of a Web service must include a JMS binding and a SOAP address, which specifies a JMS endpoint URL string, in order to be accessible on the JMS transport. A JMS binding is a wsdl:binding element containing a wsdlsoap:binding element whose transport attribute ends in soap/jms, rather than the typical soap/http value.

    In addition to the JMS binding, a wsdl:port element referencing the JMS binding must be included in the wsdl:service element within the WSDL file. The wsdl:port element should contain a wsdlsoap:address element whose location attribute specifies a JMS endpoint URL string.

    Note that The specification of the actual JMS endpoint URL string can be deferred until you publish the WSDL file. When you develop the Web service, a placeholder such as file:/unspecified_location can be used for the endpoint URL string.

  2. Decide on the names and types of JMS objects that your application usesBefore your application can be installed, you need to...

    1. Decide whether your Web service receives its requests from a queue or a topic.

    2. Decide whether to use a secure destination (queue or topic) or a nonsecure destination.

    3. Decide on the names for your destination, connection factory and listener port. The following list provides examples of the names that might be used for the mythical StockQuote Web service:

      • Queue: StockQuote_Q (JNDI name: jms/StockQuote_Q)

      • Connection factory: StockQuote_CF (JNDI name: jms/StockQuote_CF)

      • Listener port: StockQuoteEJB_ListenerPort

  3. Define the JMS administered objects. Once you have decided on the names and types of the JMS objects, use the administrative console or the wsadmin scripting interface to define the JMS objects.

  4. Add the JMS endpoints to your EAR file using the endptEnabler command tool.You must run the endptEnabler command to add a JMS endpoint or router module for each Web service-enabled EJB JAR file contained in the EAR file. By default, the endptEnabler command adds only HTTP endpoints, but the -transport jms option can be used to request the addition of JMS endpoints.

  5. Deploy the Web services application.During the install process you are prompted for two types of information for each Web service-enabled EJB JAR contained in your EAR file:

    • The JNDI name of the connection factory to be used by the EJB JAR file message driven bean (MDB) listener for sending reply messages.

      If your Web service contains two-way operations, the MDB listener, defined inside the JMS endpoint added by endptEnabler command, needs to access a queue connection factory in order 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 install process, provide the actual JNDI name of the queue connection factory that should be used by the MDB listener for that Web service. You might want to use the same connection factory that you defined for use by clients in step 2.

    • The name of the listener port to be used by the MDB listener.

      A listener port 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 listener port so that messages from the desired queue or topic are properly delivered to the MDB. During deployment, you can modify the name of the listener port associated with each MDB listener. The listener port name contained in the input EAR file displays as a default value. If you specify the correct listener port name to the endptEnabler command, perhaps through the use of properties, during step 3, you can accept the default value. Otherwise, enter the correct listener port name.

      Hint: By default, the endptEnabler command produces listener port names of the form <ejb-jar-name>_ListenerPort. To simplify this step, define the listener ports that follow this naming convention during step 2.

  6. Publish the WSDL file.In this step, you enter the JMS endpoint URL string to use for each Web service-enabled EJB JAR file belonging to the application. The JMS endpoint URLs are then written to the published WSDL files for use by clients.

    For example, suppose that an application called StockQuoteService contains an EJB JAR file named StockQuoteEJB, which contains one or more Web services accessible on the JMS transport. Suppose that, in step 2, you defined a queue with the JNDI name jms/StockQuote_Q and a connection factory with the JNDI name jms/StockQuote_CF to be used by your application. In this example, you would specify the following string as the JMS URL prefix within the Publish WSDL user interface:

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

    The WSDL publisher uses this partial URL string to produce the actual JMS URL for each port component defined in the EJB JAR file. The published WSDL file can be used by clients needing to invoke the Web service.

 

See Also

Using Web services based on Web Services for J2EE
Enabling a Web services-enabled EAR file
Publishing WSDL files
endptEnabler command
Java Messaging Service endpoint URL syntax