MyEclipse Logo
 

Developing JAX-WS Web Services & Clients Tutorial

Table of Contents
download the latest MyEclipse version

help and support
 

1. Introduction

This document will outline the process of developing a JAX-WS web service and deploying it using MyEclipse to the internal MyEclipse Tomcat server. 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 also supports developing web services using the existing XFire framework from previous MyEclipse releases. For folks needing to develop and deploy WebSphere JAX-RPC or WebSphere JAX-WS web services, please take a look at our MyEclipse Blue Edition of the MyEclipse IDE.

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. However, if you 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-WS web service can also be generated in any existing Java EE 5 web project.

Name the project WebServiceProject. Note that JAX-WS support is only available for Java EE 5 projects and later, if you need to use an older project type (J2EE 1.4 or 1.3) you must use the XFire Web Services support instead:

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 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:

Now we are going to create a new class, Calculator, in the new package we just created:

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 since we have our Calculator class already and want to generate a JAX-WS web service from it:

This is the last screen of the web service wizard. On this screen you have to select the Java bean that implements the operations for your web service, in our case it will be the single Calculator class that we wrote in the previous section:

Once you set the Java bean class, MyEclipse 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. Select Generate WSDL in project and hit Finish.

After clicking Finish MyEclipse will generate the JAX-WS delegate class as well as the necessary JAX-WS descriptor into the WEB-INF directory of your web project. MyEclipse will also modify the web.xml file to include the new web service mappings so you can deploy and use the web service.

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

JAX-WS is part of the Java EE 5 specification, if you are deploying your project to a full Java EE 5-compliant server, you should be ready to deploy your project right now without any further changes to the libraries. However, there are some common servers, like Jetty or Tomcat, that do not implement the entire Java EE 5 spec and will need the JAX-WS libraries deployed with your project in order to run.

IMPORTANT: In MyEclipse we have tried to make this process easier by including the JAX-WS RI (Metro 1.1) with our embedded MyEclipse Tomcat server, so your web services will run out of the box on MyEclipse Tomcat, but if you plan to deploy to an external server that does not provide the JAX-WS libraries, you will need to follow the steps below on how to augment your build path to include them (so they are deployed). You can also install the JAX-WS libraries directly into your application server's /lib directory ususally if you don't want to add the libraries directly to your project; please check your Application Server's documentation for more information regarding that.

If you do want to add the libraries to your project build path, please keep reading section 6.1, otherwise skip to section 6.2.


6.1 Adding JAX-WS Libraries to Your Build Path

First thing we need to do is open our project's Java Build Path > Libraries preference page by right-clicking on our project, and going to Properties, from there we want to click the Libraries button:

Now you want to click MyEclipse Libraries and hit Next, then scroll down and select both the JAX-WS library containers to be added to your project's build path:

So we end up wth something like the following:

Now we have the JAX-WS libraries in our project's build path, and they will be deployed along with our project to MyEclipse Tomcat.


6.2 Deploying and Running the JAX-WS Web Service

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:

If you have multiple server connectors configured, MyEclipse will ask you which one you want to use, for the purpose of this tutorial select MyEclipse Tomcat. If you don't have any connectors configured, MyEclipse Tomcat will be used automatically for you to deploy your project to and then run.

Now MyEclipse will perform the following steps for you automatically:

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

The MyEclipse Web Browser will popup and show you the default index.jsp page of our web app, we don't actually need this because we aren't testing a web page, so you can close this view.


6.3 Testing our JAX-WS Web Service

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:8080/WebServiceProject/CalculatorPort?WSDL

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

  • http://localhost:8080 = We know the server is running on localhost, and we know the default Tomcat port is 8080. 
  • /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 name.
  • /CalculatorPort = As we saw from the last screenshot in Section #5, when our JAX-WS web service was generated, it was bound using a servlet-mapping in the web.xml file to the /CalculatorPort 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 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.

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:

Now we select the project we want to generate the client into, and the type of client we want. In this case we are putting the client into the WebServiceClientProject we created and want it to be a JAX-WS client:

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 and generate the client into the new package com.myeclipseide.ws.client:

http://localhost:8080/WebServiceProject/CalculatorPort?WSDL

Now MyEclipse 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.

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 CalculatorDelegate 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:

  1. Add 3 and 7
  2. Subtract 2 from 12
  3. Multiply 9 by 9
  4. 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 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) {
    /* Create the service instance */
    CalculatorService service = new CalculatorService();
    CalculatorDelegate delegate = service.getCalculatorPort();

    /* Using the web service, perform the 4 calculations */
    System.out.println("1. 3+7=" + delegate.add(3, 7));
    System.out.println("2. 12-2=" + delegate.subtract(12, 2));
    System.out.println("3. 9*9=" + delegate.multiply(9, 9));
    System.out.println("4. 40/2=" + delegate.divide(40, 2));
}
Web service client main method code

Now that our main method is written, we can run it. Right-click on the WebServiceClient class we created, go down to Run As and select 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:

1. 3+7=10
2. 12-2=10
3. 9*9=81
4. 40/2=20
Console output from the web service client

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


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.

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.