Définition des types de ressources dans les applications RESTful

Les ressources sont représentées par plusieurs formats. Les formats XML, JavaScript Object Notation (JSON), Atom, binaires (tels que PNG, JPEG, GIF), de texte ordinaire et propriétaires sont utilisés pour représenter les ressources. REST (Representational State Transfer) offre la possibilité de représenter une même ressource dans plusieurs formats.

Avant de commencer

Définissez les ressources dans les application Web JAX-RS.

Pourquoi et quand exécuter cette tâche

Les ressources ont des représentations. Une représentation de ressource est le contenu dans le message HTTP qui est envoyé à et retourné par la ressource en utilisant l'identificateur URI. Chaque représentation que prend en charge une ressource a un type de support correspondant. Par exemple, si une ressource doit retourner du contenu formaté XML, vous pouvez utiliser application/xml comme type de support associé dans le message HTTP.

Selon les exigences de votre application, les ressources peuvent retourner des représentations dans un seul format préféré ou dans plusieurs formats. Par exemple, les ressources qui font l'objet d'un accès en utilisant des clients JavaScript peuvent préférer les représentations JSON, car JSON est simple à consommer.

JAX-RS fournit les annotations @Consumes et @Produces pour déclarer les types de supports acceptables pour une méthode de ressource pour la lecture et l'écriture.

JAX-RS associe également des types Java™ aux et depuis les représentations de ressource en utilisant des fournisseurs d'entité. Un fournisseur d'entité MessageBodyReader lit une entité de demande et désérialise l'entité de demande en type Java. Un fournisseur d'entité MessageBodyWriter sérialise un type Java en entité de réponse.

Tableau 1. Fournisseurs d'entité standard et types de Java de base. Ce tableau répertorie les types Java de fournisseurs et de base d'entité standard dans l'environnement d'exécution JAX-RS, avec les types de contenu pris en charge correspondant.
Type Java MessageBodyReader MessageBodyWriter Types de contenu pris en charge
byte[] X X */*
java.io.InputStream X X */*
java.io.Reader X X */*
java.lang.String X X */*
java.io.File X X */*
javax.activation.DataSource X X */*
javax.xml.transform.Source X X text/xml, application/xml, application/*+xml
javax.ws.rs.core.MultivaluedMap X X application/x-www-form-urlencoded
JAXB types X X text/xml, application/xml, application/*+xml
javax.ws.rs.core.StreamingOutput   X */*

Si une valeur String est utilisée comme paramètre d'entité de demande, le fournisseur d'entité MessageBodyReader désérialise le corps de la demande en nouvelle chaîne. Si un type JAXB est utilisé comme type de retour dans une méthode de ressource, MessageBodyWriter sérialise l'objet Java Architecture for XML Binding (JAXB) en corps de réponse.

Si vous avez besoin d'un mappage personnalisé entre un type Java et une représentation spécifique, voir les informations d'utilisation d'un fournisseur d'entité définie par l'application.

Si le client peut gérer plusieurs formats et que vous voulez que le serveur détermine la meilleure représentation de ressource à retourner, lisez les informations relatives à l'utilisation de la négociation de contenu dans les applications JAX-RS pour gérer plusieurs types de contenus.

Les spécifications pour XML, JSON et Atom fournissent des détails relatifs aux formats des représentations des ressources pour les applications. Voir les spécifications pour en savoir plus sur les formats de représentations des ressources.

Procédure

  1. Déterminez le format de représentation de ressource, tel que XML, JSON ou ATOM, à utiliser pour la demande ou la réponse.
  2. Ajoutez les annotations @Consumes et @Produces de manière appropriée à la méthode de ressource.
  3. Si la ressource doit lire le contenu de la demande, ajoutez un paramètre d'entité de demande à la méthode de ressource. Ce paramètre est un paramètre Java unique dans la méthode qui n'a pas d'annotation.
  4. Si la méthode de ressource retourne du contenu dans la réponse, retournez un objet Java inscriptible par un fournisseur d'entité JAX-RS. Cet objet Java est associé à l'entité de réponse dans la réponse HTTP. L'objet retourné doit être un type Java JAX-RS prise en charge ou associé dans un type javax.ws.rs.core.Response ou javax.ws.rs.core.GenericEntity.

Résultats

Vous avez associé les entités de demande au paramètre d'entité de méthode de ressource et les objets de réponse retournés sont associés à l'entité de réponse de la représentation de ressource.

Exemple

L'exemple suivant explique comment définir XML comme représentation de ressource pour une application de librairie RESTful.

  1. Identifiez les méthodes de ressource pour lire l'entité de demande ou l'entité de réponse.

    Dans l'exemple de méthode retrieveSpecificBookInformation qui suit, aucune entité de demande n'est lue. Toutefois, un objet de réponse est retourné. Cet objet encapsule un objet JAXB qui contient les informations d'entité. L'ajout de l'annotation @Produces dans la méthode de ressource avec le type de support application/xml indique que la méthode de ressource retourne toujours une représentation XML avec le type de support application/xml.

    Les clients ayant une valeur d'en-tête de requête HTTP Accept compatible avec le type de support application/xml appellent correctement la méthode.

    Les clients qui ne disposent pas d'une valeur d'en-tête HTTPAccept compatible avec le type de support application/xml reçoivent automatiquement l'état de réponse 406 Not Acceptable qui indique que le serveur ne peut pas produire une réponse acceptable.

    L'exemple suivant identifie les méthodes de ressource qui lisent l'entité de demande ou retournent une entité de réponse :

    /*
     * Book.java
     * Cette classe représente un livre individuel. L'annotation @Produces définit le type de support application/xml.
     */
    @Path(“/bookstore/books/{bookID}”)
    public class Book {
      @GET
      @Produces(“application/xml”)
      public javax.ws.rs.core.Response retrieveSpecificBookInformation(@PathParam(“bookID”) String theBookID, @Context javax.ws.rs.core.HttpHeaders headers) {
       /* … */
       return
        Response.ok(/* JAXB object to represent response body entity */).expires(/* Expires response header value*/).header(“CustomHeaderName”, “CustomHeaderValue”).build();
       }
       @PUT
       public String updateBookInformation(@PathParam(“bookID”) String theBookID, String theRequestEntity,
        @javax.ws.rs.HeaderParam(“Content-Length”) String contentLengthHeader) { /* … */ }
    
       @DELETE
       public void removeBook(@PathParam(“bookID”) String theBookID) { /* … */ }
    }
  2. Identifiez les méthodes de ressource qui doivent consommer les informations de demande.

    Dans le fragment de code suivant, la méthode PUT dans la ressource book accepte le contenu de l'entité de demande si le type de support text/plain est envoyé, comme défini dans l'annotation @Consumes. Cette méthode retourne le contenu avec une représentation text/plain, comme défini dans les annotations @Produces.

    Si un client n'envoie pas un message avec la valeur Content-Type, text/plain, la méthode de ressource PUT n'est pas appelée. Si Content-Type: application/xml est envoyé dans les en-têtes de requête HTTP, la méthode Java updateBookInformation n'est pas appelée.

    La méthode DELETE ne lit pas une entité de demande et ne retourne pas non plus une entité de réponse ; par conséquent, elle ne nécessite pas une annotation @Consumes ni une annotation @Produces.

    L'exemple suivant identifie les méthodes de ressource qui consomment les informations de demande :

    /*
     * Book.java
     * Cette classe représente des livres individuels avec des en-têtes personnalisés.
     */
    @Path(“/bookstore/books/{bookID}”)
    public class Book {
      @GET
      @Produces(“application/xml”)
      public javax.ws.rs.core.Response retrieveSpecificBookInformation(@PathParam(“bookID”) String theBookID, @Context javax.ws.rs.core.HttpHeaders headers) {
        /* … */
        return Response.ok(/* JAXB object to represent response body entity */).expires(/* Expires response header value).header(“CustomHeaderName”, “CustomHeaderValue”).build();
      }
      @PUT
      @Consumes(“text/plain”)
      @Produces(“text/plain”)
      public String updateBookInformation(@PathParam(“bookID”) String theBookID, String theRequestEntity, @javax.ws.rs.HeaderParam(“Content-Length”) String contentLengthHeader) {
        /* … */
        String responseEntity = /* a plain text representation */;
        return responseEntity;
      }
    
      @DELETE
      public void removeBook(@PathParam(“bookID”) String theBookID) { /* … */ }
    }

Que faire ensuite

Voir la spécification JAX-RS pour la liste de tous les formats de supports standard pris en charge pour les représentations.

Les utilisateurs expérimentés peuvent envisager de définir des mappages personnalisés entre les types Java et les représentations ou d'utiliser la négociation de contenu pour que les clients négocient les représentations de ressource préférées. Pour plus d'informations sur ces options, voir les informations relatives à l'utilisation des formats d'entité définis personnalisés ou à la gestion de plusieurs types de contenus avec les informations de négociation de contenu.


Icône indiquant le type de rubrique Rubrique de tâche



Icône d'horodatage Dernière mise à jour: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxrs_defresource_mediatype
Nom du fichier : twbs_jaxrs_defresource_mediatype.html