Developing a JAX-WS EJB web service for W3C SOAP over JMS

A web service bound to the W3C candidate recommendation for SOAP over JMS must run in the EJB container of a JEE application server. This task is step 2 of connecting an Axis2 web service client and a web service deployed to WebSphere Application server using the W3C SOAP over JMS protocol.


Before you begin

Use Rational® Application Developer to create the EJB web service. The web service wizard in Rational Application Developer has an option to create a web service using the W3C candidate recommendation for the SOAP over JMS binding. Rational Application Developer 7.54 is required. The exercise used Rational Application Developer included in Rational Software Architect for WebSphere Software v7.5.5.1,

The EJB is deployed to WebSphere Application Server from Rational Application Developer as part of this task.

To create the WSDL actually used in the task, you must first set up the Liberty profile. Then we can either import the WSDL from the Dynamic Web project in the Eclipse Galileo workspace, or from the running HTTP web service deployed to the Liberty profile.

WebSphere Application Server might still be running. If it is not, we can start it from the Servers view in RAD.


About this task

In this task, you redeploy the StockQuoteAxis service from running as a JAX-RPC Axis service run by the SimpleJavaListener using IBM MQ transport for SOAP, to being a JAX-WS service running in WebSphere Application server using the W3C SOAP over JMS protocol.

There are two parts to migrating the service from the SimpleJavaListener to WebSphere Application Server:
  1. Generate the web service interface from the WSDL for the service using the Top-down EJB web service wizard in Rational Application Developer.
  2. Implementing the service by importing the IBM MQ SOAP sample StockQuoteAxis.java.

An alternative approach would have been to generate the service bottom up, from the StockQuoteAxis.java. However, to be sure that the interface to the migrated service is identical, the top-down approach is better, as it uses the same WSDL.

The web service is developed for the EJB container and not the Web container because the JMS support is part of the EJB container.


Procedure

  1. Start Rational Application Developer, and verify WebSphere Application Server is running.
    1. Start Rational Application Developer in a new workspace.
    2. Open the Java EE perspective.
    3. Open the Servers tab, and check WebSphere Application Server is running.

      • If there is no WebSphere Application Server v7.0 in the view, right-click in the view > New > Server. Follow the choices in the wizard to create a WebSphere Application Server v7.0 instance.
      • If the server is present, but not started, click the arrow head to start it.
      • To verify the properties and get quick access to the server logs, right-click WebSphere Application Server v7.0 at localhost > Properties > WebSphere Application Server.
      • To administer the server, either use an external browser and open the URL, http://localhost:9061/ibm/console/unsecureLogon.jsp, or right-click WebSphere Application Server v7.0 at localhost > Run administrative console.
      • The default setting is to publish automatically. Many people prefer deploy updates to the server manually. Double-click WebSphere Application Server v7.0 at localhost, and expand the Publishing twisty in the Overview window. Click Never publish automatically.
      • Another default that you might want to alter is to clear the Terminate server on workbench shutdown checkbox in the Overview window.
  2. Create the JEE projects You must create an Enterprise Application Project (EAR) and an Enterprise Java Bean (EJB) Project.
    1. File > New > Enterprise Application Project. Name the project W3CJMSEAR > Finish.

      The defaults must identify WebSphere Application Server v7.0 as the target runtime, and EAR version 5.0. The default configuration must be selected.

    2. File > New > EJB Project. Name the project W3CJMSEJB. Select W3CEARJMS as the EAR Project Name > Next.

      The default EJB module version is 3.0 and the default configuration is used again.

    3. Clear the Create an EJB Client JAR module checkbox> Finish.
  3. Generate and deploy the EJB web service from the StockQuoteAxis WSDL.
    1. Run > Launch the Web Services Explorer.
    2. Select the WSDL page using the icons in the Web Services Explorer window > click WSDL main in the Navigator.
    3. In the Actions window, type in or browse to the WSDL URL for StockQuoteAxis.wsdl. If we have Liberty running with StockQuoteAxis deployed as an HTTP service, the URL is: 
      http://localhost:8080/StockQuoteAxis/services/StockQuoteAxis?wsdl
      If you have the WSDL in the file system, the URL might be: 
      File:\Dirpath\StockQuoteAxis\WebContent\wsdl\StockQuoteAxis.wsdl
    4. Click the line containing the imported URL in the Navigator tree.

      It is the line immediately following WSDL Main, if it is the first WSDL we have imported into Web Services Explorer.

    5. In the Actions window, click Launch Web Service Wizard > Web Service Skeleton > Go
    6. In the Web Service wizard, select Top down EJB Web Service

      Select or verify the Configuration using information from Table 1 Check Overwrite files without warning > Next.

      Table 1. Top down EJB web service configuration
      Field Value
      Server WebSphere Application Server v7.0
      Web service run time IBM WebSphere JAX-WS
      Service project W3CJMSEJB
      Service EAR project W3CJMSEAR
      Configuration: No client generation
    7. On the page subtitled, Specify options for creating a WebSphere JAX-WS EJB Top Down Web Service, check the Switch to JMS binding box. Also check Enable Wrapper Style, Copy WSDL to project, and Generate Web Service Deployment Descriptor > Next.
    8. On the page titled, WebSphere JAX-WS JMS Binding Configuration, check Use SOAP/JMS interoperability protocol and provide values from Table 2, leaving other fields blank > Next.
      Table 2. WebSphere JAX-WS JMS Binding Configuration
      Field Value
      JMS destination queue
      Destination JNDI name: requestaxis
      JMS connection factory qm1
      Reply to Name W3CJMSEAR
      Configuration: replyaxis
    1. On the page titled, WebSphere JAX-WS Router Project Configuration, type qm1as in the ActivationSpec JNDI name field > Next.

      RAD takes about 30 seconds to a minute to generate and deploy the project.

    2. Ignore the options in the Web Service Publication page> Finish.
  4. Check the generated WSDL.

    You asked for the service-specific WSDL to be generated and saved in the project.

    1. In the Enterprise Explorer navigator, open the folder W3CJMSEJB > ejbmodule > META-INF > wsdl. Double-click StockQuoteAxis.wsdl to open it in the WSDL editor. Inspect the binding; you see the JMS url: 
      jms:jndi:requestaxis?jndiConnectionFactoryName=qm1&targetService=StockQuoteAxis
  5. Optional step: Bind the EJB to SOAP over HTTP using JAX-WS.

    Providing two bindings to the EJB gives clients the choice of SOAP bindings to call the web service. It also provides clients with the means to query the Web server to obtain its WSDL, using HTTP.

    The steps to bind an EJB to SOAP over HTTP are not included as part of the task.

  6. Implement and redeploy StockQuoteAxis using the sample StockQuoteAxis.java
    1. In the Enterprise Explorer navigator, open the folder W3CJMSEJB > Services Double-click StockQuoteAxisService to open the implementation class in a Java editor.
    2. Open the StockQuoteAxis.java sample program in the WebSphere MQ Installation directory\tools\soap\samples\java\server folder> Select all the methods, but not the class name > Copy.
    3. In StockQuoteAxisSoapBindingImpl.java select all the methods, but not the class name, and paste in the methods from StockQuoteAxis.java.
    4. Add a print statement to output to the WebSphere Application Server console when the service is called. Change the getQuote(String symbol) method: 
      public float getQuote(String symbol) {
System.out.println("StockQuoteAxisSoapBindingImpl called with symbol: "
+ symbol);
return ((float) 55.25);
    5. Correct the imports: Source > Organize imports > Save.
    6. Correct the three errors due to the implementation not matching the interface.

      The errors are due to three of the methods in StockQuoteAxis.java throwing exceptions, and the WSDL for the service not containing any fault messages. The problem is diagnosed as being a mismatch between the method signatures and the method web service annotations.

      Either annotate the methods with @WebFault and regenerate the WSDL, or keep the interface unchanged, and remove the exceptions.

      To keep the interface the same, remove the three throws exception from the method signatures > Save.


What to do next

Deploying to an Axis2 client using W3C SOAP over JMS