Developing a JAX-WS POJO Web Service has been edited by Shiva Kumar H R (Jul 02, 2008).

(View changes)


This tutorial will take you through the steps required in developing, deploying and testing a Web Service in Apache Geronimo. After completing this tutorial you should be able to understand how to develop simple JAX-WS compliant web services in Apache Geronimo using Eclipse development environment.

This application has a Java class which contains two functions, one which converts amount in Dollars to Rupees and the other which converts Rupees to Euros. We will expose these two methods as the services provided by our deployed Web Service.

We will also create two types of clients to access the Web service. One is a Web based client and the other is a Java client.

Types of Web Services

For new users, Web Services can be created in two ways.

  • Bottom Up Web Service - creating web services from Java classes.
  • Top Down Web Service - creating web services from WSDL document.

This tutorial will help you in creating a Bottom Up Web Service from a Java class which will be exposed as a servlet to the client applications.

To run this tutorial, as a minimum you will be required to have installed the following prerequisite software.

  • Sun JDK 5.0+ (J2SE 1.5)
  • Apache Geronimo 2.x
  • Eclipse IDE for Java EE Developers - Europa release
  • Geronimo Eclipse Plug-in 2.x

Details on installing eclipse are provided in the Development environment section. This tutorial will take you through the following steps:

Setting Up Eclipse for Application Development

  1. Create a Dynamic Web Project
    • Select File->New->Other
    • In the popup window, Select Web->Dynamic Web Project and click Next
    • Type jaxws-converter as the Project Name and click Next
    • On the Project Facets page, the default selections (as shown below) are enough as Geronimo has axis2 web container already running, click Next

    • Make sure that the check box Generate Deployment Descriptor is selected and click Next
    • On the Geronimo Deployment Page modify the Group Id to org.apache.geronimo.samples.jaxws and the artifact id to jaxws-converter.
    • Click Finish

This completes the configuration of Eclipse for application development.

Creating the Web Services Implementation code

To deploy the Converter service we are going to create a POJO interface and a class and expose it as a servlet. The steps required are:

  1. In Project Explorer view, expand jaxws-converter project, right click on Java Resources: src and select New->Package
  2. Name the package to org.apache.geronimo.samples.jaxws and click Finish
  3. Right click on the new package and select New->Interface
  4. Name the interface as Converter and click Finish
  5. Add the following code to the Converter interface
    package org.apache.geronimo.samples.jaxws;
    import java.math.BigDecimal;
    import javax.jws.WebService;
            targetNamespace = "")
    public interface Converter {
    	public BigDecimal dollarToRupees(BigDecimal dollars);
    	public BigDecimal rupeesToEuro(BigDecimal rupees);
  1. In Project Explorer view, right click on the new package and select New->Class
  2. Name the class as ConverterService, add org.apache.geronimo.samples.jaxws.Converter as Interface and click Finish
  3. Add the following code to the ConverterService class
    package org.apache.geronimo.samples.jaxws;
    import java.math.BigDecimal;
    import javax.jws.WebService;
    @WebService(serviceName = "Converter",
            endpointInterface = "org.apache.geronimo.samples.jaxws.Converter",
            targetNamespace = ""
    public class ConverterService implements Converter {
    	private BigDecimal rupeeRate = new BigDecimal("40.58");
    	private BigDecimal euroRate = new BigDecimal("0.018368");
    	public BigDecimal dollarToRupees(BigDecimal dollars) {
    		BigDecimal result = dollars.multiply(rupeeRate);
    		return result.setScale(2, BigDecimal.ROUND_UP);
    	public BigDecimal rupeesToEuro(BigDecimal rupees) {
    		BigDecimal result = rupees.multiply(euroRate);
    		return result.setScale(2, BigDecimal.ROUND_UP);

Let us try to understand each annotation

  • @WebService- This annotation can be used with a Java class as well as with interface. In our case we used it with both interface as well as the POJO. This annotation declares the POJO as a WebService. @WebService annotation is utilized in generating the WSDL file.
    • serviceName is same as the WSDL element service
    • name is same as the WSDL element <portType name>
    • endpointInterface suggests the user defined name for the Service Endpoint Interface(SEI).
    • portName is the element portName
    • targetNamespace is the XML namespace of the WSDL and some of the XML elements generated from the WebService
  • @WebMethod- This annotation is applied to a method to expose it as a WebService method. In case you have multiple methods you can use this annotation to selectively expose methods as WebService method. If you donot use this annotation all the public methods will be exposed as WebService.
  • @WebParam- This annotation is used along with @WebMethod annotation to define the WebService. It is used to customize parameter used in the message part of the wsdl.

This completes the development of the Web Service Implementation code.

Setting Up the Deployment Descriptor and Deployment Plan

For the client applications to enquire about the services provided we need to create a WSDL file which provides the mapping between services exposed by web service and functions in the Java class

Some Typical Web Services Terminology

For new users, the terms that are most commonly used in Web Services are

  • Web Services Description Language (WSDL) - The WSDL defines services as collections of network endpoints, or ports
  • Simple Object Access Protocol (SOAP) - SOAP is a protocol for exchanging XML-based messages over computer networks, normally using HTTP/HTTPS.
  • Universal Description, Discovery and Integration (UDDI) - UDDI is a directory service where businesses can register and search for Web services
  1. Expand WEB-INF directory and add the following code to web.xml
    <?xml version="1.0" encoding="UTF-8"?>
    <web-app xmlns:xsi=""
    	id="WebApp_ID" version="2.5">

This completes the setting up of Deployment descriptor and Deployment Plan.

Deploy and Test the Web Service

Now, we will look into the steps involved in deploying and testing our web service without any clients.


  1. In Servers view, right click on the Apache Geronimo Server Runtime and select Add and Remove Projects
  2. In the popup dialog, select the jaxws-converter project, click Add and then click Finish
  3. Wait for some time till the server status is changed to synchronized.


  1. Once the application is deployed on to the server, Launch a browser and go to the following url.
  2. Now you should see the screen telling that this is Converter Web Service

    WSDL File

    You can also view the WSDL file generated by Geronimo based on the annotations specified by going to the following url

Using Web Services Explorer in Eclipse

  1. Go to Eclipse and select Run->Launch the Web Services Explorer from the main menu.
  2. Web Services Explorer opens up as shown below:

  3. On the top right corner of this explorer, click on the icon for "WSDL Page". Under Navigation section, you will now see WSDL Main. Click that WSDL Main link to enter the URL of WSDL document.

  4. Enter the URL of our WSDL document i.e http://localhost:8080/jaxws-converter/converter?wsdl in the form and click Go. Now you can see the methods that are exposed by our Web Service.

  5. Clicking on any method takes us to a page with form asking for input parameters.If you dont see any field to enter input arguments click Add.

  6. Enter any argument and examine the status frame at the bottom to see the result.

This concludes our deploy and test section.

Generated files by Geronimo

For our convenience Geronimo automatically generates the required files to deploy the Web Services. The WSDL file is created by Geronimo after processing the annotations in our source file.

You can see the Geronimo created files in the directory <INSTALL_DIR>/repository/org/apache/geronimo/samples/jaxws/jaxws-converter/1.0/, at this location you can find a new directory which geronimo created for deploying the web service which contains the WSDL file and other required stubs.

How Geronimo creates the WSDL and other required files?

Geronimo has a inbuilt plugin names jaxws-builder which helps in creating the WSDL and other required files to deploy the web service by using the jaxws-tools provided by Sun

Try looking into source of jaxws-builder to better understand how the necessary files are getting created.

Developing a client

Now, we will focus on developing a client for our application. We will develop two types of clients to demonstrate how web services can be consumed in both cases.

  • A Web based client
  • POJO client

Web based Client

Now we will go through the steps involved in creating a client for consuming the web service just deployed.

Developing the Web based Client

  1. Right Click the jaxws-converter, and Select New->JSP

  2. Name the jsp as index.jsp and click Finish

  3. Add the following code to the index.jsp
<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
<meta content="text/html; CHARSET=iso-8859-1" http-equiv="Content-Type">

<h3>This from invokes a Web Service.</h3>
Please type an amount and click submit to see the result.
<form action="result.jsp">Amount(in Dollars): <input type="text"
	name="amount"> <input type="submit" value="Submit"></form>
  1. Right click again and add another jsp named result.jsp

  2. Add the following code to result.jsp
<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
<%@page import=""%>
<%@page import="javax.xml.namespace.QName"%>
<%@page import="java.math.BigDecimal"%>
<%@ page import=""%>
<%@ page import="org.apache.geronimo.samples.jaxws.Converter"%>
<meta content="text/html; CHARSET=iso-8859-1" http-equiv="Content-Type">
	String amount = request.getParameter("amount");

	if (amount != null && amount.trim().length() > 0) {


		try {
			BigDecimal dollars = new BigDecimal(amount);
			URL url = new URL(
			QName qname = new QName(
			Service service = Service.create(url, qname);
			Converter conv = (Converter) service
			BigDecimal rupees = conv.dollarToRupees(dollars);
			BigDecimal euros = conv.rupeesToEuro(rupees);

			out.println(dollars + " Dollars equals to " + rupees
					+ " Rupees");
			out.println(rupees + " Rupees equals to " + euros
					+ " Euros");

		} catch (Exception e) {
			out.println("Error: " + e.getMessage());


This concludes the development section of our web based client.

Deploying and Testing the Web Client


  1. Right now our server status might be reporting that we need to republish.

  2. Right click on the Apache Geronimo Server Runtime present in the servers view and select Publish

  3. Wait for some time till the server status changes to Synchronized


  1. Right click the index.jsp present under WebContent directory of our project and select Run As->Run On Server

  2. In the popup, check the check box Always use this servr when running the project and then click Finish

  3. Now Eclipse will try to open the jsp in a web browser which shows you a form to enter amount in Dollars.

  4. Enter any amount and press submit, the jsp should display the result that is returned by the web service.


Note that we accessed the webservice in the jsp by creating a service, and then retrieving the Converter port from the WSDL document.

POJO Client

Here we will have a look on how to create a plain old java client for consuming the web service.

Developing the Client

  1. Create a Java Project
    • Select File->New->Project

    • In the popup window select Java->Java Project and then click Next

    • Name the project as jaxws-converterclient and then click Next

    • Now go to the Projects tab and click Add

    • Select the jaxws-converter project in the next page and click Ok

    • Now click Finish in the New Java Project dialog.
  1. Right click the src directory and select New->Package

  2. Name the package as org.apache.geronimo.samples.jaxws and click Finish

  3. Right click the newly created package and select New->Class

  4. Name the class as ConverterClient and click Finish

  5. Add the following code to the
package org.apache.geronimo.samples.jaxws;

import java.math.BigDecimal;

import javax.xml.namespace.QName;

public class ConverterClient {
	public static void main(String args[]) {
		try {
			BufferedReader dataIn = new BufferedReader(new InputStreamReader(;
			System.out.println("enter a amount to convert:");
			String number = new String();
			number = dataIn.readLine();
			BigDecimal amount  = new BigDecimal(number);
	        URL url = new URL("http://localhost:8080/jaxws-converter/converter?wsdl");
			QName qname = new QName("","Converter");
			Service service = Service.create(url, qname);
			Converter conv =(Converter)service.getPort(Converter.class);
			BigDecimal result = conv.dollarToRupees(amount);
			System.out.println(amount+" dollars equals to "+result+" rupees");
			BigDecimal result1 = conv.rupeesToEuro(result);
			System.out.println(result+" rupees equals to "+result1+" euros");
		} catch (Exception e) {


This completes the development section of our POJO client

Adding necessary jar files to the class path

Errors in Java Project

Now our Java project might show many errors and even if we resolve the errors the application may not run properly. This is due to the missing jar files required to access web service in class path

  1. Right click the jaxws-converterclient project and then select Properties

  2. Select Java Build Path and then go to Libraries tab

  3. Click on Add External JARS and then add the axis2-adb-1.3.jar from the location <GERONIMO_INSTALL_DIR>/repository/org/apache/axis2/axis2-adb/1.3/ and then click Open
    Version Numbers

    The version numbers may differ slightly. It wont matter much.

  4. Repeat the above step for the following external JARS
External JARS Required

axis2-adb-1.3.jar - <GERONIMO_INSTALL_DIR>/repository/org/apache/axis2/axis2-adb/1.3/axis2-adb-1.3.jar
axis2-java2wsdl-1.3.jar - <GERONIMO_INSTALL_DIR>\repository\org\apache\axis2\axis2-java2wsdl\1.3\axis2-java2wsdl-1.3.jar
axis2-jaxws-1.3.jar - <GERONIMO_INSTALL_DIR>\repository\org\apache\axis2\axis2-jaxws\1.3\axis2-jaxws-1.3.jar
axis2-jaxws-api-1.3.jar - <GERONIMO_INSTALL_DIR>\repository\org\apache\axis2\axis2-jaxws-api\1.3\axis2-jaxws-api-1.3.jar
axis2-kernel-1.3.jar - <GERONIMO_INSTALL_DIR>\repository\org\apache\axis2\axis2-kernel\1.3\axis2-kernel-1.3.jar
axis2-metadata-1.3.jar - <GERONIMO_INSTALL_DIR>\repository\org\apache\axis2\axis2-metadata\1.3\axis2-metadata-1.3.jar
axis2-saaj-1.3.jar - <GERONIMO_INSTALL_DIR>\repository\org\apache\axis2\axis2-saaj\1.3\axis2-saaj-1.3.jar
axiom-api-1.2.5.jar - <GERONIMO_INSTALL_DIR>\repository\org\apache\ws\commons\axiom\axiom-api\1.2.5\axiom-api-1.2.5.jar
axiom-dom-1.2.5.jar - <GERONIMO_INSTALL_DIR>\repository\org\apache\ws\commons\axiom\axiom-dom\1.2.5\axiom-dom-1.2.5.jar
axiom-impl-1.2.5.jar - <GERONIMO_INSTALL_DIR>\repository\org\apache\ws\commons\axiom\axiom-impl\1.2.5\axiom-impl-1.2.5.jar
XmlSchema-1.3.1.jar - <GERONIMO_INSTALL_DIR>\repository\org\apache\ws\commons\schema\XmlSchema\1.3.1\XmlSchema-1.3.1.jar
neethi-2.0.jar - <GERONIMO_INSTALL_DIR>\repository\org\apache\neethi\neethi\2.0\neethi-2.0.jar
wsdl4j-1.6.1.jar - <GERONIMO_INSTALL_DIR>\repository\wsdl4j\wsdl4j\1.6.1\wsdl4j-1.6.1.jar
xml-resolver-1.1.jar - <GERONIMO_INSTALL_DIR>\repository\xml-resolver\xml-resolver\1.1\xml-resolver-1.1.jar
xml-beans-2.3.0.jar - <GERONIMO_INSTALL_DIR>\repository\org\apache\xmlbeans\xmlbeans\2.3.0\xmlbeans-2.3.0.jar
commons-codec-1.3.jar - <GERONIMO_INSTALL_DIR>\repository\commons-codec\commons-codec\1.3\commons-codec-1.3.jar
commons-httpclient-3.0.1.jar - <GERONIMO_INSTALL_DIR>\repository\commons-httpclient\commons-httpclient\3.0.1\commons-httpclient-3.0.1.jar
wstx-asl-3.2.1.jar - <GERONIMO_INSTALL_DIR>\repository\woodstox\wstx-asl\3.2.1\wstx-asl-3.2.1.jar

This completes the adding external JARs to the project


If you are running Java 6 you don't need to worry about the external JARs as they are all inbuilt into JRE 6.


  1. Now Right click the ConverterClient.class and select Run As->Run as Java Application

  2. Now enter the amount in the console window of Eclipse
  3. The output will be shown which is retrieved by accessing the methods of Web service.

This completes the process of deploying the web services in Geronimo and developing different types of clients. Completing this tutorial should give you a solid understanding about the deployment and consumption of Web Services in Apache Geronimo.
Also Look at the way Geronimo simplified our lives by creating all the necessary files automatically when we deploy the application.

Powered by Atlassian Confluence (Version: 2.2.9 Build:#527 Sep 07, 2006) - Bug/feature request

Unsubscribe or edit your notifications preferences