Home | Download | 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>``/javaeetutorial5/examples/jaxws/helloservice/` and the client is in `<INSTALL>``/javaeetutorial5/examples/jaxws/simpleclient/`.

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

> Figure 15-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 or service endpoint implementation (SEI) is a Java interface or class, respectively, that declares the methods that a client can invoke on the service. An interface is not required when building a JAX-WS endpoint. The web service implementation class implicitly defines a SEI.

> You may specify an explicit interface by adding the `endpointInterface` element to the `WebService` annotation in the implementation class. You must then provide a interface 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 that connect a web service client to the JAX-WS runtime. For reference documentation on `wsgen`, see the Application Server man pages at `http://docs.sun.com/`.

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

> 1. Code the implementation class.
> 2. Compile the implementation class.
> 3. Use `wsgen` to generate the artifacts required to deploy the service.
> 4. Package the files into a WAR file.
> 5. Deploy the WAR file. The web service artifacts (which are used to communicate with clients) are generated by the Application Server during deployment.
> 6. Code the client class.
> 7. Use `wsimport` to generate and compile the web service artifacts needed to connect to the service.
> 8. Compile the client class.
> 9. 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 implicitly 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 JAXB-compatible parameters and return types. See Default Data Type Bindings (page 512).
> - 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 and Packaging the Service

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

>     ant

> This command calls the `default` target, which builds and packages the application into an WAR file, `helloservice.war`, located in the `dist` directory.

> ### Deploying the Service

> You deploy the service using `ant`.

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

> #### Deploying the Service

> To deploy the `helloservice` example, follow these steps:

> 1. In a terminal window, go to `<``INSTALL``>/javaeetutorial5/examples/jaxws/helloservice/`.
> 2. Make sure the Application Server is started.
> 3. Run `ant 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:

>     ant undeploy

> ##### The all Task

> As a convenience, the `all` task will build, package, and deploy the application. To do this, enter the following command:

>     ant all

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

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

> `http://localhost:4848/`

> 2. Enter the admin username and password to log in to the Admin Console.
> 3. Click Web Services in the left pane of the Admin Console.
> 4. Click `Hello`.
> 5. Click Test.
> 6. Under Methods, enter a name as the parameter to the `sayHello` method.
> 7. Click the `sayHello` button.

> This will take you to the `sayHello` Method invocation page.

> 8. 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 port, a local object that acts as a proxy for the remote service. The port 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 port, the client performs these steps:

> 1. 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;`

> 2. 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.

> 3. 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/java` 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 `helloservice`, as described in "Deploying the Service." Then navigate to `<``INSTALL``>/examples/jaxws/simpleclient/` and do the following:

>     ant

> This command calls the `default` target, which builds and packages the application into a JAR file, `simpleclient.jar`, located in the `dist` directory.

> The run the client, do the following:

>     ant run