TP3 - Partie 1 - Une bibliothèque - Mobilité des canaux

Remarque préalable : pour hériter d'annotations JAX-RS, il est nécessaire de respecter certaines règles, décrites dans la spécification de JAX-RS (voir ci-dessous un extrait). En pratique, nous définissons les annotations des méthodes dans les interfaces pour les hériter dans les classes, qui n'en comportent aucune au niveau des méthodes.

Extrait de la spécification de JAX-RS, version 2, section 3.6, Annotation Inheritance

JAX-RS annotations may be used on the methods and method parameters of a super-class or an implemented interface. Such annotations are inherited by a corresponding sub-class or implementation class method provided that the method and its parameters do not have any JAX-RS annotations of their own. Annotations on a super-class take precedence over those on an implemented interface. The precedence over conflicting annotations defined in multiple implemented interfaces is implementation specific. Note that inheritance of class or interface annotations is not supported.

Annoter l'interface Bibliotheque de manière à vérifier les propriétés suivantes. On utilisera les constantes de la classe configuration.JAXRS.

Remarque : pour importer ces constantes, préférer une directive d'importation statique, qui donne un accès direct aux constantes.

import static configuration.JAXRS.*;

• Chaque méthode est qualifiée par le type idoine de méthode HTTP. Cependant, la méthode chercher doit être qualifiée par PUT et non par GET, bien qu'elle soit pure et idempotente. En effet, une méthode PUT permet de transmettre des informations par le corps du message, contrairement à une méthode GET. Comme les informations qui nous intéressent constituent la description d'un livre, il est préférable de les transmettre par le corps du message plutôt que l'URL, via le chemin ou la requête.

• Les chemins relatifs d'accès aux méthodes sont les suivants :

  • chercher : vide
  • repertorier : catalogue, valeur de la constante SOUSCHEMIN_CATALOGUE

  Ainsi, si l'URI de la ressource est http://localhost:8080/Projet/bibliotheque, une URI sera par exemple : http://localhost:8080/Projet/bibliotheque/catalogue.

  (Pour indiquer un chemin C, on utilise l'annotation @Path("C").)

• Les données sont produites ou consommées au format application/xml, valeur de la constante TYPE_MEDIA.

  (Pour indiquer qu'un résultat est sérialisé suivant un certain format F, on utilise l'annotation @Produces(F) ou Consumes(F). On doit utiliser ici la constante TYPE_MEDIA comme argument.)

L'implémentation proposée, ImplemBibliotheque, implémente l'interface Bibliotheque mais aussi l'interface Archive, par l'intermédiaire de l'interface BibliothequeArchive.

Annoter la classe ImplemBibliotheque de manière à vérifier les propriétés suivantes.

• Cette ressource est un singleton.
• Le chemin relatif d'accès à la ressource est bibliotheque, valeur de la constante CHEMIN_BIBLIO.

A ce stade, il n'existe pas de relations entre la ressource principale, la bibliothèque, et ses sous-ressources, les livres. On aurait pu établir cette relation dans l'interface Bibliotheque, avec une méthode permettant d'obtenir un livre, étant donné son identifiant. Cependant, nous avons pris le parti de manipuler les livres de la biliothèque uniquement via leurs adresses, a priori quelconques puisque les livres peuvent être situés n'importe où. C'est pourquoi l'interface Bibliotheque ne renvoie que des hyperliens pointant vers des livres et ne propose pas de telle méthode permettant d'obtenir un livre. En revanche, l'interface Archive donne accès aux livres considérés comme des sous-ressources de la bibliothèque.

La ressource principale Archive contient donc des sous-ressources, les livres de type Livre. Une telle structure formée de ressources et de sous-ressources peut être définie statiquement, ce qui implique que toutes les ressources soient connues initialement. Si ce n'est pas le cas, elle doit être définie dynamiquement. Ici, l'archive est connue statiquement, mais ses sous-ressources livresques ne le sont pas, puisqu'elles sont ajoutées dynamiquement. Elles sont donc calculées à la demande, par une méthode, sousRessource, qui renvoie un livre étant donné un identifiant : c'est un accesseur à une sous-ressource (ou un sélecteur de sous-ressource). Il est à noter qu'une même méthode ne peut être à la fois la cible d'une requête (et donc annotée par une méthode Http) et l'accesseur à une sous-ressource. Il est nécessaire de déclarer deux méthodes : voir les méthodes sousRessource et getRepresentation, respectivement un accesseur à une sous-ressource et une méthode permettant d'obtenir une représentation.

Voir la section 3.4.1 de la spécification de JAX-RS, version 2.

• Annoter les méthodes des interfaces Archive et Livre de manière à vérifier les propriétés suivantes (en utilisant le cas échéant les constantes de la classe configuration.JAXRS).
  • Les méthodes Archive.getRepresentation, Archive.ajouter et Livre.getTitre sont annotées par une méthode HTTP.
  • Le chemin relatif (complétant l'URI de base http://localhost:8080/Projet/bibliotheque) permettant d'obtenir le titre du livre d'identifiant id est id/titre, où titre est la valeur de la constante SOUSCHEMIN_TITRE. Quelle méthode est alors exécutée ?
  • Le chemin relatif (complétant l'URI de base http://localhost:8080/Projet/bibliotheque) permettant d'obtenir la représentation du livre d'identifiant id est id. Quelle méthode est alors exécutée ?
  • Le chemin relatif pour l'ajout d'un livre est vide.
  • Les données produites sont au format XML, indiqué par la valeur TYPE_MEDIA.

Quelle est l'annotation qui prouve que les classes modele.ImplemLivre, infrastruture.jaxrs.HyperLien et infrastruture.jaxrs.HyperLiens sont traduisibles (marshallable) ?

Remarque : l'interface modele.Livre doit être annotée de la même manière.

Etudier la classe de configuration infrastructure.jaxb.FournisseurTraduction.

Les paramètres de chemin et les requêtes, des chaînes de caractères, doivent pouvoir être traduits en des identifiants ou des livres, et réciproquement. Définir dans les interfaces Livre et IdentifiantLivre une fonction fromString réalisant cette traduction.

Voir les explications consacrées au pilotage des traducteurs de données.

JAX-RS ne respecte pas les conventions habituelles concernant le statut HTTP des réponses, pour les requêtes POST renvoyant un objet, ni pour les requêtes GET ou PUT ne renvoyant rien (null ou une option Optional vide). C'est la raison pour laquelle nous développons des filtres.

Deux filtres, AdapterServeurReponsesGETNullEn404 et AdapterServeurReponsesPOSTCreated (du paquet infrastructure.jaxrs) sont fournis. Expliquer la transformation des messages que ces classes réalisent.

Annoter les méthodes de l'interface Archive lorsqu'elles doivent utiliser ces filtres.

Lorsqu'un client interroge une bibliothèque pour chercher un livre, il peut recevoir une réponse de statut 404, ce qui signifie que la requête a été infructueuse. Dans le code Java, nous avons choisi de traduire cette possibilité par le type de retour Optional<HyperLien<Livre>> pour la méthode chercher. Il est nécessaire de traduire les options côté serveur lors de l'envoi des réponses, côté client lors de la réception des réponses, par des filtres-intercepteurs. Commençons par le serveur.

• Définir dans le paquet infrastructure.jaxrs.annotations une annotation ReponsesPUTOption comme les annotations ReponsesPOSTCreated ou ReponsesGETNull404.
• Annoter la méthode chercher renvoyant une option dans Bibliotheque.
• Dans le paquet infrastructure.jaxrs, définir la classe AdapterServeurReponsesPUTOptionEn404OuValeur implémentant ReaderInterceptor et ContainerResponseFilter, et l'annoter par @Provider et ReponsesPUTOption pour établir la liaison entre les méthodes exposées comme services et l'utilisant (la méthode chercher en l'occurrence) et ce filtre-intercepteur.
  • Lui donner pour priorité Priorities.HEADER_DECORATOR.
  • Implémenter les méthodes suivant la spécification générale suivante : si l'option est vide, transformer la réponse en 404, sinon, remplacer l'entité par la valeur de l'option. Détaillons.
    • Dans la méthode aroundReadFrom, réaliser la traduction (unmarshalling) du corps du message, pour récupérer la description du livre (de type Livre pour simplifier), en utilisant la méthode proceed. Mémoriser ce livre dans une propriété du contexte passé en argument. Cette mémorisation permet la communication entre l'intercepteur et le filtre.

    • Dans la méthode filter, si l'entité est de type Optional<?>, alors la convertir en Optional<?>. Si l'option n'est pas présente, convertir la réponse en 404 à l'aide de la méthode convertirEn404, sinon, modifier l'entité en la valeur de l'option.

      private static String DESCRIPTION_LIVRE = "descriptionLivre";
      private void convertirEn404(
        ContainerRequestContext requete, ContainerResponseContext reponse) {
        System.out.println("recherche : 404 NOT FOUND !");
        String contenu = requete.getUriInfo().getRequestUri().toString();
        // Utilisation de la propriété pour récupérer la description du livre recherché.
        contenu = contenu + " - " + requete.getProperty(DESCRIPTION_LIVRE);
        reponse.setEntity(contenu, null, MediaType.TEXT_PLAIN_TYPE);
        reponse.setStatus(Response.Status.NOT_FOUND.getStatusCode());
      }
      

• Enregistrer ce filtre-intercepteur dans Service du paquet configuration. Si la classe est enregistrée, deux instances sont créées, l'une pour le filtre, l'autre pour l'intercepteur. Si une instance est enregistrée, elle joue le rôle de filtre et d'intercepteur simultanément. En l'absence d'état, ces deux situations sont équivalentes.

Voir la section "Communication entre les filtres et les intercepteurs" du cours JAX-RS - Filtres et intercepteurs.

Dans le fichier web.xml, à l'intérieur de l'élément servlet, référencer la définition du service dans la classe configuration.Service.

<init-param>
   <param-name>javax.ws.rs.Application</param-name>
   <param-value>configuration.Service</param-value>
</init-param>
<load-on-startup>1 </load-on-startup>

Etudier le code de cette classe. Cette configuration est propre à Jersey.

Lancer Tomcat. Tester avec un outil permettant de produire des requêtes http.

Alternative : lancer le serveur Grizzly (sur le port 8081), en exécutant l'application serveur.Lancement. L'adresse du serveur est fixée dans configuration.JAXRS et peut être modifiée.

Annoter les interfaces Bibliotheque et Archive conformément aux annotations côté serveur. Noter une différence : il est inutile de définir une annotation côté client pour un filtre (ou un intercepteur). En effet, pour les filtres côté client, la norme JAX-RS ne propose pas de mécanismes utilisant une annotation des méthodes. On doit configurer les cibles de type WebTarget par les filtres utilisés. Vérifier les annotations de l'interface Livre.

Vérifier que les classes ImplemLivre et ImplemIdentifiantLivre implémentent la méthode toString. Pourquoi est-ce indispensable ? Est-ce utile que les interfaces associées fournissent une fonction valueOf ou fromString ?

Bien noter que les implémentations des ressources ne sont pas utiles : on y accède via des proxys (de type BibliothequeArchive). Pour les sous-ressources de type Livre, une implémentation est nécessaire : en effet, on utilise à la fois des proxys vers des livres et des représentations complètes de livres.

Les filtres et les intercepteurs appartiennent au paquet infrastructure.jaxrs.

Un premier filtre-intercepteur AdapterClientReponsesPOSTCreated est fourni. Expliquer la transformation des messages qu'il réalise.

Pour les réponses de type 404 non liéés à une option, aucun filtre n'est prévu : il sera donc nécessaire de traiter les exceptions de type WebApplicationException.

En revanche, des filtres ou intercepteurs sont prévus pour traiter les types options.

• Un second filtre-intercepteur est fourni : la classe AdapterClientReponsesPUT404EnOption permet de transformer une réponse de statut 404 en une option vide si le type attendu est Optional. Etudier son code, et en particulier le rôle de la propriété ERREUR404 qui permet de relier le filtre à l'intercepteur.

Il reste à définir un intercepteur transformant une valeur en une option contenant cette valeur, lorsque le type attendu est Optional<?>.

• Définir un intercepteur AdapterClientReponsesPUTEnOption de type ReaderInterceptor, avec la priorité Priorities.HEADER_DECORATOR + 2, ce qui implique que cet intercepteur intervient après le précédent.
  • Dans la méthode aroundReadFrom, si le type de la réponse vaut Optional.class, alors :
    • récupérer le type générique de la réponse,
    • le convertir en un ParameterizedType,
    • récupérer son seul type argument (qui dans notre cas, sera HyperLien<Livre>),
    • modifier le type de la réponse en utilisant la fonction Types.convertirTypeEnClasse du paquet infrastructure.langage,
    • enfin, renvoyer Optional.of(reponse.proceed()) ;
    • sinon, renvoyer reponse.proceed(), autrement dit la traduction du document en objet (via la fonction unmarshalling).

Pour pouvoir utiliser ces filtres-intercepteurs, les enregistrer dans la configuration définie dans la fonction configuration.JAXRS.client. Pour le filtre-intercepteur, noter la différence entre l'enregistrement d'une instance et celle d'une classe : dans le premier cas, un seul filtre-intercepteur est créé, dans le second, un filtre et un intercepteur sont créés, ce qui pourrait poser problème si un état devait être partagé entre eux.

Configurer l'adresse dans la classe configuration.JAXRS (par les constantes SERVEUR et CHEMIN).

Déployer l'application serveur et lancer le serveur.

Premier test : lancer le client AppliCliente.

Second test : lancer le client ClientConcurrence plusieurs fois consécutivement de manière à étudier la concurrence. Qu'observe-t-on ?

Ajouter un verrou (de type java.util.concurrent.locks.Lock, objet de la classe java.util.concurrent.locks.ReentrantLock) dans la classe ImplemBibliotheque du serveur de manière à garantir que toutes les requêtes POST aboutissent effectivement à un ajout d'un livre dans la bibliothèque. Quel est l'avantage d'utiliser un tel verrou plutôt que le verrou associé à l'objet this (via la primitive synchronized) ?

Tester.

Créer une nouvelle classe cliente implémentant le scénario suivant. (On pourra s'inspirer de la classe AppliCliente.)

• Ajouter à la bibliothèque dix livres aux titres deux à deux distincts.
• Chercher un livre présent dans la bibliothèque.
• Chercher un livre absent de la biblitohèque.
• Définir un livre proxy à partir d'un hyperlien en utilisant la classe ClientRessource du paquet infrastructure.jaxrs.
• Afficher son type.
• Récupérer son titre.
• Récupérer le livre associé.
• Afficher son type.

Bien noter la manipulation des hyperliens et la relation entre les livres et les livres proxy, tous deux de type Livre.

A quoi sert la classe ClientRessource ?