Explore os parâmetros de solicitação de Jersey

1. Introdução

Jersey é uma estrutura Java popular para a criação de serviços da Web RESTful.

Neste tutorial, exploraremos como ler diferentes tipos de parâmetro de solicitação por meio de um projeto Jersey simples.

2. Configuração do Projeto

Usando os arquétipos Maven, seremos capazes de gerar um projeto de trabalho para nosso artigo:

mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-grizzly2
  -DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMode=false
  -DgroupId=com.example -DartifactId=simple-service -Dpackage=com.example
  -DarchetypeVersion=2.28

O projeto Jersey gerado será executado em um contêiner Grizzly.

Agora, por padrão, o endpoint para nosso aplicativo seráhttp://localhost:8080/myapp.

Vamos adicionar um recursoitems, que usaremos para nossos experimentos:

@Path("items")
public class ItemsController {
    // our endpoints are defined here
}

Observe, a propósito, queJersey also works great with Spring controllers.

3. Tipos de parâmetros anotados

Portanto, antes de realmente lermos quaisquer parâmetros de solicitação, vamos esclarecer algumas regras. The allowed types of parameters are:

Tipos primitivos, comofloat echar
Tipos que têm um construtor com um único argumentoString
Tipos que possuem um método estáticofromString ouvalueOf; para aqueles, um único argumentoString é obrigatório
Coleções - comoList,Set eSortedSet – dos tipos descritos acima

Além disso, podemosregister an implementation of the ParamConverterProvider extensão JAX-RS SPI. O tipo de retorno deve ser uma instânciaParamConverter capaz de uma conversão deString em um tipo.

4. Biscoitos

Podemos resolvercookie values em nossos métodos Jersey usando a anotação@CookieParam:

@GET
public String jsessionid(@CookieParam("JSESSIONId") String jsessionId) {
    return "Cookie parameter value is [" + jsessionId+ "]";
}

Se iniciarmos nosso contêiner, podemoscURL este endpoint para ver a resposta:

> curl --cookie "JSESSIONID=5BDA743FEBD1BAEFED12ECE124330923" http://localhost:8080/myapp/items
Cookie parameter value is [5BDA743FEBD1BAEFED12ECE124330923]

5. Cabeçalhos

Ou podemos resolverHTTP headers com a anotação@HeaderParam:

@GET
public String contentType(@HeaderParam("Content-Type") String contentType) {
    return "Header parameter value is [" + contentType+ "]";
}

Vamos testar novamente:

> curl --header "Content-Type: text/html" http://localhost:8080/myapp/items
Header parameter value is [text/html]

6. Parâmetros do caminho

Especialmente com APIs RESTful, é comum incluir informações no caminho.

Podemos extrair elementos de caminho com@PathParam:

@GET
@Path("/{id}")
public String itemId(@PathParam("id") Integer id) {
    return "Path parameter value is [" + id + "]";
}

Vamos enviar outro comandocurl com o valor3:

> curl http://localhost:8080/myapp/items/3
Path parameter value is [3]

7. Parâmetros de consulta

Geralmente, usamos parâmetros de consulta nas APIs RESTful para obter informações opcionais.

Para ler esses valores, podemos usar a anotação@QueryParam:

@GET
public String itemName(@QueryParam("name") String name) {
    return "Query parameter value is [" + name + "]";
}

Então, agora podemos testar comcurl, como antes:

> curl http://localhost:8080/myapp/items?name=Toaster
Query parameter value if [Toaster]

8. Parâmetros do formulário

Para ler os parâmetros de um envio de formulário, usaremos a anotação@FormParam:

@POST
public String itemShipment(@FormParam("deliveryAddress") String deliveryAddress,
  @FormParam("quantity") Long quantity) {
    return "Form parameters are [deliveryAddress=" + deliveryAddress+ ", quantity=" + quantity + "]";
}

Também precisamos definir oContent-Type adequado para simular a ação de envio do formulário. Vamos definir os parâmetros do formulário usando o sinalizador-d:

> curl -X POST -H 'Content-Type:application/x-www-form-urlencoded' \
  -d 'deliveryAddress=Washington nr 4&quantity=5' \
  http://localhost:8080/myapp/items
Form parameters are [deliveryAddress=Washington nr 4, quantity=5]

9. Parâmetros da matriz

A matrix parameter é um parâmetro de consulta mais flexível, pois eles podem ser adicionados em qualquer lugar no URL.

Por exemplo, emhttp://localhost:8080/myapp;name=value/items, o parâmetro da matriz éname.

Para ler esses valores, podemos usar a anotação@MatrixParam disponível:

@GET
public String itemColors(@MatrixParam("colors") List colors) {
    return "Matrix parameter values are " + Arrays.toString(colors.toArray());
}

E agora vamos testar novamente nosso endpoint:

> curl http://localhost:8080/myapp/items;colors=blue,red
Matrix parameter values are [blue,red]

10. Parâmetros do Bean

Finalmente, vamos verificar como combinar os parâmetros de solicitação usando parâmetros de bean. Para esclarecer,a bean parameter é na verdade um objeto que combina diferentes tipos de parâmetros de solicitação.

Usaremos um parâmetro de cabeçalho, um caminho e um formulário aqui:

public class ItemOrder {
    @HeaderParam("coupon")
    private String coupon;

    @PathParam("itemId")
    private Long itemId;

    @FormParam("total")
    private Double total;

    //getter and setter

    @Override
    public String toString() {
        return "ItemOrder {coupon=" + coupon + ", itemId=" + itemId + ", total=" + total + '}';
    }
}

Além disso, para obter essa combinação de parâmetros, usaremos a anotação@BeanParam:

@POST
@Path("/{itemId}")
public String itemOrder(@BeanParam ItemOrder itemOrder) {
    return itemOrder.toString();
}

No comandocurl, adicionamos esses três tipos de parâmetros e terminaremos com um único objetoItemOrder:

> curl -X POST -H 'Content-Type:application/x-www-form-urlencoded' \
  --header 'coupon:FREE10p' \
  -d total=70 \
  http://localhost:8080/myapp/items/28711
ItemOrder {coupon=FREE10p, itemId=28711, total=70}

11. Conclusão

Para resumir, criamos uma configuração simples para um projeto de Jersey para nos ajudar a explorar como ler diferentes parâmetros de uma solicitação usando Jersey.

A implementação de todos esses snippets está disponívelover on Github.

TOC

Explore os parâmetros de solicitação de Jersey