Introdução a WEB Services SOAP com JAX-WS

A idea central dos WEB Services parte da antiga necessidade de integrar os diversos sistemas de uma empresas através da exposição das funcionalidades dos sistemas de uma forma não intrusiva, desacoplada, independente de linguagem de programação.

Já falamos aqui de JAX-RS e RESTful WEB Services, que são uma forma de expor as funcionalidades do seu sistema baseando no estilo arquitetural REST. Os WEB Services JAX-RS são bastante centrados no HTTP, pois esse possui mecanismos para que façamos "REST acontecer". Outra forma de criarmos Web Services é através dio protocolo SOAP.
SOAP(que significa Simple Object Access Protocol, não, não significa sabonete) baseia-se na troca de XMLs entre o cliente e o servidor para que a comunicação e invocação de funções seja feita. Ao contrário de WEB Services RESTful, O SOAP é totalmente agnóstico ao meio que ele está utilizando para enviar e receber os seus XMLs, no entanto, o HTTP ainda é o meio mais utilizado.
Nesse artigo nós vamos exemplificar o SOAP e falar como é possível criar, em Java, WEB Services que seguem esse protocolo. Já podemos adiantar que: é MUITO fácil.

Idioma falado: XML

O idiota no mundo SOAP é XML. O meio de transporte não importa, importa é receber um XML, que será lido pelo servidor e o mesmo irá responder com outro XML. Mas como o cliente sabe qual o formato que deve ter o XML?

Os XMLs do SOAP são como envelopes, eles contém um cabeçalho e o corpo, veja:

Isso, no entanto, não é o suficiente para que o cliente saiba as funções que o servidor expõe e nem como chama-lás. É aí que entra o  WSDL.

O Web Services Description Language(WSDL) é a forma que temos para descrever o serviço WEB que o servidor tem disponível. É um XML com meta-informações sobre o Web Service, logo, o cliente deve ler o mesmo para "aprender" como chamar a função remota no servidor. É o contrato do serviço. 

Por fim, de forma super resumida, um WEB Service SOAP funciona da seguinte maneira:

• O cliente lê o WSDL de um dado WEB Service;
• De acordo com o WSDL, o cliente monta uma mensagem SOAP e descobre também a localização do serviço no WSDL;
• O servidor recebe o XML do cliente, interpreta e invoca as funções necessárias;
• Com a resposta da invocação, o servidor monta outro XML e responde para o cliente

Claro que há muita coisa para ser discutida, como: tipos de dados, conteúdos binários, segurança, etc. para isso foram criadas diversas especificações abertas que poderemos abordar no futuro. Para mais informações, procure por WS-*.

Criando WEB Services SOAP com Java

No mundo JEE, usamos a especificação JAX-WS para criarmos nossos WEB Services SOAP.

A versão do JAX-WS contida do JEE 6 é 2.2 e, mais uma vez, temos um framework moderno e orientado a anotações. Ou seja, boa parte do trabalho fica com o servidor de aplicação e você se concentra na lógica da aplicação.

O WSDL é gerado automaticamente pelo servidor de aplicação ou você pode usar um WSDL para gerar a classe Java correspondente! O servidor também recebe a request do cliente em XML e chama o método Java correspondente, nada mais simples!

Hoje no nosso exemplo vamos nos divertir criando algo mega inovador: uma calculadora! Bem, sem dar muitos rodeios, vamos ao código:

import javax.ejb.Stateless;
import javax.jws.WebParam;
import javax.jws.WebService;

@WebService
@Stateless
public class CalculadoraWS {

 public double fazerOp(@WebParam(name = "num1") double a,
   @WebParam(name = "num2") double b, @WebParam(name = "op") String op) {
  // Por que você não clona o projeto e cria mais funções para brincar?
  switch (op) {
  case "+":
   return a + b;
  case "-":
   return a - b;
  case "*":
   return a * b;
  case "/":
   return a / b;
  default:
   throw new IllegalArgumentException("Operação '" + op
     + "' não reconhecida. Informa '+', '-', '*' ou '/'.");
  }
 }
}

Pontos importantes do código:

• Mais uma vez a anotação Stateless está ali, na cabeça da classe! O nome Stateless quer dizer que queremos que essa classe seja um EJB de sessão, uma classe gerenciada pelo JBoss, mas que não mantenha estado, ou seja, após uma requisição, ela não precisa manter nada e pode ser reusada para outras requisições. EJB é bastante amplo e não vou falar muito aqui, em futuros artigos iremos abordar mais... Uma dica para os apressadinhos: What is a session bean?
• As anotações do JAX-WS estão ali! Segue uma breve explicação de cada uma delas:
• WebService: É a anotação que usamos para informar que nossa classe é um WEB Service. Simples assim;
• WebMethod: Usamos essa anotação para marcar um método Java como uma operação exposta pelo WEB Service;
• WebParam: Na verdade nem precisaríamos desse parâmetro! Colocamos ele para deixar mais bonito o nome. Enfim, essa anotação serve para informar dados sobre os parâmetros do método do WS.

Se você utiliza Maven, veja o pom.xml do projeto (link para github). Dessa vez adicionamos como dependência toda a API do JEE 6! Notem também que estamos configurando a versão do Java com um plugin do Maven. Como usamos uma funcionalidade só do Java 7, que é o switch com Strings, temos que falar que o nosso projeto está no level de compilação do Java 7, ou teremos erros na hora de compilar... Boiou com Maven? Saiba mais aqui.

"Deployando" e usando o WEB Service

Ao realizar o deploy da aplicação no JBoss AS 7 e nos logs você deveria ver algo semelhante ao seguinte no console:

Pronto! Seu WEB Service está preparado para uso. A primeira coisa que você pode fazer é acessar o WSDL gerado, veja o código dele acessando o endereço http://localhost:8080/calculadora-jax-ws/CalculadoraWS?wsdl:

Aí você pode invocar o Web Service enviando para o servidor usando o método HTTP POST na URL base do WEB Service. Mas hoje iremos usar a ferramenta SoapUi. É possível também criar um cliente Java usando a ferramenta wsconsume, mas hoje não iremos entrar nessa questão deixando para uma postagem futura.
O soapUI é uma ótima ferramenta, baixe agora!. Há um screenshot do XML gerado com ela abaixo. Veja como fica muito mais fácil interagir com o nosso WEB Service!

Vá além!

O código já está no github e abaixo o vídeo que fiz groselhando e, eventualmente, falando sobre código. Veja que você pode estender esse WS e criar mais funções para nossa mega calculadora ou até explorar o JAX-WS.

Vídeo em breve

Você pode clonar ele e criar coisas mais legais e interessantes. No nosso WEB Service, criamos uma calculadora, mas poderia ser acesso ao banco de dados, algum processamento, uma lógica complexa, etc.

Conclusão

Apresentamos uma importante especificação do JEE, o JAX-WS. Claro que há muita coisa a ser falada, mas esse é o ponto de entrada para quem quer começar.