Contents


Develop and deploy JAX-WS Web services on WebSphere Application Server Community Edition V2.0

Comments

IBM WebSphere Application Server Community Edition V2.0 (hereafter referred to as Community Edition) is an application server built on top of Apache Geronimo 2.0, an open source application server created by the Apache Software Foundation. Community Edition server is a fully compliant and certified Java Platform, Enterprise Edition 5.0 (Java EE 5) container suitable for everything from a development environment to enterprise-level deployments.

Java EE 5 introduced a number of new and updated features, such as Enterprise JavaBeans™ 3.0 (EJB 3), and also simplified the development and deployment of applications by the use of annotations and dependency injection. One of the new features introduced in Java EE 5 was Java API for XML-based Web services (JAX-WS) 2.0.

JAX-WS

JAX-WS 2.0 is the new Web services stack in Java EE 5, designed to replace the old Java API for XML-Based RPC (JAX-RPC) 1.1 based Web services. JAX-WS adds numerous new features and improvements over JAX-RPC such as support for:

  • Java Architecture for XML Binding (JAXB) 2.0.
  • Simple Object Access Protocol (SOAP) 1.2, as well as SOAP 1.1.
  • Web Services Description Language (WSDL) 2.0, as well as WSDL 1.1.
  • Web Services Interoperability (WS-I) Basic Profile 1.1 for improved Web services interoperability.

One of the key features of JAX-WS is simplified development and deployment of Web service clients and endpoints with the use of annotations. Using annotations simplifies the code and reduces -- and in some cases completely eliminates -- the need for deployment descriptors.

Develop Web service endpoint

Endpoint implementation

Creating a basic Web service using JAX-WS is very easy: simply annotate the class with the @WebService annotation. Listing 1 shows the simplest implementation of the JAX-WS calculator service that provides a simple add() function.

Listing 1. Calculator Web service implementation
import javax.jws.WebService;

@WebService()
public class Calculator {
    
    public int add(int value1, int value2) {
        System.out.println("adding " + value1 + " and " + value2);
        return value1 + value2;
    }
}

And that's it! The annotated Web service implementation is all you need to write to deploy and publish a JAX-WS Web service. You don't need to write any deployment descriptors, such as web.xml or webservices.xml, or create a WSDL file. These descriptors will be automatically updated or generated by the server during the deployment. Of course, these descriptors can still be provided to override the defaults and customize the deployment. For example, since a web.xml file was not provided, one will be automatically generated by the server during the deployment:

  • The generated web.xml file will contain a servlet-mapping for the Web service.
  • That servlet-mapping specifies part of a URL address that will trigger the given Web service.
  • By default, that address is set to the Web service name. In this case, the Web service name is CalculatorService, and, therefore, the Calculator Web service will be accessible under the /CalculatorService address. You can change that default address by providing a custom web.xml file with a different servlet-mapping entry for the Web service.

Also, notice that the service class does not implement any interfaces. In JAX-WS, the Web service does not need to implement or provide a Service Endpoint Interface (SEI). In such cases, the SEI will be implied from the service implementation class, as in this example.

Additionally, since JAX-WS uses JAXB for all data binding purposes, the jaxrpc-mapping file is no longer necessary.

Building and deploying the service

The steps below describe how to build and deploy the service. For the purpose of this article, use Apache Maven version 2.0.5 or greater to build the sample code:

  1. Download the sample file included with this article and unzip it to a directory of your choice. This directory will be referred to as sample_install.
  2. Build the service code by executing the mvn install command in the sample_install\jaxws-calculator\service directory. This Maven command will compile the service code and create the jaxws-calculator-service-1.0.war file in the target/ subdirectory.
  3. Start the Community Edition server (if it is not already running). Use the administrative console to deploy the WAR file or execute the command in Listing 2, where wasce_install is the Community Edition installation directory.
    Listing 2. Deploy the service WAR file
    wasce_install\bin\deploy.bat --user system -password manager deploy
    sample_install\jaxws-calculator\service\target\jaxws-calculator-service-1.0.war
  4. Check if the service is successfully published by opening http://localhost:8080/jaxws-calculator-service-1.0/CalculatorService?wsdl in your Web browser. If the service was successfully deployed and is running, the server should return the WSDL that was generated for this service.

Develop Web service client

To write a Web service client for this service, you first need to generate the portable artifacts from the service WSDL. The portable artifacts are a set of classes needed for service invocation, such as the SEI, the service class, and the JAXB generated classes that represent the schema types. These portable artifacts can be generated by the jaxws-tools command line tool included in Community Edition, or by the wsgen or wsimport tools from Sun Microsystems™.

Generate portable artifacts

For the purpose of this article, you will use the wsimport tool to generate the portable artifacts. The wsimport tool takes a WSDL file as input and generates the necessary SEI, service, and JAXB classes. To simplify the build instructions, the wsimport step was integrated into the Maven build script. This script uses the wsimport Ant task to generate the portable artifacts. Listing 3 shows an excerpt from the Maven build script that invokes the wsimport Ant task.

Listing 3. wsimport Ant task
...
  <wsimport
      destdir="${pom.basedir}/target/classes"
      sourcedestdir="${pom.basedir}/target/generated"
      debug="true" keep="true"
      wsdl="http://localhost:8080/jaxws-calculator-service-1.0/CalculatorService?wsdl" />
...

In this example, the wsimport Ant task retrieves the WSDL directly from the Calculator Web service. The Community Edition server must be up and running and the service must be properly deployed for wsimport to work.

These artifacts can also be generated by the jaxws-tools command line tool, included in Community Edition, by executing the command shown in Listing 4.

Listing 4. Using the jaxws-tools command
wasce_install\bin\jaxws-tools.bat wsimport 
     -s sample_install\jaxws-calculator\client\src\main\java 	
     http://localhost:8080/jaxws-calculator-service-1.0/CalculatorService?wsdl

Client implementation

Listing 5 shows a basic Web service client implementation. This is a simple servlet that calls the add() function of the Calculator Web service and returns the result. The two values to add are passed as parameters x and y to the servlet. Be aware that the CalculatorService class is the Service class and the Calculator class is the SEI class generated by the wsimport tool (in the previous step). The client is written as a servlet to demonstrate another new Java EE 5 feature: dependency injection.

Listing 5. Calculator Web service client implementation
import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.xml.ws.Service;
import javax.xml.ws.WebServiceRef;

public class CalculatorClient extends HttpServlet {

    @WebServiceRef CalculatorService service;
    
    public void doGet(HttpServletRequest req, HttpServletResponse resp) 
        throws ServletException, IOException {
        int x = Integer.parseInt(req.getParameter("x"));
        int y = Integer.parseInt(req.getParameter("y"));
        Calculator calculator = service.getCalculatorPort();
        int sum = calculator.add(x, y);
        resp.getWriter().println(x + " + " + y + " = " + sum);
    }

}

The @WebServiceRef annotation on the service variable causes the server to automatically add a service reference entry in the deployment descriptor and, at run time, lookup and inject the value of this reference into the variable. Before, with Java 2 Platform, Enterprise Edition (J2EE), these two tasks had to be done by hand; you had to explicitly define the service reference in the deployment descriptor and then write extra code to perform a JNDI lookup to obtain the actual reference.

Since the CalculatorClient is a regular servlet, a web.xml file is still necessary to define and publish the servlet. However, the web.xml file is a little bit simpler, as shown in Listing 6, because it does not need to define the service reference.

Listing 6. web.xml
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
                             http://java.sun.com/xml/ns/j2ee/web-app_2_5.xsd"
         version="2.5">

    <display-name>JAX-WS Client Sample</display-name>

    <servlet>
        <display-name>JAX-WS Client Sample Servlet</display-name>
        <servlet-name>CalculatorClientServlet</servlet-name>
        <servlet-class>org.apache.geronimo.example.jaxws.CalculatorClient</servlet-class>
        <load-on-startup>0</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>CalculatorClientServlet</servlet-name>
        <url-pattern>/client</url-pattern>
    </servlet-mapping>

</web-app>

Building and deploying the client

Follow these steps to build and deploy the client:

  1. Build the client code by executing the mvn install command in the sample_install\jaxws-calculator\client directory. This Maven command will first generate the client artifacts, then compile the client code, and finally create the jaxws-calculator-client-1.0.war file under the target/ subdirectory.
  2. Use the Community Edition administrative console to deploy the WAR file, or execute the command in Listing 7.
    Listing 7. Deploy the client war file
    wasce_install\bin\deploy.bat --user system -password manager deploy
    sample_install\jaxws-calculator\client\target\jaxws-calculator-client-1.0.war

Testing the Web service sample

Once the client war file is deployed, open http://localhost:8080/jaxws-calculator-client-1.0/client?x=5&y=10 in your Web browser to invoke the CalculatorClient servlet which, in turn, will invoke the Calculator Web service. The x and y values to add are specified in the URL. After invoking the Web service, the servlet will return the result of the addition. Figure 1 shows the expected output of the servlet.

Figure 1. Servlet result
Figure 1. Servlet result
Figure 1. Servlet result

Conclusion

Thanks to the improvements in Java EE 5 and the introduction of JAX-WS, developing and deploying Web services is much easier than ever before. This article demonstrated how to build JAX-WS clients and services with WebSphere Application Server Community Edition V2.0, and highlighted some the new features of Java EE 5 and JAX-WS along the way. Go ahead and get started on your first JAX-WS Web service project on Community Edition now!


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=257686
ArticleTitle=Develop and deploy JAX-WS Web services on WebSphere Application Server Community Edition V2.0
publish-date=09252007