Developing JAX-RPC Web Services for WebSphere

Introduction
System Requirements
Creating a Project
Creating the Service Class
Creating a Web Service
Deploying & Testing the Web Service
Creating a Client for the Web Service
Resources
Feedback

1. Introduction

This document will outline the process of developing a JAX-RPC web service and deploying it to WebSphere using MyEclipse Blue. The web service used in this tutorial will be a very simple calculator service that provides add, subtract, multiply and divide operations to the caller.

MyEclipse Blue also supports developing web services using both the existing XFire framework from previous MyEclipse releases as well as the new, and preferred, Java EE 5 web service specification: JAX-WS.

Additional resources covering web service creation using JAX-RPC, JAX-WS or XFire are included in the Resources section of this document.

2. System Requirements

This tutorial was created with MyEclipse Blue Edition 6.1. If you are using another version of MyEclipse Blue Edition (possibly newer), most of these screens and instructions should still be very similar.

If you are using a newer version of MyEclipse and notice portions of this tutorial looking different than the screens you are seeing, please let us know and we will make sure to resolve any inconsistencies.

3. Creating a Project

To get started we will create a simple Web Service Project by selecting Web Service Project from the new toolbar menu:

Note: A JAX-RPC web service can also be created in any existing Web Project.

Name the project WebServiceProject and select WebSphere 6.1 from the Target server combo; you may be warned if you haven't yet configured the WebSphere 6.1 connector, you can do this later. After you are done you can click Finish:

Now that we have created the web project, we can now create the simple Java class that we will use as the basis of our web service.

4. Creating the Service Class

The service class is nothing more than a simple plain Java class that will provide implementations for the methods we want to expose as web service. In this particular tutorial we are going to write a simple 19-line Calculator class that implements a few typical operations found on a calculator.

Let's first create a package for our new class under our Source directory by right-clicking on the Source directory and selecting New > Package:

The package name we are going to use for this tutorial is com.myeclipseide.ws:

As mentioned above, this simple class is a calculator implementation that provides the functions:

add
subtract
multiply
divide

For any 2 ints. The implementation of the class looks like:


											package com.myeclipseide.ws;
											

											

											public class Calculator {
											

											    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);
											

											    }
											

											}

Calculator class implementation

As you can see from the source code, this class is a very simple POJO offering 4 operations. There is no use of special annotations, interfaces or base classes.

5. Creating a Web Service

Now that we have our service class written ( Calculator.java) we need to create a web service that exposes that server class as a web service. To do that we start by clicking the New Web Service toolbar button:

On the next screen in the Strategy section, select the Bottom-up scenario. The web service generation uses the target server to generate the correct stub and implementation classes for the web service you will be hosting from that particular application server.

If you have not already set a target server or if you haven't configured WebSphere 6.1 yet, click the Configure Target Server link to do it:

After clicking the configure link a dialog will popup asking you to set the Target Server. You may have noticed that the dialog that popped up is actually your project properties dialog, as the target server is a project property that can be set at any time:

Note: If you have not configured the WebSphere 6.1 connector, you will not see it in the Target server combo and service generation will not be possible. Please refer to the WebSphere tutorial in the Resources section for configuration instructions.

After the Target Server is set, click OK and then click Next to continue onto the next step of the web service creation.

This is the last screen of the web service wizard. On this screen you have to select the implementation type for the web service, in our case it will be the single implementation class and then the name of the class has to be specified:

Once you set the Service impl class, MyEclipse Blue will automatically fill out the remainder of the wizard fields for you. Of course you are welcome to customize or adjust them if you want, but in this case we are going to leave them all the way they are and hit Finish.

After clicking Finish MyEclipse Blue will generate 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:

Checking your project contents will show you all the artifacts that have been generated for you in order for that web service to be deployable to the target server:

Now that our web service is created, we are ready to deploy it and test it out.

6. Deploying & Testing the Web Service

The first step of testing our web service to make sure it works will be to deploy it to our application server (WebSphere 6.1 in this case) and test it using the Web Service Explorer.

The fastest way to deploy our web service is to deploy our web project using the Run As or Debug As action of MyEclipse Server Application. We can do that by right-clicking on our project, going down to Debug As (or Run As) and selecting MyEclipse Server Application:

Then MyEclipse Blue will ask you wish server, that you have configured would you like to deploy your web project to. In this tutorial we select WebSphere 6.1:

After hitting Finish, MyEclipse Blue will perform the following steps for us automatically:

Package our web project, and deploy it in Exploded format to the application server we chose.
Start the application server for us, loading our web project

Now we are ready to connect to the web service and test it out.

The first thing we need to do is load the Web Services Explorer from the toolbar by clicking it's button:

After the Web Services Explorer is loaded, we want to click on the WSDL mode button, then click on WSDL Main to open the Open WSDL screen. Then we want to enter the URL for our web service WSDL which is:

http://localhost:9081/WebServiceProject/services/Calculator?WSDL

NOTE: The default WebSphere port is 9080, if the URL above doesn't work for you, try changing the port from 9081 to 9080 and try again.

We can break the URL down into the following components to understand how we arrived at that URL:

http://localhost:9081 = We know the server is running on localhost, and we know the port it has been binding our web projects to is 9081. To confirm this, you can watch the Console view while the server deploys a new web project, it will print out the ports it binds the web project to as it deploys it. The default WebSphere port is 9080, if the URL above doesn't work for you, try changing the port from 9081 to 9080 and try again.
/WebServiceProject = We know by default the Web Context-root that is used to deploy web projects matches the name of the projects. Since we didn't customize our Web Context-root for this project, it will be the same name as our project.
/services/Calculator = As we saw from the last screenshot in Section #5, when our 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 can be added to the end of any web service which will tell the web service to return it's full WSDL to the caller. In this case, the WSDL is returned to our Web Services Explorer tool which loads it up, and displays the web services exposed operations to us.

Now the Web Services Explorer will load up all the operations exposed to us from this web service and display them to us:

For the purposes of testing this web service, we can click one of the operations to use the explorer to test them. Let's click the add operation.

Now we are shown the Invoke a WSDL Operation screen. We are shown the endpoint we are going to test ( Calculator) and each argument the operation takes along with a field to enter values for each operation.

Enter the values "10" and "20" to add, then click Go:

After clicking Go, down in the Status view you'll see the response from the web service, which in this case was "30", and is correct.

Now that we tested our web service, and it works, let's close the Web Services Explorer and move onto the next step... creating a web service client!

7. Creating a Client for the Web Service

Now that we have deployed our web service and tested it, we will use MyEclipse Blue to generate a web service client for us. The web service client will allow us to interact directly with the web service and all it's exposed operations without needing to write all the marshalling or connection code ourselves.

In MyEclipse Blue, while you are generating your web service, you are given the option to generate a client for that web service at the same time. You are certainly welcome to use that feature any time you wish, but for the purposes of this tutorial we felt a more typical situation you might find yourself in, is needing to create a web service client against a service that has already been deployed and not one you are generating. Because of this, in this section we will generate the web service client in a separate Java Project, as if this web service were already deployed and we just wanted to hook up to it. This will keep the lines between web service and web service client creation very clearly separated for this tutorial, which we hope makes the topic easier to learn.

Anyway, as we mentioned the first step to create the web service client will be to create a new Java Project to put the code into. We will do that by clicking the new toolbar button, then clicking Java Project:

Now give your project a name and click Finish:

After the project has been created, we now want to create a new Web Service Client. Select New Web Service Client from the web service toolbar menu:

In the New Web Service Client wizard select WebSphere 6.1 as the Target Server. This provides the web service generation services that MyEclipse Blue will invoke to create your JAX-RPC client.

In this tutorial we will also be selecting the JAX-RPC framework for our web service client, but you are certainly free to generate any other kind of client you wish:

The last step of the web service client creation is to specify either a WSDL File or a WSDL URL for the wizard to retrieve the web service WSDL from. In our case we are using the URL:

http://localhost:9081/WebServiceProject/services/Calculator?WSDL

NOTE: The default WebSphere port is 9080, if the URL above doesn't work for you, try changing the port from 9081 to 9080 and try again.

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 will choose an appropriate default.

Now MyEclipse Blue will load the WSDL for the web service you are attempting to create a client for and validate it for you, letting you know of any problems that may exist with the WSDL:

NOTE: If any error occurs with validation, make 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 get errors during the validation process, please bring it to the attention of the author of the web service if possible so it can be corrected.

Once the validation process is done, click Next to review the libraries that will be added to your project's build path :

Now you can click Finish to have the client generated for you:

After the client has been generated for you, you'll notice a new package in your Source folder as well as a few new classes that you can use to work with your web service:

With the new generated resources we can utilize the CalculatorServiceLocator class to access a reference to our web service and then execute the operations that we exposed for it ( add, subtract, multiply and divide).

In this tutorial let's write some code that uses the different operations from our web service. As an example let's say we want to compute the following 4 things:

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

First we will want to create a new class, with a main method in it. Just as we did before, we create a new class, give it the name WebServiceClient and tell MyEclipse Blue to generate a main method for us:

After our class is generated for us, we need to provide an implementation of the main method so that it does the 4 mathematical calculations we listed above. The code, for the entire main method, to do those calculations with our web service and then print the results to the console is as follows:


											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));
											

											}

Web service client main method code

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.

Now that our main method is written, we can run it.

Before we run this new class we just wrote, we need to adjust the JRE used to build and run this new Java Project to match the same runtime used for the application server we are deploying to (WebSphere 6.1 in this case).

To do this, right-click on the WebServiceClientProject project and go down to Properties:

Then click on the Java Build Path preference node, click the Libraries tab, and then select the "myeclipse" JRE and click Remove:

Then click Add Library..., select JRE System Library and click Next:

And then select Alternative JRE then click the dropdown and be sure to select the JDK configured to run your application server (WebSphere 6.1 in this case) then click Finish:

After you have completed those steps and the web service client project is setup to run with the same JRE (or JDK) used to launch your application server, you can finally run this class by right-clicking on it, going down to Run As (or Debug As) and selecting Java Application:

When we do that, our client code runs, accesses our web service using the locator class generated for it and then we get the following output in our console:

Console output from the web service client

And that's all there is to generating and using web service clients for JAX-WS, JAX-RPC or XFire web services using MyEclipse Blue.

8. Resources

In this section we want to provide you with additional links to resources that supplement the topics covered in this tutorial. While this is not an exhaustive list, we do make an effort to point to the more popular links that should provide you with diverse, high-quality information.

Example Web Service Project & Web Service Client Project

NOTE: The example projects provided are 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.

9. Feedback

We would like to hear from you! If you liked this tutorial, has some suggestions or even some corrections for us please let us know. We track all user feedback about our learning material in our Documentation Forum. Please be sure to let us know which piece of MyEclipse material you are commenting on so we can quickly pinpoint any issues that arise.