Tutorial SOA Passo a Passo com Java 6

Implementando e disponibilizando serviços em Java

Nesse artigo iremos implementar um Web Service em Java como o ponto de partida para uma aplicação orientada a serviços (SOA - Service-Oriented Architecture).

Começamos definindo a interface para o nosso serviço:

Sem muitos mistérios aqui. Apenas note as anotações utilizadas e atente para o fato de que não é possível utilizar overload de métodos num web service, isto é, os nomes dos métodos precisam ser diferentes.

O POJO User está listado abaixo:

Agora vamos implementar o nosso serviço:

De novo sem mistérios aqui. Apenas repare que utilizamos novamente a anotação @WebService e que agora passamos como parâmetro a interface do serviço que estamos implementando. O termo técnico para a interface do serviço é SEI (Service Endpoint Interface) e para a classe que implementa o serviço SIB (Service Implementation Bean).

Feito isso nos resta agora publicar o nosso serviço para o mundo, ou seja, disponibilizá-lo na Internet para que qualquer cliente em qualquer linguagem e em qualquer lugar possa utilizá-lo. Há diversas maneiras de publicar o seu serviço:

Lightweight: Standalone Java Application (simple Java program)

Middleweight: Web Container (Tomcat, Jetty, Resin, etc.)

Heavyweight: Application Server (GlassFish, Weblogic, WebSphere, JBoss, etc.)

Inicialmente utilizaremos o método mais simples e leve (lightweight), que é um aplicativo standalone Java. Em artigos posteriores analisaremos como disponibilizar o serviço no Tomcat.

Abaixo está o código para um pequeno servidor Java que disponibiliza o nosso serviço para o mundo:

Estamos utilizando a classe javax.xml.ws.Endpoint, que é bastante simples e útil. A porta escolhida aleatoriamente é a 54321.

Se você tentar executar a classe acima receberá o seguinte erro:

Isso porque o web service precisa de diversas classes auxiliares que podem ser geradas automaticamente utilizando o comando abaixo dentro do diretório onde suas classes estão, normalmente bin ou classes.

Feito isso o pacote ws.hello.jaxws é gerado com as classes necessárias para a publicacão do serviço.

Agora execute novamente a classe ws.hello.HelloPublisher utilizando o comando abaixo:

Abra o seu browser e digite a seguinte URL para visualizar a especificação do seu serviço, que nada mais é que o documento WSDL (Web Service Definition Language):

http://localhost:54321/hello?wsdl

Se você visualizar um documento XML que começa com a linha <definitions targetNamespace="http://hello.ws/" name="HelloImplService"> então pode comemorar: O seu serviço já está disponível para o mundo!

Para ter certeza disso utilize o script Ruby abaixo para fazer uma requisição ao método sayHello:

Caso você queira receber a segunda parte desse artigo que explica como gerar stubs e implementar um cliente em Java para acessar todos os métodos do serviço e também demonstra como disponibilizar o web service via Tomcat, envie um email para sergio.oliveira.jr at gmail.com com o seguinte título "Artigo SOA".

Em futuros artigos serão também discutidos segurança e como disponibilizar o serviço em alguns applications servers como GlassFish e JBoss.

Implementando um cliente em Ruby

Continuando o nosso tutorial vamos implementar agora um cliente em Ruby para consumir todos os métodos do nosso serviço. Utilizaremos o Soap4R que é a biblioteca padrão do Ruby para SOAP.

Atenção: A distribuição padrão do Ruby já vem com o Soap4R. Entretanto queremos utilizar a última versão dessa biblioteca e para isso instalaremos o seu gem.

Quando você instala o Soap4R você ganha de presente o script wsld2ruby.rb que você pode utilizar para gerar as classes auxiliares em Ruby a partir do WSDL do serviço publicado. Essas classes serão de grande ajuda na hora de codificar o cliente, como veremos mais adiante.

Gere as classes auxiliares com o comando abaixo:

Veja agora como podemos codificar um cliente para os nossos serviços em Ruby:

# Cliente em Ruby para acessar o serviço http://localhost:54321/hello?wsdl

# Precisamos dessas duas linhas abaixo para
# forçar a utilização do gem do Soap4R ao
# invés da distribuição desatualizada
# que vem dentro do Ruby
require 'rubygems'
gem 'soap4r'

# Importa a classe gerada pelo wsdl2ruby.rb
require 'HelloImplServiceDriver'

# Então só precisamos fazer isso:
service = Hello.new

# O método sayHello não recebe nenhum parâmetro
puts service.sayHello(nil).m_return

# Mesmo quando um método não recebe nenhum parâmetro
# o mais certo é passar o objeto SOAP corresopndente
puts service.sayHello(SayHello.new).m_return

# Para cada serviço (método) é criado um objeto correspondente
# para servir como um transportador dos parâmetros do serviço
puts service.sayHelloTo(SayHelloTo.new("Sergio")).m_return

# O wsdl2ruby também cria o objeto User esperado como parâmetro
# pelo serviço sayHelloToUser
puts service.sayHelloToUser(SayHelloToUser.new(User.new("saoj@saoj.com.br", "saoj"))).m_return

# Para o serviço que retorna um User recebemos um User como tem que ser
u = service.getUserFromEmail(GetUserFromEmail.new("saoj@saoj.com.br")).m_return
puts "User: #{u.username} / #{u.email} / #{u}"

# E para o serviço que retorna um array, recebemos um Ruby array
# OBS: Nesse caso não precisamos chamar o método m_return pois o
# valor retornado já é um Array de Users
list = service.getAllUsers(GetAllUsers.new)
list.each_with_index do |v,k|
  puts "U#{k}: #{v.username} / #{v.email}"
end

Caso o código acima não tenha ficado claro pra você, dê uma olhada no arquivo HelloImplService.rb que foi gerado automaticamente pelo wsdl2ruby. Nesse arquivo você encontrará a definição das classes utilizadas pelo nosso cliente tais como SayHelloTo, SayHelloToUserResponse, User, etc.

require 'xsd/qname'

# OBS: Para o código não ficar muito grande, algumas partes foram omitidas.

# {http://hello.ws/}sayHelloToUser
#   arg0 - User
class SayHelloToUser
  attr_accessor :arg0

def initialize(arg0 = nil)
    @arg0 = arg0
  end
end

# {http://hello.ws/}user
#   email - SOAP::SOAPString
#   username - SOAP::SOAPString
class User
  attr_accessor :email
  attr_accessor :username

def initialize(email = nil, username = nil)
    @email = email
    @username = username
  end
end

# {http://hello.ws/}sayHelloToUserResponse
#   m_return - SOAP::SOAPString
class SayHelloToUserResponse
  def m_return
    @v_return
  end

def m_return=(value)
    @v_return = value
  end

def initialize(v_return = nil)
    @v_return = v_return
  end
end

# {http://hello.ws/}sayHelloTo
#   arg0 - SOAP::SOAPString
class SayHelloTo
  attr_accessor :arg0

def initialize(arg0 = nil)
    @arg0 = arg0
  end
end

# {http://hello.ws/}sayHelloToResponse
#   m_return - SOAP::SOAPString
class SayHelloToResponse
  def m_return
    @v_return
  end

def m_return=(value)
    @v_return = value
  end

def initialize(v_return = nil)
    @v_return = v_return
  end
end

# {http://hello.ws/}getAllUsers
class GetAllUsers
  def initialize
  end
end

# {http://hello.ws/}getAllUsersResponse
class GetAllUsersResponse < ::Array
end

Nada te impede por exemplo de "abrir" a classe User que foi gerada automaticamente no arquivo acima para melhorá-la adicionando novos métodos:

Implementando um cliente em Java

Assim como no caso do Ruby, vamos utilizar o programa wsimport do JAX-WS para gerar automaticamente todas as classes que precisamos a partir do WSDL e codificar nosso cliente de maneira muito fácil.

Os parâmetros utilizados são:

-p ws.hello.client.wsdl Pacote onde as classes serão geradas

-d classes Diretório onde as classes (*.class) serão copiadas

-s src Diretório onde o código fonte (*.java) será gerado

Resumindo: O código gerado terá a linha package ws.hello.client.wsdl em todos as classes Java. O código fonte (arquivos *.java) vai ficar em src\ws\hello\client\wsdl e as corresopndentes classes (ele gera *.class também) em classes\ws\hello\client\wsdl.

Feito isso basta você pegar o port do serviço que nada mais é que uma interface com todos os métodos do serviço para você chamar como se estivesse fazendo chamadas locais de uma API. Veja como é fácil:

Note que o objeto User (ws.hello.client.wsdl.User) também é criado de forma automática pelo wsimport.

Disponibilizando o seu serviço via Tomcat

A classe HelloPublisher.java serve apenas para testar o nosso web service, não sendo viável para o ambiente de produção. Veremos então como publicar o nosso serviço num web container como o Tomcat.

Crie um projeto novo para o Tomcat e copie o pacote ws.hello junto com o código para dentro do diretório onde fica o seu código-fonte, no meu caso WEB-INF\src.

Crie o arquivo WEB-INF\web.xml com o seguinte código XML:

A classe com.sun.xml.ws.transport.http.servlet.WSServlet é o servlet que vai publicar e servir para o mundo o serviço. Já a classe com.sun.xml.ws.transport.http.servlet.WSServletContextListener é responsável por ler o arquivo sun-jaxws.xml com a especificação da implementação do serviço. Crie o arquivo WEB-INF\sun-jaxws.xml abaixo:

Até o momento temos utilizado a implementação do JAX-WS que vem junto com o Java 6, mas agora teremos que utilizar a última versão desse framework pois as classes acima não estão presentes na implentação que vem junto com a distribuição da JSE. Para baixar e instalar o JAX-WS é fácil:

Acesso o site https://jax-ws.dev.java.net/

Baixe o jar da última versão

Execute o comando java -jar jaxwsXXXXXX.jar para instalá-lo.

O diretório jaxws-ri será criado no mesmo diretório onde você baixou o jar do jax-ws. Dentro desse diretório, na pasta lib, estão os jars que precisaremos adicionar na nossa aplicação web. Coloque os jars a seguir dentro do seu diretório WEB-INF\lib: jaxb-impl.jar, jaxws-rt.jar, stax-ex.jar e streambuffer.jar.

Estamos quase prontos para publicar o nosso serviço, faltando ainda utilizar o programa wsgen para gerar as classes auxiliares do nosso web service. Rode o comando abaixo:

Repare que fizemos isso dentro do diretório WEB-INF\classes para que as classes geradas fiquem no lugar correto dentro do pacote ws.hello.jaxws.

Nota: Temos utilizado até agora a versão do wsgen que vem junto com o Java 6. Caso queira utilizar a última versão do wsgen e do wsimport basta colocar o diretório jaxws-ri\bin que você baixou no seu path.

Feito isso você está pronto para rodar a sua aplicação web e publicar o seu serviço para o mundo. A estrutura do seu projeto web deve ter ficado assim:

Segurança e Autenticação para o seu serviço

Caso queira receber o restante desse tutorial envie um email para sergio.oliveira.jr at gmail.com colocando no assunto "Artigo SOA".