Page History

{scrollbar}
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.

{info:title=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.
{info} 

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)
* Eclipse 3.3.1.1 (Eclipse Classic package of Europa distribution), which is platform specific
* Web Tools Platform (WTP) 2.0.1
* Data Tools Platform (DTP) 1.5.1
* Eclipse Modeling Framework (EMF) 2.3.1
* Graphical Editing Framework (GEF) 3.3.1

Details on installing eclipse are provided in the [Development environment] section. This tutorial is organized in the following sections:
{toc}
This tutorial will take you through the following steps:
h2. Setting Up Eclipse for Application Development
# Create a Dynamic Web Project
#* Select *File->New->Project*
\\ \\ \\ !1.gif! \\ \\ \\ 
#* In the popup window, Select *Web->Dynamic Web Project* category and click *Next*
\\ \\ \\ !2.gif! \\ \\ \\
#* Type *jaxws-converter* as the *Project Name* and click *Next*..
\\ \\ \\ !3.gif! \\ \\ \\
#* The default options should work in the case of Geronimo as it has axis2 web container already running, click *Next*
\\ \\ \\ !4.gif! \\ \\ \\
#* Make sure that the check box *Generate Deployment Descriptor* is selected and click *Next*
\\ \\ \\ !5.gif! \\ \\ \\
#* Modify the *Group Id* to *org.apache.geronimo.samples.jaxws* and the *artifact id* to *jaxws-converter*.
\\ \\ \\ !6.gif! \\ \\ \\
#*  Click *Finish*

This completes the configuration of Eclipse for application development.

h2. Creating the Web Services Implementation code

To deploy the Converter service we are going to create a POJO class and expose it as a servlet. The steps required are:
# Right click on *JavaRsources:src* and select *New->Package*
\\ \\ \\ !7.gif! \\ \\ \\
# Name the package to *org.apache.geronimo.samples.jaxws* and click *Finish*
\\ \\ \\ !8.gif! \\ \\ \\
# Right click on the new package and select *New->Class*
\\ \\ \\ !9.gif! \\ \\ \\
# Name the class as *Converter* and click *Finish*
\\ \\ \\ !10.gif! \\ \\ \\
# Add the following code to the Converter class
{code:title=Bar.java|borderStyle=solid}

package org.apache.geronimo.samples.jaxws;

import javax.jws.WebService;

@WebService(serviceName = "Converter",
            portName="ConverterPort",
            targetNamespace = "http://jaxws.samples.geronimo.apache.org"
            )
public class Converter
{
  public float celsiusToFarenheit ( float celsius )
  {
    return (celsius * 9 / 5) + 32;
  }

  public float farenheitToCelsius ( float farenheit )
  {
    return (farenheit - 32) * 5 / 9;
  }
}

{code}

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.

h2. 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

{info:title=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

{info} 

# Expand *WEB-INF* directory and add the following code to web.xml
{code:xml}

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://java.sun.com/xml/ns/javaee"
	xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
	id="WebApp_ID" version="2.5">
	<display-name>Converter</display-name>
	<servlet>
		<display-name>Converter</display-name>
		<servlet-name>Converter</servlet-name>
		<servlet-class>
			org.apache.geronimo.samples.jaxws.Converter
		</servlet-class>
	</servlet>

	<servlet-mapping>
		<servlet-name>Converter</servlet-name>
		<url-pattern>/converter</url-pattern>
	</servlet-mapping>

</web-app>

{code}

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

h2. Deploy and Test the Web Service

h4. Deploy
# Right click on the *Apache Geronimo* Server Runtime present in the servers view and select *Add or Remove Projects*
\\ \\ \\ !11.gif! \\ \\ \\
# In the popup dialog, select the *jaxws-converter* project and click *Add*
\\ \\ \\ !12.gif! \\ \\ \\
# Make sure that *jaxws-converter* is in the *configured projects* list and then click *Finish*
\\ \\ \\ !13.gif! \\ \\ \\
# Wait for some time till the server status is changed to synchronized.

h4. Testing
# Once the application is deployed on to the server, Launch a browser and go to the following url.
[http://localhost:8080/jaxws-converter/converter]
# Now you should see the screen telling that this is Converter Web Service
\\ \\ \\ !14.gif! \\ \\ \\
{info:title=WSDL File}
You can also view the WSDL file generated by Geronimo based on the annotations specified by going to the following url
[http://localhost:8080/jaxws-converter/converter?wsdl]
{info} 

h5. Using Web Services Explorer in Eclipse
# Go to *Eclipse* and *Run->Launch the Web Services Explorer* from the main menu.
\\ \\ \\ !15.gif! \\ \\ \\
# Click the *WSDL* icon to go to the *WSDL main page*.
\\ \\ \\ !16.gif! \\ \\ \\
# Click the *WSDL main* link to enter the URL of WSDL document.
\\ \\ \\ !17.gif! \\ \\ \\
# Enter the URL of our WSDL document i.e [http://localhost:8080/jaxws-converter/converter?wsdl] in the form and click *Go*
\\ \\ \\ !18.gif! \\ \\ \\
# Now you can see the methods that are exposed by our Web Service.
\\ \\ \\ !19.gif! \\ \\ \\
# Clicking on any method takes us to a page with form asking for input parameters.
\\ \\ \\ !20.gif! \\ \\ \\
# Enter any argument and examine the status frame at the bottom to see the result.
\\ \\ \\ !21.gif! \\ \\ \\

{dynamictasklist:thingsToDo}