Definición de parámetros para representaciones de solicitudes en recursos de aplicaciones RESTful
Los parámetros se utilizan para pasar y añadir información adicional a una solicitud. Puede utilizar parámetros como parte del URL o en las cabeceras. Los parámetros de vía de acceso, de matriz, de consulta, de cabecera y de cookies son útiles para pasar información adicional a una solicitud.
Acerca de esta tarea
Hay diversos tipos de parámetros. La API de Java™ para RESTful Web Services (JAX-RS) permite acceder de forma fácil a todos los tipos de parámetros utilizando parámetros inyectados anotados.
Puede utilizar cualquier tipo básico primitivo Java incluido java.lang.String como parámetro, así como los tipos Java con un constructor que utilice una serie única o un método estático valueOf(String). Además, puede utilizar las interfaces List, SortedSet y Set en que el tipo genérico es uno de los tipos mencionados anteriormente como, por ejemplo, un Set cuando un parámetro puede tener varios valores. Si es necesario analizar las solicitudes, utilice String como tipo de parámetro para poder completar la inspección básica y la personalización de respuestas de vía de acceso con error.
JAX-RS proporciona las siguientes anotaciones para utilizarlas en parámetros de método de recursos para especificar que el método se puede invocar con valores de parámetros correctos.
- Anotación javax.ws.rs.PathParam
Los parámetros de vía de acceso forman parte del URL. Por ejemplo, el URL puede incluir /collection/{elemento}, donde {elemento} es un parámetro de vía de acceso que identifica el elemento en la colección. Dado que los parámetros de vía de acceso forman parte del URL, son esenciales para identificar la solicitud.
Si las partes del URL son los parámetros, puede utilizar un parámetro anotado @javax.ws.rs.PathParam; por ejemplo:
En este ejemplo, las solicitudes a /bookstore/books/12345 asignan el valor de 12345 a 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/ */ } }
- Anotación javax.ws.rs.MatrixParam
Los parámetros de matriz forman parte del URL. Por ejemplo, si el URL incluye el segmento de vía de acceso, /collection;itemID=itemIDValue, el nombre del parámetro de matriz es itemID e itemIDValue es el valor.
Puede leer parámetros de matriz con un parámetro anotado @javax.ws.rs.MatrixParam; por ejemplo:
En este ejemplo, las solicitudes a /bookstore/books;page=25;filter=test invocan al parámetro getBookCollectionInfo para que el valor de la variable page se establezca en 25 y el valor de la variable filter se establezca en 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. */ } }
- Anotación javax.ws.rs.QueryParam
Los parámetros de consulta se agregan al URL después de un signo "?" con pares nombre-valor. Por ejemplo, si el URL es http://example.com/collection?itemID=itemIDValue, el nombre de parámetro de consulta es itemID eitemIDValue es el valor. Los parámetros de consulta se suelen utilizar al filtrar u paginar a través de solicitudes HTTP GET.
Puede leer parámetros de consulta con un parámetro anotado @javax.ws.rs.QueryParam; por ejemplo:
En este ejemplo, las solicitudes a /bookstore/books;page=25;filter=test invocan al parámetro getBookCollectionInfo para que el valor de la variable page se establezca en 25 y el valor de la variable filter se establezca en 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. */ } }
- Anotación javax.ws.rs.HeaderParam
Los parámetros de cabecera son cabeceras HTTP. Aunque hay predefinidas cabeceras HTTP, también puede utilizar cabeceras personalizadas. Las cabeceras a menudo contienen información de metadatos de control para el cliente, el intermediario o el servidor.
Si se ha de leer una cabecera de solicitud HTTP, utilice la anotación @javax.ws.rs.HeaderParam; por ejemplo:@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" */ } }
En este ejemplo, las solicitudes a /bookstore/books/ con un valor de cabecera de solicitud HTTPRange de bytes=0-499 invocan al método bytes=0-499 como el valor de la variable rangeValue.
- Anotación javax.ws.rs.CookieParam
Los parámetros cookie son cabeceras HTTP especiales. Mientras que las cookies se asocian a la identificación de sesión del almacenamiento de a datos con estado que no se aceptan como RESTful, las cookies pueden contener información sin estado.
Si se envía una cookie HTTP, como por ejemplo mycustomid=customvalue123, puede recuperar el valor de la variable mycustomid utilizando el ejemplo siguiente:@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. */ } }
- Anotación javax.ws.rs.FormParam
Los parámetros de formulario se utilizan al enviar un formulario HTML desde un navegador con un tipo de medioapplication/x-www-form-urlencoded. Los parámetros de formulario y los valores se codifican en cuerpo de mensaje de la solicitud con un formato similar al siguiente: firstParameter=firstValue&secondParameter=secondValue. La anotación javax.ws.rs.FormParam permite un acceso fácil a valores de parámetro de formulario individuales.
Si se envía un formulario y el valor de entidad es firstName=Bob&lastName=Smith, puede recuperar los valores de los parámetros de formulario utilizando el ejemplo siguiente:@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" */ } }
Avoid trouble: Puede utilizar cualquiera de un único parámetro no anotado para representar el cuerpo del mensaje o puede utilizar varios parámetros anotados FormParam, pero no ambos. Dado que FormParam requiere que se lea el cuerpo del mensaje de solicitud y el cuerpo del mensaje se representan como una corriente de bytes, el cuerpo del mensaje no se puede leer de nuevo. El código siguiente no es válido:
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 */ } }
Elija una de las formas siguientes para definir variables y poder leer parámetros.
Procedimiento
Resultados
Los métodos de recursos están definidos de modo que se pueden invocar con los valores de parámetro adecuados.