Chapter 11. Using Web Services

Table of Contents

11.1.1. Creating a Web Service in Java
11.1.2. Creating a Web Service From WSDL

11.2.1. Developing a Java SE Client

This chapter describes how to create a web service and client using JAX-WS 2.2, and how to call the web service.

11.1. Creating Web Services

JEUS 8 supports Java EE 7 web services, and JAX-WS 2.2 is the core functionality of the Java EE web services. JAX-WS replaces the existing JAX-RPC features. Since JAXB 2.2 and later versions fully support all XML schema types, Java to XML mappings can be well defined without having to rely on the JAX-RPC specification. In addition, a new web service model called Java Web Services 2.0, which includes SAAJ 1.3 that enables direct handling of SOAP 1.2 messages, has been added to JEUS.

11.1.1. Creating a Web Service in Java

Developing a Web service from an existing Java class involves:

Creating a service implementation bean that includes the web service annotations.

The following constraints apply when creating service implementation beans:
- javax.jws.WebService annotation must be included to indicate that the class is a service implementation bean.
- The arguments and the return type of web service methods must be compatible with the mapping definition between JAXB 2.0 and XML schema.
- The arguments and return type of a web service method should not implement the java.rmi.Remote interface directly or indirectly.
A method's arguments, return type, and binding method can be customized by using the annotations defined in the javax.jws package. The following example shows how to create a service implementation bean.

The sample web service implementation class is in the following path
```
JEUS_HOME/samples/getting_started/webservices/from_java/src/java/fromjava/server
```
[Example 11.1] <<AddNumbersImpl.java>>
```
package fromjava.server;

import javax.jws.WebService;

@WebService
public class AddNumbersImpl {
    public int addNumbers(int number1, int number2) {
        return number1 + number2;
    }
}
```
JAX-WS provides the convenience of developing a web service from an existing Java class by adding the @WebService annotation to define the class as a web service.
Creating Artifacts that are Portable Across Vendors

After a service implementation bean has been created and compiled, portable artifacts, which are portable across vendors, need to be generated. Portable artifacts are the files generated by a JAX-WS tool that complies with the JAX-WS specification and are portable across vendors. The artifacts include java classes and WSDL that contain information required for accurate Java-to-WSDL mappings.

JEUS provides a console script called wsgen, and it is located in the 'JEUS_HOME/bin' directory.
```
wsgen –cp <classpath> -d <destination_dir> fromjava.server.AddNumbersImpl
```
Portable artifacts are created in the previous path. A WSDL can also be created by using the '-wsdl' option with wsgen. However, this option should not be used because JAX-WS does not need to include a WSDL for a web service endpoint.
Packaging and Deploying a Web Service

Packaging a web service involves packaging the service implementation bean with the Java classes and deployment descriptors that are referenced by the service implementation bean. They are packaged as a WAR file. The following example only includes the fromjava.server.jaxws.AddNumbers, fromjava.server.jaxws.AddNumbersResponse classes. These classes must be in the 'WEB-INF/classes' folder. After being packaged into the AddNumbers.war file, they are deployed to JEUS.

The web service can be accessed at the following URL.
```
http://localhost:8088/AddNumbers/addnumbers
```
The following page is displayed when the web service has been deployed successfully.

[Figure 11.1] AddNumbers Successfully Deployed

Simple Way to Execute a Web Service Created from Java

The sample web service can easily be executed in JEUS in the following way.

The tasks, from service packaging to client program execution, can be easily performed by executing the jant command from the 'JEUS_HOME/samples/getting_started/webservices/from_java/' directory.

The sample code can be compiled by using jant as in the following.

%JEUS_HOME%/samples/getting_started/webservices/from_java> jant

After the web service has been compiled successfully, the result can be verified in the web browser.

11.1.2. Creating a Web Service From WSDL

The JAX-RPC programming model can be used to develop a web service from existing Java classes. When starting from a WSDL to create a web service, SOAP messages must be defined and shared through the WSDL. Java classes are created according to the defined message types.

In general, developing a web service from a WSDL involves:

Generating a Service Endpoint Interface.

In this step, Java interface and class files for the web service are created from the public WSDL by using the wsimport console script provided by JEUS. The script is in the 'JEUS_HOME/bin' directory.

Execute the following command from the 'JEUS_HOME/samples/getting_started/webservices/from_wsdl' directory.
```
wsimport -keep -p fromwsdl.server -d ./build/classes  ./web/WEB-INF/wsdl/AddNumbers.wsdl
```
Artifacts that include service endpoint interfaces and service definition classes will be created in the specified path.

The following example shows the created service endpoint interface. The interface includes JAX-WS annotation.
[Example 11.2] <<AddNumbersImpl.java>>
```
package fromwsdl.server;

@javax.jws.WebService(endpointInterface = "fromwsdl.server.AddNumbersPortType", 
wsdlLocation = "WEB-INF/wsdl/AddNumbers.wsdl",
targetNamespace = "urn:AddNumbers", serviceName = "AddNumbersService", 
portName = "AddNumbersPort")
public class AddNumbersImpl {

    public int addNumbers(int number1, int number2) {
        return number1 + number2;
    }
}
```
Implementing a Service Endpoint Interface

After a service endpoint interface has been created, a service implementation bean must be implemented with the actual logic. Add the @javax.jws.WebService Annotation to the service implementation bean. This annotation must have an endpoint interface member property that defines the service endpoint interface.
Packaging and Deploying a Web Service in a WAR File

Packaging a web service created from WSDL into a WAR file is similar to packaging a web service created from Java classes.

Generate the portable artifacts required for web service execution. Save the artifacts in the 'WEB-INF/classes' directory. The artifacts include the service endpoint interfaces created by the wsimport script and the service implementation beans. Next, package them into a WAR file. For example, if the WAR package's name is AddNumbers.war, the package can be accessed at the following address after being deployed to JEUS. If the web service has already been created from Java and deployed, it must be removed and then redeployed because they have the same context names.
```
http://localhost:8088/AddNumbers/addnumbers
```
Use this URL to verify that the web service has been deployed successfully.

[Figure 11.2] Successful Deployment of a Web Service Created from WSDL

Simple Way to Execute a Web Service Created from WSDL

The sample web service can easily be executed in JEUS in the following way.

The tasks, from service packaging to client program execution, can be easily performed by executing the jant command from the 'JEUS_HOME/samples/getting_started/webservices/from_java/' directory.

The sample code can be compiled by using jant as in the following.

%JEUS_HOME%/samples/getting_started/webservices/from_wsdl> ant

After the web service has been compiled successfully, the result can be verified in the web browser.

11.2. Building Web Service Clients

After the web service has been deployed, it can be accessed by client programs. Clients are classified into Java SE clients and Java EE clients based on their operating environments.

This section only describes the Java SE clients that run like regular Java programs.

11.2.1. Developing a Java SE Client

In JAX-WS, a dynamic proxy that corresponds to a web service endpoint is created internally and used as a service endpoint interface implementation. Client programs can invoke a web service method, which is defined by a service endpoint interface, by using the proxy.

Portable artifacts must be generated to allow this. The wsimport script tool must be used to create the required artifacts from WSDL.

The following example illustrates how to use wsimport. Run the following command from the 'JEUS_HOME/samples/getting_started/webservices/from_wsdl' directory.

Example:

wsimport –p fromwsdl.client –d ./build/classes http://localhost:8088/AddNumbers/addnumbers?wsdl

After the service endpoint interfaces and the service classes have been created, write a client Java program that uses them.

The following is an example of a web service client program. The example is similar to the sample web service client program provided for JAX-RPC. The sample program creates a service instance and obtains a proxy object that implements the service endpoint interface from the service instance.

The sample code is in the 'JEUS_HOME/samples/getting_started/webservices/from_wsdl/src/java/fromwsdl/client' directory.

[Example 11.3] <<AddNumbersClient.java>>

package fromwsdl.client;

public class AddNumbersClient {

    public static void main(String[] args) {
        AddNumbersPortType port = new AddNumbersService().getAddNumbersPort();

        int number1 = 10;
        int number2 = 20;

        System.out.println("##############################################");
        System.out.println("### JAX-WS Webservices examples - fromwsdl ###");
        System.out.println("##############################################");
        System.out.println("Testing Java class webservices from WSDL...");
        int result = port.addNumbers(number1, number2);
        if (result == 30) {
            System.out.println("Success!");
        }
    }
}

The following result will be displayed when the client program has been compiled and executed successfully.

Example:

[java] ##############################################
[java] ### JAX-WS Webservices examples - fromwsdl ###
[java] ##############################################
[java] Testing Java class webservices from WSDL...
[java] Success!

Prev	Up	Next
Chapter 10. Using EJBs	Home	Appendix A. Installing JDK

Chapter 11. Using Web Services
Prev	Part III. Starting JEUS	Next