How to make a JAX-WS

In this demo we will make a Calculator JAX-WS service in Eclipse. I will make two
Java projects in Eclipse: one for the service and one for the client.
This demo is separated in three parts:
1. Create a Service
2. Test your service http://localhost:8080/WS/Calculator?wsdl
3. Create a Client

Let Java generate a proxy automatically based on the wsdl

Call proxy methods to call the service!

4. Monitoring the exchange of SOAP messages between the client and the
service

1. Create a JAX-WS Service

In Eclipse, create a new Java project (for example, JAXWSService). This will be
the project for the service. In order to make a working service, we need to do
three things:
1.

Create the service interface

2.

Implement the service interface

3.

Publish the service (start running it at some address, e.g.,

http://localhost:8080/WS/Calculator).

1.A Create the service endpoint (interface)

Add package to the project (e.g., examples.soapservice). Add interface Calculator
to the project. These will be the methods that the service will expose:
package examples.soapservice;
import javax.jws.*;

@WebService
public interface Calculator {
@WebMethod

SOA week 1 SOAP demo

Maja Pesic

public int add(int nr1, int nr2);

@WebMethod
public int substract(int nr1, int nr2);
}

1.B Implement the service endpoint

Add one class that will implement the Calculator interface:
package examples.soapservice;
import javax.jws.WebService;
@WebService(endpointInterface="examples.soapservice.Calculator")
public class MyCalculator implements Calculator {
@Override
public int add(int nr1, int nr2){
return nr1 + nr2;
}
@Override
public int substract(int nr1, int nr2){
return nr1 - nr2;
}
}

1.C Publish the service (start running it at some address,

e.g., http://localhost:8080/WS/Calculator).
Add one more class with a main method. Here you can specify the address of
your service and start it up.
package examples.soapservice;
import javax.xml.ws.Endpoint;
public class ServicePublisher {
public static void main(String[] args) {
Endpoint.publish("http://localhost:8080/WS/Calculator", new MyCalculator());
System.out.println("Running service on http://localhost:8080/WS/Calculator!");

}
SOA week 1 SOAP demo

Maja Pesic

2. Test your service (does it run?)

You can already test your service by requesting it to give you its wsdl. You do this
by typing this in in your Internet browser: http://localhost:8080/WS/Calculator?
wsdl. An XML description of your service is opened in your browser.
Take time to look at the wsdl file. You can find the description of methods add and
substract.

3. Create a Client for your JAX-WS Service

If you want to create a client for a service (e.g., your Calculator service), you
must be able to call the methods of the service in the client project. So, you have
to learn how to access services methods from the client.
import
import
import
import

java.net.URL; // standard JAVA class

javax.xml.namespace.QName; // standard JAVA class
javax.xml.ws.Service;
// standard JAVA class
examples.soapservice.Calculator; // interface from the SERVICE

public class JAXWSManualClient {

public static void main(String[] args) throws Exception {
Calculator calculator = // somehow connect to your service
int result = calculator.add(2,45)
System.out.println(result);
}
}

So, the problem is how to import all necessary interfaces (and maybe also some
classes) from the Service to your client project.
There are two ways to do this:
A. Include services interfaces and classes in your client project as an external
library (i.e., as a JAR file), which contains interfaces and classes that are
needed for communication with the service. If you include this library in
your client project, you can use librarys interfaces and classes to call the
methods of the service. This approach assumes that the service provider
made such a library and is willing to give it to you. For example, service
provider can put such a jar file on a website, so that you can download it.
In the sections below, this approach is described as Creating a Client with
the services library.
B. Sometimes the service provider does not offer a jar library. In that case,
you must only rely on the wsdl file , because this file is always available

SOA week 1 SOAP demo

Maja Pesic

(http://localhost:8080/WS/Calculator?wsdl), and it contains description of

all methods (and necessary data types) of the service. In this case, it is
necessary to parse this XML file in order to discover which methods to call,
which are necessary parameters, etc. This will take a lot of programming
work, and the result is not that big - you just want to be able to use the
following two lines of code:
Calculator calculator = // somehow connect to the SERVICE
int result = calculator.add(2,45);

Luckily, Java provides a simple tool called wsimport (find it in the BIN folder
of your JDK installation). When you call the wsimport tool you must give it
the URL of the wsdl (http://localhost:8080/WS/Calculator?wsdl) , and this
tool will automatically create several classes and interfaces for you based
in the wsdl file. You can use these interfaces and classes to call the
methods of the service (the two lines of code shown above). In the sections
below, this approach is described as Creating a Client with the wsimport
tool.

3.A Creating a Client with the services library

In Eclipse, create a new Java project (for example, JAXWSClientLib). This will be
the project for the client. Now you will have to add a jar library to this project.

Create a new folder in the Client project root called lib (next to the src
and bin). You will put the library (as a .jar file) in this folder.
Now go to your Service project to create the .jar file (the library). Select
interfaces (and classes) you want to put in the library and go to Export.
Choose, Java -> JAR file. Choose the name of the jar file (e.g.
CalculatorService.jar), browse to the location of your lib folder in the
client project and let Eclipse create the jar file there.
Now you have to add the reference to CalculatorService.jar in your
Client project. Choose Properties-> Java Build Path -> Libraries ->
Add External JARs and add the jar from the lib folder.

Now you can connect to and call the service as follows:

import
import
import
import

java.net.URL; // standard JAVA class

javax.xml.namespace.QName; // standard JAVA class
javax.xml.ws.Service;
// standard JAVA class
examples.soapservice.Calculator; // interface from the SERVICE

public class JAXWSManualClient {

public static void main(String[] args) throws Exception {
// using standard JAVA classes
URL url = new URL("http://localhost:8080/WS/Calculator?wsdl");
//1st argument service URI, refer to wsdl document 1st line
//2nd argument is service name, refer to wsdl document 1st line
QName qname = new QName("http://soapservice.examples/", "MyCalculatorService");
Service service = Service.create(url, qname);
// here you are using the interface Calculator from the SERVICE

SOA week 1 SOAP demo

Maja Pesic

Calculator calculator = service.getPort(Calculator.class);

int result = calculator.add(2,45)
System.out.println(result);
}
}

The calculator service uses only standard types (int). Sometimes the service
methods will use complex types as parameters or return values. For example, the
service could have a method Person findPerson(int personID). Class Person is
made in the Service project. In this case, you will have to select both the service
interface and class Peron while creating the jar file in the Service project (second
step).

3.B Creating a Client with the wsimport tool

In Eclipse, create a new Java project (for example, JAXWSClientWsimport). This
will be the project for the client. Now you will have to call the wsimport tool in
order to create necessary classes in your client project:

First publish (start up) your service. The wsimport tool will request the wsdl
file from the service, so the service must be up and running.

In order to be able to execute the wsdimport tool from anywhere on your hard
disc, you must add this tool to the PATH My Computer-> Properties ->
Advanced System Settings->Environment Variables -> System
variables. Find variable Path and add the path to your wsimpirt tool ad the
end of the existing path (do not remove existing applications from the
Path!!!). For example, add ;c:\Program Files\Java\jdk1.7.0_67\bin\ to the
existing Path.

Execute the wsimport tool:

1. From Command Prompt. Go to the source folder of your client project,
and type in this command:
wsimport -keep http://localhost:8080/WS/Calculator?wsdl

2. Create a ImportServiceRefrence.bat file in your Eclipse client project

with these commands:
cd d:\School\SOA\EclipseWorkspace\ JAXWSClientWsimport\src\
wsimport -keep http://localhost:8080/WS/Calculator?wsdl
pause

to see/edit the content of the .bat file > Open with Text editor
to execute the .bat file > Open with System editor.

Once you execute the wsimport tool, you can see that several classes and
interfaces are added to your client project (make sure to first Refresh the
project!).

SOA week 1 SOAP demo

Maja Pesic

SOA week 1 SOAP demo

Maja Pesic

Now you can call the service as follows:

package myclient;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.handler.MessageContext;
import examples.soapservice.Calculator;
import examples.soapservice.MyCalculatorService;
import examples.soapservice.Poruka;
public class JAXWSClientWsimport {
public static void main(String[] args) {
MyCalculatorService calculatorService = new MyCalculatorService();
Calculator calculator = calculatorService.getMyCalculatorPort();
int result = calculator.add(6, 7);
System.out.println(6 + 7 = " + result);
result = calculator.add(100, 5);
System.out.println(100 + 5 = " + result);
}
}

4. Monitoring the exchange of SOAP messages between

the client and the service
Originally, the Service is published at port 8080, and all communication between
the service and the client (exchange of SOAP messages) goes through this port.

service

client

8080

Eclipse has a tool for monitoring exchanging text messages on a specific port: the
TCP/IP Monitor tool. You can use this tool to see the SOAP messages that are
exchanged between the service and the client. If your client sends all its requests
to the port of the TCP/IP Monitor, then this tool will:
1.
2.
3.
4.

Show the SOAP message of the clients request;

Forward the SOAP message to the service;
Receive the SOAP message of the services reply, and
Forward the SOAP message of the services reply to the client.

service

8080

SOA week 1 SOAP demo

9000
TCP/IP Monitor

Maja Pesic

client

This tool can be found in Eclipse menu Window -> Show View > Debug
-> TCP/IP Monitor. The right view should be shown at the bottom of your
Eclipse screen (next to Console, Problems, Debug, etc.).

You will have to add a new monitor for your service by clicking on the
Properties in the pop-up menu. First you should setup the port of the monitor,
and then the host and port of the service. Also, it is important to change the
client the client should no longer send its request to the service port (8080), but
to the monitor (9000).

SOA week 1 SOAP demo

Maja Pesic