Table of Contents
This chapter describes how to create a web service and client using JAX-WS 2.2, and how to call the web service.
JEUS 7 supports Java EE 6 web services, and JAX-WS 2.2 is the core functionality of Java EE 6 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 7.
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 7.
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.
Simple Way to Execute a Web Service Created from Java
The sample web service can easily be executed in JEUS 7 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> jantAfter the web service has been compiled successfully, the result can be verified in the web browser.
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 7. 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 7. 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.
Simple Way to Execute a Web Service Created from WSDL
The sample web service can easily be executed in JEUS 7 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> antAfter the web service has been compiled successfully, the result can be verified in the web browser.
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.
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!