Web Services SOAP

Introdução

Serviço Web (Web Service) é uma forma padronizada para integração entre aplicações diferentes.

Através do Web Service (WS) é possível integrar aplicações desenvolvidas com linguagens de programação diferente, pois o Web Service utiliza a troca de arquivos XML para realizar a comunicação.

Quando desenvolvemos uma aplicação com WS precisamos informar para quem for utilizar (consumir) o WS como ele funciona, para isso criamos um arquivo WSDL e enviamos este arquivo para quem for criar o cliente para o WS, após o cliente ser criado a comunicação feita entre as aplicações utiliza envelopes SOAP no formato XML como mostrado na figura a seguir:

Web Service Description Language

Web Service Description Language (WSDL) é um documento no padrão XML que descreve o funcionamento de um Web Service.

Neste documento podemos descrever:

• como encontrar o Web Service;
• quais métodos possuem esse Web Service;
• quais parâmetros os métodos recebem;
• o que os métodos retornam;

Exemplo de WSDL:

Neste exemplo temos o WSDL de um Web Service chamado ExemploWS que possui o método olaMundo que não recebe parâmetro e retorna uma String.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!-- Generated by JAX-WS RI at http://jax-ws.dev.java.net. 
RI's version is JAX-WS RI 2.1.3.1-hudson-749-SNAPSHOT. -->
<definitions targetNamespace="http://ws.exemplo.pbc/"
name="ExemploWSService" xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="http://ws.exemplo.pbc/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <ns1:Policy wsu:Id="ExemploWSPortBinding_olaMundo_WSAT_Policy"
    xmlns:ns1="http://www.w3.org/ns/ws-policy">
    <ns1:ExactlyOne>
      <ns1:All>
        <ns2:ATAlwaysCapability
          xmlns:ns2="http://schemas.xmlsoap.org/ws/2004/10/wsat"/>
        <ns3:ATAssertion ns1:Optional="true" ns4:Optional="true"
        xmlns:ns4="http://schemas.xmlsoap.org/ws/2002/12/policy"
        xmlns:ns3="http://schemas.xmlsoap.org/ws/2004/10/wsat"/>
      </ns1:All>
    </ns1:ExactlyOne>
  </ns1:Policy>
  <types>
    <xsd:schema>
      <xsd:import namespace="http://ws.exemplo.pbc/"
        schemaLocation="ExemploWSService_schema1.xsd"/>
    </xsd:schema>
  </types>
  <message name="olaMundo">
    <part name="parameters" element="tns:olaMundo"/>
  </message>
  <message name="olaMundoResponse">
    <part name="parameters" element="tns:olaMundoResponse"/>
  </message>
  <portType name="ExemploWS">
    <operation name="olaMundo">
      <input message="tns:olaMundo"/>
      <output message="tns:olaMundoResponse"/>
    </operation>
  </portType>
  <binding name="ExemploWSPortBinding" type="tns:ExemploWS">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/
      http" style="document"/>
    <operation name="olaMundo">
      <ns5:PolicyReference
        URI="#ExemploWSPortBinding_olaMundo_WSAT_Policy"
        xmlns:ns5="http://www.w3.org/ns/ws-policy"/>
      <soap:operation soapAction=""/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>
  <service name="ExemploWSService">
    <port name="ExemploWSPort" binding="tns:ExemploWSPortBinding">
      <soap:address location="REPLACE_WITH_ACTUAL_URL"/>
    </port>
  </service>
</definitions>

Simple Object Access Protocol

Simple Object Access Protocol (SOAP) é um padrão com tags XML utilizado para enviar requisições e receber respostas de um Web Service.

Exemplo de mensagem SOAP:

<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Header/>
<S:Body>
  <ns2:olaMundo xmlns:ns2="http://ws.exemplo.pbc/"/>
</S:Body>
</S:Envelope>

Exemplo de resposta SOAP:

<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
  <ns2:olaMundoResponse xmlns:ns2="http://ws.exemplo.pbc/">
    <return>Ola Mundo!!!</return>
  </ns2:olaMundoResponse>
</S:Body>
</S:Envelope>

Criando um Web Service com EJB 3.0

Para criar um serviço web baseado no EJB 3.0, podemos utilizar a Java API for XML-based Web Services (JAX-WS), através dessa API podemos adicionar anotações ao EJB para que ele possa ser utilizado como um serviço web.

Algumas das anotações que utilizamos para definir um web service:

• javax.jws.WebService - Define uma classe como um WS (Está classe precisa ser um Stateless Session Bean).
• javax.jws.WebMethod - Define que um método será disponibilizado via WS.
• javax.jws.WebParam - Define os parâmetros que serão recebidos pelo WS.
• javax.jws.WebResult - Define o nome da tag XML com o conteúdo do retorno, por padrão a tag de retorno do método chama .

Exemplo de Web Service:

@WebService()
@Stateless()
public class ExemploWS {

  @WebMethod(operationName = "olaMundo")
  public String olaMundo() {
    return "Ola Mundo!!!";
  }

}

A figura a seguir apresenta um exemplo visual de um web service no NetBeans:

No NetBeans após criar um Web Service e publica-lo no Glassfish, podemos testa-lo clicando com o botão direito do mouse no nome do Web Service (dentro da guia Serviços Web) e selecionando a opção Testar serviço Web como mostrado na figura a seguir:

Após clicar no item Testar serviço web será aberto no navegador uma página para testar os métodos do web service como a figura a seguir, se clicarmos em WSDL File (arquivo WSDL) podemos ver o XML do WSDL gerado e se clicarmos na operação olaMundo veremos a execução de seu método:

Quando clicamos no método olaMundo podemos ver a requisição e a resposta no formato SOAP como mostrado na figura a seguir:

Outro exemplo de Web Service

Neste exemplo temos um Web Service que faz uma conexão com o banco de dados para consultar as vendes de livros realizados em um período recebido via parâmetro e retorna um simples texto com as informações das vendas.

@WebService()
@Stateless()
public class VendasWS {
  @PersistenceContext(unitName = "LivrariaPU")
  private EntityManager em;

  @WebMethod(operationName = "consultarVendasPorPeriodo")
  public String consultarVendasPorPeriodo(
    @WebParam(name="inicioPeriodo") String inicioPeriodo,
    @WebParam(name="fimPeriodo") String fimPeriodo) {
    String retorno = "";
    try {
      DateFormat dateFormat = new SimpleDateFormat("dd/MM/yyyy");
      VendaDAO dao = new VendaDAO(em);
      List<Venda> vendas =
        dao.procurarPorPeriodo(dateFormat.parse(inicioPeriodo), 
        dateFormat.parse(fimPeriodo));

      for(Venda venda : vendas) {
        retorno += venda.getCliente().getNome() + " - " 
          + dateFormat.format(venda.getDataVenda());
        retorno += "\n-----Livros------";
        for(Livro livro : venda.getLivros()) {
          retorno += "\nTitulo: " + livro.getTitulo() 
            + " - R$" + livro.getPreco();
        }
        retorno += "\nTotal: R$" + venda.getValorTotal() 
          + "\n--------------\n\n";
      }
    } catch (ParseException ex) {
      ex.printStackTrace(); //Erro ao converter as datas.
    }
    return retorno;
  }
}

Criando um cliente para um Web Service

O NetBeans possui uma maneira automática para geração de clientes de web services, para isto basta termos o WSDL do WS, no exemplo abaixo vamos criar um cliente para o WS de Ola Mundo.

Crie um projeto de Aplicativo Java chamado ExemploWSCliente.

Para gerar um cliente para o web service, clique com o botão direito em cima de Pacotes de código-fonte, selecione Novo e clique em Cliente para serviço Web... como mostrado na figura a seguir:

Ou clique em Novo e selecione Outro..., na tela de Novo arquivo selecione a categoria Serviços Web e marque a opção Cliente para serviço web.

Para especificar o Web Service que será gerado o cliente, podemos fazer isso de duas formas:

• Quando conhecemos o projeto do Web Service:

Na tela de Novo Cliente para Serviço Web selecione a opção Projeto e clique em Procurar..., irá aparecer uma tela onde podemos encontrar os web services criados nos projetos que temos aberto no NetBeans, selecione o Web Service desejado e clique em OK como mostrado na figura a seguir:

Informe o Pacote que será gerado o código do cliente do serviço web e clique em Finalizar.

• Quando o Web Service é desenvolvido por outra pessoa e temos apenas o URL do WSDL:

Na tela de Novo Cliente para Serviço Web selecione a opção WSDL URL e informe a url do WSDL. Informe o Pacote que será gerado o código do cliente do serviço web e clique em Finalizar.

Após criar o cliente para o serviço web podemos testa-lo, para isto vamos criar uma classe para chamar o Web Service:

package pbc.exemplo.ws.cliente;

import pbc.exemplo.ws.ExemploWS;
import pbc.exemplo.ws.ExemploWSService;

/**
 * Classe utilizada para testar o web service.
 */
public class TesteWS {
  public static void main(String[] args) {
    ExemploWSService service = new ExemploWSService();
    ExemploWS port = service.getExemploWSPort();

    System.out.println(port.olaMundo());
  }
}

Quando executarmos esta classe teremos a saída no console:

Ola Mundo!!!