JAX-RS: At ease with REST

December 29th, 2009 by Henri Bezemer

In this post I will create a RESTful service using the JSR 311 JAX-RS implementation called Jersey on the GlassFish application server. This service will closely match the capabilities of the typical hello world demo. The focus of this post is to show how to develop a RESTful service with JAX-RS and Maven and how to deploy it on a J2EE application server like GlassFish.

Step 1 (optional): install Jersey on GlassFish 2.1

It is not necessary install Jersey on the application server. Instead the Jersey runtime libraries can be bundled together with the services in a WAR deployment file. However, if you decide to install Jersey, take the following simple steps:

  • launch the Update Tool (found in the GlassFish installation at updatecenter/bin/updatetool)
  • Select the Jersey software component and click Install.
  • The tool installs a number of jars in the GlassFish lib directory and documentation and examples in the jersey directory.
  • Restart GlassFish.

When I did the installation I ended up with Jersey version 1.1.4 (the version number can be verified by looking at this file: lib/jersey-bundle-1.1.4.jar).

Step 2: write the Maven POM

Here’s a Maven2 POM that will compile your RESTful services and package them in a WAR deployable file:

<project
	xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.zienit.simple</groupId>
	<artifactId>simplerest</artifactId>
	<packaging>war</packaging>
	<name>simplerest</name>
	<version>0.0.1-SNAPSHOT</version>
	<repositories>
		<repository>
			<id>maven-repository.dev.java.net</id>
			<name>Java.net Repository for Maven 1</name>
			<url>http://download.java.net/maven/1/</url>
			<layout>legacy</layout>
		</repository>
		<repository>
			<id>maven2-repository.dev.java.net</id>
			<name>Java.net Repository for Maven 2</name>
			<url>http://download.java.net/maven/2/</url>
		</repository>
	</repositories>
	<dependencies>
		<dependency>
			<groupId>junit</groupId>
			<artifactId>junit</artifactId>
			<version>3.8.1</version>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>com.sun.jersey</groupId>
			<artifactId>jersey-server</artifactId>
			<version>1.1.4</version>
			<scope>provided</scope>
		</dependency>
	</dependencies>
	<build>
		<finalName>simplerest</finalName>
		<plugins>
			<plugin>
				<artifactId>maven-compiler-plugin</artifactId>
				<configuration>
					<source>1.5</source>
					<target>1.5</target>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

First of all, at line 8 it is stated that we want Maven to produce a WAR file. Lines 11-23 define the repositories where Maven will download the Jersey artifacts from. Lines 31-36 define the dependency on the jersey-server artifact, version 1.1.4. Because the scope is set to provided (line 35), the Jersey jars will not be bundled with the produced WAR file. If you didn’t install Jersey on your application server, simply remove this line. Line 41-47 make sure that the Java code is compiled as version 1.5. This is needed to make use of annotations.

Step 3: write a RESTful java service

Here is the Java code:

package com.zienit.simplerest;

import javax.ws.rs.*;

@Path("/at-ease")
public class AtEase {

	@GET
	@Produces("text/html")
	public String hello() {
		return "<html><body>At Ease!</body></html>";
	}
}

The annotations make this thing fly. @Path describes the path where this RESTful resource can be found. This path will be appended to the path to the JAX-RS servlet (more on this later). The method hello() is associated with the HTTP GET operation on this resource at line 8. This method will produce content of mime-type “text/html”, in other words plain html (line 9).

Step 4: write the web.xml deployment descriptor

Here is the deployment descriptor:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
	<servlet>
		<servlet-name>jersey</servlet-name>
		<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
	</servlet>
	<servlet-mapping>
		<servlet-name>jersey</servlet-name>
		<url-pattern>/*</url-pattern>
	</servlet-mapping>
</web-app>

This web.xml simply maps a servlet, provided by Jersey, to a url pattern that matches any url.

Step 5: build and deploy

Let Maven build the WAR file from the Java source code:

mvn install

Deploy the generated simplerest.war file (which Maven creates in the target directory) on the application server. I use the GlassFish console to do this. Notice the context root of the deployed web application. On GlassFish the default context root is set to the name of the WAR file, in this case “simplerest”.

Step 6: test the RESTful service

Use your browser to get the RESTful resource at :

http://localhost:8080/simplerest/at-ease

where:

  • http://localhost:8080 is the url for your application server
  • simplerest is the context root for the web application and
  • /at-ease is the path defined by the @Path annotation in the Java code.

Since the resource is represented by plain html, it will directly show up in your browser: At Ease!

No Comments

Comments are closed.