Medientypen für Ressourcen in RESTful-Anwendungen definieren
Ressourcen werden in verschiedenen Formaten dargestellt. XML, JavaScript Object Notation (JSON), Atom, Binärformate wie Klartext, PNG, JPEG, GIF und proprietäre Formate werden für die Darstellung von Ressourcen verwendet. Representational State Transfer (REST) bietet die Flexibilität, eine einzelne Ressource in vielen Formaten darzustellen.
Vorbereitende Schritte
Ressourcen in JAX-RS-Webanwendungen definieren
Informationen zu diesem Vorgang
Ressourcen haben Darstellungen. Eine Ressourcendarstellung ist der Inhalt in der HTTP-Nachricht, die an die Ressource, die den URI verwendet, gesendet oder von ihr zurückgegeben wird. Jede Darstellung, die von einer Ressource unterstützt wird, hat einen entsprechenden Medientyp. Wenn eine Ressource beispielsweise Inhalt zurückgibt, der als XML formatiert ist, können Sie in der HTTP-Nachricht application/xml als zugeordneten Medientyp verwenden.
Je nach Anforderungen Ihrer Anwendung können Ressourcen Darstellungen in einem einzigen bevorzugten Format oder in mehreren Formaten zurückgeben. Es ist beispielsweise möglich, dass Ressourcen, die mit JavaScript-Clients aufgerufen werden, JSON-Darstellungen bevorzugen, weil JSON einfach zu lesen ist.
JAX-RS stellt @Consumes- und @Produces-Annotationen bereit, um die Medientypen, die für Lese- und Schreibzugriffe einer Ressourcenmethode gültig sind, zu deklarieren.
JAX-RS nimmt mit Entitäsprovidern auch Zuordnungen zwischen Java™-Typen und Ressourcendarstellungen vor. Der Entitätsprovider MessageBodyReader liest eine Anforderungsentität und entserialisiert sie in einen Java-Typ. Der Entitätsprovider MessageBodyWriter führt eine Serialisierung aus einem Java-Typ in eine Antwortentität durch.
Java-Typ | MessageBodyReader | MessageBodyWriter | Unterstützte Inhaltstypen |
---|---|---|---|
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-Typen | X | X | text/xml, application/xml, application/*+xml |
javax.ws.rs.core.StreamingOutput | X | */* |
Wenn ein String-Wert als Anforderungsentitätsparameter verwendet wird, entserialisiert der Entitätsprovider MessageBodyReader den Anforderungshauptteil in einen neuen String. Wenn ein JAXB-Typ als Rückgabetyp für eine Ressourcenmethode verwendet wird, serialisiert MessageBodyWriter das JAXB-Objekt (Java Architecture for XML Binding) in einen Antworttext.
Wenn Sie eine angepasste Zuordnung eines Java-Typs zu einer bestimmten Darstellung benötigen, sollten Sie die Informationen zur Nutzung anwendungsdefinierter Entitätsprovider lesen.
Wenn Ihr Client mehrere Formate bearbeiten kann und der Server die beste zurückzugebende Ressourcendarstellung bestimmen soll, sollten Sie sich mit der Inhaltsvereinbarung in JAX-RS-Anwendungen vertraut machen, um sich in die Lage zu versetzen, mehrere Inhaltstypen bereitzustellen.
Die Spezifikationen für XML, JSON und ATOM enthalten Details zu den Formaten der Ressourcendarstellung für Anwendungen. Weitere Informationen zu den Formaten von Ressourcendarstellungen finden Sie in den entsprechenden Spezifikationen.
Vorgehensweise
- Legen Sie das Format für die Ressourcendarstellung fest, das für die Anforderung oder die Antwort verwendet werden soll, wie z. B. XML, JSON oder ATOM.
- Fügen Sie die Annotationen "@Consumes" und "@Produces" entsprechend zur Ressourcenmethode hinzu.
- Wenn die Ressource den Inhalt der Anforderung lesen muss, fügen Sie einen Entitätsparameter zur Ressourcenmethode hinzu. Der Anforderungsentitätsparameter ist ein einzelner Java-Parameter in der Methode, die keine Annotation hat.
- Wenn die Ressourcenmethode Inhalt in der Antwort zurückgibt, geben Sie ein Java-Objekt zurück, für das ein JAX-RS-Provider eine Schreibzugriffsberechtigung hat. Dieses Java-Objekt wird der Antwortentität in der HTTP-Antwort zugeordnet. Das zurückgegebene Objekt muss ein von JAX-RS unterstützter Java-Typ sein oder in einem javax.ws.rs.core.Response- bzw. javax.ws.rs.core.GenericEntity-Typ eingeschlossen sein.
Ergebnisse
Sie haben die Anforderungsentitäten dem Entitätsparameter der Ressourcenmethode zugeordnet, und alle zurückgegebenen Antwortobjekte werden der Antwortentität für die Ressourcendarstellung zugeordnet.
Beispiel
Das folgende Beispiel veranschaulicht die Definition von XML als Ressourcendarstellung für eine RESTful-Buchhandlungsanwendung.
- Geben Sie die Ressourcenmethoden an, die die Anforderungsentität lesen oder eine Antwortentität zurückgeben sollen.
In der folgenden Methode "retrieveSpecificBookInformation" gibt es keine Anforderungsentität, die gelesen wird. Es gibt jedoch ein Antwortobjekt, das zurückgegeben wird. Dieses Objekt schließt ein JAXB-Objekt ein, das die Entitätsinformationen enthält. Wird die Annotation @Produces in der Ressourcenmethode mit dem Medientyp application/xml hinzugefügt, wird damit angezeigt, dass die Ressourcenmethode immer eine XML-Darstellung mit dem Medientyp application/xml zurückgibt.
Clients, die einen Wert für den Anforderungsheader "Accept HTTP" haben, der mit dem Medientyp application/xml kompatibel ist, rufen die Methode ordnungsgemäß auf.
Clients, die einen Wert für den Header "Accept HTTP" haben, der mit dem Medientyp application/xml nicht kompatibel ist, empfangen automatisch einen Antwortstatus 406 Not Acceptable, der anzeigt, dass der Server keine zulässige Antwort erzeugen kann.
Im folgenden Beispiel sind die Ressourcenmethoden angegeben, die die Anforderungsentität lesen oder eine Antwortentität zurückgeben:
/* * Book.java * Diese Klasse repräsentiert einzelne Bücher. Die Annotation "@Produces" gibt den Medientyp "application/xml" an. */ @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(/* ein JAXB-Objekt, das die Entität des Antwortteils darstellt */).expires(/* Wert des Antwortheaders Expires*/).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) { /* … */ } }
- Geben Sie die Ressourcenmethoden an, die die Anforderungsinformationen konsumieren müssen.
Im folgenden Ausschnitt akzeptiert die PUT-Methode in der Buchressource den Inhalt der Anforderungsentität, falls der gesendete Medientyp text/plain laut Definition in der @Consumes-Annotation ist. Diese Methode gibt Inhalt mit einer Darstellung des Typs text/plain laut Definition in den @Produces-Annotationen zurück.
Wenn ein Client eine Nachricht sendet, deren Content-Type-Wert nicht text/plain ist, wird die Ressourcenmethode PUT nicht aufgerufen. Wird der Wert Content-Type: application/xml in den HTTP-Anforderungshedern gesendet, wird die Java-Methode updateBookInformation nicht aufgerufen.
Die Methode DELETE ist nicht dafür zuständig, Anforderungsentitäten zu lesen oder zurückzugeben, daher benötigt sie keine @Consumes- oder @Produces-Annotation.
Im folgenden Beispiel sind die Ressourcenmethoden angegeben, die die Anforderungsinformationen konsumieren:
/* * Book.java * Diese Klasse repräsentiert einzelne Bücher mit angepassten Headern. */ @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(/* ein JAXB-Objekt, das die Entität des Antwortteils darstellt */).expires(/* Wert des Antwortheaders Expires*/).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) { /* … */ } }
Nächste Schritte
Die JAX-RS-Spezifikation enthält eine Liste aller Standardmedienformate, die für Darstellungen unterstützt werden.
Fortgeschrittene Benutzer können angepasste Zuordnungen von Java-Typen zu Darstellungen definieren oder die Inhaltsvereinbarung für Clients verwenden, um bevorzugte Ressourcendarstellungen zu vereinbaren. Näheres zu diesen Optionen finden Sie in den Artikeln, die sich mit der Nutzung angepasster definierte Entitätsformate oder der Bereitstellung mehrerer Inhaltstypen mit Informationen zur Inhaltsvereinbarung befassen.