...

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.

...

test the deployed web service by using the Web Services Explorer in Eclipse

...

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.

1. Sun JDK

...

1. 6.0+ (J2SE 1.

...

1. 6)
2. Eclipse IDE for Java EE Developers, which is platform specific
3. Apache Geronimo Eclipse Plugin 2.1.x

...

1. Apache Geronimo Server 2.1.x

   Geronimo version 2.1.x, Java 1.5 runtime, and Eclipse Ganymede are used is used in this tutorial but other versions can be used instead (e.g., Geronimo version 2.2, Java 1.6, Eclipse Europa)

...

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

...

...

Create a Dynamic Web Project to host the Web Service

1. From Eclipse main menu, select File -->New->Other> New --> Other.
   
   
2. In the New dialog, select Web ->Dynamic -> Dynamic Web Project and click Next.
   
   
3. Type jaxws-converter as the Project Name and click Next
4. On the Project Facets page, the default selections as shown below are enough (Geronimo has an embedded Axis2 container already running) and click Next
   Image Removed
5. .
   
   
6. Make sure that the check box Generate Deployment Descriptor is selected and click Next.
   
   
7. On the Geronimo Deployment Page modify the Group Id to org.apache.geronimo.samples.jaxws and the Artifact Id to jaxws-converter.
   
   
8. Click Finish

Add the POJO Interface

...

and Class that

...

implements the Web Service

1. In Project Explorer view, expand jaxws-converter project, right-click on Java Resources: src and select New ->Package-> Package.
   
   
2. Specify org.apache.geronimo.samples.jaxws as the package name and click Finish.
   
   
3. Right-click on the new package and select New ->Interface-> Interface.
   
   
4. Name the interface as Converter and click Finish.
   
   
5. Add the following code to the Converter interface Code Blocktitle: Converter.javaborderStylesolid package org.apache.geronimo.samples.jaxws; import java.math.BigDecimal; import javax.jws.WebService; @WebService(name="ConverterPortType", targetNamespace = "http://jaxws.samples.geronimo.apache.org") public interface Converter { public BigDecimal dollarToRupees(BigDecimal dollars); public BigDecimal rupeesToEuro(BigDecimal rupees); }
6. Right-In Project Explorer view, right click on the new package and select New -->Class> Class.
   
   
7. Name the class as ConverterService, add org.apache.geronimo.samples.jaxws.Converter as Interface the interface and click Finish.
   
   
8. Add the following code to the ConverterService class Code Blocktitle: ConverterService.javaborderStylesolid package org.apache.geronimo.samples.jaxws; import java.math.BigDecimal; import javax.jws.WebService; @WebService(serviceName = "Converter", portName = "ConverterPort", endpointInterface = "org.apache.geronimo.samples.jaxws.Converter", targetNamespace = "http://jaxws.samples.geronimo.apache.org" ) 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); } }
9. Let us try to understand each annotation:
   
   

• @WebService - This 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 specified the user defined class name for of 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 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 don't use this annotation all the public methods will be exposed as WebService.
  
  
• @WebParam - This 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 wsdlWSDL.

Expose the Web Service as a Servlet in web.xml

...

1. In Project Explorer view, double-click on jaxws-converter --> WebContent ->WebContent->WEB> WEB-INF -->web> web.xml to open it in an editor and add the following <servlet> and <servlet-mapping> elements inside it.

...

1. 
   xml

...

1. <?xml

...

1. version="1.0"

...

1. encoding="UTF-8"?>

...

1. <web-app

...

1. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

...

1. xmlns="http://java.sun.com/xml/ns/javaee"

...

1. xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"

...

1. xsi:schemaLocation="http://java.sun.com/xml/ns/javaee

...

1. http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"

...

1. id="WebApp_ID"

...

1. version="2.5">

...

1. <display-name>jaxws-converter</display-name>

...

1. <servlet>

...

1. <display-name>Converter</display-name>

...

1. <servlet-name>Converter</servlet-name>

...

1. <servlet-class>

...

1. org.apache.geronimo.samples.jaxws.ConverterService

...

1. </servlet-class>

...

1. </servlet>

...

1. <servlet-mapping>

...

1. <servlet-name>Converter</servlet-name>

...

1. <url-pattern>/converter</url-pattern>

...

1. </servlet-mapping>

...

1. </web-app>

...

Deploy the Web Service

...

...

1. In Servers view, right-click on Apache Geronimo Server Runtime and select Add and Remove Projects.
   
   
2. In the popup dialog, select jaxws-converter project, click Add, and then click Finish
   . Start the Geronimo server if it is not already running. The Web Service will now be deployed, and Geronimo will create the required .wsdl WSDL and other required artifacts.
   
   
3. Once the Web Service is deployed on to the server (Server Status says Synchronized), launch a browser and go to the following url:
   
   http://localhost:8080/jaxws-converter/converter.
   
   You should see a message from Axis2 engine as below:
   Image Removed
   Image Added
   
   
4. You can also view the WSDL file generated by Geronimo by going to the following url:
   
   http://localhost:8080/jaxws-converter/converter?wsdl

...

1. 
   
   Generated files by Geronimo

   Geronimo processes the annotations in source files and automatically generates the required artifacts to deploy the Web Service.

   You can see the Geronimo created files in the directory <INSTALL_DIR>/repository/org/apache/geronimo/samples/jaxws/jaxws-converter/1.0/jaxws-converter-1.0.car/. 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.

...

...

Geronimo has

...

a built-in

...

plug-in

...

named jaxws-

...

tools which provides tools for generating WSDL and other

...

necessary files used in JAX-WS web services. The plug-in relies on Sun's wsgen and wsimport tools to generate the web services artifacts. Please see wsgen or wsimport documentation for more information.

Test the Web Service using Eclipse

...

Web Services Explorer

1. From Eclipse's main menu, click Run -->Launch > Launch the Web Services Explorer.
   
   
2. The Web Services Explorer will open up as shown below:
   Image Removed
   Image Added
   
   
3. On the top right corner of this explorer, click on the icon for "WSDL Page". Under the Navigation frame, you will now see WSDL Main (instead of UDDI Main). Click that WSDL Main link and the Actions frame would will show a form as below:
   Image Removed
   Image Added
   
   
4. Enter the URL of your 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 your Web Service.
   Image Removed
   Image Added
   
   
5. Clicking on any method would will take you to a form asking for input parameters. If you don't see any field to enter input arguments click Add.
   Image Removed
   Image Added
   
   
6. Enter the input arguments and click Go. You can see the output of the Web Service in the Status frame at the bottom.
   Image Removed

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

...

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
	pageEncoding="ISO-8859-1"%>
<html>
<head>
<title>Converter</title>
<meta content="text/html; CHARSET=iso-8859-1" http-equiv="Content-Type">
</head>

<body>
<center>
<h3>This from invokes a Web Service.</h3>
<br>
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>
<br>
</center>
</body>
</html>

...

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
	pageEncoding="ISO-8859-1"%>
<%@page import="java.net.URL"%>
<%@page import="javax.xml.namespace.QName"%>
<%@page import="java.math.BigDecimal"%>
<%@ page import="javax.xml.ws.Service"%>
<%@ page import="org.apache.geronimo.samples.jaxws.Converter"%>
<html>
<head>
<title>Converter</title>
<meta content="text/html; CHARSET=iso-8859-1" http-equiv="Content-Type">
</head>
<body>
<%
	String amount = request.getParameter("amount");

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

		out.println("<center>");

		try {
			BigDecimal dollars = new BigDecimal(amount);
			URL url = new URL(
					"http://localhost:8080/jaxws-converter/converter?wsdl");
			QName qname = new QName(
					"http://jaxws.samples.geronimo.apache.org",
					"Converter");
			Service service = Service.create(url, qname);
			Converter conv = (Converter) service
					.getPort(Converter.class);
			BigDecimal rupees = conv.dollarToRupees(dollars);
			BigDecimal euros = conv.rupeesToEuro(rupees);

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

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

		out.println("<center>");
	}
%>
</body>
</html>

This concludes the development section of our web based client.

Deploying and Testing the Web Client

Deploy

...

Testing

...

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

...

package org.apache.geronimo.samples.jaxws;

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.math.BigDecimal;
import java.net.URL;

import javax.xml.namespace.QName;
import javax.xml.ws.Service;

public class ConverterClient {
	public static void main(String args[]) {
		try {
			BufferedReader dataIn = new BufferedReader(new InputStreamReader(System.in));
			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("http://jaxws.samples.geronimo.apache.org","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) {
			e.printStackTrace();
		}
	}

}

This completes the development section of our POJO client

Adding necessary jar files to the class path

...

...

1. 
   Image Added
   
   

This completes the process of deploying the web service to Geronimo and testing it. You can also refer to the following tutorial to develop a actual client for a web service that is already deployed on Geronimo Developing Clients for a JAX-WS Web Service

This completes the adding external JARs to the project

Testing

...

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.