Du POJO au JSON grâce aux annotations JAX-RS

JAX-RS est l’acronyme pour Java API for RESTFul Services.

Cette API (Application Programming Interface) met à disposition des annotations pour créer simplement des services REST.

1. Les bases

Une fois choisie et ajoutée dans votre projet, l’implémentation de JAX-RS, la première étape est de choisir la méthode HTTP qui appellera telle ou telle méthode de votre application.

a. Choix de la méthode HTTP

Bien que le protocole HTTP soit large, comme vu dans le chapitre Introduction à REST, les méthodes prises en charge dans JAX-RS se limitent aux méthodes OPTIONS, HEAD, GET, POST, PUT et DELETE. Vous ne pourrez donc pas utiliser PATCH, LINK, UNLINK, TRACE et CONNECT.

Les annotations suivantes sont disponibles :

@OPTIONS pour connaître les méthodes implémentées.
@HEAD pour connaître les en-têtes d’une ressource.
@GET pour récupérer une ressource.
@POST pour créer une ressource.
@PUT pour modifier une ressource.
@DELETE pour supprimer une ressource.

Ces annotations sont à positionner dans la classe, non pas à la déclaration de la classe, mais à la déclaration de la méthode qui sera exécutée.

@HEAD

Il est à noter qu’il n’est pas obligatoire d’implémenter la méthode HEAD. Pour répondre à une requête HEAD envoyée au service REST, JAX-RS regarde s’il y a une méthode avec l’annotation @HEAD, et si la méthode n’existe pas, c’est la méthode avec l’annotation @GET qui est automatiquement exécutée, mais son corps ne sera pas renvoyé. Cependant, les performances peuvent être moindres dans ce cas.

@OPTIONS

Comme pour l’annotation @HEAD, il est possible mais non obligatoire d’implémenter manuellement la méthode OPTIONS à l’aide de l’annotation @OPTIONS. Si la méthode n’existe pas, le résultat sera généré automatiquement à l’aide des méthodes définies dans la classe appelée.

b. Choix du chemin d’appel

Une fois votre méthode choisie, il reste à déterminer l’URL qui sera appelée. Elle sera relative à...

Implémentations de JAX-RS

Dans les pages qui suivent, vont être abordées trois implémentations de JAX-RS : Jersey, Apache CXF et JBoss RESTEasy.

1. Jersey

Jersey est une librairie pour Java dont le but est de simplifier la création de services web de type RESTful, par le biais de l’implémentation de JAX-RS et plus spécifiquement, les JSR (Java Specification Requests) 311 et 339.

Le projet se situe à cette adresse : https://jersey.java.net/

a. Création d’un projet fonctionnant avec Jersey

Jersey est un projet fonctionnant avec Maven. En partant du principe que Maven est installé sur votre poste, voici comment créer, sous l’IDE (Integrated Development Environment) Eclipse, un projet utilisant Jersey.

Dans votre console, déplacez-vous dans le répertoire qui contiendra votre projet.

Tapez ensuite :


mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart- 
webapp -DarchetypeGroupId=org.glassfish.jersey.archetypes 
-DinteractiveMode=false -DgroupId=com.book -DartifactId=jersey- 
service -Dpackage=com.book.chapter4 -DarchetypeVersion=2.7

Cela va créer un projet JEE, sous le modèle d’une application fonctionnant avec Jersey.

Par défaut, il se nommera jersey-service, et le groupe Maven sera nommé com.book. La commande Maven va aussi créer un premier package com.book.chapter4.

Vous pouvez modifier ses trois valeurs si vous le souhaitez.

Ensuite, il vous faut vous déplacer dans le répertoire nouvellement créé et lancer la commande suivante :


mvn eclipse:eclipse -Dwtpversion=2.0

Maven va donc transformer le projet en un projet directement utilisable sous Eclipse.

Il reste alors à ouvrir Eclipse et à sélectionner le projet dans le menu File - Import - Existing projects into workspace puis à vous laisser guider.

N’oubliez pas, si vous comptez, dans votre projet, ne pas uniquement faire des requêtes REST, de changer le web.xml afin de changer le mapping. Ce conseil est aussi valable si vous voulez personnaliser votre page d’erreur.

Dans les exemples de ce livre, le mapping a été modifié au bénéfice du suivant :


<servlet-mapping> 
    <servlet-name>Jersey Web Application</servlet-name> 
    <url-pattern>/rest/*</url-pattern> ...

Classes concrètes et interfaces

Il est d’usage courant de scinder le code d’une application entre interfaces et classes d’implémentation. Dans le cas d’un service REST, l’interface est le lieu où les annotations (@Path, @GET, @Produces...) sont ajoutées, afin de séparer la couche d’implémentation de la couche web.

Voici l’interface de service des titres de musique. Chaque définition de méthode est précédée de l’annotation correspondant à la méthode HTTP qui provoquera son appel.


@Path("/TitreMusique") 
public interface IServiceTitreMusique { 
 
    @GET 
    @Path("{identifiant}") 
    @Produces(MediaType.APPLICATION_JSON) 
    TitreMusique getTitre( 
        @PathParam("identifiant") final int identifiant 
    ); 
 
    @POST 
    @Produces({MediaType.APPLICATION_JSON}) 
    @Consumes(MediaType.APPLICATION_JSON) 
    Response postTitre(final TitreMusique titreMusique); 
 
    @PUT 
    @Path("{identifiant}") 
  ...

Sécurité avec JAX-RS

À moins d’avoir développé deux applications hébergées sur le même serveur et d’interdire les appels aux méthodes REST depuis l’extérieur, il faut obligatoirement mettre en place une sécurisation de l’accès aux données et à leurs modifications.

Que ce soit sous Jersey, Apache CXF ou JBoss RESTEasy, des solutions existent.

1. Authentification

a. Apache CXF et l’authentification basique

Une méthode d’authentification qu’il est possible de mettre en place est équivalente à celle qui serait présente sur un serveur tournant avec Apache qui aurait une configuration de type AuthType Basic avec un fichier listant les mots de passe.

La première étape consiste à créer une implémentation de RequestHandler. Cette implémentation vérifiera la validité du nom d’utilisateur et du mot de passe fournis. En cas d’erreur, le serveur demandera une nouvelle authentification. La méthode handleRequest est la méthode invoquée à la réception d’une requête.


public class AuthenticationHandler implements RequestHandler { 
 
    @Override 
    public Response handleRequest( 
        final Message message,  
        final ClassResourceInfo resourceClass 
    ) { 
        final AuthorizationPolicy police  
                = (AuthorizationPolicy) 
                       message.get(AuthorizationPolicy.class); 
 
        if (police == null) { 
            return echec(); 
        } 
        final String nomDUtilisateur = police.getUserName(); 
        final String motDePasse = police.getPassword(); 
 
        if (verifie(nomDUtilisateur, motDePasse)) { 
            return null; 
        } 
 
        return echec(); 
    }

La méthode echec retourne un code d’erreur...

Production de JSON avec Java et REST