Aula 24: Web Services (II)

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

Última Aula Introdução e motivação. Tipos de Web Services. Big Web Services: conceitos. Formato WSDL. SOAP. JAX-WS: introdução. Diego Passos (UFF) Web Services (II) TEPIS II 2 / 36

Aula de Hoje 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 (II) TEPIS II 3 / 36

JAX-WS: Desenvolvendo um Web Service O desenvolvimento de um Web Service com a JAX-WS é bastante simples. De forma resumida, basta desenvolver a classe que implementa os métodos de negócio do Web Service e anotá-la com @WebService. Esta anotação define a classe declarada como um Web Service Endpoint. Mais especificamente, a JAX-WS define os seguintes conceitos: Service Endpoint Implementation (ou SEI): classe que implementa os métodos que podem ser invocados em um Web Service. Service Endpoint Interface: idem, mas como uma interface. A interface é opcional: a implementação do serviço pode conter apenas a classe propriamente dita. Mas a interface pode ser definida para isolar os métodos públicos (i.e., expostos pela API do Web Service). Neste caso, a classe que implementa os métodos deve explicitamente referenciar a interface com o elemento endpointinterface na anotação @WebService. Diego Passos (UFF) Web Services (II) TEPIS II 4 / 36

JAX-WS: Desenvolvendo um Web Service (II) Há quatro passos envolvidos na implantação de um Web Service no J2EE: Codificação da classe que implementa os serviços. Compilação desta classe. Empacotamento dos arquivos/recursos em um pacote WAR. Disponibilização do pacote WAR no servidor de aplicação. Durante a disponibilização, o servidor de aplicação se encarrega de gerar outros artefatos necessários. Diego Passos (UFF) Web Services (II) TEPIS II 5 / 36

JAX-WS: Desenvolvendo um Web Service (III) Há algumas restrições e requisitos no desenvolvimento de um Web Service com o JAX-WS: Os métodos de negócio (a serem providos pelo Web Service) devem ser públicos. Eles não podem ser estáticos, nem finais. Eles também devem ser anotados com @WebMethod. Há restrições em relação aos tipos de parâmetros e tipos de retorno destes métodos. Em síntese, eles devem poder ser convertidos para tipos representáveis no SOAP. O JAX-WS provê uma série de conversões automáticas para os tipos mais comuns (Strings, inteiros, valores reais,... ). Tipos mais complexos (como classes definidas pelo usuário, por exemplo) podem ser usados também. Mas requerem a especificação de regras de conversão. Veremos mais detalhes sobre isso ainda neste curso. Diego Passos (UFF) Web Services (II) TEPIS II 6 / 36

JAX-WS: Desenvolvendo um Web Service (IV) Continuação das restrições... A classe que implementa o Web Service não pode ser declarada como final ou abstract. Ela também precisa declarar um construtor público padrão (sem argumentos). A classe não pode declarar um método finalize. A classe pode declarar métodos com as anotações @PostConstruct e @PreDestroy. Similares às anotações das EJBs. Servem para manipulação do ciclo de vida. Diego Passos (UFF) Web Services (II) TEPIS II 7 / 36

JAX-WS: Exemplo de Código de um Web Service package helloservice.endpoint; import javax.jws.webservice; import javax.jws.webmethod; @WebService public class Hello { private String message = new String("Hello, "); public void Hello() { } } @WebMethod public String sayhello(string name) { return message + name + "."; } Exemplo bastante simples. Não especificamos uma interface. Apenas uma operação exportada: sayhello(). Diego Passos (UFF) Web Services (II) TEPIS II 8 / 36

JAX-WS: Montagem e Disponibilização Um Web Service deve ser empacotado como um módulo web do J2EE. Pacote WAR. Contendo as classes que implementam o Web Service. Assim como outros tipos de componentes, o processo de disponibilização pode variar entre servidores de aplicação diferentes. Mas é interessante notar que o servidor se encarrega de gerar artefatos necessários ao uso do Web Service. Exemplo (com Glassfish): pacote chamado WebService1.war com a classe Hello do exemplo anterior: http://servidor:8080/webservice/helloservice: exibe informações do Web Service. http://servidor:8080/webservice/helloservice?wsdl: exibe o arquivo WSDL gerado automaticamente. Versão 1.1. http://servidor:8080/webservice/helloservice?xsd=1: exibe XML Schema gerado automaticamente. Usado nas definições de tipo do WSDL. Diego Passos (UFF) Web Services (II) TEPIS II 9 / 36

JAX-WS: Artefatos Gerados Exemplo de página de informações do Web Service: Web Services Endpoint Information Service {http://endpoint.helloservice Name: /}HelloService Port Name: {http://endpoint.helloservice /}HelloPort Address: WSDL: http://172.16.10.75:8080 /WebService1/HelloService http://172.16.10.75:8080 /WebService1 /HelloService?wsdl Implementation helloservice.endpoint.hello class: Diego Passos (UFF) Web Services (II) TEPIS II 10 / 36

JAX-WS: Artefatos Gerados (II) Exemplo de arquivo WSDL gerado automaticamente (trechos). <?xml version= 1.0 encoding= UTF-8?> <definitions> <types> <xsd:schema> <xsd:import namespace="http://endpoint.helloservice/" schemalocation="http://172.16.10.75:8080/webservice1/helloservice?xsd=1"/> </xsd:schema> </types>... <message name="sayhello"> <part name="parameters" element="tns:sayhello"/> </message> <message name="sayhelloresponse"> <part name="parameters" element="tns:sayhelloresponse"/> </message> <porttype name="hello">... <operation name="sayhello"> <input wsam:action="http://endpoint.helloservice/hello/sayhellorequest" message="tns:sayhello"/> <output wsam:action="http://endpoint.helloservice/hello/sayhelloresponse" message="tns:sayhelloresponse"/> </operation> </porttype> <binding name="helloportbinding" type="tns:hello">... </binding> <service name="helloservice"> <port name="helloport" binding="tns:helloportbinding"> <soap:address location="http://172.16.10.75:8080/webservice1/helloservice"/> </port> </service> </definitions> Diego Passos (UFF) Web Services (II) TEPIS II 11 / 36

JAX-WS: Artefatos Gerados (III) Exemplo de arquivo XML Schema gerado automaticamente (trechos). <?xml version= 1.0 encoding= UTF-8?> <xs:schema xmlns:tns="http://endpoint.helloservice/" xmlns:xs="http://www.w3.org/2001/xmlschema" version="1.0" targetnamespace="http://endpoint.helloservice/"> <xs:element name="hello" type="tns:hello"/> <xs:element name="helloresponse" type="tns:helloresponse"/> <xs:element name="sayhello" type="tns:sayhello"/> <xs:element name="sayhelloresponse" type="tns:sayhelloresponse"/> <xs:complextype name="sayhello"> <xs:sequence> <xs:element name="arg0" type="xs:string" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="sayhelloresponse"> <xs:sequence> <xs:element name="return" type="xs:string" minoccurs="0"/> </xs:sequence> </xs:complextype>... </xs:schema> Diego Passos (UFF) Web Services (II) TEPIS II 12 / 36

JAX-WS: Testando Serviço Nas versões mais recentes do Glassfish é possível testar um endpoint Web Service sem um cliente específico. Utilizando um browser comum, pode-se acessar uma URL especial. No serviço de exemplo dos últimos slides http://servidor/webservice1/helloservice?tester. O servidor de aplicação gera uma página que lista os métodos disponíveis no serviço. Interface permite especificar valores para os parâmetros e executar métodos. Diego Passos (UFF) Web Services (II) TEPIS II 13 / 36

JAX-WS: Testando Serviço (II) sayhello Method invocation Method parameter(s) Type Value java.lang.string Diego Method returned java.lang.string : "Hello, Diego." SOAP Request <?xml version="1.0" encoding="utf-8"?><s:envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <S:Body> <ns2:sayhello xmlns:ns2="http://endpoint.helloservice/"> <arg0>diego</arg0> </ns2:sayhello> </S:Body> </S:Envelope> SOAP Response <?xml version="1.0" encoding="utf-8"?><s:envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <S:Body> <ns2:sayhelloresponse xmlns:ns2="http://endpoint.helloservice/"> <return>hello, Diego.</return> </ns2:sayhelloresponse> </S:Body> </S:Envelope> Diego Passos (UFF) Web Services (II) TEPIS II 14 / 36

JAX-WS: Aplicações Cliente A API JAX-WS também pode ser usada para construir clientes de Big Web Services. Para isso, o cliente precisa, de alguma forma, conhecer as operações disponíveis no Web Service. Ao menos aquelas que deseja utilizar. Este conhecimento pode ser realizado de várias formas: Proxy estático. Proxy dinâmico. Invocação dinâmica de interface (DII). Diego Passos (UFF) Web Services (II) TEPIS II 15 / 36

JAX-WS: Proxy Estático No proxy estático, o cliente utiliza o Web Service através da manipulação de objetos locais. Mais que isso, estes objetos são instâncias de classes previamente geradas, incorporadas em tempo de compilação ao código do cliente. Estas classes representam os recursos descritos no arquivo WSDL do Web Service. Manipulações destes objetos locais resultam em envio (e, possivelmente, recebimento) de mensagens para o Web Service. Isto, no entanto, é transparente para o cliente. Do seu ponto de vista, é como se estes objetos implementassem, localmente, os serviços. Diego Passos (UFF) Web Services (II) TEPIS II 16 / 36

JAX-WS: Proxy Estático (II) O primeiro passo para utilizar um proxy estático é gerar as classes necessárias. O próprio JDK distribuído pela Sun possui um utilitário para isso: o wsimport. Recebe como argumento um arquivo (ou URL) do tipo WSDL. Criar uma série de classes. Estas classes devem ser usadas no código do cliente. Diego Passos (UFF) Web Services (II) TEPIS II 17 / 36

JAX-WS: Proxy Estático (III) Exemplo de código de cliente de um Web Service: import helloservice.endpoint.helloservice; import javax.xml.ws.webserviceref; public class HelloAppClient { private static HelloService service; /** * @param args the command line arguments */ public static void main(string[] args) { service = new HelloService(); System.out.println(sayHello("world")); } } private static String sayhello(java.lang.string arg0) { helloservice.endpoint.hello port = service.gethelloport(); return port.sayhello(arg0); } A classe helloservice.endpoint.helloservice é uma das geradas pelo wsimport. Diego Passos (UFF) Web Services (II) TEPIS II 18 / 36

JAX-WS: Proxy Estático (IV) Declaramos um atributo do tipo HelloService. Este atributo é instanciado no método main(). private static HelloService service;... public static void main(string[] args) { service = new HelloService();... Este objeto representa o serviço disponibilizado pelo Web Service. Note que em nenhum momento referenciamos o arquivo WSDL ou o endereço do Web Service. Estas informações estão incluídas na classe HelloService. Diego Passos (UFF) Web Services (II) TEPIS II 19 / 36

JAX-WS: Proxy Estático (IV) Outra parte relevante do código é a utilização do método gethelloport(). Ele retorna, neste caso, um objeto do tipo Hello que age como um proxy para o serviço. helloservice.endpoint.hello port = service.gethelloport(); return port.sayhello(arg0); Este objeto tem a mesma interface da classe Hello que usamos para implementar o Web Service. Ao menos em relação às operações exportadas. Utilizamos os métodos exportados pelo Web Service como se estes fossem locais do objeto Hello. Implicitamente, o código no proxy gera mensagens SOAP, recebe as respostas, as interpreta e retorna os valores de retorno. Diego Passos (UFF) Web Services (II) TEPIS II 20 / 36

JAX-WS: Proxy Dinâmico A ideia do proxy dinâmico é bem parecida com a do proxy estático. Ainda usaremos objetos locais que se servirão de proxy para o objeto que implementa o Web Service. A diferença é que não utilizaremos os artefatos previamente criados a partir do arquivo WSDL. Ao invés disso, pediremos à API do JAX-WS que crie estes objetos dinamicamente para nós. Note que, de alguma forma, ainda precisaremos saber qual a interface (métodos e assinaturas) para utilizar os serviços. Diego Passos (UFF) Web Services (II) TEPIS II 21 / 36

JAX-WS: Proxy Dinâmico (II) Exemplo de código: import javax.xml.rpc.servicefactory; import javax.xml.rpc.service;... interface MyHello { public String sayhello(string msg); }... public void invokeservice() { String msg = "teste"; ServiceFactory sfactory = ServiceFactory.newInstance(); Service service = sfactory.createservice(new URL("http://servidor:8080/WebService/HelloService?wsdl"), new QName("http://servidor:8080/WebService/HelloService")); MyHello hello = (MyHello) service.getport(myhello.class); String resp = hello.sayhello(msg);... A interface MyHello só é criada para sabermos as assinaturas dos métodos do Web Service. Em relação ao código do proxy estático, substituimos o uso das classes geradas pelo wsimport por classes genéricas da própria API. Ainda temos que indicar a localização do arquivo WSDL. A partir dele a API constrói dinamicamente o proxy. Diego Passos (UFF) Web Services (II) TEPIS II 22 / 36

JAX-WS: Proxy Dinâmico (III) A abordagem de proxy dinâmico fazia mais sentido há alguns anos atrás. A geração dos artefatos necessários aos clientes era específica de cada servidor de aplicação e muitas vezes esses artefatos não eram portáveis. Hoje, isso deixou de ser um problema. Podemos gerar os artefatos a partir de qualquer arquivo WSDL. Mesmo para Web Services que sequer são implementados em Java. Diego Passos (UFF) Web Services (II) TEPIS II 23 / 36

JAX-WS: Invocação Dinâmica de Interface Os dois métodos anteriores assumiam que, de alguma forma, o cliente tem acesso ao arquivo WSDL do Web Service. A invocação dinâmica de interface (DII) é o método a ser usado quando este não é o caso. Por algum motivo, não temos acesso a um arquivo WSDL. Mesmo assim, conhecemos as operações disponibilizadas por um Web Service. Sabemos seus nomes, argumentos e tipos de retorno. Neste caso, não teremos a figura do proxy (estático ou dinâmico). Ao invés disso, iremos configurar no próprio código do cliente as assinaturas das operações. Diego Passos (UFF) Web Services (II) TEPIS II 24 / 36

JAX-WS: Invocação Dinâmica de Interface (II) O código de um cliente DII é similar ao caso do proxy dinâmico, no sentido de que criaremos objetos do tipo Service e ServiceFactory. No entanto, ao invés de passarmos uma referência para o arquivo WSDL (que não temos), criaremos um objeto genérico do tipo Call. Este objeto representa uma chamada remota genérica. Podemos configurá-la programaticamente, especificando parâmetros, tipos de retorno, etc. Uma vez configurado, o objeto Call tem um método invoke() que chama a operação remota. Diego Passos (UFF) Web Services (II) TEPIS II 25 / 36

JAX-WS: Invocação Dinâmica de Interface (III) Exemplo de código: final String endpoint = "http://localhost:9090/jent-examples/services/echo"; final String servicename = "EchoService"; final String portname = "echo"; final String operationname = "echo"; final String servicens = "http://localhost:8080/jent-examples/services/echo"; final String xsdns = "http://www.w3.org/2001/xmlschema"; final String jaxrpcns = "http://java.sun.com/jax-rpc-ri/internal"; QName serviceqname = new QName(serviceNS, servicename); QName portqname = new QName(serviceNS, portname); QName operationqname = new QName(serviceNS, operationname); try { ServiceFactory factory = ServiceFactory.newInstance(); Service service = factory.createservice(serviceqname); Call call = service.createcall(portqname); call.settargetendpointaddress(endpoint); call.setreturntype(new QName(xsdNS, "string")); call.setoperationname(operationqname); call.addparameter("message", new QName(xsdNS, "string"), ParameterMode.IN); String msg = "Hi there"; Object[] opparams = {msg}; String resp = (String)call.invoke(opParams); System.out.println("Sent: \"" + msg + "\", got response \"" + resp + "\""); } catch (ServiceException se) { System.err.println("Service generated an error: " + se.getmessage()); } catch (RemoteException re) { System.err.println("Communication error: " + re.getmessage()); } Diego Passos (UFF) Web Services (II) TEPIS II 26 / 36

JAX-WS: Invocação Dinâmica de Interface (IV) Uma vez instanciado o objeto Call, utilizamos seus métodos para especificar como o Web Service é acessado. Na verdade, as informações são de uma operação específica. No exemplo anterior, configuramos as seguintes informações: O nome (qualificado) da porta. O endpoint do serviço. O tipo de retorno (com namespace). O nome da operação. A lista de parâmetros com tipos (neste caso, há um único parâmetro). Call call = service.createcall(portqname); call.settargetendpointaddress(endpoint); call.setreturntype(new QName(xsdNS, "string")); call.setoperationname(operationqname); call.addparameter("message", new QName(xsdNS, "string"), ParameterMode.IN); Diego Passos (UFF) Web Services (II) TEPIS II 27 / 36

JAX-WS: Invocação Dinâmica de Interface (V) Uma vez configurado, o objeto Call pode ser usado para efetivamente executar a operação. Para isso, usa-se o método invoke(). Parâmetro único: vetor de Object. Valores passados como parâmetros para a operação. String msg = "Hi there"; Object[] opparams = {msg}; String resp = (String)call.invoke(opParams); Diego Passos (UFF) Web Services (II) TEPIS II 28 / 36

JAX-WS: Tipos Suportados Em seu arquivo WSDL, Web Service define suas operações. Isto inclui os tipos dos parâmetros de entrada e do valor de retorno. Estes tipos são definidos em termos de: Tipos básicos do XML. Tipos complexos definidos por um XML Schema. De toda forma, para usar os Web Services em Java, é preciso haver um mapeamento entre os tipos Java e os tipos esperados pelo Web Service. Como fazer isso? Diego Passos (UFF) Web Services (II) TEPIS II 29 / 36

JAX-WS: Tipos Suportados (II) Vamos ver o que foi feito nos exemplos anteriores. Cliente com Invocação Dinâmica de Interface: String msg = "Hi there"; Object[] opparams = {msg}; String resp = (String)call.invoke(opParams); Cliente com proxy estático: private static String sayhello(java.lang.string arg0) { helloservice.endpoint.hello port = service.gethelloport(); return port.sayhello(arg0); } Operação sayhello() espera receber uma xsd:string e retorna uma xsd:string Ambos tipos padrão do XML. Em ambos os clientes, passamos o parâmetro como uma String (tipo Java). E também recebemos a resposta desta forma. Diego Passos (UFF) Web Services (II) TEPIS II 30 / 36

JAX-WS: Tipos Suportados (III) Conclusão: nestes exemplos, houve uma conversão impĺıcita entre tipos Java e tipos XML. Esta conversão foi realizada pela própria API JAX-WS. A API segue regras de mapeamento pré-determinadas para realizar esta conversão. De fato, há uma tabela de mapeamento. Contanto que usemos apenas tipos que constam nesta tabela, não teremos dificuldade na interação entre Java e Web Services. Diego Passos (UFF) Web Services (II) TEPIS II 31 / 36

JAX-WS: Tipos Suportados (IV) Tabela de conversão: XML para Java. XML Java XML Java xsd:string java.lang.string xsd:integer java.math.biginteger xsd:int int xsd.long long xsd:short short xsd:decimal java.math.bigdecimal xsd:float float xsd:double double xsd:boolean boolean xsd:byte byte xsd:qname javax.xml.namespace.qname xsd:datetime javax.xml.datatype.xmlgregoriancalendar xsd:base64binary byte[] xsd:hexbinary byte[] xsd:unsignedint long xsd:unsignedshort int xsd:unsignedbyte short xsd:time javax.xml.datatype.xmlgregoriancalendar xsd:date javax.xml.datatype.xmlgregoriancalendar xsd:g javax.xml.datatype.xmlgregoriancalendar xsd:anysimpletype java.lang.object xsd:anysimpletype java.lang.string xsd:duration javax.xml.datatype.duration xsd:notation javax.xml.namespace.qname Diego Passos (UFF) Web Services (II) TEPIS II 32 / 36

JAX-WS: Tipos Suportados (V) Tabela de conversão: Java para XML. Java java.lang.string java.math.biginteger java.math.bigdecimal java.util.calendar java.util.date javax.xml.namespace.qname java.net.uri javax.xml.datatype.xmlgregoriancalendar javax.xml.datatype.duration java.lang.object java.awt.image javax.activation.datahandler javax.xml.transform.source java.util.uuid XML xs:string xs:integer xs:decimal xs:datetime xs:datetime xs:qname xs:string xs:anysimpletype xs:duration xs:anytype xs:base64binary xs:base64binary xs:base64binary xs:string Diego Passos (UFF) Web Services (II) TEPIS II 33 / 36

JAX-WS: Tipos Suportados (VI) Há ainda mapeamentos padrão para vetores (tipo XML Array). Por fim, é possível fazer mapeamentos automáticos para tipos complexos (tipo XML xsd:complextype). Neste caso, a API tenta realizar o mapeamento para uma Java Bean com o mesmo nome definido para o tipo. Atributos da Java Bean também devem corresponder aos elementos internos do tipo complexo. Note ainda que, caso o mapeamento automático não seja adequado, é possível estabelecer um mapeamento manual utilizando deployment descriptors. Fora do escopo do curso. Diego Passos (UFF) Web Services (II) TEPIS II 34 / 36

Próxima Aula 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 (II) TEPIS II 35 / 36

Referências Conteúdo e exemplos baseados em: Tutorial da Oracle sobre Web Services. http://docs.oracle.com/javaee/6/tutorial/doc/bnayk.html Jim Farley e William Crawford. Java Enterprise in a Nutshell: A Practical Guide. Terceira edição. Capítulo 12. Diego Passos (UFF) Web Services (II) TEPIS II 36 / 36