RESTful webservices running on JBoss

JBoss provides a simple way to implement REST webservices, this page explains how to use the RestEasy library.

What is REST ?

REST stands for REpresentational State Transfer, it is based on HTTP/1.1.

A RESTful web service is a simple web service implemented using HTTP and the principles of REST. It is a collection of resources, with three defined aspects:

the base URI for the web service, such as http://gazelle.ihe.net/RetrieveValueSet
the Internet media type of the data supported by the web service.
the set of operations supported by the web service using HTTP methods (e.g., POST, GET, PUT or DELETE).

Pre-requisites

Implementing RESTful web services with RestEasy for a use on JBoss requires JBoss-seam 2.2 or higher and JBoss 5 or higer.

Using RestEasy in a maven project

If you are about to use ReastEasy into a Gazelle maven project, a good way to proceed is to use gazelle-seam Maven project as a parent for your project. Note that version 1.11 of gazelle-seam artifact requires Jboss-seam 2.2.1.Final.

<parent>
<groupId>net.ihe.gazelle.maven</groupId>
<artifactId>gazelle-seam</artifactId>
<version>1.11</version>
</parent>

You EJB module needs to be dependant of jaxrs-resteay, a module from the JBoss community. You will also need to add a dependency to scannotation package. Add the following lines in the pom.xml file of your EJB module.

<dependency>
 <groupId>org.jboss.resteasy</groupId> 
<artifactId>resteasy-jaxrs</artifactId> 
<version>${version.resteasy}</version> 
</dependency> 
<dependency> 
<groupId>org.scannotation</groupId> 
<artifactId>scannotation</artifactId> 
<version>1.0.2</version> 
</dependency>

Using ${version.resteasy} instead of a static version number maintains the consistency between your project and the libraries supported by the version of JBoss-seam you use.

Implementation

As we do when implementing SOAP web services, adding some annotations in Java classes and interfaces is quitly enough to declare REST services. In addition of these annotations, some updates need to be done in the WEB-INF/web.xml file of your WAR module.

The most basic annotations are exposed here.

First of all, you can choose to customize the URI in which the service will be reachable using the @Path annotation. Note that the base URI ("/") is the base URL of the WAR module. That means that it refers to the main directory of your WAR archive. Then, for each method you will be able to customize the different parameters using either @QueryParam or @PathParameter.

Let's take an example. The project is named TestRest and the web interface will be reachable at http://localhost:8080/TestRest. We will first create a local interface to define two services (Test1 and Test2), the base URI of which will be /resteasy. Consequently, the service will be reachable at http://localhost:8080/TestRest/resteasy/Test1.

import javax.ejb.Local; 
import javax.ws.rs.GET; 
import javax.ws.rs.Path; 
import javax.ws.rs.Produces; 
import javax.ws.rs.QueryParam; 

@Local 
@Path("/") // base URI will be defined in the web.xml file 
public interface TestLocal {
/** 
* This method will return "Hello username" where username is the string given as parameter 
* To call this method the URL to use is http://localhost:8080/TestRest/resteasy/Test1?username=toto 
*/ 
@GET // HTTP GET method 
@Path("/Test1") // path of the service 
public String test1(@QueryParam("username") String username); 

/** 
 * This method will return "Welcome username" where username is the string given as parameter 
 * To call this method, the URL to use is http://localhost:8080/TestRest/resteasy/Test2/toto 
*/ 
@GET 
@Path("/Test2") 
public String test2(@PathParam("username") String username);
}

Then, you have to create the stateless bean wich implements this interface as you can show it below.

import javax.ejb.Stateless; 

@Stateless 
public class Test implements TestLocal { 

public String test1(String username) 
{ 
return "Hello " + username; 
} 

public String test2(String username) 
{ 
return "Welcome " + username; 
} 
}

Finally, you will have to update the web.xml file contained in your WAR module in order to bind this service and to declare filters. The lines to append to your file are available below.

<context-param>
<param-name>resteasy.jndi.resources</param-name> 
<param-value>TestRest/Test/local</param-value> 
<!--If you need to declare more than one resource, separate them by comas --> 
</context-param> 
<!-- The following lines are required only if you decide not to use the application base path as base URI for your REST services --> 
<context-param> 
<param-name>resteasy.servlet.mapping.prefix</param-name> 
<param-value>/resteasy</param-value> 
</context-param> 
<!-- end of optional lines --> 
<listener> 
<listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class> 
</listener> 
<servlet> <
servlet-name>Resteasy</servlet-name> 
<servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
</servlet> 
<servlet-mapping> 
<servlet-name>Resteasy</servlet-name> 
<url-pattern>/resteasy/*</url-pattern> 
</servlet-mapping>

Compile and deploy your application. You should be able to access the web interface at http://localhost:8080/TestRest and the RESTful webservices at http://localhost:8080/TestRest/resteasy

Further documentation

Full JBoss documentation concerning RestEasy is available here.

You are here

What is REST ?

Pre-requisites

Using RestEasy in a maven project