Developing JAX-RPC Web Services for WebSphere

1. Create a Web Service Project

You can download the sample project created in this turorial. The sample is configured to run against WebSphere 6.1. You may need to adjust the target  server and/or the runtime JRE libraries used to build the projects to more closely match your particular build and deployment environment.

1. Click the drop-down arrow , and select Web Service Project.
   
   Opening a new web service projectNote: A JAX-RPC web service can be created in any existing Web project.
2. Type WebServiceProject as the project name, select the JAX-RPC framework option, and select your WebSphere version from the Target runtime drop-down.
   
   You might receive a warning if you haven’t yet configured the WebSphere connector; you can do this later. Click Finish. 
   
   Note: This tutorial uses the default JavaEE 6 version; however, JavaEE 7 is an available option when creating new projects.
   New Web Service Project window

Now that you have a new web project, you can create the Java class to use as the basis of your web service.

2. Create a Service Class

The service class is nothing more than a plain Java class that provides implementations for the methods you want to expose as web service. In this tutorial, you will write a simple Calculator class that implements a few typical calculator operations.

1. Expand the WebServiceProject folder in the Explorer, and right-click the src folder. Select New>Package.
   
   
   Creating a package for the class
2. Type com.myeclipseide.ws in the Name field, and click Finish.
   
   New Java Package window
3. Right-click the com.myeclipseide.ws package, and select New>Class.
4. Type Calculator in the Name field, and click Finish. This creates a Calculator.java file in the package.
   
   New Java Class window

Calculator.java opens in the editor.

This class is a calculator implementation that provides the following functions for two integers:

• add
• subtract
• multiply
• divide

This class is a very simple POJO offering four operations. There is no use of special annotations, interfaces, or base classes.  Copy the following code, paste it into your class file between the brackets, and click .

 public int add(int a, int b) { 
                     return (a + b); 
                 } 

 public int subtract(int a, int b) { 
                      return (a - b); 
                 } 

 public int multiply(int a, int b) { 
                      return (a * b); 
                 } 

 public int divide(int a, int b) { 
                      return (a / b); 
                 } 

3. Create a Web Service

Now that you have the service class written (Calculator.java), you need to create a web service that exposes that server class as a web service.

1. Click .
2. Select the Create web service from Java class (Bottom-up scenario) option.
   
   New web service creation strategyThe bottom-up web service generation uses the target server to generate the correct stub and implementation classes for the web service you are hosting from that particular application server.
   
   If you have not set a target server or if you haven’t yet configured WebSphere, click the Configure target server link.
   
   The project Properties window opens allowing you to set the targeted runtimes. You can open the project properties to change the targeted runtime at any time.
   
   Setting the target serverNote: If you have not configured the WebSphere connector, it will not be listed as a targeted runtime, and service generation will not be possible. Refer to WebSphere Connectors in MyEclipse.
3. After the target runtime is set, click OK.
4. Click Next to continue creating the web service. Select the implementation type for the web service. In this case, select Implementation class, type com.myeclipseide.ws.Calculator in the Service impl class field, and click Finish.
   
   Setting the web service classMyEclipse generates the web service stubs and binding classes necessary for this web service to be deployed to the target application server set in the first step.
5. Check your project contents to view the artifacts generated for you so the web service can be deployed to the target server.
   
   Generated artifacts

4. Deploy the Project

1. Right-click the project, and select Debug As (or Run As)>MyEclipse Server Application.
2. 
   Debugging as a server application
3. Select the server to which you want to deploy your web project. In this case, select your WebSphere server, and click Finish.
   
   Selecting the server for deployment

MyEclipse performs the following steps automatically:

• Packages the web project and deploys it as an Exploded type (as opposed to the Packaged type) to the application server.
• Starts the application server and loads the web project.

5. Connect to the Web Service to Test

1. Load the Web Services explorer by clicking .
2. Click on the Web Services explorer toolbar, and click the WSDL Main link to open the Open WSDL page.
   
   Opening the WSDL page
3. Type http://localhost:9080/WebServiceProject/services/Calculator?WSDL in the WSDL URL field, and click Go.
   
   The URL is broken down into the following components:
   
   http://localhost:9080 — The server is running on localhost, and the port it has been binding the web projects to is the default port of 9080. To confirm this, you can watch the Console view while the server deploys a new web project. It displays the ports it binds the web project to as it deploys it.
   
   /WebServiceProject — By default, the Web Context-root used to deploy a web project matches the name of the project. Because we didn’t customize the Web Context-root for this project, it is the same name as the project.
   
   /services/Calculator — As shown in the screenshot in Section 3, when the JAX-RPC web service was generated, it was bound using a servlet-mapping in the web.xml file to the /services/Calculator path.
   
   ?WSDL — This is a universal query string argument that, when added to the end of a web service, tells the web service to return its full WSDL to the caller. In this case, the WSDL is returned to the Web Services Explorer tool, which loads it and displays the web services exposed operations.
   
   The Web Services Explorer loads all the operations exposed to us from this web service.
   
   Web service exposed operations
4. To test the web service, click the Add operation in the Navigator to use the explorer to test it. The Invoke a WSDL Operation page appears in the Explorer. The page displays the endpoint you are testing (Calculator), and each argument the operation takes along with a field for entering test values.
5. Type the values 10 and 20 in the a and b fields, respectively, and click Go.
   
   Testing the add operation

The Status displays the response from the web service, which in this case is 30.

6. Create a Client for the Web Service

The web service client allows you to interact directly with the web service and its exposed operations without writing all the marshaling or connection code.

In MyEclipse, while you are generating a web service, you are given the option to generate a client for the web service at the same time. You can use this feature any time, but for this tutorial we felt a more typical situation is needing to create a web service client against a service that has already been deployed rather than one you are generating.

In this section, you generate a web service client in a separate Java project because the web service is already deployed and you want to hook up to it. This keeps the lines between web service and web service client creation very clearly separated for this tutorial.

1. Click the drop-down arrow , and select Java Project.
2. Type WebServiceClientProject in the Project name field, and click Finish.
   New Java Project window
3. Click the drop-down arrow , and select New Web Service Client.
4. Select your Web Service Client project from the Project drop-down, select the JAX-RPC framework option, and select your WebSphere server as the Target Server. This provides the web service generation services that MyEclipse invokes to create your JAX-RPC client. Click Next.
   
   Creating a new web service client
5. Be sure the WSDL URL option is selected, and type http://localhost:9080/WebServiceProject/services/Calculator?WSDL in the WSDL URL field.
   
   You can use the namespace to package mapping list to customize the packages generated based on the namespaces defined in the source WSDL file. If you don’t specify a mapping, the generation tools choose an appropriate default.
   
   Specifying the WSDL URL for the client
6. Click Next. MyEclipse loads the WSDL for the web service validates it for you, letting you know of any problems that might exist with the WSDL.
   
   Note: If any error occurs with validation, be sure the web service is deployed and the application server hosting it is running. If you are trying to generate a client to a 3rd party web service and you get errors during the validation process, bring it to the attention of the author of the web service, if possible, so it can be corrected.
   
   Validation status
7. Click Finish to have MyEclipse generate the client for you.

After the client has been generated, a new package appears in your src folder as well as a few new classes you can use to work with your web service.

With the new generated resources you can use the CalculatorServiceLocator class to access a reference to the web service and then execute the operations you exposed (add, subtract, multiply and divide).

As an example say you want to compute the following 4 things:

• Add 3 and 7
• Subtract 2 from 12
• Multiply 9 by 9
• Divide 40 by 2

6.1 Using the Web Service Operations

In this example, add code that uses the operations from the web service to make these calculation. First, you need to create a new class with a main method in it.

1. Right-click the com.myeclipseide.ws package, and select New>Class.
2. Name it WebServiceClient, select the Public static void main checkbox, and click Finish.
   
   New Java class to contain the main methodAfter you create the class, you need to provide an implementation of the main method so it does the four mathematical calculations listed listed above. The code to perform those calculations with the web service and then print the results to the console is as follows:
   
   

   package com.myeclipseide.ws;
   import java.rmi.RemoteException;
   import javax.xml.rpc.ServiceException;
   
   public class WebServiceClient {
   
    public static void main(String[] args) throws ServiceException,     RemoteException { 
          /* Create a locator instance */ 
         CalculatorServiceLocator locator = new CalculatorServiceLocator();
         /* Get access to the service using the locator */
          Calculator_SEI calculator = locator.getCalculator();
         /* Using the web service, perform the 4 calculations */
          System.out.println("1. 3+7=" + calculator.add(3, 7)); 
         System.out.println("2. 12-2=" + calculator.subtract(12, 2)); 
         System.out.println("3. 9*9=" + calculator.multiply(9, 9)); 
         System.out.println("4. 40/2=" + calculator.divide(40, 2));       } 
   }

   Note: The reason for defining the main method to throw the ServiceException and RemoteException is to avoid having try-catch blocks in the main method implementation. In the case of writing a real client, catching and handling the exceptions can be an important part of writing good code.

3. Replace the default code in the Java class file with the code shown above, and click .
   
   Code for the main method in the new Java class

4. Run the class by right-clicking it, and selecting Run As (or Debug As)>Java Application.
   
   Running the class as a Java application

The client code runs, accesses the web service using the locator class generated for it, and then the following output appears in the console: