Aula 25: Web Services (III)

Aula 25: Web Services (III) Diego Passos Universidade Federal Fluminense Técnicas de Projeto e Implementação de Sistemas II Diego Passos (UFF) Web Services (III) TEPIS II 1 / 39

Última Aula A API JAX-WS. Como escrever Big Web Services. Montagem e disponibilizaçao. Geração dos artefatos. Como escrever um cliente. Mapeamento de tipos de dados. Diego Passos (UFF) Web Services (III) TEPIS II 2 / 39

Aula de Hoje RESTful Web Services: Visão geral. A API JAX-RS. Como escrever RESTful Web Services. Tipos de anotações utilizadas. Provedores de Entidades. Recebendo parâmetros. Informações contextuais. Diego Passos (UFF) Web Services (III) TEPIS II 3 / 39

RESTful Web Services: Visão Geral Até agora, discutimos um tipo específico de Web Services: os Big Web Services. Padrão do W3C. Baseado em SOAP, XML. Relativamente complexos. Uma alternativa em voga atualmente são os RESTful Web Services. Baseados no padrão arquitetural REST (Representational State Transfer). Abstração da arquitetura da Web. O padrão REST determina uma série de restrições na iteração entre os componentes do sistema. Diego Passos (UFF) Web Services (III) TEPIS II 4 / 39

RESTful Web Services: Visão Geral (II) Exemplos de restrições impostas pelo padrão REST: Modelo cliente-servidor. Comunicação stateless. Respostas podem ser cacheadas. Interface uniformizada dos serviços. Uso de URIs (identificam funcionalidades e recursos). Mensagens auto-descritivas (contém toda a informação necessária para entendê-las; não sendo necessário estado). Estado do sistema só muda através da interação do cliente com hypermidia. Diego Passos (UFF) Web Services (III) TEPIS II 5 / 39

RESTful Web Services: Visão Geral (III) Em termos práticos, a diferença entre Big Web Services e RESTful Web Services está na padronização. Os Big Web Services são padronizados e por isso demandam a geração de inúmeros artefatos. Como o arquivo WSDL, por exemplo. O conceito de RESTful Web Service é bem mais flexível. Qualquer serviço ofertado pela Web que esteja de acordo com as restrições arquiteturais REST. Esta liberdade faz com que seja mais fácil desenvolver um Web Service do tipo REST. Por outro lado, é difícil elaborar uma API genérica, especialmente do lado do cliente. Diego Passos (UFF) Web Services (III) TEPIS II 6 / 39

RESTful Web Services: JAX-RS O J2EE inclui uma API para auxiliar na criação de RESTful Web Services. JAX-RS. Análoga à JAX-WS. Utiliza bastante o conceito de anotações. Desenvolvedor anota classes e métodos definindo recursos e ações que podem ser executadas. As anotações do JAX-WS são de tempo de execução. São interpretadas por um servidor de aplicação para gerar as classes auxiliares necessárias para implantar o Web Service. Diego Passos (UFF) Web Services (III) TEPIS II 7 / 39

JAX-RS: Anotações Há um grande número de anotações na API. Alguns exemplos: @Path: Identifica a URL para a qual a classe será mapeada. O atributo especificado para esta anotação será usado como o sufixo da URI. Considerando o endereço base do servidor. @GET: Um método anotado com esta anotação processará requisições HTTP do tipo GET. Há anotações para outros métodos como @POST, @PUT, @DELETE, @HEAD. Diego Passos (UFF) Web Services (III) TEPIS II 8 / 39

JAX-RS: Anotações (II) @Produces: Define o tipo MIME da resposta gerada pelo serviço. e.g., plain/text, application/json. @Consumes: Define o tipo MIME da entrada provida pelo cliente. e.g., plain/text, application/json. Diego Passos (UFF) Web Services (III) TEPIS II 9 / 39

JAX-RS: Exemplo de Código import javax.ws.rs.get; import javax.ws.rs.produces; import javax.ws.rs.path; // The Java class will be hosted at the URI path "/helloworld" @Path("/helloworld") public class HelloWorldResource { // The Java method will process HTTP GET requests @GET // The Java method will produce content identified by the MIME Media // type "text/plain" @Produces("text/plain") public String getclichedmessage() { // Return some cliched textual content return "Hello World"; Web Service servido na URL (relativa) /helloworld. Requisições HTTP do tipo GET resultam em chamadas ao método getclinchedmessage(). Saída gerada para o cliente é do tipo text/plain. Diego Passos (UFF) Web Services (III) TEPIS II 10 / 39

JAX-RS: Exemplo de Código (II) E se precisarmos receber conteúdo do usuário? @POST @Consumes("text/plain") public void postclichedmessage(string message) { // Store the message Conteúdo da requisição do usuário é passado como parâmetro (String) do método. Diego Passos (UFF) Web Services (III) TEPIS II 11 / 39

JAX-RS: A Anotação @Path e Templates Vimos um uso bastante simplificado da anotação @Path. Ela recebia como atributo uma String especificando uma URL estática (/helloworld). Esta anotação, no entanto, é bem mais poderosa. Ela permite que especifiquemos templates. Estes templates podem ser usados, por exemplo, para usarmos parte de uma URL como uma variável/parâmetro. Diego Passos (UFF) Web Services (III) TEPIS II 12 / 39

JAX-RS: A Anotação @Path e Templates (II) Considere o seguinte exemplo: Queremos criar um Web Service para consultar informações sobre usuários de um sistema. O Web Service será mapeado para a URL /users/. O cliente deve especificar o nome do usuário (do qual quer obter informações). Uma opção seria colocar o nome do usuário no corpo da requisição. Ao invés disso, podemos usar uma solução baseada em templates: @Path("/users/{username") public class UserResource { @GET @Produces("text/xml") public String getuser(@pathparam("username") String username) {... A sintaxe {username cria uma variável username. Se o cliente acessa a URL /users/diego esta variável terá o valor diego. Esta variável pode ser acessada pelos métodos. Diego Passos (UFF) Web Services (III) TEPIS II 13 / 39

JAX-RS: A Anotação @Path e Templates (III) É possível ainda especificar o formato das variáveis através de expressões regulares. Suponha no exemplo anterior que nomes de usuário só podem ser compostos por letras e números. Podemos restringir isso com a seguinte declaração: @Path("/users/{username: [a-za-z][a-za-z0-9]*") public class UserResource { @GET @Produces("text/xml") public String getuser(@pathparam("username") String username) {... Se tentamos acessar a URL /users/diego3, o acesso é bem sucedido. Se tentamos acessar a URL /users/diego_passos, recebemos um erro 404. Diego Passos (UFF) Web Services (III) TEPIS II 14 / 39

JAX-RS: A Anotação @Path e Templates (IV) Também podemos definir um template com mais de uma variável. Exemplo: queremos nome e sobrenome do usuário. @Path("/users/{nome/{sobrenome") public class UserResource { @GET @Produces("text/plain") public String getuser(@pathparam("nome") String nome, @PathParam("sobrenome") String sobrenome) { return "Nome completo: " nome + " " + sobrenome; Diego Passos (UFF) Web Services (III) TEPIS II 15 / 39

JAX-RS: A Anotação @Path e Templates (V) Algumas outras observações: Uma mesma variável pode ser especificada múltiplas vezes em uma anotação @Path. Exemplo: @Path("/users/{nome/{nome"). Neste caso, só serão aceitas requisições a URLs cujos dois últimos componentes sejam iguais. Variáveis podem ser vazias. Exemplo: @Path("/users/{nome/home"). Cliente acessa URL /users//home. Variável nome ganha o valor (String vazia). Note ainda que a anotação @Path pode ser usada para métodos específicos. Aquele método será mapeado para aquela URL. Diego Passos (UFF) Web Services (III) TEPIS II 16 / 39

JAX-RS: Anotações Designadoras de Métodos de Requisição São anotações utilizadas para associar um método HTTP a um método da classe. Vimos exemplos de uso de duas: @GET e @POST. São também suportadas: @PUT: incluir um recurso. @DELETE: remover um recurso. @HEAD: informações sobre um recurso. Os métodos HTTP HEAD e OPTIONS são suportados por padrão, mesmo se não implementados explicitamente. Implementação padrão do HEAD retorna o mesmo que a implementação do GET, sem o conteúdo. Diego Passos (UFF) Web Services (III) TEPIS II 17 / 39

JAX-RS: Anotações Designadoras de Métodos de Requisição (II) A implementação do OPTIONS é mais interessante. Ela retorna (como esperado) o conjunto de requisições que são suportadas. Mas também retorna um documento WADL: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <application xmlns="http://wadl.dev.java.net/2009/02"> <doc xmlns:jersey="http://jersey.java.net/" jersey:generatedby="jersey: 2.10.4 2014-08-08 15:09:00"/> <grammars/> <resources base="http://172.16.10.75:8080/webservice2/services/"> <resource path="basicpost"> <method id="postclinchedmessage" name="post"> <request> <representation mediatype="text/plain"/> </request> <response> <representation mediatype="text/plain"/> </response> </method> </resource> </resources> </application> Diego Passos (UFF) Web Services (III) TEPIS II 18 / 39

JAX-RS: Anotações Designadoras de Métodos de Requisição (III) O WALD é um formato de documento utilizado para descrever aplicações Web em geral. Hoje, o exemplo mais comum de uso é com os RESTful Web Services. Provê informação sobre as operações oferecidas. Parâmetros esperados. Formato da entrada. Formato da resposta. É o equivalente para RESTful Web Services do WSDL para Big Web Services. Diego Passos (UFF) Web Services (III) TEPIS II 19 / 39

JAX-RS: Anotações Designadoras de Métodos de Requisição (IV) Não há uma assinatura definida para os métodos de requisição. Eles podem receber inúmeros parâmetros (e.g., extraídos do template da anotação @Path). Eles podem ter vários tipos de retorno diferentes. Mas há algumas restrições: O tipo de retorno deve ser void, um tipo básico de Java, ou um javax.ws.rs.core.response. Este último provê uma maneira de manipular metadados da resposta. Diego Passos (UFF) Web Services (III) TEPIS II 20 / 39

JAX-RS: Incluindo Metadados nas Respostas Isso é feito com as classes Response e ResponseBuilder. Exemplo de funcionalidades: Definição de cookies. Definição de headers. Definição de código de status. Definição do media type. Exemplo de código: @Path("/users/{nome/{sobrenome") public class UserResource { @GET @Produces("text/plain") public Response getuser(@pathparam("nome") String nome, @PathParam("sobrenome") { return Response.status(404).entity("User not found").build(); Diego Passos (UFF) Web Services (III) TEPIS II 21 / 39

JAX-RS: Provedores de Entidades Suponha que desejemos escrever um Web Service que adiciona um usuário a uma base de dados. Usuários têm as seguintes propriedades: Nome completo. Apelido. Data de nascimento. CPF. Senha. Temos uma classe User com esta representação. O Web Service recebe estes dados no corpo de uma requisição POST. Como obter, a partir da requisição, um objeto do tipo User? Diego Passos (UFF) Web Services (III) TEPIS II 22 / 39

JAX-RS: Provedores de Entidades (II) Primeira abordagem: receber o corpo da requisição como texto e fazer o parse. Código resultante: @POST @Consumes("text/plain") @Produces("text/plain") public String postclichedmessage(string message) { User u = new User(); // Parse da mensagem e preenchimento do objeto.... // Adição do usuário à base.... // Envio da resposta ao usuário.... Há muita coisa sendo feita neste método. Note também que a assinatura do método é enganosa: Implicitamente, o método espera que o corpo da mensagem seja um User. Ou melhor, sua representação em texto. Diego Passos (UFF) Web Services (III) TEPIS II 23 / 39

JAX-RS: Provedores de Entidades (III) Podemos implementar isso de outra forma: usando um provedor de entidade. Exemplo de código: @Provider @Consumes("text/user") public class UserUnmarshaller implements MessageBodyReader { @Override public boolean isreadable(class aclass, Type type, Annotation[] annotations, MediaType mediatype) { return true; @Override public Object readfrom(class aclass, Type type, Annotation[] annotations, MediaType mediatype, MultivaluedMap multivaluedmap, InputStream inputstream) throws IOException, WebApplicationException { User result = null; try { // Parse da mensagem (lida do inputstream). // Resultado deve ser colocado no objeto result. //... catch (Exception e) { e.printstacktrace(); return result; Diego Passos (UFF) Web Services (III) TEPIS II 24 / 39

JAX-RS: Provedores de Entidades (IV) A classe do slide anterior implementa um decodificador para o tipo de mídia text/user. Fictício, criado para este exemplo. Tendo a classe UserUnmarshaller carregada, podemos usar este tipo de mídia para tornar transparente o parse dos dados: @POST @Consumes("text/user") @Produces("text/plain") public String postclichedmessage(user u) { // Já recebemos automaticamente uma instância de User preenchida com os dados da requisição. // Basta fazer a inserção no banco.... // Envio da resposta ao usuário.... Diego Passos (UFF) Web Services (III) TEPIS II 25 / 39

JAX-RS: Provedores de Entidades (V) Podemos fazer também o processo inverso. Na resposta, enviamos um User. Ou melhor, sua representação textual. Novamente, ao invés de fazer o próprio método, escrevemos um provedor de entidade. Neste caso, no entanto, como se trata de uma resposta, o provedor precisa fazer a operação contrária. Este provedor deve implementar a interface MessageBodyWriter. Diego Passos (UFF) Web Services (III) TEPIS II 26 / 39

JAX-RS: Provedores de Entidades (VI) Para tipos mais comuns, a JAX-RS já provê provedores de entidades padrão. Estes provedores mapeiam tipos comuns do Java a tipos de mídia comuns. Por exemplo: byte[] */*. String text/*. File */*. MultivaluedMap<String,String> application/x-www-form-urlencoded. Para usá-los, basta definir o método com os tipos de parâmetro/retorno adequados aos tipos de mídia. Diego Passos (UFF) Web Services (III) TEPIS II 27 / 39

JAX-RS: Anotação @Produces Como visto nos exemplos anteriores, esta anotação declara o tipo de conteúdo que é produzido por um dado método. A anotação também pode ser usada na declaração da classe. Neste caso, todos os métodos podem produzir o tipo especificado de conteúdo. Se um método específico declara a anotação, esta se sobrepõe à anotação da classe. Note que a anotação define os tipos de dados que podem ser gerados pelos métodos. Por isso, a anotação pode conter mais de um tipo. Exemplo: @Produces("image/jpeg,image/png"). Diego Passos (UFF) Web Services (III) TEPIS II 28 / 39

JAX-RS: Anotação @Produces Quando um cliente envia uma requisição, ele pode especificar um conjunto de formatos aceitáveis. Neste caso, o JAX-RS procura entre todos os métodos que atendem àquele tipo de requisição o que se encaixa melhor ao que o cliente requisitou. Se nenhum método se encaixa, servidor retorna um erro 406. Exemplo: @Path("/myResource") @Produces("text/plain") public class SomeResource { @GET public String dogetasplaintext() {... @GET @Produces("text/html") public String dogetashtml() {... Diego Passos (UFF) Web Services (III) TEPIS II 29 / 39

JAX-RS: Anotação @Consumes Também já vista em exemplos anteriores. Equivalente à @Produces para dados de entrada. Segue as mesmas convenções da anotação @Produces: Pode ser aplicada a uma classe inteira. Pode receber mais de uma especificação de formato de dados. JAX-RS utiliza para identificar qual o método (mais) adequado para tratar uma requisição. De forma similar à anotação @Produces, se nenhum método declara consumir um dado formato, é retornado um erro 415. Diego Passos (UFF) Web Services (III) TEPIS II 30 / 39

JAX-RS: Recebendo Parâmetros Vimos anteriormente um exemplo de obtenção de parâmetros através da URL. Definimos um template usando a anotação @Path. Declaramos parâmetros de métodos usando a anotação @PathParam. Mas existem muitas maneiras de um cliente codificar seus parâmetros em uma requisição HTTP: Query. Form. Cookies. Headers. Matrix. A JAX-RS suporta todas estas formas. Diego Passos (UFF) Web Services (III) TEPIS II 31 / 39

JAX-RS: Query Parameters São parâmetros passados em uma URL explicitamente. Exemplo: http://servidor/webservice/user?username=diego&action=remove Podemos acessar estes parâmetros com a anotação @QueryParam. Podemos ainda definir valores padrão com a anotação @DefaultValue. Usados em caso de omissão. @Path("smooth") @GET public Response smooth( @DefaultValue("2") @QueryParam("step") int step, @DefaultValue("true") @QueryParam("min-m") boolean hasmin, @DefaultValue("true") @QueryParam("max-m") boolean hasmax, @DefaultValue("true") @QueryParam("last-m") boolean haslast, @DefaultValue("blue") @QueryParam("min-color") ColorParam mincolor, @DefaultValue("green") @QueryParam("max-color") ColorParam maxcolor, @DefaultValue("red") @QueryParam("last-color") ColorParam lastcolor ) {... Diego Passos (UFF) Web Services (III) TEPIS II 32 / 39

JAX-RS: Query Parameters Há restrições em relação aos tipos dos parâmetros. Só se pode usar tipos com as seguintes características: Tipos primitivos, exceto char. Classes correspondentes a tipos primitivos, exceto Character. Qualquer classe com construtor que recebe um único argumento do tipo String. Qualquer classe com um método estático valueof(string). List<T>, Set<T>, SortedSet<T>, onde T cai em um dos casos anteriores. Usado para atributos multi-valorados. Caso não seja possível mapear o valor presente na URL para o tipo do parâmetro, é gerado um erro 400. Exemplo: parâmetro declarado como int, usuário especifica valor teste. Diego Passos (UFF) Web Services (III) TEPIS II 33 / 39

JAX-RS: Outros Tipos de Parâmetros Há suporte para as seguintes outras anotações relacionadas a parâmetros: @CookieParam: associa um parâmetro a um cookie enviado pelo cliente. @HeaderParam: associa um parâmetro a um header da requisição. @FormParam: associa um parâmetro a um campo de formulário enviado pelo cliente. @MatrixParam: associa um parâmetro ao matrix parameter correspondente. Matrix parameters são similares aos query parameters. Mas permitem diferenciar parâmetros por nível da URL. Exemplo: http://servidor/webservice/categoria;nome=frutas/objetos;nome=abacaxi Em todos os casos, a correspondência é feita pelo nome. Nome do parâmetro declarado no método deve bater com o nome do cookie/header/... Note que, no caso do @FormParam, o tipo de conteúdo deve ser application/x-www-form-urlencoded. Diego Passos (UFF) Web Services (III) TEPIS II 34 / 39

JAX-RS: A Anotação @Context Anotação especial que pode ser usada em certos parâmetros de um método. Permite obter informações contextuais. Referências a objetos específicos que contem informações sobre a requisição. Exemplo: Objeto UriInfo: permite obtenção de informações sobre a URL. Objeto HttpHeaders: permite acesso mais direto aos headers. Diego Passos (UFF) Web Services (III) TEPIS II 35 / 39

JAX-RS: A Anotação @Context (II) Exemplo de código: @GET public String get(@context UriInfo ui, @Context HttpHeaders hh) { MultivaluedMap<String, String> queryparams = ui.getqueryparameters(); MultivaluedMap<String, String> pathparams = ui.getpathparameters(); MultivaluedMap<String, String> headerparams = hh.getrequestheaders(); Map<String, Cookie> pathparams = hh.getcookies();... return ui.getabsolutepath().tostring(); Diego Passos (UFF) Web Services (III) TEPIS II 36 / 39

JAX-RS vs. Servlets De certa forma, a JAX-RS é bem parecida com os Servlets HTTP. Ambos permitem criar aplicações Web. Escrevemos uma classe que é mapeada para uma ou mais URLs. Métodos específicos nesta classe são chamados pelo container quando tipos específicos de requisição são recebidas. Podemos manipular parâmetros, cookies, headers... Qual a diferença, então? Ambas as tecnologias são equivalentes? Diego Passos (UFF) Web Services (III) TEPIS II 37 / 39

JAX-RS vs. Servlets (II) A resposta é não. Servlets são componentes capazes de tratar requisições (tipicamente HTTP) em um nível bastante baixo. É possível manipular todos os aspectos das requisições e respostas, desde que obedecidas as regras do protocolo HTTP. Podemos, por exemplo, criar um Web Service RESTful. A JAX-RS é uma API especificamente dedicada a criação de serviços RESTful. Temos controle sobre muita coisa, mas dentro das limitações arquiteturais REST. Por exemplo, não podemos (ou não deveríamos) guardar estado interno sobre os clientes através de sessões. Em suma: É mais fácil implementarmos serviços RESTful com a JAX-RS. Mas temos mais liberdade arquitetural com os Servlets. Diego Passos (UFF) Web Services (III) TEPIS II 38 / 39

Referências Conteúdo e exemplos baseados em: Tutorial da Oracle sobre Web Services. http://docs.oracle.com/javaee/6/tutorial/doc/bnayk.html Diego Passos (UFF) Web Services (III) TEPIS II 39 / 39