JDJ Feature — Java API for XML Web Services (JAX-WS)

WebLogic Server 10 Technology Preview supports JEE 5. A feature of JEE 5 is the Java API for XML Web Services (JAX-WS) used to create Web Services and Web Service clients. WebLogic Server 10 provides the jwsc task to create the Web Service artifacts and the clientgen task to create the artifacts for Web Service clients. In this article we'll create an example JAX-WS 2.0 Web Service in WebLogic Server 10 Technology Preview.

JAX-WS is an API to create Web applications and Web Services using the XML-based Web Services functionality. To create a Web Service first create a Service Endpoint Implementation (SEI) class. The implementation class is annotated with javax.jws.WebService annotation. The implementation class must not be abstract or final, and must contain a default public constructor.

A Web Service provides operations that are made available to Web Service clients. So add business methods to the Web Service class. The business methods are public and must not be static or final and may be annotated with the javax.jws.WebMethod annotation. By default all public methods are made available as Web Service operations.

Preliminary Setup
Download and install the WebLogic Server 10 Technical Preview. Download and install Apache Ant, which is required to run Ant tasks to create Web Service and client classes. Download and install JDK 5 if not already installed. It's required to run Apache Ant.

Using the WebLogic server Configuration Wizard create a WebLogic domain, base_domain.

Creating a Web Service
We'll create a JAX-WS 2.0 Web Service. First, set the WebLogic server environment by running the setDomainEnv command script.

C:\BEA\user_projects\domains\base_domain\bin> setDomainEnv

Next, create a project directory in the C:\BEA\user_projects directory with the mkdir command. The directory names should be separated with backslashes instead of forward slashes for the mkdir command to run.

C:\BEA\user_projects> mkdir webservices\hello_webservice

Create an src directory under the project directory that contains subdirectories corresponding to the package name of the Java Web Service class.

C:\BEA\user_projects\webservices\hello_webservice>mkdir src\webservices\hello_webservice

Create a Java Web Service (JWS) file for implementing a JAX-WS Web Service. Annotate the Web Service implementation class HelloWsImpl with the @WebService annotation. JSR 181: Web Services Metadata for the Java Platform defines the standard annotations that can be used in a Java Web Service. The javax.jws.WebService annotation specifies that a class implements a Web Service. The attributes that may be specified in the javax.jws.WebService annotation are discussed in Table 1. All of them are optional.

Add a Web Service method that returns a Hello message. By default all public methods are exposed as Web Service operations. Web Service methods may be annotated with the @WebMethod annotation. Attributes operationName and action may be specified in the WebMethod annotation. The operationName attribute specifies the name of the operation as mapped to the wsdl:operation element in the WSDL. Default value is the method name. For SOAP bindings, the action attribute maps to the SoapAction header in the SOAP messages.

The HelloWsImpl Web Service implementation class is listed below.

package webservices.hello_webservice;
import javax.jws.WebService;

@WebService()
public class HelloWsImpl {

     public String hello(String name) {

         return "Hello "+name +" Welcome to Web Services!";

     }

}

Copy the HelloWsImpl.java class to the C:\BEA\user_projects\webservices\hello_webservice\src\webservices\hello_webservice directory.

WebLogic Server 10 provides WebLogic Web Services Ant tasks to create Web Services and client classes. The jwsc Ant task takes an annotated JWS file as input and generates all the artifacts required to create a WebLogic Web Service.
The generated files include the following.

Java Source files that implement a standard JSR-921 Web Service, such as the Service Endpoint Interface (SEI). For a JWS class HelloWsImpl an SEI HelloWsImplPortType.java gets created.
Standard and WebLogic-specific deployment descriptors. The standard webservices.xml deployment descriptor and the JAX-RPC mapping files get created. The WebLogic-specific Web Services deployment descriptor weblogic-webservices.xml also gets created.
The WSDL file that describes the Web Service.
The XML Schema representation of any Java user-defined types used as parameters or return values of Web Service methods.

A jws sub-element of the jwsc element specifies a JWS file. By default jwsc generates a JAX-RPC 1.1 Web Service. To generate a JAX-WS 2.0 Web Service specify the type attribute of the jws element as type="JAXWS".

Subsequent to generating the Web Service artifacts, jwsc compiles the JWS and Java files and packages the generated artifacts and classes into a Web application WAR file. Jwsc also creates an enterprise application directory structure. The Web Service may be deployed as a WAR file or packaged into an EAR file and deployed. Jwsc generates a WAR file corresponding to each jws element that's a direct sub-element of the jwsc element. JWS files may be grouped by adding the jws elements to a module element, which is a direct sub-element of the jwsc element. If a module element is specified only one WAR file is generated.

In addition to the standard attributes some WebLogic specific attributes may be specified in the jwsc ant task. Only the srcdir and destdir attributes are required. The WebLogic specific jwsc attributes are discussed in Table 2.

A jws element specifies a JWS file to compile. A jws element may be specified as a direct sub-element of the jwsc element or be included in a module element, which is a direct sub-element of the jwsc element. The only required attribute of the jws element is file, which specifies the JWS file. Some of the other attributes that may be specified in the jws element are discussed in Table 3.

Next, create a build.xml file to generate the artifacts for a Web Service from the example JWS file. To the build.xml file add a taskdef element for the jwsc task that specifies the class for the jwsc task. Add a target to build the Web Service. Specify a jwsc task with srcdir as src and destdir as output/HelloWsEar. Using a jws element specify the JWS file to be compiled. Specify the type attribute of the jws element as JAXWS as the Web Service is a JAX-WS 2.0 Web Service. The build.xml file is listed below.

Next, we shall run the build-service target to generate the Web Service artifacts. Run the build-service target with the following command.

C:\BEA\user_projects\webservices\hello_webservice>ant build-service

The artifacts for a Web Service get generated and packaged into a WAR file HelloWsImpl.war in the directory C:\BEA\user_projects\webservices\hello_webservice\output\HelloWsEar\webservices\hello_webservice. An exploded directory structure for an EAR application including the application.xml and weblogic-application.xml also get generated. The output from the ant command is shown in Figure 1.

To deploy the Web Service copy the WAR file HelloWsImpl.war to the C:\BEA\user_projects\domains\base_domain\autodeploy directory. Start WebLogic with the command script C:\BEA\user_projects\domains\base_domain\bin\startWebLogic.

When the Web application is deployed the application server and the JAX-WS runtime generate the WSDL file and any additional artifacts required to invoke the Web Service from a client. The WSDL may be accessed with URL http://localhost:7001/HelloWsImpl/HelloWsImplService?WSDL. (Figure 2)

Creating a Client
In this section we'll create a JAX-RPC Java client for the Web Service created in the previous section. We'll use the clientgen Ant task to generate the client component files. First, create a project directory for the client application.

C:\BEA\user_projects> mkdir \webservices\simple_client

Create an src directory under the project directory. The sub-directories of the src directory should correspond to the package name of the Java client class, which we'll create next

C:\BEA\user_projects\webservices\simple_client> mkdir src\webservices\jaxws\client

Create a Java client application Main.java in package webservices.jaxws.client. In the Java client application create an instance of the HelloWsImplService service.

HelloWsImplService service = new HelloWsImplService();

Obtain a proxy to the service from the service using the getHelloWsImplPort() method.

HelloWsImpl port = service.getHelloWsImplPort();

Invoke the hello(String) method of the service.

result = port.hello("Deepak");

The Java client application Main.java class is listed below.

package webservices.jaxws.client;

public class Main {
   public static void main(String[] args) {
     HelloWsImplService service = new HelloWsImplService();
     HelloWsImpl port = service.getHelloWsImplPort();
     String result = null; result = port.hello("Deepak");
     System.out.println(result);
   }
}

Next, we'll generate the client application artifacts required to invoke the Web Service using the clientgen task. The clientgen task generates the following artifacts.

The client-side copy of the WSDL file.
The Java source code for the Stub and Service interface implementations for the Web Service.
Java classes for any user-defined XML Schema data types defined in the WSDL file.
JAX-RPC deployment descriptor that describes the mapping between the Java data types and the corresponding XML Schema types in the WSDL file.

The only required attribute of the clientgen task is one of destDir or destFile and wsdl. Some of the commonly used attributes of the clientgen task are discussed in Table 4.

Create a build.xml file in the C:\BEA\user_projects\webservices\simple_client directory. Specify the class name for the clientgen task with the taskdef element.

Add a target build-client to the build.xml file to generate the client artifacts. Add a clientgen element to the target element. Specify type as JAXWS, destDir as output/clientclass, packageName as webservices.jaxws.client, and wsdl as http://localhost:7001/HelloWsImpl/HelloWsImplService?WSDL.

Add javac elements to the target element to com-pile the client artifact Java classes and the Main.java client Java application. The build.xml file is listed below.

Run the build-client target to generate the client artifacts and compile the Java classes.

C:\BEA\user_projects\webservices\simple_client> ant build-client

The client artifacts get generated and the Java classes get compiled. The output from the build-client target is shown in Figure 3.

Next, add a target to the build.xml file to run the client Java application Main.java. Add a target run. Also add a path element to specify the classpath to run the Main.java application. The classpath should include the output/clientclass directory that contains the client artifacts and the system property java.class.path. The modified build.xml file is shown below.

Next, run the target run.

The Web Service operation hello() gets invoked with a String argument and the result returned by the Web Service gets output as shown in Figure 4.

Conclusion
WebLogic Server 10 Technical Preview supports JEE 5 and the JAX-WS 2.0 Web Services. WebLogic server 10 also provides Ant tasks jwsc and clientgen to generate the Web Service artifacts and client artifacts.

JDJ Feature — Java API for XML Web Services (JAX-WS)

© 2008 SYS-CON Media