This tutorial takes you through the steps that are required to consume Yahoo! REST Web Services. Although there isn't much for this tutorial to deal with any Geronimacal Issues, this clearly demonstrates the ease of developing or consuming REST service without any external tools compared to SOAP Web Services.

We will explore two REST services from many that are exposed by Yahoo! which are Yahoo! Search and Yahoo! Maps. You might need an appid to query the results from Yahoo Server. For the time being I have added my appid in the code wherever needed.

Yahoo! is one company which is very much in the support of RESTful Web Services. Many of the Yahoo! API's and Services are REST. Some examples are Search, Maps, Mail, Flickr, del.ico.us etc

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 steps required are:

Create a Dynamic Web Project to consume the Web Service

From Eclipse main menu, select File->New->Other
In the New dialog, select Web->Dynamic Web Project and click Next
Type jaxws-rest-yahoo as the Project Name and click Next
On the Project Facets page, the default selections are enough.
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.rest and the Artifact Id to jaxws-rest-yahoo.
Click Finish

Developing the Web based Client

Right Click the jaxws-rest-yahoo, and Select New->JSP
Name the jsp as index.jsp and click Finish
Add the following code to the index.jsp

index.jsp


<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
	pageEncoding="ISO-8859-1"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>My Yahoo! Search</title>
</head>
<body>
<center>
<h1>Yahoo! Web Search</h1>
<a href="maps.jsp">Search Yahoo! Maps</a> <br>
<br>
<fieldset><legend><b>Enter your query here</b></legend>
<table bgcolor="#CCC">
	<tr>
		<td>
		<form action="index.jsp">Search: <input type="text"
			name="query"> <input type="submit" value="Submit"></form>
		</td>
	</tr>
</table>
</fieldset>
</center>
<jsp:include page="/SearchHandler" />
</body>
</html>

Right click again and add another jsp named maps.jsp
Add the following code to maps.jsp

maps.jsp


<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
	pageEncoding="ISO-8859-1"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>My Yahoo! Maps</title>
</head>
<body>
<center>
<h1>Yahoo! Maps Search</h1>
<a href="index.jsp">Search Yahoo! Web</a> <br>
<br>
<fieldset><legend><b>Address Details</b></legend>
<form action="maps.jsp">
<table bgcolor="#ABC">
	<tr align="center">
		<td>Street: <input type="text" name="street"></td>
	</tr>
	<tr align="center">
		<td>City: <input type="text" name="city"></td>
	</tr>
	<tr align="center">
		<td>State: <input type="text" name="state"></td>
	</tr>
	<tr align="center">
		<td>Zip: <input type="text" name="zip"></td>
	</tr>
	<tr align="center">
		<td><input type="submit" value="Submit"></td>
	</tr>
</table>
</form>
</fieldset>
</center>
<jsp:include page="/MapHandler" />
</body>
</html>

Now we need to create the two servlets which will handle the requests generated by user.
Right click again and add a Servlet named ConverterHandler
Add the following code to ConverterHandler.java

SearchHandler.java


package org.apache.geronimo.jaxws.rest;

import java.io.IOException;
import java.io.InputStream;
import java.io.PrintWriter;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.xpath.XPath;
import javax.xml.xpath.XPathConstants;
import javax.xml.xpath.XPathExpressionException;
import javax.xml.xpath.XPathFactory;

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpStatus;
import org.apache.commons.httpclient.methods.GetMethod;
import org.w3c.dom.Document;
import org.w3c.dom.NodeList;
import org.xml.sax.SAXException;

public class SearchHandler extends javax.servlet.http.HttpServlet implements
		javax.servlet.Servlet {
	static final long serialVersionUID = 1L;

	public SearchHandler() {
		super();
	}

	protected void doGet(HttpServletRequest request,
			HttpServletResponse response) throws ServletException, IOException {

		PrintWriter out = response.getWriter();
		String query = request.getParameter("query");
		if (query != null) {
			out.println("<fieldset>");
			out.println("<legend><b>Results</b></legend>");
			query = query.replace(" ", "+");
			String requestquery = "http://api.search.yahoo.com/WebSearchService/V1/webSearch?appid=cW2Y0DPV34GoE6x.f"+
"JJQNp503kCIXUd21hrSIzSNF2GjZ1VkpMPdMuq6keXrJu2kKWnSMFY-&query="
					+ query + "&results=10";
			HttpClient client = new HttpClient();
			GetMethod method = new GetMethod(requestquery);
			int statusCode = client.executeMethod(method);

			if (statusCode != HttpStatus.SC_OK) {
				System.err.println("Method failed: " + method.getStatusLine());
			}
			InputStream rstream = null;
			rstream = method.getResponseBodyAsStream();
			Document queryresponse = null;
			try {
				queryresponse = DocumentBuilderFactory.newInstance()
						.newDocumentBuilder().parse(rstream);
			} catch (SAXException e) {
				e.printStackTrace();
			} catch (ParserConfigurationException e) {
				e.printStackTrace();
			}

			XPathFactory factory = XPathFactory.newInstance();
			XPath xPath = factory.newXPath();
			NodeList nodes = null;
			try {
				nodes = (NodeList) xPath.evaluate("/ResultSet/Result",
						queryresponse, XPathConstants.NODESET);
			} catch (XPathExpressionException e) {
				e.printStackTrace();
			}
			int nodeCount = nodes.getLength();
			for (int i = 0; i < nodeCount; i++) {
				String title = null;
				String summary = null;
				String url = null;
				String size = null;
				String cached = null;
				try {
					title = (String) xPath.evaluate("Title", nodes.item(i),
							XPathConstants.STRING);
					summary = (String) xPath.evaluate("Summary", nodes.item(i),
							XPathConstants.STRING);
					url = (String) xPath.evaluate("Url", nodes.item(i),
							XPathConstants.STRING);
					NodeList n = (NodeList) xPath.evaluate("Cache", nodes
							.item(i), XPathConstants.NODESET);
					for (int j = 0; j < n.getLength(); j++) {
						cached = (String) xPath.evaluate("Url", n.item(j),
								XPathConstants.STRING);
						size = (String) xPath.evaluate("Size", n.item(j),
								XPathConstants.STRING);
					}

				} catch (XPathExpressionException e) {
					e.printStackTrace();
				}
				out.print("<font size='4'><a href='" + url + "'>" + title
						+ "</a></font>");
				out.print("<br>" + summary);
				out.print("<br><font color='green'>" + url + "</font>");
				if (size != null) {
					out
							.print("<font color='blue'> - "
									+ (new Integer(size) / 1000)
									+ "k - </font> <a href='" + cached
									+ "'>Cached</a>");
				}
				out.println("<br><br>");

			}
			out.println("</fieldset>");
		}
	}

	protected void doPost(HttpServletRequest request,
			HttpServletResponse response) throws ServletException, IOException {
		doGet(request, response);
	}
}

Right click again and add a Servlet named MapHandler
Add the following code to MapHandler.java

MapHandler.java


package org.apache.geronimo.jaxws.rest;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.PrintWriter;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpStatus;
import org.apache.commons.httpclient.methods.GetMethod;

public class MapHandler extends javax.servlet.http.HttpServlet implements
		javax.servlet.Servlet {
	static final long serialVersionUID = 1L;

	public MapHandler() {
		super();
	}

	protected void doGet(HttpServletRequest request,
			HttpServletResponse response) throws ServletException, IOException {
		PrintWriter out = response.getWriter();
		String street = request.getParameter("street");
		String city = request.getParameter("city");
		String state = request.getParameter("state");
		String zip = request.getParameter("zip");
		String query = null;
		if (street != null)
			query += "street=" + street + "&";
		if (city != null)
			query += "city=" + city + "&";
		if (state != null)
			query += "state=" + state + "&";
		if (city != null)
			query += "zip=" + zip;
		if (query != null) {
			out.println("<fieldset>");
			out.println("<legend><b>Map View</b></legend>");
			query = query.replace(" ", "+");
			String requestquery = "http://local.yahooapis.com/MapsService/V1/mapImage?appid=cW2Y0DPV34GoE6x.f"
+"JJQNp503kCIXUd21hrSIzSNF2GjZ1VkpMPdMuq6keXrJu2kKWnSMFY-&amp"
					+ query;
			HttpClient client = new HttpClient();
			GetMethod method = new GetMethod(requestquery);
			int statusCode = client.executeMethod(method);

			if (statusCode != HttpStatus.SC_OK) {
				System.err.println("Method failed: " + method.getStatusLine());
			}
			InputStream rstream = null;
			rstream = method.getResponseBodyAsStream();
			BufferedReader br = new BufferedReader(new InputStreamReader(
					rstream));
			String line, url = null;
			int i = 0;
			out.println("<br><br><br><center>");
			while ((line = br.readLine()) != null) {
				if (i == 1 && line.contains("Result")) {
					url = line.substring(62, line.length() - 9);
					out.println("<img src='" + url + "' />");
				}
				i++;
			}
			out.println("</center>");
			br.close();
		}
		out.println("</fieldset>");

	}

	protected void doPost(HttpServletRequest request,
			HttpServletResponse response) throws ServletException, IOException {
		doGet(request, response);
	}
}

Here the servlet might notify that some imports are not resolved. We need to add two external jar files to resolve these errors.
The jar files that needed to be added in the build path are:
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

This concludes the development section of our web based client.

Setting Up the Deployment Plan

As two external jars have been added to the project's build path, One needs to specify them as dependencies so that at runtime application can resolve the classes.
Expand WebContent/WEB-INF directory and open geronimo-web.xml
Add the following code to geronimo-web.xml

geronimo-web.xml


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns8:web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.2"
	xmlns:ns2="http://geronimo.apache.org/xml/ns/deployment-1.2"
	xmlns:ns3="http://geronimo.apache.org/xml/ns/naming-1.2"
	xmlns:ns4="http://openejb.apache.org/xml/ns/openejb-jar-2.2" 
	xmlns:ns5="http://openejb.apache.org/xml/ns/pkgen-2.1"
	xmlns:ns6="http://geronimo.apache.org/xml/ns/j2ee/application-2.0"
	xmlns:ns7="http://geronimo.apache.org/xml/ns/security-2.0" 
	xmlns:ns8="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1"
	xmlns:ns9="http://java.sun.com/xml/ns/persistence"
	xmlns:ns10="http://geronimo.apache.org/xml/ns/j2ee/application-client-2.0">
	<ns2:environment>
		<ns2:moduleId>
			<ns2:groupId>org.apache.geronimo.samples.jaxws.rest</ns2:groupId>
			<ns2:artifactId>jaxws-rest-yahoo</ns2:artifactId>
			<ns2:version>1.0</ns2:version>
			<ns2:type>car</ns2:type>
		</ns2:moduleId>

		<ns2:dependencies>
			<ns2:dependency>
				<ns2:groupId>commons-codec</ns2:groupId>
				<ns2:artifactId>commons-codec</ns2:artifactId>
				<ns2:version>1.3</ns2:version>
				<ns2:type>jar</ns2:type>
			</ns2:dependency>
			<ns2:dependency>
				<ns2:groupId>commons-httpclient</ns2:groupId>
				<ns2:artifactId>commons-httpclient</ns2:artifactId>
				<ns2:version>3.0.1</ns2:version>
				<ns2:type>jar</ns2:type>
			</ns2:dependency>
		</ns2:dependencies>
	</ns2:environment>
	<ns8:context-root>/jaxws-rest-yahoo</ns8:context-root>
</ns8:web-app>

Deploy and test our custom built Yahoo!

Child pages

Consuming Yahoo! REST Web Services

Create a Dynamic Web Project to consume the Web Service

Developing the Web based Client

Setting Up the Deployment Plan