This Tech Tip reprinted with permission by

Java API for XML Web Services (JAX-WS) 2.0, JSR 224, is an important part of the Java EE 5 platform. A follow-on release of Java API for XML-based RPC 1.1(JAX-RPC), JAX-WS simplifies the task of developing web services using Java technology. It addresses some of the issues in JAX-RPC 1.1 by providing support for multiple protocols such as SOAP 1.1, SOAP 1.2, XML, and by providing a facility for supporting additional protocols along with HTTP. JAX-WS uses JAXB 2.0 for data binding and supports customizations to control generated service endpoint interfaces. With its support for annotations, JAX-WS simplifies web service development and reduces the size of runtime Jar files.

A sample package accompanies this tip. It demonstrates a simple web service that is accessed using JAX-WS 2.0 through a standalone Java client. The example is based on an open source implementation of the Java EE 5 SDK called GlassFish. The sample package includes the source code for the example, build scripts, and an ant build file.

Let's start by doing some initial setup. If you haven't already done so, download GlassFish from the GlassFish Downloads page. (This tip was tested with Build 29 of GlassFish.) Then set the following environment variables:

  • GLASSFISH_HOME. This should point to where you installed GlassFish (for example C:\Sun\AppServer)
  • ANT_HOME. This should point to where ant is installed. Ant is included in the GlassFish bundle that you downloaded. (In Windows, it's in the lib\ant subdirectory.) You can also download Ant from the Apache Ant Project page. The example requires Apache ant 1.6.5.
  • JAVA_HOME. This should point to the location of JDK 5.0 on your system.

Also, add the ant location to your PATH environment variable.

Then download the sample package and extract its contents. The main directory for this tip is jaxws-techtip.

Building the Web Service

With the initial setup done, it's time to build a web service. In this example, the web service is developed from a Java class. To build the web service:

  • Write an endpoint implementation class.
  • Compile the endpoint implementation class.
  • Optionally generate portable artifacts required for web service execution.
  • Package the web service as a WAR file and deploy it.

Write an endpoint implementation class

If you navigate down through the <Sample_install_dir>\jaxws-techtip directory structure, you'll find an endpoint directory. In that directory, you'll see a class named Calculator. The class is an endpoint implementation of a simple service that adds two integers:

 package endpoint;
   import javax.jws.WebService;
   import javax.jws.WebMethod;
   public class Calculator {
           public Calculator() {}
           @WebMethod(operationName="add", action="urn:Add")
           public int add(int i, int j) {
                   int k = i +j ;
                   System.out.println(i + "+" + j +" = " + k);
                   return k;

JAX-WS 2.0 relies heavily on the use of annotations as specified in A Metadata Facility for the Java Programming Language (JSR 175) and Web Services Metadata for the Java Platform (JSR 181), as well as additional annotations defined by the JAX-WS 2.0 specification.

Notice the two annotations in the Calculator class: @WebService and @WebMethod. A valid endpoint implementation class must include a @WebService annotation. The annotation marks the class as a web service. The name property value in the @WebService annotation identifies a Web Service Description Language (WSDL) portType (in this case, "Calculator"). The serviceName ("CalculatorService") is a WSDL service. TargetNamespace specifies the XML namespace used for the WSDL. All the properties are optional. For details on default values of these properties, see section 4.1 of the specification Web Services Metadata for the Java Platform, JSR 181.

The @WebMethod annotation exposes a method as a web service method. The operationName property value in the annotation of the Calculator class identifies a WSDL operation (in this case, add), and the action property value ("urn:Add") specifies an XML namespace for the WSDL and some of the elements generated from this web service operation. Both properties are optional. If you don't specify them, the WSDL operation value defaults to method name, and the action value defaults to the targetNamespace of the service.

Compile the implementation class

After you code the implementation class, you need to compile it. Start GlassFish by entering the following command:

  <GF_install_dir>\bin\asadmin start-domain domain1

where <GF_install_dir> is the directory where you installed GlassFish. Then navigate to the jaxws-techtip folder in the <Sample_install_dir>\jaxws directory structure, and execute the following command.

   ant compile 

Executing the command is equivalent to executing the following javac command (on one line):

  javac -classpath $GLASSFISH_HOME/lib/javaee.jar -d 
  ./build/classes/service/ endpoint/

Generate portable artifacts for web service execution

This step is optional. GlassFish's deploy tool automatically generates these artifacts if they are not bundled with a deployable service unit during deployment of the web service. However if you want to generate these artifacts manually, execute the following command:

   ant generate-runtime-artifacts

This creates a build/generated directory below jaxws-techtip, and executes the following wsgen command (on one line):

   $GLASSFISH_HOME/bin/wsgen -cp ./build/classes/service 
   -keep -d ./build/classes/service 
   -r ./build/generated -wsdl endpoint.Calculator

A WSDL file (CalculatorService.wsdl) is generated in the build/generated directory, along with a schema file (CalculatorService_schema1.xsd), which defines the schema for CalculatorService.wsdl.

JavaBean technology components (JavaBeans) aid in marshaling method invocations, responses, and service-specific exceptions. These classes are used during execution of the web service on an application server. The JavaBean classes are generated in the /build/classes/service/endpoint/jaxws directory below jaxws-techtip. The classes are:  

Package and deploy the WAR file

Next you need to package and deploy the service. To do that, you need to specify details about the service in deployment descriptors. Web services can be bundled as a servlet or as a stateless session bean. Web services bundled as servlets are packaged in Web Archive (WAR) files. In this tip, the service is bundled as a servlet.

To package the service as a WAR file, navigate to the jaxws-techtip folder and execute the following command:

   ant pkg-war  

For the structure of the war file, you can take a look at the pkg-war target in the build.xml file.

You can deploy the generated war file by executing the following command:

   ant deploy-app 

This is equivalent to executing the following asadmin deploy command (on one line):

   bash$GLASSFISH_HOME/bin/asadmin deploy --user admin
   --passwordfile passwd --host localhost --port 4848
   --contextroot jaxws-webservice --upload=true --target server

Building the Client

After you deploy the web service, you can access it from a client program. Here are the steps to follow to build the client:

  1. Write the client.
  2. Generate portable artifacts required to compile the client.
  3. Compile the client.
  4. Run the client.

Write the Client

The following program, JAXWSClient, is a standalone client program provided with the sample code for this tip. It invokes an add operation on the deployed service ten times, adding 10 to numbers from 0-to-9.

 package client;
   import com.techtip.jaxws.sample.CalculatorService;
   import com.techtip.jaxws.sample.Calculator;

   public class JAXWSClient {
       static CalculatorService service;
      public static void main(String[] args) {
         try {
           JAXWSClient client = new JAXWSClient();
         } catch(Exception e) {
      public void doTest(String[] args) {
        try {
             " Retrieving port from the service " + service);
          Calculator port = service.getCalculatorPort();
             " Invoking add operation on the calculator port");
          for (int i=0;i>10;i++) {
            int ret = port.add(i, 10);
            if(ret != (i + 10)) {
              System.out.println("Unexpected greeting " + ret);
               " Adding : " + i + " + 10 = "  + ret);
        } catch(Exception e) {

The @WebServiceRef annotation in JAXWSClient is used to declare a reference to a web service. The value of the wsdlLocation parameter in @WebServiceRef is a URL pointing to the location of the WSDL file for the service being referenced. The @WebServiceRef annotation supports additional optional properties, as specified in section 7.9 of JSR 224. The static variable named service will be injected by the application client container.

Notice the import statements in JAXWSClient: com.techtip.jaxws.sample.CalculatorService and com.techtip.jaxws.sample.Calculator. These imports are for portable artifacts that will generated in the next step. CalculatorService is the portable artifact for the service implementation. Calculator is the Java interface for the service endpoint generated from the WSDL identified by the wsdlLocation property of @WebServiceRef.

The client retrieves the endpoint Calculator from the CalculatorService through the method getWebServiceRefNamePort, where WebServiceRefName is the name property of @WebServiceRef, or the value of the WSDP port in the generated WSDL file. After it retrieves the endpoint, the client invokes the add operation the required ten times.

Generate portable artifacts for the client

As mentioned earlier, CalculatorService and Calculator are portable artifacts. To generate all the portable artifacts for the client, navigate to the jaxws-techtip folder and issue the following command:

ant generate-client-artifacts 

This is equivalent to executing following wsimport command (on one line):

   $GLASSFISH_HOME/bin/wsimport -keep  -d ./build/classes/client 

This generates the artifacts in the build/classes/client/com/techtip/jaxws/sample directory under jaxws-techtip. The artifacts are:

Compile the client

The next step is to compile the client classes. You can do that by entering the following command:

   ant compile-client

The ant compile task compiles client/JAXWSClient and writes the class file to the build /classes/client subdirectory. It is equivalent to running the following command (on one line):

   javac -d ./build/classes/client 
   -classpath $GLASSFISH_HOME/lib/javaee.jar:
   ./build/classes/client client/

Run the client

To see how the sample works, execute following command:

   ant runtest-jaxws

which is equivalent to executing following command executed from build/classes/client folder.:

   $GLASSFISH_HOME/bin/appclient -mainclass client.JAXWSClient     

You should see output similar to the following:

        [echo] Executing appclient with client class as 
        [exec]  Retrieving port from the service 
        [exec]  Invoking add operation on the calculator port
        [exec]  Adding : 0 + 10 = 10
        [exec]  Adding : 1 + 10 = 11
        [exec]  Adding : 2 + 10 = 12
        [exec]  Adding : 3 + 10 = 13
        [exec]  Adding : 4 + 10 = 14
        [exec]  Adding : 5 + 10 = 15
        [exec]  Adding : 6 + 10 = 16
        [exec]  Adding : 7 + 10 = 17
        [exec]  Adding : 8 + 10 = 18
        [exec]  Adding : 9 + 10 = 19
   Total time: 6 seconds

About the Author

Manisha Umbarje is a member of the product engineering group for the Sun Java System Application Server.

Copyright (c) 2004-2005 Sun Microsystems, Inc.
All Rights Reserved.