Parameter für Anforderungsdarstellungen von Ressourcen in RESTful-Anwendungen definieren
Parameter werden verwendet, um zusätzliche Informationen an eine Anforderung zu übergeben und zu dieser hinzuzufügen. Sie können Parameter als Teil des URL oder in den Headern verwenden. Pfadparameter, Matrixparameter, Abfrageparameter, Headerparameter und Cookieparameter sind nützlich, um weitere Informationen an eine Anforderung zu übergeben.
Informationen zu diesem Vorgang
Es sind mehrere Parametertypen vorhanden. JAX-RS (Java™ API for RESTful Web Services) ermöglicht über annotierte eingefügte Parameter den einfachen Zugriff auf alle Parametertypen.
Sie können alle primitiven Java-Basistypen einschließlich "java.lang.String" als Parameter verwenden, ebenso wie Java-Typen mit einem Konstruktor, der eine einzelne Zeichenfolge (String) oder eine statische valueOf(String)-Methode verwendet. Darüber hinaus können Sie List-, SortedSet- und Set-Schnittstellen verwenden, deren generischer Typ einer der zuvor genannten Typen ist, wie z. B. ein Set, wenn ein Parameter mehrere Werte haben kann. Wenn Sie Anforderungen syntaktisch analysieren müssen, sollten Sie "String" als Parametertyp verwenden, um Reaktionen auf Fehler in grundlegender Weise prüfen und anpassen zu können.
JAX-RS stellt die folgenden Annotationen für Ressourcenmethodenparameter bereit, um anzugeben, dass die Ressourcenmethode mit richtigen Parameterwerten aufgerufen werden kann.
- Annotation "javax.ws.rs.PathParam"
Pfadparameter sind Bestandteile des URL. Der URL kann beispielsweise den Abschnitt /collection/{item} enthalten. Dabei steht {item} für einen Pfadparameter, der das Element in der Sammlung angibt. Da Pfadparameter Bestandteile des URL sind, sind sie für die Angabe der Anforderung wesentlich.
Wenn Teile des URL Parameter sind, können Sie einen mit "@javax.ws.rs.PathParam" annotierten Parameter verwenden. Beispiel:
In diesem Beispiel wird Anforderungen, die sich auf /bookstore/books/12345 beziehen, der Wert 12345 für die Variable theBookId zugeordnet.@javax.ws.rs.Path(“/bookstore/books/{bookId}”) public class BooksCollection { @javax.ws.rs.GET public String getSpecificBookInfo(@javax.ws.rs.PathParam(“bookId”) String theBookId) { /* theBookId enthält das nächste Pfadsegment nach /bookstore/books/ */ } }
- Annotation "javax.ws.rs.MatrixParam"
Matrixparameter sind Teil des URL. Wenn beispielsweise der URL das Pfadsegment /collection;itemID=itemIDValue enthält, lautet der Matrixparametername itemID, und itemIDValue ist der Wert.
Sie können Matrixparameter mit einem mit "@javax.ws.rs.MatrixParam" annotierten Parameter lesen. Beispiel:
In diesem Beispiel rufen Anforderungen des Typs /bookstore/books;page=25;filter=test den Parameter getBookCollectionInfo auf, damit die Variable page auf den Wert 25 und der Wert für die Variable filter auf test gesetzt wird.@javax.ws.rs.Path(“/bookstore/books”) public class BooksCollection { @javax.ws.rs.GET public String getBookCollectionInfo(@javax.ws.rs.MatrixParam(“page”) int page, @javax.ws.rs.MatrixParam(“filter”) String filter) { /* Diese Anweisung verwendet die Seiten- und Filterparameter. */ } }
- Annotation "javax.ws.rs.QueryParam"
Abfrageparameter werden nach einem Fragezeichen mit Name/Wert-Paaren an den URL angefügt. Beispiel: Wenn der URL http://example.com/collection?itemID=itemIDValue lautet, ist der Abfrageparametername itemID und itemIDValue der Wert. Abfrageparameter werden oft beim Filtern oder beim Paging von HTTP-GET-Anforderungen verwendet.
Sie können Abfrageparameter mit einem mit "@javax.ws.rs.QueryParam" annotierten Parameter lesen. Beispiel:
In diesem Beispiel rufen Anforderungen des Typs /bookstore/books;page=25;filter=test den Parameter getBookCollectionInfo auf, damit die Variable page auf den Wert 25 und der Wert für die Variable filter auf test gesetzt wird.@javax.ws.rs.Path(“/bookstore/books”) public class BooksCollection { @javax.ws.rs.GET public String getBookCollectionInfo(@javax.ws.rs.QueryParam(“page”) int page, @javax.ws.rs.QueryParam(“filter”) String filter) { /* Diese Anweisung verwendet die Seiten- und Filterparameter. */ } }
- Annotation "javax.ws.rs.HeaderParam"
Headerparameter sind HTTP-Header. Es gibt zwar vordefinierte HTTP-Header, Sie können jedoch auch angepasste Header verwenden. Header enthalten oft Metadateninformationen für den Client, den Vermittler oder den Server.
Wenn ein HTTP-Anforderungsheader gelesen werden muss, verwenden Sie die Annotation "@javax.ws.rs.HeaderParam". Beispiel:@javax.ws.rs.Path(“/bookstore/books/”) public class BooksCollection { @javax.ws.rs.GET public String getBookCollectionInfo(@javax.ws.rs.HeaderParam(“Range”) String rangeValue) { /* Die Variable "rangeValue" enthält den Wert des HTTP-Anforderungsheaders "Range" */ } }
In diesem Beispiel rufen Anforderungen, die sich auf /bookstore/books/ beziehen, und deren Range-Wert des HTTP-Anforderungsheaders bytes=0-499 lautet, die Methode mit bytes=0-499 als Wert für die Variable rangeValue auf.
- Annotation "javax.ws.rs.CookieParam"
Cookieparameter sind besondere HTTP-Header. Cookies werden zwar zum Speichern von Sitzungsidentifikationsdaten bzw. von statusabhängigen Daten, die nicht als RESTful-Daten akzeptiert werden, können jedoch auch statusunabhängige Informationen enthalten.
Wird ein HTTP-Cookie gesendet, wie z. B. mycustomid=customvalue123, können Sie den Wert der Variable mycustomid mit dem folgenden Beispiel abrufen:@javax.ws.rs.Path(“/bookstore/books/”) public class BooksCollection { @javax.ws.rs.GET public String getBookCollectionInfo(@javax.ws.rs.CookieParam(“mycustomid”) String mycustomid) { /* Der Cookiewert wird an die Variable "mycustomid" übergeben. */ } }
- Annotation "javax.ws.rs.FormParam"
Formularparameter werden verwendet, wenn ein HTML-Format mit dem Medientyp application/x-www-form-urlencoded von einem Browser gesendet wird. Die Formularparameter und -werte werden im Text der Anforderungsnachricht in folgendem Format codiert: firstParameter=firstValue&secondParameter=secondValue. Die Annotation "javax.ws.rs.FormParam" ermöglicht einen einfachen Zugriff auf einzelne Werte von Formularparametern.
Wird ein Formular übergeben und ist der Entitätswert firstName=Bob&lastName=Smith, können Sie die Werte anhand des folgenden Beispiels von den Formularparametern abrufen:@javax.ws.rs.Path(“/customer”) public class Custommer { @javax.ws.rs.POST public String postCustomerInfo(@javax.ws.rs.FormParam(“firstName”) String firstName, @javax.ws.rs.FormParam("lastName") String lastName) { /* firstName hat den Wert "Bob" und secondName den Wert "Smith" */ } }
Fehler vermeiden: Sie können entweder einen einzelnen, nicht annotierten Parameter verwenden, um den Nachrichtentext darzustellen, oder Sie können mehrere mit "FormParam" annotierte Parameter verwenden. Beides gleichzeitig ist nicht möglich. Da "FormParam" voraussetzt, dass der Text der Anforderungsnachricht gelesen und als Bytedatenstrom dargestellt wird, kann der Nachrichtentext nicht erneut gelesen werden. Der folgende Code ist nicht gültig:
gotcha@javax.ws.rs.Path(“/bookstore/books”) public class BooksCollection { @javax.ws.rs.POST public String postSpecificBookInfo(@javax.ws.rs.FormParam(“bookId”) String theBookId, String theRequestEntity) { /* Dieser Code ist ungültig. Es kann nur entweder "FormParam" oder der Anforderungsentitätsparameter wie "String theRequestEntity", nicht beides. */ } }
Wählen Sie eine der folgenden Methoden aus, um Variablen für das Lesen von Parametern zu definieren.
Vorgehensweise
Ergebnisse
Ihre Ressourcenmethoden sind definiert und können mit entsprechenden Parameterwerten aufgerufen werden.