Definindo Tipos de Mídia para Recursos nos Aplicativos RESTful

Os recursos são representados por vários formatos. Os formatos XML, JavaScript Object Notation (JSON), Atom, formatos binários como PNG, JPEG, GIF, texto simples e proprietário são usados para representar recursos. O Representational State Transfer (REST) fornece a flexibilidade para representar um único recurso em vários formatos.

Antes de Iniciar

Defina os recursos no aplicativo da Web JAX-RS.

Sobre Esta Tarefa

Os recursos possuem representações. Uma representação de recurso é o conteúdo na mensagem HTTP que é enviado para ou retornado do recurso que usa o URI. Cada representação que um recurso suporta possui um tipo de mídia correspondente. Por exemplo, se um recurso retornar o conteúdo formatado como XML, é possível usar application/xml como o tipo de mídia associado na mensagem HTTP.

Dependendo dos requisitos do seu aplicativo, os recursos podem retornar representações em um único formato preferencial ou em vários formatos. Por exemplo, os recursos acessados usando clientes JavaScript podem preferir representações JSON porque o JSON é fácil de consumir.

O JAX-RS fornece anotações @Consumes e @Produces para declarar os tipos de mídia que são aceitos para que um método de recurso execute leitura e gravação.

O JAX-RS também mapeia os tipos Java™ para e a partir de representações de recursos usando provedores de entidade. Um provedor de entidade MessageBodyReader lê uma entidade de pedido e desserializa a entidade de pedido em um tipo Java. Um provedor de entidade MessageBodyWriter é serializado a partir de um tipo Java em uma entidade de resposta.

Tabela 1. Provedores de Entidade Padrão e Tipos Básicos Java. Essa tabela inclui os provedores de entidade padrão e os tipos Java básicos que são incluídos no ambiente de tempo de execução JAX-RS, junto com os tipos de conteúdo suportados correspondentes.
Tipo Java MessageBodyReader MessageBodyWriter Tipos de Conteúdo Suportados
byte[] X X */*
java.io.InputStream X X */*
java.io.Reader X X */*
java.lang.String X X */*
java.io.File X X */*
javax.activation.DataSource X X */*
javax.xml.transform.Source X X text/xml, application/xml, application/*+xml
javax.ws.rs.core.MultivaluedMap X X application/x-www-form-urlencoded
Tipos JAXB X X text/xml, application/xml, application/*+xml
javax.ws.rs.core.StreamingOutput   X */*

Se um valor String for usado como o parâmetro de entidade de pedido, o provedor de entidade MessageBodyReader desserializa o corpo do pedido em uma nova String. Se um tipo JAXB for usado como o tipo de retorno em um método de recurso, MessageBodyWriter serializará o objeto Java Architecture for XML Binding (JAXB) em um corpo de resposta.

Se você precisar de um mapeamento customizado a partir de um tipo Java para uma representação específica, consulte as informações sobre o uso de um provedor de entidade definido pelo aplicativo.

Se seu cliente puder manipular vários formatos e você desejar que o servidor determine a melhor representação de recurso a ser retornada, consulte o uso da negociação de conteúdo nos aplicativos JAX-RS para atender vários tipos de conteúdo.

A especificação para XML, JSON e Atom fornece detalhes sobre os formatos de representações de recursos para os aplicativos. Consulte as especificações para saber mais sobre os formatos de representações de recursos.

Procedimento

  1. Determine o formato de representação de recurso, como XML, JSON ou ATOM a ser usado para o pedido ou resposta.
  2. Inclua as anotações @Consumes e @Produces apropriadamente no método de recurso.
  3. Se o seu recurso precisar ler o conteúdo do pedido, inclua um parâmetro de entidade de pedido no método de recurso. O parâmetro de entidade de pedido é um parâmetro Java único no método que não possui uma anotação.
  4. Se o método de recurso retornar conteúdo na resposta, retorne um objeto Java que seja gravável por um provedor de entidade JAX-RS. Este objeto Java é mapeado para a entidade de resposta na resposta HTTP. O objeto retornado deve ser um tipo Java suportado pelo JAX-RS ou agrupado em um tipo javax.ws.rs.core.Response ou javax .ws.rs.core.GenericEntity.

Resultados

Você mapeou as entidades de pedido para o parâmetro de entidade de método de recurso e quaisquer objetos de resposta que forem retornados são mapeados para a entidade de resposta para a representação de recurso.

Exemplo

O seguinte exemplo mostra a definição de XML como a representação de recurso para um aplicativo de livraria RESTful.

  1. Identifique os métodos de recurso que deseja para ler a entidade de pedido ou retornar uma entidade de resposta.

    No exemplo de método retrieveSpecificBookInformation seguinte, não há nenhuma entidade de pedido que seja lido. Entretanto, há um objeto de resposta que é retornado. Esse objeto agrupa um objeto JAXB que contém as informações da entidade. Incluir a anotação @Produces no método de recurso com um tipo de mídia application/xml indica que o método de recurso sempre retorna uma representação XML com um tipo de mídia application/xml.

    Os clientes que possuem um valor de cabeçalho de pedido Accept HTTP compatível com o tipo de mídia application/xml chamam o método corretamente.

    Os clientes que não possuem um valor de cabeçalho Accept HTTP compatível com o tipo de mídia application/xml automaticamente recebem um status de resposta 406 Não Aceito que indica que o servidor não pode produzir uma resposta aceitável.

    O seguinte exemplo identifica os métodos de recurso que leem a entidade de pedido ou retornam uma entidade de resposta:

    /*
     * Book.java
     * Esta classe representa os manuais individuais. A anotação @Produces especifica um tipo de mídia application/xml.
     */
    @Path(“/bookstore/books/{bookID}”)
    public class Book {
      @GET
      @Produces(“application/xml”)
      public javax.ws.rs.core.Response retrieveSpecificBookInformation(@PathParam(“bookID”) String theBookID,
       @Context javax.ws.rs.core.HttpHeaders headers) {
       /* … */
       return
        Response.ok(/* JAXB object to represent response body entity */).expires(/* Expires response header value*/).header(“CustomHeaderName”, “CustomHeaderValue”).build();
       }
       @PUT
       public String updateBookInformation(@PathParam(“bookID”) String theBookID, String theRequestEntity,
        @javax.ws.rs.HeaderParam(“Content-Length”) String contentLengthHeader) { /* … */ }
    
       @DELETE
       public void removeBook(@PathParam(“bookID”) String theBookID) { /* … */ }
    }
  2. Identifique os métodos de recurso necessários para consumir as informações de pedido.

    No seguinte fragmento, o método PUT no recurso de manual aceita o conteúdo de entidade de pedido se um tipo de mídia text/plain for enviado, conforme definido na anotação @Consumes. Esse método retorna conteúdo com uma representação text/plain, conforme especificado nas anotações @Produces.

    Se um cliente não enviar uma mensagem com um valor Tipo de Conteúdo de text/plain, o método de recurso PUT não será chamado. Se Content-Type: application/xml for enviado nos cabeçalhos de pedido HTTP, o método updateBookInformation Java não será chamado.

    O método DELETE não lê uma entidade de pedido nem retorna uma entidade de resposta, portanto, ele não requer nenhuma das anotações @Consumes ou @Produces.

    O seguinte exemplo identifica os métodos de recurso que consomem as informações de pedido:

    /*
     * Book.java
     * Esta classe representa os manuais individuais com cabeçalhos customizados.
     */
    @Path(“/bookstore/books/{bookID}”)
    public class Book {
      @GET
      @Produces(“application/xml”)
      public javax.ws.rs.core.Response retrieveSpecificBookInformation(@PathParam(“bookID”) String theBookID, @Context javax.ws.rs.core.HttpHeaders headers) {
        /* … */
        return Response.ok(/* JAXB object to represent response body entity */).expires(/* Expires response header value).header(“CustomHeaderName”, “CustomHeaderValue”).build();
      }
      @PUT
      @Consumes(“text/plain”)
      @Produces(“text/plain”)
      public String updateBookInformation(@PathParam(“bookID”) String theBookID, String theRequestEntity, @javax.ws.rs.HeaderParam(“Content-Length”) String contentLengthHeader) {
        /* … */
        String responseEntity = /* a plain text representation */;
        return responseEntity;
      }
    
      @DELETE
      public void removeBook(@PathParam(“bookID”) String theBookID) { /* … */ }
    }

O que Fazer Depois

Consulte a especificação JAX-RS para obter uma lista de todos os formatos de mídia padrão que são suportados para as representações.

Usuários avançados podem considerar a definição de mapeamentos customizados de tipos Java para representações ou considerar o uso da negociação de conteúdo para clientes para negociar representações de recursos preferidas. Para saber mais sobre essas opções, consulte as informações sobre o uso dos formatos de entidade definidos customizados ou as informações sobre o atendimento de vários tipos de conteúdo com a negociação de conteúdo.


Ícone que indica o tipo de tópico Tópico de Tarefa



Ícone de registro de data e hora Última atualização: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxrs_defresource_mediatype
Nome do arquivo: twbs_jaxrs_defresource_mediatype.html