Mini Tutorial : REST Web Service avec JBoss RESTEasy

Voici un mini tutorial sur JBoss RESTEasy, l'implementation de JAX-RS 1.2.GA de JBoss avec le serveur JBoss 5.1. Ce mini tutorial est directement inspiré de l'excellent tutoriel de Damien Gouyette : Exposer un service crud RESTul avec JBoss RESTasy  http://dgouyette.developpez.com/tutoriels/java/exposer-service-crud-restful-avec-jboss-resteasy/

J'ai eu quelques misères à en faire fonctionner les sources et à récupérer les bonnes versions des bibliothèques sous maven avec netbeans,  aussi en m'inspirant des sources de Damien Gouyette j'ai eu l'idée de me faire un mini projet pilote, un genre de CRUD sans le C ni le U, ni le D, bref juste un READ, c a d un GET dans le monde REST.

Et finalement j'en fait un mini tutorial que je poste sur mon blog. Les sources complètes du projet sous maven sont disponible à la fin de l'article dans un zip.

L'objet de tutorial est de faire un appel Rest GET de la forme : http://localhost:8080/RestEasyTutorial/rest/hello/bill .

il s'agit de l'appel d'une des ressources des services REST du site http://localhost:8080/RestEasyTutorial . La ressource se nomme hello et l'identifiant est bill dans cet exemple. Cet appel va retourner hello bill. 

La déclaration des ressources se fait via des annotations dans une classe Java :

package com.davidgimelle.tutorial.resteasyread;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.core.Response;

@Path("hello")
public class HelloWorld {

    @GET
    @Path("/{qui}")
    public Response echoService(@PathParam("qui") String message) {
        return Response.status(200).entity("hello "+message).build();
    }

}

- L'annotation @Path sur la classe détermine le nom de la ressource.

- @GET précise quelle méthode sera appelée en cas de requête Http GET sur cette ressource.

- @Path sur la méthode précise la forme des paramètres sur la ressource

- @PathParam précise quel paramètre va être utilisé dans la méthode

Ces classes de ressources REST doivent être déployées dans une application web. Cette application web nécessite un fichier web.xml qui va définir comment est configurer RESTEasy :

<?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">
    <display-name>RestEasyTutorial</display-name>
   

   <context-param>
      <param-name>resteasy.scan</param-name>
      <param-value>true</param-value>
   </context-param>

    <context-param>
        <param-name>resteasy.servlet.mapping.prefix</param-name>
        <param-value>/rest</param-value>
    </context-param>

    <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>/rest/*</url-pattern>
    </servlet-mapping>

</web-app>

- Le context-param resteasy.scan à true signifie que les sources du war vont être scannées à la recherche des annotations RESTEasy pour publier les ressources automatiquement lors du démarrage de l'application.

- Le servlet-mapping RESTEasy avec la valeur /rest/* précise que tous les appels de cette forme sont à destination de RESTEasy.

Les dépendances maven nécessaires au bon fonctionnements de RESTEasy sont les suivantes :

    <repositories>
        <repository>
            <id>jboss</id>
            <url>http://repository.jboss.com/maven2/</url>
        </repository>
    </repositories>

    <dependencies>

        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>servlet-api</artifactId>
            <version>2.5</version>
            <scope>provided</scope>
        </dependency>

        <dependency>
            <groupId>org.jboss.resteasy</groupId>
            <artifactId>resteasy-jaxrs</artifactId>
            <version>1.2.GA</version>
        </dependency>

    </dependencies>

Le repository http://repository.jboss.com/maven2/ permet de télécharger la dépendance resteasy-jaxrs.

Ce mini tuto est terminé. Vous pouvez tétécharger les sources du projet maven complet de ce mini tuto ici.

N'oubliez pas de suivre le tutorial de Damien Gouyette pour bien comprendre comment fonctionne REST, comment faire un CRUD et surtout comment faire des tests automatisées des services RESTEasy. On ne test jamais assez. !

Sources : http://www.davidgimelle.com/src/RestEasyReadTutorial-src.zip

Testé le 10 juin 2010 avec :

resteasy-jaxrs 1.2.GA, JBoss 5.1.0.GA, Java jdk 1.5_20, maven 2.0.9 et netbeans 6.7.1

Références :

Le tutorial de Damien Gouyette : http://dgouyette.developpez.com/tutoriels/java/exposer-service-crud-restful-avec-jboss-resteasy/

JBoss RestEasy : http://www.jboss.org/resteasy

Rest dans wikipedia : http://en.wikipedia.org/wiki/Representational_State_Transfer

Pour acheter des objets RestEasy : http://www.cafepress.co.uk/jbossorg/7097895