Implémentation de formats d'entité personnalisés

Java™ API for RESTful Web Services (JAX-RS) permet aux développeurs d'ajouter un fournisseur d'entité personnalisé à l'application. Utilisez des fournisseurs d'entité personnalisés lorsque vous voulez utiliser des types Java pour représenter les corps de message de demande entrant et les corps de message de réponse. En ajoutant un fournisseur d'entité personnalisé, vous pouvez désérialiser les types Java personnalisés dans les corps de message et sérialiser le type de support sous forme de corps de message.

Pourquoi et quand exécuter cette tâche

Un fournisseur d'entité personnalisé est créé en annotant une classe avec une annotation javax.ws.rs.ext.Provider. La classe doit implémenter l'interface javax.ws.rs.ext.MessageBodyReader ou javax.ws.rs.ext.MessageBodyWriter ou les deux. Vous devez ajouter la classe de fournisseur à la liste des classes retournées dans la méthode javax.ws.rs.core.Application subclass getClasses().

Procédure

  1. Créez une classe Java correspondant au fournisseur d'entité personnalisé. Dans cette procédure, l'exemple de code crée un programme de lecture et un programme d'écriture pour les types com.ibm.json.java.JSONObject pour que vous puissiez utiliser le type com.ibm.json.java.JSONObject comme paramètre d'entité de demande entrante et comme type de retour devant contenir l'entité de réponse.
    public class MyEntityProvider {
    
    }
  2. Ajoutez l'annotation @javax.ws.rs.ext.Provider. En ajoutant cette annotation, vous indiquez à l'environnement d'exécution JAX-RS que la classe est un fournisseur JAX-RS. Si cette annotation de fournisseur n'est pas spécifiée, l'environnement d'exécution ne détecte pas que la classe est un fournisseur personnalisé.
    @javax.ws.rs.ext.Provider
    public class MyEntityProvider {
    }
  3. (Facultatif) Ajoutez une annotation @javax.ws.rs.Consumes ou @javax.ws.rs.Produces si vous voulez limiter les types de supports pris en charge par le fournisseur d'entité.  Dans le fragment de code suivant, le fournisseur est appelé uniquement lorsque le type de contenu entrant ou sortant est application/json.
    @javax.ws.rs.ext.Provider
    @javax.ws.rs.Consumes("application/json")
    @javax.ws.rs.Produces("application/json")
    public class MyEntityProvider {
    
    }
  4. Implémentez javax.ws.rs.ext.MessageBodyReader<T> si le fournisseur d'entité doit désérialiser un corps de message.

    Vous pouvez utiliser le type générique <T> pour limiter les types pris en charge par le fournisseur d'entité.

    En définissant le programme de lecture de corps de message sous la forme javax.ws.rs.ext.MessageBodyReader<com.ibm.json.java.JSONObject>, l'environnement d'exécution JAX-RS sait que seuls des objets com.ibm.json.java.JSONObject peuvent être produits.

    Si un fournisseur d'entité doit prendre en charge un ensemble de types complexes, implémentez javax.ws.rs.ext.MessageBodyReader<Object>.

    @javax.ws.rs.ext.Provider
    @javax.ws.rs.Consumes("application/json")
    @javax.ws.rs.Produces("application/json")
    public class MyEntityProvider implements 
        javax.ws.rs.ext.MessageBodyReader<com.ibm.json.java.JSONObject> {
    
    
    
        public boolean isReadable(Class<?> type, 
                                  Type genericType, 
                                  Annotation[] annotations, 
                                  MediaType mediaType) { 
            return com.ibm.json.java.JSONObject.class == type; 
        } 
    
    
        public com.ibm.json.java.JSONObject readFrom(Class<com.ibm.json.java.JSONObject> type, 
                               Type genericType, 
                               Annotation[] annotations, 
                               MediaType mediaType, 
                               MultivaluedMap<String, String> httpHeaders, 
                               InputStream entityStream) throws IOException, WebApplicationException {
            /* Ce flux InputStream lit entityStream et crée l'objet. */
            com.ibm.json.java.JSONObject retObj = com.ibm.json.java.JSONObject.parse(entityStream);
            return retObj; 
        } 
    
    }
  5. Implémentez javax.ws.rs.ext.MessageBodyWriter<T> si le fournisseur d'entité doit sérialiser un corps de message. Vous pouvez implémenter les interfaces MessageBodyReader<T> et MessageBodyWriter<T> dans la même classe Java. Dans le fragment de code suivant, seule l'implémentation MessageBodyWriter est indiquée.
    @Provider 
    public class MyEntityProvider implements 
        MessageBodyWriter<Object> {
    
    
    
        public long getSize(Object t, 
                            Class<?> type, 
                            Type genericType, 
                            Annotation[] annotations, 
                            MediaType mediaType) { 
            /* return -1 if the content length cannot be determined */
    
            return -1; 
        } 
    
    
        public boolean isWriteable(Class<?> type, 
                                   Type genericType, 
                                   Annotation[] annotations, 
                                   MediaType mediaType) { 
            return MyType.class == type; 
        } 
    
    
        public void writeTo(Object t, 
                            Class<?> type, 
                            Type genericType, 
                            Annotation[] annotations, 
                            MediaType mediaType, 
                            MultivaluedMap<String, Object> httpHeaders, 
                            OutputStream entityStream) throws IOException, WebApplicationException { 
            entityStream.write(MyType.getBytes()); 
        } 
    
    }
  6. Ajoutez le fournisseur d'entité personnalisé à la sous-classe javax.ws.rs.core.Application et le fournisseur au groupe de classes retournées par la méthode getClasses(). Vous pouvez ajouter plusieurs fournisseurs d'entité personnalisés au groupe de classes retournées.
    public class MyApplication extends javax.ws.rs.core.Application {
        public Set<Class<?>> getClasses() {
            Set<Class<?>> classes = new HashSet<Class<?>>();
            classes.add(MyEntityProvider.class);
            return classes;
        }
    }  

Résultats

Vous avez défini un fournisseur d'entité personnalisé et vous l'avez ajouté à l'application Web JAX-RS.

Eviter les incidents Eviter les incidents:

Suivez les conseils ci-dessous pour résoudre les erreurs courantes d'implémentation des formats d'entité personnalisés :

Fournisseurs personnalisés introuvables.
Pour résoudre ce problème, procédez comme suit :
  • Vérifiez que le fournisseur est annoté avec @javax.ws.rs.ext.Provider. Une classe qui ne dispose pas de l'annotation n'est pas enregistrée comme fournisseur.
  • Vérifiez que le fournisseur a été ajouté au groupe de classes retournées par la méthode getClasses() pour les sous-classes de la classe javax.ws.rs.core.Application.
  • Vérifiez que la valeur @javax.ws.rs.Produces ou @javax.ws.rs.Consumes dans la classe de fournisseur est valide.
  • Vérifiez que la méthode javax.ws.rs.ext.MessageBodyReader#isReadable ou javax.ws.rs.ext.MessageBodyWriter#isWritable est correctement implémentée et qu'elle retourne correctement la valeur true lorsque la méthode est utilisée.
En-têtes ou sortie du fournisseur d'entités Custom MessageBodyWriter incorrects.
Pour résoudre ce problème, procédez comme suit :
  • Vérifiez que la taille de la réponse dans javax.ws.rs.ext.MessageBodyWriter#getSize est égale à -1 si la taille est inconnue ou correspond à la taille correcte lorsque la taille est connue. Les clients peuvent tronquer la réponse si la valeur de taille est erronée.
  • Si des en-têtes HTTP sont définis dans la méthode javax.ws.rs.ext.MessageBodyWriter#writeTo, vous devez définir les en-têtes avant l'envoi du reste de la réponse HTTP. Les en-têtes HTTP sont envoyés au début d'une réponse. Par conséquent, si vous définissez les en-têtes après le début de l'envoi du corps de message de réponse principal au client, il est trop tard pour envoyer les en-têtes de réponse.
gotcha

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_customentityformats_impl
Nom du fichier : twbs_jaxrs_customentityformats_impl.html