Movatterモバイル変換

Creating a Simple Web Service and Client with JAX-WS

This section shows how to build and deploy a simple web service andclient. The source code for the service is intut-install/javaeetutorial5/examples/jaxws/helloservice/ and theclient is intut-install/javaeetutorial5/examples/jaxws/simpleclient/.

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

Figure 16-1 Communication between a JAX-WS Web Service and a Client

Diagram showing a client and web service communicating through a SOAP message.

The starting point for developing a JAX-WS web service is a Javaclass annotated with thejavax.jws.WebService annotation. The@WebService annotation defines the class as aweb service endpoint.

Aservice endpoint interface orservice endpoint implementation (SEI) is a Java interface or class, respectively, thatdeclares the methods that a client can invoke on the service. Aninterface is not required when building a JAX-WS endpoint. The web service implementation classimplicitly defines an SEI.

You may specify an explicit interface by adding theendpointInterface element tothe@WebService annotation in the implementation class. You must then provide an interfacethat defines the public methods made available in the endpoint implementation class.

You use the endpoint implementation class and thewsgen tool to generate the webservice artifacts that connect a web service client to the JAX-WS runtime.

Together, thewsgen tool and the Application Server provide the Application Server’s implementationof JAX-WS.

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

Code the implementation class.
Compile the implementation class.
Usewsgen to generate the artifacts required to deploy the service.
Package the files into a WAR file.
Deploy the WAR file. The web service artifacts (which are used to communicate with clients) are generated by the Application Server during deployment.
Code the client class.
Usewsimport to generate and compile the web service artifacts needed to connect to the service.
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 thejavax.jws.WebService orjavax.jws.WebServiceProvider annotation.
The implementing class may explicitly reference an SEI through theendpointInterface element of the@WebService annotation, but is not required to do so. If noendpointInterface is 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 declaredstatic orfinal.
Business methods that are exposed to web service clients must be annotated withjavax.jws.WebMethod.
Business methods that are exposed to web service clients must have JAXB-compatible parameters and return types. SeeDefault Data Type Bindings.
The implementing class must not be declaredfinal and must not beabstract.
The implementing class must have a default public constructor.
The implementing class must not define thefinalize method.
The implementing class may use thejavax.annotation.PostConstruct orjavax.annotation.PreDestroy annotations on its methods for life cycle 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 serviceendpoint using the@WebService annotation.Hello declares a single method namedsayHello, annotatedwith the@WebMethod annotation.@WebMethod exposes the annotated method to web serviceclients.sayHello returns a greeting to the client, using the name passedtosayHello to compose the greeting. The implementation class also must define adefault, public, no-argument constructor.

package helloservice.endpoint;import javax.jws.WebService;@WebServicepublic class Hello {    private String message = new String("Hello, ");    public void Hello() {}    @WebMethod    public String sayHello(String name) {        return message + name + ".";    }}

Building, Packaging, and Deploying the Service

You can build, package, and deploy thehelloservice application using either NetBeans IDEorant.

Building, Packaging, and Deploying the Service Using NetBeans IDE

Follow these instructions to build, package, and deploy thehelloservice example toyour Application Server instance using NetBeans IDE.

In NetBeans IDE, select File→Open Project.
In the Open Project dialog, navigate totut-install/javaeetutorial5/examples/jaxws/.
Select thehelloservice folder.
Select the Open as Main Project check box.
Click Open Project.
In the Projects tab, right-click thehelloservice project and select Undeploy and Deploy.

This builds and packages to application intohelloservice.war, located intut-install/javaeetutorial5/examples/jaxws/helloservice/dist/, and deploysthis WAR file to your Application Server instance.

Building, Packaging, and Deploying the Service Using Ant

To build and packagehelloservice using Ant, in a terminal window, go tothetut-install/javaeetutorial5/examples/jaxws/helloservice/ directory and type the following:

ant

This command calls thedefault target, which builds and packages the application intoan WAR file,helloservice.war, located in thedist directory.

To deploy thehelloservice example, follow these steps:

In a terminal window, go totut-install/javaeetutorial5/examples/jaxws/helloservice/.
Make sure the Application Server is started.
Runant deploy.

You can view the WSDL file of the deployed service by requestingthe URLhttp://localhost:8080/helloservice/hello?WSDL in a web browser. Now you are ready to create aclient that accesses this service.

Undeploying the Service

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

ant undeploy

The`all` Task

As a convenience, theall 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 ofa web service endpoint. To test thesayHello method ofHelloService, do thefollowing:

Open the Admin Console by typing the following URL in a web browser:
```
http://localhost:4848/
```
Enter the admin user name 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 thesayHello method.
Click thesayHello button.
This will take you to thesayHello 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 thesayHello method ofHelloService. Itmakes this call through a port, a local object that acts asa proxy for the remote service. The port is created at development timeby thewsimport tool, which generates JAX-WS portable artifacts based on aWSDL file.

Coding the Client

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

Uses thejavax.xml.ws.WebServiceRef annotation to declare a reference to a web service.@WebServiceRef uses thewsdlLocation 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 invokinggetHelloPort on the service.
```
Hello port = service.getHelloPort();
```
The port implements the SEI defined by the service.
Invokes the port’ssayHello method, passing to the service a name.
```
String response = port.sayHello(name);
```

Here is the full source ofHelloClient, which is located in thetut-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

You can build and run thesimpleclient application using either NetBeans IDE orant. To build the client, you must first have deployedhelloservice, as described inBuilding, Packaging, and Deploying the Service.

Building and Running the Client in NetBeans IDE

Do the following to build and runsimpleclient:

In NetBeans IDE, select File→Open Project.
In the Open Project dialog, navigate totut-install/javaeetutorial5/examples/jaxws/.
Select thesimpleclient folder.
Select the Open as Main Project check box.
Click Open Project.
In the Projects tab, right-click thesimpleclient project and select Run.

You will see the output of the application client in the Outputpane.

Building and Running the Client Using Ant

In a terminal navigate totut-install/examples/jaxws/simpleclient/ and type the following command:

ant

This command calls thedefault target, which builds and packages the application intoa JAR file,simpleclient.jar, located in thedist directory.

The run the client, type the following command:

ant run