Bruno Pereira

Implementação com a JAX-RS (Java API for RESTFul Web Services)

Para oferecer melhor suporte a serviços REST em Java, foi criada a JSR-311. Veja os objetivos desta JSR.

Com a JAX-RS, um recurso web é implementado como uma classe Recurso e as requisições são tratadas por métodos da mesma. Uma classe Recurso é simplesmente um POJO contendo anotações da JAX-RS para indicar os mapeamentos e operações existentes.

Ciclo de vida e ambiente

Por padrão, uma nova instância da classe Recurso é criada para cada requisição àquele Recurso. Inicialmente o construtor é invocado, dependências necessárias são injetadas, e então o método adequado é executado. Após estas etapas, o objeto fica disponível para o coletor de lixo.

As classes Recurso são instanciadas pelo runtime JAX-RS e devem possuir pelo menos um construtor público. Um construtor público pode incluir parâmetros com uma das seguintes anotações: @Context, @HeaderParam, @CookieParam, @MatrixParam, @QueryParam e @PathParam. Estas anotações realizam injeção de dependências relativas a serviços REST, e são apresentadas na Tabela 3.

Tabela 3. Anotações da JAX-RS para injeção de dependências

Com exceção do Context, estes parâmetros são enviados dentro de URIs, query strings, cabeçalhos HTTP e cookies. Sendo assim, sua representação na camada de transporte é como String. Entretanto, podemos colocar estas anotações sobre parâmetros que não são String, para já recebermos os dados convertidos em um formato mais adequado para nossa manipulação. Tipos de parâmetros que podem ser marcados com estas anotações são:

• Tipos primitivos
• Classes que possuam um construtor tendo uma única String como parâmetro
• Classes que possuam um método estático valueOf() recebendo uma String como parâmetro;
• List<T>, Set<T> ou SortedSet<T>, onde T satisfaz a condição 2 ou a 3.

A seguir um exemplo de uso destas anotações:

@GET
@Path("{usuarioId}")
public Response buscarUsuario(@PathParam("usuarioId") String usuarioId) {
Usuario usuario = usuarioService.buscar(usuarioId);
Response resposta = Response.ok(usuario).build();
return resposta;
}

Este exemplo mostra como poderia ser um método de busca de usuário recebendo uma URI /usuario/{usuarioId}, como /usuario/123. O parâmetro usuarioId do método poderia ser int ou Integer, caso o ID do usuário fosse um número inteiro. A implementação da API faria a conversão do parâmetro enviado na URI para o tipo especificado no método.

Requisições aos métodos de Recursos

Um método de Recurso é uma operação exposta como um serviço REST. Estes métodos ficam em uma classe Recurso e são anotados com o método HTTP associado à operação em questão. O conjunto de anotações que define os métodos HTTP que podem ser utilizados nas operações é: @GET, @POST, @PUT, @DELETE, @HEAD e @OPTIONS.

Métodos de Recursos que serão expostos para os clientes devem ser públicos. Implementações da JSR devem alertar os desenvolvedores caso encontrem métodos não-públicos que sejam marcados com alguma destas anotações de método HTTP.

Os parâmetros dos métodos são convertidos da requisição de acordo com as anotações apresentadas na Tabela 3. Um método de Recurso pode ter no máximo um parâmetro não-anotado. Este parâmetro não-anotado será obtido do corpo da requisição.

A obtenção de parâmetros do corpo da requisição só faz sentido quando estamos falando de requisições POST e PUT. Estes são os únicos métodos HTTP que possuem um corpo, e quase sempre são utilizados em operações de criação e atualização de Recursos, respectivamente. O trecho a seguir apresenta um exemplo de método que recebe requisições POST para cadastro de usuários.

@POST
public Response cadastrarUsuario(Usuario usuario) {
usuario = usuarioService.cadastrar(usuario);
try {
return Response.created(new URI(usuario.getCodUsuario())).build();
} catch (URISyntaxException e) { throw new RuntimeException(e); }
}

Respostas dos métodos de Recursos

As respostas aos métodos de Recursos podem ser declaradas como void, Response ou qualquer outra classe Java. Retornar void implica em enviar uma resposta com corpo vazio, o que é mapeado em um status HTTP 204 (No Content). Este status é utilizado pela JSR para indicar que a requisição teve sucesso, e a resposta não possui corpo.

Colocar uma classe Java como tipo de resposta fará com que o objeto retornado seja colocado no corpo da resposta. Um objeto nulo enviado na resposta implicará em status HTTP 204 e um objeto não-nulo implicará no status HTTP 200.

A classe Response pode ser colocada como tipo de retorno dos métodos caso desejemos ter mais controle sobre a resposta. Com esta forma de retorno, conseguimos especificar cabeçalhos, corpo, status, cookies e mais algumas informações da resposta enviada.

Até este momento não mencionamos nada a respeito do formato dos Recursos manipulados. Mostramos exemplos de busca e cadastro de usuários, mas ficou explícita nos exemplos apenas a manipulação de objetos Java. A questão dos formatos é muito importante e é coberta na seção “Manipulação de diferentes formatos”.

Tratamento de erros e exceções

Como padrão, quando ocorre uma exceção durante uma chamada REST, o cliente recebe um status HTTP 500 (Internal Server Error). Em muitas situações este status pode não ser satisfatório, pois não fornece muita informação sobre o erro que ocorreu no servidor. Para resolver este problema a JSR-311 permite que a resposta seja personalizada em caso de exceções. Podemos fazer este controle de duas formas.

A primeira forma é com uma exceção especial. Basta disparar uma unchecked exception javax.ws.rs.WebApplicationException. Criando esta exceção podemos passar o status HTTP e um objeto Response, permitindo total controle da resposta que será enviada para o usuário.

Porém, em uma aplicação grande é muito comum termos o lançamento de outras exceções em camadas inferiores. Para esta situação a JSR-311 permite que seja criada uma classe para mapear a resposta correspondente a cada exceção. Este mapeamento seria conhecido apenas pela camada de serviços REST.

A classe de mapeamento deve implementar a interface javax.ws.rs.ext.ExceptionMapper e ser anotada com @Provider. A partir daí, quando a exceção especificada for disparada o controle vai passar para o método toResponse() desta classe. Este método poderá construir a resposta de acordo com a exceção, que é passada como parâmetro.

Sobre a segunda forma de tratar exceções vale citar que ela ainda está sendo implementada na versão 0.8 da especificação, e está sujeita a modificações até a finalização da JSR.

O trecho a seguir apresenta um exemplo de mapeamento de exceção para uma resposta com status HTTP customizado.

@Provider
public class ItemJaVendidoExceptionMapper implements ExceptionMapper {
public Response toResponse(ItemJaVendidoException e) {
return Response.status(Response.Status.GONE).build();
}
}

Anterior — Índice — Próxima