Home | PDF | API | FAQ | Search | Feedback | History

Creating a Simple Web Service and Client with JAX-WS

This section shows how to build and deploy a simple web service and client. The source code for the service is in <INSTALL>/jwstutorial13/examples/jaxws/helloservice/ and the client is in <INSTALL>/jwstutorial13/examples/jaxws/simpleclient/.

Figure 1-1 illustrates how JAX-WS technology manages communication between a web service and client.

Figure 1-1 Communication Between a JAX-WS Web Service and a Client

The starting point for developing a JAX-WS web service is a Java class annotated with the javax.jws.WebService annotation. The WebService annotation defines the class as a web service endpoint.

A service endpoint interface (SEI) is a Java interface that declares the methods that a client can invoke on the service. An SEI is not required when building a JAX-WS endpoint. The web service implementation class implicitly defines a SEI.

You may specify an explicit SEI by adding the endpointInterface element to the WebService annotation in the implementation class. You must then provide a SEI that defines the public methods made available in the endpoint implementation class.

You use the endpoint implementation class and the wsgen tool to generate the web service artifacts and the stubs that connect a web service client to the JAX-WS runtime. For reference documentation on wsgen, see the Application Server man pages at .

Together, the wsgen tool and the Application Server provide the Application Server's implementation of JAX-WS.

These are the basic steps for creating the web service and client:

Code the implementation class.
Compile the implementation class.
Deploy the WAR file. The tie classes (which are used to communicate with clients) are generated by the Application Server during deployment.
Code the client class.
Use wsimport to generate and compile the stub files.
Compile the client class.
Run the client.

The sections that follow cover these steps in greater detail.

Requirements of a JAX-WS Endpoint

JAX-WS endpoints must follow these requirements:

The implementing class must be annotated with either the javax.jws.WebService or javax.jws.WebServiceProvider annotation.
The implementing class may explicitly reference an SEI through the endpointInterface element of the @WebService annotation, but is not required to do so. If no endpointInterface is not specified in @WebService, an SEI is implicityly defined for the implementing class.
The business methods of the implementing class must be public, and must not be declared static or final.
Business methods that are exposed to web service clients must be annotated with javax.jws.WebMethod.
Business methods that are exposed to web service clients must have JAX-B-compatible parameters and return types. See Default Data Type Bindings.
The implementing class must not be declared final and must not be abstract.
The implementing class must have a default public constructor.
The implementing class must not define the finalize method.
The implementing class may use the javax.annotation.PostConstruct or javax.annotation.PreDestroy annotations on its methods for lifecycle event callbacks.

The @PostConstruct method is called by the container before the implementing class begins responding to web service clients.

The @PreDestroy method is called by the container before the endpoint is removed from operation.

Coding the Service Endpoint Implementation Class

In this example, the implementation class, Hello, is annotated as a web service endpoint using the @WebService annotation. Hello declares a single method named sayHello, annotated with the @WebMethod annotation. @WebMethod exposes the annotated method to web service clients. sayHello returns a greeting to the client, using the name passed to sayHello to compose the greeting. The implementation class also must define a default, public, no-argument constructor.

package helloservice.endpoint;

import javax.jws.WebService;

@WebService()
public class Hello {
  private String message = new String("Hello, ");

  public void Hello() {}

  @WebMethod()
  public String sayHello(String name) {
    return message + name + ".";
  }
} 

Building the Service

To build HelloService, in a terminal window go to the <INSTALL>//examples/jaxws/helloservice/ directory and type the following:

The build task command executes these subtasks:

compile-service

The compile-service Task

Thisasant task compiles Hello.java, writing the class files to the build subdirectory. It then calls the wsgen tool to generate JAX-WS portable artifacts used by the web service. The equivalent command-line command is as follows:

wsgen -d build -s build -classpath build
    helloservice.endpoint.Hello 

The -d flag specifies the output location of generated class files. The -s flag specifies the output location of generated source files. The -classpath flag specifies the location of the input files, in this case the endpoint implmentation class, helloservice.endpoint.Hello.

Packaging and Deploying the Service

You package and deploy the service using asant.

Upon deployment, the Application Server and the JAX-WS runtime generate any additional artifacts required for web service invocation, including the WSDL file.

Packaging and Deploying the Service with asant

To package and deploy the helloservice example, follow these steps:

In a terminal window, go to <INSTALL>/javaeetutorial5/examples/jaxws/helloservice/.
Run asant create-war.
Make sure the Application Server is started.
Set your admin username and password in <INSTALL>/javaeetutorial5/examples/common/build.properties.
Run asant deploy.

You can view the WSDL file of the deployed service by requesting the URL http://localhost:8080/helloservice/hello?wsdl in a web browser. Now you are ready to create a client that accesses this service.

Undeploying the Service

At this point in the tutorial, do not undeploy the service. When you are finished with this example, you can undeploy the service by typing this command:

asant undeploy 

Testing the Service Without a Client

The Application Server Admin Console allows you to test the methods of a web service endpoint. To test the sayHello method of HelloService, do the following:

Open the Admin Console by opening the following URL in a web browser:

  http://localhost:4848/

Enter the admin username and password to log in to the Admin Console.
Click Web Services in the left pane of the Admin Console.
Click Hello.
Click Test.
Under Methods, enter a name as the parameter to the sayHello method.
Click the sayHello button.

This will take you to the sayHello Method invocation page.

Under Method returned, you'll see the response from the endpoint.

A Simple JAX-WS Client

HelloClient is a stand-alone Java program that accesses the sayHello method of HelloService. It makes this call through a stub, a local object that acts as a proxy for the remote service. The stub is created at development time by the wsimport tool, which generates JAX-WS portable artifacts based on a WSDL file.

Coding the Client

When invoking the remote methods on the stub, the client performs these steps:

Uses the javax.xml.ws.WebServiceRef annotation to declare a reference to a web service. WebServiceRef uses the wsdlLocation element to specify the URI of the deployed service's WSDL file.

@WebServiceRef(wsdlLocation="http://localhost:8080/
    helloservice/hello?wsdl")
static HelloService service;

Retrieves a proxy to the service, also known as a port, by invoking getHelloPort on the service.

Hello port = service.getHelloPort();

The port implements the SEI defined by the service.

Invokes the port's sayHello method, passing to the service a name.

String response = port.sayHello(name);

Here's the full source of HelloClient, located in the <INSTALL>/javaeetutorial5/examples/jaxws/simpleclient/src/ directory.

package simpleclient;

import javax.xml.ws.WebServiceRef;
import helloservice.endpoint.HelloService;
import helloservice.endpoint.Hello;

public class HelloClient {
  @WebServiceRef(wsdlLocation="http://localhost:8080/
      helloservice/hello?wsdl")
  static HelloService service;

  public static void main(String[] args) {
    try {
      HelloClient client = new HelloClient();
      client.doTest(args);
    } catch(Exception e) {
      e.printStackTrace();
    }
  }

  public void doTest(String[] args) {
    try {
      System.out.println("Retrieving the port from 
          the following service: " + service);
      Hello port = service.getHelloPort();
      System.out.println("Invoking the sayHello operation 
          on the port.");

      String name;
      if (args.length > 0) {
        name = args[0];
      } else {
        name = "No Name";
      }

      String response = port.sayHello(name);
      System.out.println(response);
    } catch(Exception e) {
      e.printStackTrace();
    }
  }
} 

Building and Running the Client

To build the client, you must first have deployed HelloServiceApp, as described in "Packaging and Deploying the Service with asant." Then navigate to <JAVA_EE_HOME>/examples/jaxws/simpleclient/ and do the following:

asant build 

The run the client, do the following:

asant run 

All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.