Définition des paramètres des représentations de demande dans les ressources dans les applications RESTful
Les paramètres permettent d'envoyer ou d'ajouter des informations supplémentaires à une demande. Vous pouvez utiliser des paramètres dans l'URL ou dans les en-têtes. Les paramètres de chemin, de matrice, de requête, et de cookie sont pratiques pour envoyer des informations supplémentaires à une demande.
Pourquoi et quand exécuter cette tâche
Il existe plusieurs types de paramètres. Java™ API for RESTful Web Services (JAX-RS) permet d'accéder aisément à tous les types de paramètres en utilisant des paramètres injectés annotés.
Vous pouvez utiliser n'importe quel type de primitive Java standard, notamment, java.lang.String, comme paramètres, ainsi que les types Java avec un constructeur qui utilise une seule chaîne ou une méthode statique valueOf(String). En outre, vous pouvez utiliser les interfaces List, SortedSet, et Set dans lesquelles le type générique est l'un des types mentionnés précédemment, tels que Set, lorsqu'un paramètre peut avoir plusieurs valeurs. Si vous devez analyser la syntaxe des demandes, utilisez String comme type de paramètre pour effectuer une analyse et une personnalisation de base des réponses de chemin erronées.
JAX-RS fournit les annotations suivantes pouvant être utilisées dans les paramètres de méthode de ressource pour indiquer que la méthode de ressource peut être appelée avec les valeurs de paramètres correctes.
- Annotation javax.ws.rs.PathParam
Les paramètres de chemin font partie de l'URL. Par exemple, l'URL peut inclure /collection/{item}, où {item} est un paramètre de chemin qui identifie l'élément dans la collection. Etant donné que les paramètres de chemin font partie de l'URL, ils sont essentiels à l'identification de la demande.
Si des parties de l'URL sont des paramètres, vous pouvez utiliser un paramètre annoté @javax.ws.rs.PathParam, par exemple :
Dans cet exemple, les demandes à /bookstore/books/12345 affectent la valeur 12345 à la variable theBookId.@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 would contain the next path segment after /bookstore/books/ */ } }
- Annotation javax.ws.rs.MatrixParam
Les paramètres de matrice font partie de l'URL. Par exemple, si l'URL contient le segment de chemin, /collection;itemID=itemIDValue, le nom de paramètre de matrice est itemID et itemIDValue est valeur.
Vous pouvez lire les paramètres de matrice avec un paramètre annoté @javax.ws.rs.MatrixParam, par exemple :
Dans cet exemple, les demandes à /bookstore/books;page=25;filter=test appellent le paramètre getBookCollectionInfo pour que la variable page ait la valeur 25 et que la variable filter ait la valeur test.@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) { /* This statement uses the page and filter parameters. */ } }
- Annotation javax.ws.rs.QueryParam
Les paramètres de requête sont ajoutés à l'URL après un “?” avec des paires nom-valeur. Par exemple, si l'URL est http://example.com/collection?itemID=itemIDValue, le nom de paramètre de requête est itemID et la valeur est itemIDValue. Les paramètres de requête sont généralement utilisés pour filtrer et parcourir les requêtes HTTP GET.
Vous pouvez lire les paramètres de requête avec un paramètre annoté @javax.ws.rs.QueryParam, par exemple :
Dans cet exemple, les demandes à /bookstore/books;page=25;filter=test appellent le paramètre getBookCollectionInfo pour que la variable page ait la valeur 25 et la variable filter, la valeur test.@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) { /* This statement uses the page and filter parameters. */ } }
- Annotation javax.ws.rs.HeaderParam
Les paramètres d'en-tête sont des paramètres HTTP. Bien qu'il existe des en-tête HTTP prédéfinis, vous pouvez utiliser des en-têtes personnalisés. Les en-têtes contiennent généralement des informations de métadonnées de contrôle pour le client, l'intermédiaire ou le serveur.
Si un en-tête de requête HTTP doit être lu, utilisez l'annotation @javax.ws.rs.HeaderParam, par exemple :@javax.ws.rs.Path(“/bookstore/books/”) public class BooksCollection { @javax.ws.rs.GET public String getBookCollectionInfo(@javax.ws.rs.HeaderParam(“Range”) String rangeValue) { /* The rangeValue variable contains the value of the HTTP request header "Range" */ } }
Dans cet exemple, les demandes à /bookstore/books/ avec une valeur d'en-tête de requête HTTPRange égale à bytes=0-499 appellent la méthode avec bytes=0-499 comme valeur pour la variable rangeValue.
- Annotation javax.ws.rs.CookieParam
Les paramètres de cookie sont des en-têtes HTTP spéciaux. Bien que les cookies soient associés au stockage des données d'identification de session ou avec état qui ne sont pas acceptées comme données RESTful, ils peuvent contenir des informations sans état.
Si un cookie HTTP est envoyé, mycustomid=customvalue123, par exemple, vous pouvez extraire la valeur de la variable mycustomid en utilisant le code suivant :@javax.ws.rs.Path(“/bookstore/books/”) public class BooksCollection { @javax.ws.rs.GET public String getBookCollectionInfo(@javax.ws.rs.CookieParam(“mycustomid”) String mycustomid) { /* The cookie value is passed to the mycustomid variable. */ } }
- Annotation javax.ws.rs.FormParam
Les paramètres de formulaire sont utilisés lors de l'envoi d'un formulaire HTML à partir d'un navigateur avec le type de support application/x-www-form-urlencoded. Les paramètres et les valeurs de formulaire sont codés dans le corps du message de demande sous la forme firstParameter=firstValue&secondParameter=secondValue. L'annotation javax.ws.rs.FormParam permet d'accéder aisément aux valeurs des paramètres de formulaire individuels.
Si un formulaire est envoyé et que la valeur de l'entité est firstName=Bob&lastName=Smith, vous pouvez extraire les valeurs des paramètres de formulaire en utilisant le code suivant :@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 would be "Bob" and secondName would be "Smith" */ } }
Eviter les incidents: Vous pouvez utiliser un seul paramètre non annoté pour représenter le corps du message ou des paramètres annotés FormParam, mais pas les deux. Etat donné que FormParam requiert que le corps de message de demande soit lu et que le corps de message soit représenté par un flux d'octets, le corps de message ne peut pas être relu. Le code suivant n'est pas valide :
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) { /* This code is invalid. Can only use FormParam or a request entity parameter like "String theRequestEntity" and not both */ } }
Utilisez l'une des méthodes suivantes pour définir les variables pour lire les paramètres.
Procédure
Résultats
Vos méthodes de ressource sont définies pour qu'elles puissent être appelées avec les valeurs de paramètres appropriées.