Débuter avec jax-RS (Rest)

Le WebService est l’une des technologie la plus répandue pour offrir la possibilité à d’autres applications de pouvoir s’interfacer.

Depuis longtemps les WebServices se reposent sur la technologie SOAP. De plus, suivant la technologie ou le framework utilisé, un WebService peut avoir des performances et un comportement différent sans parler des problèmes interopérabilités.

Depuis Java EE6 un nouveau composant est inclut dans la specification : JAX-RS (JavaTM API for RESTful Web Services, JSR-311) connu sous le nom de Jersey

Qu’est ce qu’un WebService RESTful?

Un Service Web REST (Representational State Transfer) n’est ni un protocole, ni un format, c’est une architecture basée sur les standards du  protocole HTTP.

Vous accédez à une ressource via son URI et vous pouvez changer l’état de cette ressource en utilisant les méthodes natives de HTTP (GET, POST, PUT et DELETE).
En voici les principes simples :

  • L’URI suffit pour nommer et identifier une ressource.
  • Grâce au protocole HTTP nous disposons essentiellement des opérations suivantes GET, POST, PUT et DELETE.
  • Chaque opération est auto suffisante (stateless), chaque requête doit comporter toutes les indications nécessaires pour son exécution et ne doit pas s’appuyer sur un contexte stocké sur le serveur.
  • Utilisation de type mime : HTML, XML, TEXT, JSON ETC…

Voici la correspondance des différentes opérations entre le SQL et les opérations HTTP :


SUN + REST = Jersey

Jersey est produit par SUN et implémente la bibliothèque JSR-311 pour permettre aux développeurs de mettre en oeuvre des services REST

Cet article détaille les différentes étapes pour mettre en place un service REST.

1. Creation du Projet
 mvn archetype:create -DgroupId=com.webservice -DartifactId=WebServiceRest -Dpackagename=com.webservice

Ajoutez les dépendances suivantes dans le pom.xml

        <dependency>
            <groupId>com.sun.jersey</groupId>
            <artifactId>jersey-server</artifactId>
            <version>1.1.5</version>
        </dependency>
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>servlet-api</artifactId>
            <version>2.4</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>javax.ws.rs</groupId>
            <artifactId>jsr311-api</artifactId>
            <version>1.1.1</version>
            <scope>provided</scope>
        </dependency>

Une fois le projet mis en place nous allons configurer la webapp afin qu’elle gère les services REST

Ajoutez la déclaration suivante dans le descripteur global de déploiement web.xml :

    <servlet>
        <servlet-name>Jersey Servlet</servlet-name>
        <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
        <init-param>
            <param-name>com.sun.jersey.config.property.packages</param-name>
            <param-value>com.webservice</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>Jersey Servlet</servlet-name>
        <url-pattern>/rest/*</url-pattern>
    </servlet-mapping>

Dans la déclaration ci-dessus nous indiquons  :

  • Au container que les URI /rest/* seront des servlets REST.
  • les packages contenants les servlets (balise param-value)

Maintenant que notre webapp est capable de gérer REST nous allons créer une classe qui sera l’implémentation de notre Service REST.

Créez la classe HelloService avec le code suivant :

package com.webservice;

import javax.ws.rs.*;

/**
 * @author srenno
 */
@Path("helloservice")
public class HelloService {

    @GET
    @Path("hello")
    @Produces("application/xml")
    public String getHello() {

        return "Hello World!";
    }

    @GET
    @Path("echo")
    @Produces("application/xml")
    public String getEcho(@DefaultValue("") @QueryParam("echo") String pEcho) {
        return "Hello " + pEcho;
    }
}

Explication des différentes annotations :
  • @Path(“helloservice”) :
    • Déclaration sur le nom de la classe : Après compilation et déploiement dans un conteneur de Servlets votre servlet sera disponible via l’url suivante : http://localhost:8080/WebServiceRest/rest/helloservice. Cependant cela n’est pas suffisant la déclaration doit aussi figurer sur le nom de méthodes.
    • Déclaration sur les noms de méthodes : Ceci permet de definir l’URI de la méthode dans notre cas @Path(“hello”) fournira la ressource à l’endroit suivant : http://localhost:8080/WebServiceRest/rest/helloservice/hello
  • @GET : Définit le type d’opération
  • @Produces : Permet de définir le type mime de retour.
  • @QueryParam : Cette annotation permet l’injection de paramétres à une méthode. Dans notre exemple echoParam définit le nom de l’argument  fournit en entrée  de la méthode getHello(String)

Dans la configuration ci-dessus nous avons donc les ressources suivantes :

http://loaclhost:8080/WebServiceRest/rest/helloservice/hello

http://loaclhost:8080/WebServiceRest/rest/helloservice/echo?echo=Omer

Voila votre service rest opérationnel.

Source de l’article WebServiceRest

svn checkout http://captain-expresso.googlecode.com/svn/trunk/WebServiceRest

Le projet utilise le plugin maven-embedded-glassfish-plugin-3.0.

Une fois le plugin installer effectuer mvn clean install -Pdebug

About Sébastien Renno