Creating a Web Service

In this homework, you will learn a simple way to construct REST style Web Services. This project will also introduce you to a new language called groovy, a Java-based scripting language, in which you will develop a simple mashup. The mashup you will be creating will take data about automobile recalls and mash it together with the Google chart service.

Prerequisites

You will need to use Eclipse, version 3.3.0 or later.
You will need to install IBM's Project Zero Eclipse Plugin. The best way to install is to follow the instructions here on how to install it using the eclipse update manager.

Part 1: Get Familiar with Project Zero

First, walk through the tutorial to become familiar with the basic concepts.

Import the Project

Since this project requires database access we have provided you with a pre-configured eclipse project with the necessary JDBC jars and some helper classes. To import this project into your workspace use the following steps.

Download the zipped version of the project here.
Unzip the project on your machine (NOT into the eclipse workspace).
Open eclipse and go to File => Import which will open a wizard.
In the wizard, select General => Existing Projects into Workspace and then click next.
Ensure the "select root directory" option is selected and click browse.
Browse to and select the location of the directory that was created as a result of unzipping and click choose.
Make sure the checkbox "Copy projects into workspace" is checked.
Click finish and the project should now be in your workspace.
Rename the project to SOC_Service_[unityID].

You will find that there are three java classes in the soc.recalls package and one groovy file in the app/resources folder. These should be the only files that you need and the remainder of the assignment will involve extending these files to develop your service.

Part 2: Setup the Service

Now it's time to create the service. The service will allow you to query for automobile recalls in a RESTful manner. The service endpoint will be http://localhost:8080/resources/Recalls (this is case-sensitive). The skeleton of the Web service is already created, as app/resources/Recalls.groovy, but it is up to you to complete it. For starters you must do the following...

Open the app/resources/Recalls.groovy file. You may want to read up on the groovy language if you haven't seen it before. You can write standard Java in a groovy file, but it also allows for other operations that are not allowed in a normal Java class.
You will need to be able to read in parameters from the request. The params that you need to support are the strings "make", "model", and "year". For instance, a valid invocation of the service might be http://localhost:8080/resources/Recalls?make=ford&model=mustang&year=2005, in which your service will return all recalls for 2005 Ford Mustangs.
- Make sure you handle error cases and output appropriate error messages. For example, you should require them to specify at least one search parameter.
After reading in the parameters, you will need to query the database for results. To assist you in querying that data you are provided with a helper class soc.recalls.RecallSearch, which contains a static search method that can be called by your service. This method queries an Apache Derby database with actual recall data (located in the RecallsDB folder of your eclipse project).
Put the recall objects into the soc.recalls.RecallResponse object.
Render the RecallResponse object as XML. You will need to reference the Project Zero documentation for this, as they allow your service to output plain text, XML, and JSON.
You should test your service using many different query combinations and then make sure you handle any exceptions you encounter.

NOTE: Don't worry about deploying the project outside of eclipse. To deploy you can right click on the project folder in eclipse and select Run As... => Project Zero Application.

Part 3: Google Charts

Google offers a REST service that generates charts (images) based on information supplied by a requester. You will utilize this service to create graphs that will be included in your response. Become familiar with Google charts API before attempting to generate the REST calls programatically.

You will generate 2 charts and include the URLs in the RecallResponse object, which will get translated into XML. Both charts will be pie charts and should contain only 6 slices. If more than 6 possible entries exist, choose the largest 5 entries and use the 6th entry as an OTHER entry that aggregates all entries that are not in the largest 5.

Chart 1: Manufacturer's Chart
- This chart will display the number of recalls (the recall reports not the affected attribute) for a given vehicle make with respect to the search parameters.
- The chart should be 400x100. Don't worry if in some situations the labels are cut off.
- The chart labels should correspond to each recall's make value.
Chart 2: Year Chart
- This chart will display the number of recalls (the recall reports not the affected attribute) for all vehicles per year with respect to the search parameters.
- The chart should be 400x100. Don't worry if in some situations the labels are cut off.
- The chart labels should correspond to each recall's modelYear value.

Each chart must have a label in the RecallResponse object since it is a map, so label them "manufacturer" and "year," respectively. The output of your service should look very similar to this xml snippet.

<recallresponse>
	<chartURLs>
		<year>http://chart.apis.google.com/chart?...</year>
		...
	</chartURLs>
	<recalls>
		<item index="0">
			...
			<make>NISSAN</make>
			...
			<model>XTERRA</model>
			<modelYear>2002</modelYear>
			...
		</item>
	</recalls>
</recallresponse>

Deliverables

Please zip and upload the Eclipse project folder called SOC_Service_[your unity id], using the project name for the zip file. Zipping the file should reduce the submission size to under 8MB.
Upload a README.txt file containing your name, unity id, and any special instructions for your submission.