Definindo Parâmetros para Representações de Pedido para os Recursos nos Aplicativos RESTful
Os parâmetros são usados para transmitir e incluir informações adicionais em um pedido. É possível usar os parâmetros como parte da URL ou nos cabeçalhos. Os parâmetros de caminho, de matriz, de consulta, de cabeçalho e de cookie são úteis para transmitir informações adicionais para um pedido.
Sobre Esta Tarefa
Existem vários tipos de parâmetro. O Java™ API para Serviços da Web RESTful (JAX-RS) permite acessar facilmente todos os tipos de parâmetros usando parâmetros introduzíveis anotados.
É possível usar qualquer tipo primitivo Java básico, incluindo java.lang.String, como parâmetros, além dos tipos Java com um construtor que usa um método estático String ou valueOf(String) único. Além disso, é possível usar as interfaces List, SortedSet e Set em que o tipo genérico é um dos tipos mencionados anteriormente, como um Set, quando um parâmetro pode ter vários valores. Se você precisar analisar pedidos, use String como o tipo de parâmetro para poder concluir a inspeção e a customização básicas de respostas de caminho de erro.
O JAX-RS fornece as seguintes anotações para usar nos parâmetros de método de recursos para especificar que o método de recurso pode ser chamado com os valores de parâmetro corretos.
- Anotação javax.ws.rs.PathParam
Os parâmetros de caminho fazem parte da URL. Por exemplo, a URL pode incluir /collection/{item}, em que {item} é um parâmetro de caminho que identifica o item na coleta. Como os parâmetros de caminho fazem parte da URL, eles são essenciais para identificar o pedido.
Se partes da URL forem parâmetros, poderá usar um parâmetro anotado @javax.ws.rs.PathParam, como por exemplo:
Nesse exemplo, os pedidos para /bookstore/books/12345 designa o valor 12345 para a variável 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/ */ } }
- Anotação javax.ws.rs.MatrixParam
Os parâmetros de matriz fazem parte da URL. Por exemplo, se a URL incluir o segmento do caminho, /collection;itemID=itemIDValue, o nome do parâmetro de matriz será itemID e itemIDValue será o valor.
É possível ler os parâmetros de matriz com um parâmetro @javax.ws.rs.MatrixParam anotado, como por exemplo:
Nesse exemplo, os pedidos para /bookstore/books;page=25;filter=test chamam o parâmetro getBookCollectionInfo para que o valor da variável page seja configurado para 25 e o valor da variável filter seja configurado para 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. */ } }
- Anotação javax.ws.rs.QueryParam
Os parâmetros de consulta são anexados à URL após um “?” com os pares nome-valor. Por exemplo, se a URL for http://example.com/collection?itemID=itemIDValue, o nome do parâmetro de consulta será itemID e itemIDValue será o valor. Os parâmetros de consulta são normalmente usados ao filtrar ou paginar por meio dos pedidos HTTP GET.
É possível ler os parâmetros de consulta com um parâmetro @javax.ws.rs.QueryParam anotado, como por exemplo:
Nesse exemplo, os pedidos para /bookstore/books;page=25;filter=test chamam o parâmetro getBookCollectionInfo para que o valor da variável page seja configurado para 25 e o valor da variável filter seja configurado para 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. */ } }
- Anotação javax.ws.rs.HeaderParam
Os parâmetros de cabeçalho são cabeçalhos HTTP. Enquanto houver cabeçalhos HTTP predefinidos, também poderá usar cabeçalhos customizados. Os cabeçalhos normalmente contêm informações de metadados de controle para o cliente, intermediário ou servidor.
Se um cabeçalho de pedido HTTP tiver que ser lido, use a anotação @javax.ws.rs.HeaderParam, como por exemplo:@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" */ } }
Nesse exemplo, os pedidos para /bookstore/books/ com um valor de cabeçalho de pedido HTTP Range de bytes=0-499 chamam o método com bytes=0-499 como o valor da variável rangeValue.
- Anotação javax.ws.rs.CookieParam
Os parâmetros de cookie são cabeçalhos HTTP especiais. Enquanto os cookies são associados à identificação de sessão de armazenamento ou aos dados stateful que não são aceitos como RESTful, os cookies podem conter informações sem preservação de estado.
Se um cookie HTTP for enviado, como mycustomid=customvalue123, poderá recuperar o valor da variável mycustomid usando o seguinte exemplo:@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. */ } }
- Anotação javax.ws.rs.FormParam
Os parâmetros de formato são usados ao enviar um formato HTML a partir de um navegador com um tipo de mídia application/x-www-form-urlencoded. Os parâmetros e valores de formato são codificados no corpo da mensagem de pedido no formato como o seguinte: firstParameter=firstValue&secondParameter=secondValue. A anotação javax.ws.rs.FormParam permite acessar facilmente valores de parâmetro de formato individual.
Se um formato for enviado e o valor da entidade for firstName=Bob&lastName=Smith, poderá recuperar os valores dos parâmetros de formato usando o seguinte exemplo:@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" */ } }
Evitar Problemas: É possível usar um único parâmetro não anotado para representar o corpo da mensagem ou usar vários parâmetros FormParam anotados, mas não ambos. Como o FormParam requer que o corpo da mensagem de pedido seja lido e que o corpo da mensagem seja representado como um fluxo de bytes, o corpo da mensagem não poderá ser lido novamente. O seguinte código não é 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 */ } }
Escolha uma das seguintes maneiras para definir variáveis para os parâmetros de leitura.
Procedimento
Resultados
Seus métodos de recursos estão definidos para que eles possam ser chamados com os valores de parâmetro apropriados.