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

With Java™ EE 5 and the introduction of JAX-WS, developing and deploying Web services is much easier than ever before. Learn how to build JAX-WS clients and services with IBM® WebSphere® Application Server Community Edition V2.0, the latest version on IBM's freely available application server, based on Apache Geronimo 2.0, and get started on your first JAX-WS Web service project right now.

Share:

Jarek Gawor, Advisory Software Engineer, IBM

Author photoJarek Gawor is an advisory software engineer for IBM in Research Triangle Park, North Carolina, in the Software Group. He is an Apache Geronimo committer and PMC member. He received a Master's Degree in Computer Science from Illinois Institute of Technology.



Lin Sun (linsun@us.ibm.com), Advisory Software Engineer, IBM

Lin SunLin Sun is an advisory software engineer for IBM in Research Triangle Park, North Carolina, in the Software Group WebSphere Application Server Community Edition Development Team. She received a master's degree in information science from the University of North Carolina at Chapel Hill.



25 September 2007

Also available in Chinese

Introduction

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.

Download Community Edition V2.0 now!
IBM WebSphere Application Server Community Edition V2.0 is free to use and deploy. Download it now to get started.

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:

JAX-WS engines
Community Edition uses Apache Axis2 1.3 as its JAX-WS engine. While it is possible to configure Apache Geronimo 2.0 to use Apache CXF as an alternative JAX-WS engine, only the Apache Axis2 engine is supported in Community Edition at this time.

  • 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

Develop skills on this topic

This content is part of a progressive knowledge path for advancing your skills. See Building and deploying JAX-WS web services

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:

Deployment warning message
During deployment, you might see a warning message indicating that your Web application does not contain a WEB-INF/geronimo-web.xml deployment plan. This message can be ignored for this sample, as it does not contain any resource references that need to be resolved.

  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

Module startup dependency
In this sample, the client retrieves the WSDL directly from the service, so the service WAR module must start before the client module starts. If the client module starts first, the client will not work. Modify the wasce_install\var\config\config.xml configuration file to change the module startup order.

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

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!


Download

DescriptionNameSize
Code samplejaxws-calculator.zip8 KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


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