Monday, December 13, 2010

A Jersey REST Example with Maven

I finally got around to trying out Jersey for REST services.  Below is an end-to-end example that will build a war file that can be deployed into a Tomcat server.  I'm using Java 1.6 and Tomcat 6.0.20.

Assumption: I will assume you can create and compile a project with Apache Maven.  I used Maven 2.2.1 below.

Installing: Jersey doesn't have to be installed in a conventional sense.  You just need to have the correct jars in your web application's $CLASSPATH.  Maven will automate this for you.  Here is your POM file:

<project xmlns="" xmlns:xsi="" xsi:schemaLocation="">
<!--These are needed for Jersey -->
<name> Repository for Maven</name>
<name> Maven 1 Repository (legacy)</name>
<!-- These are the Jersey dependencies -->

Configuring: There seem to be a few options for your web.xml file.  The following worked for me.  You have to change the line in bold.
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
<servlet-name>Jersey Web Application</servlet-name>
      <--You need to change this line to match your package name -->
<servlet-name>Jersey Web Application</servlet-name>

The Code: The following is a simple Java code that takes supports both GET and POST operations with arbitrary key-value pairs.  It doesn't however support parameters with multiple values.  I show a sample code snippet below.  From other examples that I've seen, the UriInfo class seems to be the easiest way to get a Map of the request parameters with GET methods.  With POST, you have more direct access to the map.
//This package declaration should match what you used in the web.xml above.
package org.yourproject.restservices;
//These are Jersey jars

import java.util.Iterator;
@Path("/echo") public class MyService{
   public String get(@Context UriInfo ui) {
      MultivaluedMap queryParams=ui.getQueryParameters();
      return showQueryParams(queryParams);   
   public String post(MultivaluedMap queryParams) {
return showQueryParams(queryParams);  
   //Extract the parameters.  
   protected String showQueryParams(MultivaluedMap queryParams) {
Iterator it=queryParams.keySet().iterator();
String theKey=null;
String returnString="";
try {
      while(it.hasNext()) {
      returnString += URLEncoder.encode(theKey,"UTF8")
                 +"  "
catch (Exception ex) { 
   //This will probably be an UnsupportedEncodingException.
           //Handle more approrpriately. 
return returnString;


Compile and Invoke: Use "mvn clean install" to generate a war file, then copy this from your project's target directory to a waiting Tomcat server.  Better yet, add the clean up and installation code to your POM using Ant tasks.  

You can invoke this service any number of ways: directly call it in a web browser, write an HTML page that uses it as a FORM action, or invoke on the command line with curl or wget.  Here is a curl example that uses POST:

curl -d "hollow=world&true=false"


Clint Wilde said...

Great tutorial. Thanks alot.

Pradeep Kumar TR said...

This was really helpful. Thanks.

Rodrigo HJORT said...

Excellent tutorial, Marlon! Really helped me out.

Andrea said...

Great! thanks for the help!

Unknown said...

no real reason to use "mvn clean install" ... install puts the artifact in your repository. Unless you really want it there just use "mvn clean package"