Serviços da Web Java: Apresentando o Metro

Aprenda sobre uma estrutura de serviços da Web baseada nas implementações de referência JAXB e JAX-WS

A pilha de serviços da Web Metro fornece uma solução abrangente para acessar e implementar serviços da Web. Ela se baseia nas implementações de referência dos padrões Java™ JAXB 2.x e JAX-WS 2.x, com componentes incluídos para suportar tecnologias de extensão WS-* SOAP e implementação de serviço da Web real. Este artigo continua a série da coluna de Serviços da Web Java de Dennis Sosnoski com uma atenção aos princípios básicos do cliente e desenvolvimento de servidor Metro.

Dennis Sosnoski, Consultant, Sosnoski Software Solutions, Inc.

Author photoDennis Sosnoski é um consultor e instrutor especializado em XML e serviços da Web baseados em Java (este link reside fora de ibm.com). Sua experiência em desenvolvimento de software profissional se estende por mais de 30 anos, sendo que nos últimos 10 focou tecnologias XML e Java do lado do servidor. Dennis é o desenvolvedor líder da estrutura de software livre JiBX XML Data Binding (este link reside fora de ibm.com) e a estrutura de serviços da Web associada JiBX/WS (este link reside fora de ibm.com), assim como um committer na estrutura de serviços da Web Apache Axis2 (este link reside fora de ibm.com). Também foi um dos membros do Grupo de Especialistas para as especificações JAX-WS 2.0 e JAXB 2.0. O material para a série Serviços da Web Java é baseado nas aulas de treinamento de Dennis.



18/Nov/2009

A pilha de serviços da Web Metro é uma ferramenta de software livre desenvolvida pela Sun Microsystems. Ela incorpora as implementações de referência dos padrões de serviços da Web JAXB 2.x e da ligação de dados JAX-WS 2.x, juntamente com outros padrões Java relacionados a XML. Metro também inclui componentes não padrão incluídos para suportar a definição e o uso do serviço JAX-WS básico e uma variedade de extensões WS-* para a troca de mensagens SOAP.

Sobre esta série

Os serviços da Web são uma parte crucial da função da tecnologia Java na computação corporativa. Nesta série de artigos, o consultor de serviços da Web e XML, Dennis Sosnoski, aborda as principais estruturas e tecnologias que são importantes para os desenvolvedores Java que usam serviços da Web. Siga a série para manter-se informado dos desenvolvimentos mais recentes no campo e saber como é possível usá-los para auxiliar seus projetos de programação.

Metro pode ser usado como um pilha de serviços da Web independente ou como um componente integrado dentro do servidor de aplicativos Glassfish de software livre. A configuração do serviço da Web é, de certa, forma mais fácil quando se usa o Glassfish, especialmente se você estiver desenvolvendo em NetBeans IDE de software livre, o que inclui ferramentas GUI para configurar os serviços da Web básicos e as extensões WS-*. Ao manter o foco nos serviços da Web, esta série volta-se somente para o uso independente do Metro de uma maneira independente do IDE, exatamente como artigos anteriores discutiram o uso independente do Apache Axis2 em vez dos servidores de aplicativos que incorporam o Axis2 e suportam as ferramentas de GUI.

Básicos do Metro versus Axis2

Artigos anteriores desta série abordaram o Axis2 em profundidade, assim, uma discussão sobre as similaridades e diferenças entre o Metro e o Axis2 é um bom ponto de partida. As similaridades são limitadas e giram em torno principalmente dos requisitos comuns do desenvolvimento de código usando serviços da Web. Ambas as estruturas permitem iniciar a partir de um código Java existente e construir um serviço da Web (ainda que, no caso do Axis2, o suporte a essa abordagem seja limitado, a menos que você use uma ferramenta separada como a Jibx2Wsdl) ou a partir de uma descrição de serviço da Web WSDL e gerar código Java para usar ou implementar o serviço. Ambas as estruturas modelam operações de serviço como chamadas de método e tipos de porta de serviço como interfaces.

As diferenças entre o Metro e o Axis2 são muito mais notáveis do que as similaridades. Basicamente, o Metro é projetado em torno do JAXB 2.x e do JAX-WS 2.x, sem nenhum interesse em suportar nenhuma alternativa a essas tecnologias (exceto pelo uso do JAX-RPC de legado). O Axis2 é projetado para suportar uma gama ilimitada de tecnologias, especialmente na área de ligação de dados XML; apesar de incluir suporte para JAXB 2.x e JAX-WS 2.x, ele não oferece nenhum status especial a eles. (Se houver algum, o JAX-WS é, de certa forma, uma alternativa de segunda classe no Axis2 porque, — como discutido em "JAXB and JAX-WS in Axis2" — não é possível configurar WS-Security ou outros recursos para um serviço JAX-WS.)

Estruturalmente, ambas as pilhas usam manipuladores como parte do processamento de pedido e resposta. O Axis2 se baseia nessa abordagem do manipulador para implementar módulos : extensões plugáveis para a troca de mensagens SOAP básicas que são usadas para implementar tecnologias WS-* de uma maneira altamente configurável. O Metro suporta uma ampla variedade de tecnologias WS-* com manipuladores, mas essas tecnologias são integradas no mecanismo do Metro, em vez de em componentes separáveis. A abordagem de integração que o Metro usa não é tão flexível como os módulos Axis2, mas ela oferece algumas vantagens quanto à configuração e ao uso das extensões WS-*.

As duas pilhas também diferem em termos de como o código do cliente usa as definições de serviço WSDL. O Axis2 primariamente usa definições de serviço WSDL para geração de código do lado do cliente, extraindo as informações de configuração de serviço do WSDL e gerando código para construir uma configuração de cliente Axis2 correspondente no tempo de execução (ainda que seja possível também analisar uma definição de serviço WSDL no tempo de execução). O JAX-WS 2.x e, por conseguinte, o Metro necessitam de uma definição de serviço WSDL no tempo de execução para construir a configuração de serviço. Esse uso do WSDL em tempo de execução inclui algum gasto adicional de inicialização — embora somente para a primeira invocação de serviço — sem quaisquer benefícios óbvios.

Também existem diferenças no lado do servidor. Para o caso comum de transporte HTTP, o Axis2 é normalmente configurado como um aplicativo da Web distinto (um arquivo WAR), com qualquer número de serviços individuais implementados nesse aplicativo da Web Axis2 (embora ele também possa ser compactado como parte de um WAR de aplicativo). É possível implementar serviços por meio de upload de página da Web ou descartando o arquivo AAR do serviço Axis2 diretamente no diretório apropriado do aplicativo da Web Axis2 expandido. As informações de configuração de serviço individual normalmente são geradas pelo Axis2 a partir da sua definição de serviço WSDL no momento da compilação e, então, incluídas no arquivo AAR do serviço. O aplicativo da Web Axis2 padrão também fornece uma variedade de ferramentas de monitoramento e controle por meio de uma interface de página da Web.

O Metro, em contraste, necessita que você construa um arquivo WAR separado para cada aplicativo de serviço da Web, com os arquivos JAR da biblioteca do Metro incluídos no WAR ou, caso contrário, no caminho de classe (como parte da instalação do servidor HTTP) e um arquivo WEB-INF/web.xml presente no WAR que referencie o seu serviço e um servlet do Metro. Ao usar o independente do Metro, também é necessário criar um arquivo de configuração sun-jaxws.xml, que fornece informações adicionais sobre a configuração do serviço. As informações a partir desses arquivos de configuração são combinadas com as anotações JAX-WS em suas classes de serviços da Web reais para configurar o Metro integralmente para o seu serviço. Como ele não é projetado para uso desta maneira integrada, o Metro não fornece nenhuma ferramenta de monitoramento ou controle direto.

Além disso, o Axis2 e o Metro fornecem suporte ao servidor HTTP integrado. No caso do Metro, isso se dá por meio de um recurso do JAX-WS, a classe javax.xml.ws.Endpoint . Ambos os servidores HTTP integrados do Axis2 e do Metro/JAX-WS são adequados para uso em teste ou como uma porta de resposta assíncrona, mas para hospedar um serviço da Web de produção, um servidor de aplicativos Java que suporte a API Servlet é a abordagem preferencial.


Aplicativo de Amostra

O download de código fornece uma versão do serviço de gerenciamento de biblioteca simples usado em artigos anteriores dessa série, este modificado para demonstrar o uso do Metro. Como com as versões anteriores, a definição de serviço WSDL define quatro operações:

  • getBook para recuperar os detalhes para um manual particular identificado pelo International Standard Book Number (ISBN)
  • getBooksByType para recuperar os detalhes para todos os manuais de um tipo particular
  • getTypes para localizar os tipos de manuais disponíveis
  • addBook para incluir um novo manual na biblioteca

Em "JAXB and JAX-WS in Axis2" você viu como este aplicativo funcionava no Axis2, primeiro com geração de código Axis2 normal usando ligação de dados JAXB 2.x, depois com configuração de serviço JAX-WS 2.x. A maior parte do que você viu naquele artigo também se aplica ao uso do Metro. O WSDL é idêntico, exceto pelo nome do serviço e endereço de terminal, o modelo de dados JAXB gerado é o mesmo e até as classes de serviço geradas são idênticas, exceto pelo pacote Java e o nome do serviço usado nas anotações JAX-WS.

Uso do lado do cliente

O código do lado do cliente para o aplicativo de amostra no Metro é idêntico àquele para uso do JAX-WS com o Axis2 e até as etapas de construção são as mesmas. Consulte "JAXB and JAX-WS in Axis2" para detalhes sobre o código e a manipulação.

Uso do lado do servidor

O código do lado do servidor para o aplicativo de amostra no Metro também é idêntico àquele para uso do JAX-WS com o Axis2, mas as etapas de construção são um pouco diferentes. Com o Axis2, você preparou o serviço para implementação criando um arquivo JAR que contém o serviço e as classes do modelo de dados, então implementou o serviço descartando aquele JAR no diretório WEB-INF/servicejars em uma instalação de servidor Axis2.

Em vez disso, com o Metro você precisa criar um arquivo WAR que contenha o serviço e as classes do modelo de dados, os JARs da biblioteca do Metro (embora você possa, em vez disso, instalar os JARs do Metro diretamente no seu servidor da Web — se estiver usando o Tomcat, o download do Metro inclui um arquivo de construção Ant metro-on-tomcat.xml para instalar os JARs, com instruções na documentação) e um par de arquivos de configuração. O arquivo WEB-INF/web.xml configura a manipulação de servlet real. A Lista 1 mostra a versão usada para o aplicativo de amostra:

Lista 1. Aplicativo de amostra web.xml
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee">
  <display-name>MetroLibrary</display-name>
  <description>Metro Library Service</description>
  <listener>
    <listener-class>com.sun.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <servlet-name>MetroLibraryPort</servlet-name>
    <display-name>MetroLibraryService</display-name>
    <description>Endpoint for Metro Library Service</description>
    <servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>MetroLibraryPort</servlet-name>
    <url-pattern>/</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

Se você já trabalhou com aplicativos da Web Java antes, o arquivo WEB-INF/web.xml da Lista 1 deve parecer familiar (pelo menos na estrutura). As entradas particulares usadas indicam ao mecanismo de servlet no qual o arquivo WAR é implementado para usar a classe com.sun.xml.ws.transport.http.servlet.WSServletContextListener como um listener para eventos de contexto de servlet e para usar a classe com.sun.xml.ws.transport.http.servlet.WSServlet como um servlet real. Essas classes são específicas para a pilha do Metro da Sun, e as referências às classes são necessárias para o funcionamento com o Metro. O servlet é configurado para receber todos os pedidos que chegam a este aplicativo da Web (pela entrada <url-pattern>/</url-pattern> ).

Por si só, o arquivo WEB-INF/web.xml da Lista 1 apenas configura o mecanismo de servlet para usar um listener e um servlet fornecidos pelo Metro. Um arquivo separado, WEB-INF/sun-jaxws.xml (mostrado na Lista 2), é usado para configurar o Metro para rotear pedidos recebidos pelo servlet para o código de implementação de serviço.

Lista 2. Aplicativo de amostra sun-jaxws.xml
<endpoints xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime" version="2.0">

    <endpoint name="MetroLibraryPort"
        implementation="com.sosnoski.ws.library.metro.MetroLibraryImpl"
        url-pattern="/"
        wsdl-location="WEB-INF/wsdl/library.wsdl"/>

</endpoints>

O arquivo WEB-INF/sun-jaxws.xml da Lista 2 é tão simples quanto parece, com uma única definição de terminal fornecendo o nome da porta, classe de implementação, padrão a ser correspondido para pedidos e um local do documento WSDL. O local do documento WSDL é a única parte opcional desta definição de terminal. Se você não especificar um documento WSDL para um terminal de serviço no arquivo sun-jaxws.xml, o Metro automaticamente gera um no tempo de execução.

Os problemas de pacote configurável

A partir do Java SE 6, os tempos de execução de implementação de referência do JAXB 2.x e do JAX-WS 2.x (exceto para extensões de fornecedor) se tornam parte das bibliotecas Java Runtime Environment (JRE) padrão. A intenção disso foi promover o uso dessas tecnologias como padrões Java, mas isso tem um efeito colateral desfavorável: você pode precisar fazer uma mudança na sua instalação do JRE para usar versões mais novas dessas tecnologias.

O build.xml usado no download do aplicativo de amostra copia os arquivos JAR do Metro diretamente no arquivo WAR de serviço. Isso funcionou no sistema do autor quando o aplicativo foi implementado para um servidor da Web Apache Tomcat 6.0.20 usando as instalações Java SE 5 e Java SE 6 JDK/JRE. Se conflitos de carregamento de classe (como o lançamento de ClassCastException ou classes com.sun.xml... não localizadas) causarem problemas na utilização do Java SE 6 ou posterior, aqui está como corrigi-los:

  • Certifique-se de que está usando a versão mais recente do JRE disponível para o seu sistema, porque as atualizações podem incluir versões posteriores do JAXB 2.x e JAX-WS 2.x.
  • Use a propriedade do sistema java.endorsed.dirs para especificar um diretório que contenha o arquivo webservices-api.jar do diretório lib do Metro (somente o arquivo webservices-api.jar, porque incluir outros JARs causará conflitos de carregamento de classe) como uma origem de bibliotecas atualizadas. (O Tomcat 6.0.x suporta este mecanismo por meio da procura de uma variável de ambiente JAVA_ENDORSED_DIRS e usando-a como o valor da propriedade do sistema.)
  • Se tudo o mais falhar, crie um diretório endossado dentro do diretório lib da sua instalação JRE (se ainda não estiver presente) e copie o arquivo webservices-api.jar do Metro para este diretório.

Com uma das duas últimas técnicas, você não precisa incluir o webservices-api.jar do Metro no seu arquivo WAR de serviço porque ele estará diretamente disponível no caminho de classe do servidor da Web.

Construindo e executando o código de amostra

Antes de poder testar o código de amostra, é necessário fazer o download e instalar uma versão atual do Metro (o código foi testado com o release 1.5) no seu sistema (consulte Recursos). Também é necessário editar o arquivo build.properties no diretório-raiz do download do código de amostra descompactado para alterar o valor da propriedade metro-home para o caminho de instalação do seu Metro. Se você testará com um servidor em um sistema ou porta diferente, talvez você precise mudar o host-name e o host-port.

Para construir o aplicativo de amostra usando o Ant build.xml fornecido, abra um console para o diretório-raiz do código de download e digite ant. Isso primeiro invocará a ferramenta JAX-WS wsimport (incluída na distribuição do Metro), depois compile o cliente e o servidor e, finalmente, compacte o código do servidor como um WAR. Então, é possível implementar o arquivo metro-library.war gerado no seu servidor de teste e, finalmente, digitar ant run no console para tentar executar o cliente de amostra. O cliente de amostra é executado através de uma sequência de vários pedidos para o servidor, imprimindo breves resultados para cada pedido.

Infelizmente, a manipulação do Metro padrão não executará completamente o exemplo. Quando o código do servidor do Metro converte uma exceção em uma mensagem de Falha de SOAP ele também (por padrão) envia os detalhes do rastreamento de pilha. O código do cliente Metro não consegue reconhecer os dados de Falha contidos na resposta e apenas lança o objeto de Falha apropriado sem preencher os dados contidos. No código de exemplo, isso causa uma NullPointerException.

Para mudar esse comportamento padrão de certa forma inesperado, é necessário configurar uma propriedade com.sun.xml.ws.fault.SOAPFaultBuilder.disableCaptureStackTrace=false no JVM do servidor. (Sim, isso mesmo — você configura a propriedade disableCaptureStackTrace para false para desativar o envio de rastreios de pilha.) Geralmente, você precisará passar esta configuração de propriedade para a inicialização do seu servidor da Web Java. Com o Tomcat, é possível fazer isso definindo uma variável de ambiente:

CATALINA_OPTS=
 -Dcom.sun.xml.ws.fault.SOAPFaultBuilder.disableCaptureStackTrace=false

Depois de fazer essa mudança na configuração do seu servidor e reiniciá-lo, você deve poder executar o programa de exemplo integralmente.


A seguir no Metro

Neste artigo, você viu o básico do trabalho com a pilha de serviços da Web do Metro. Porque o Metro usa anotações JAX-WS 2.x para configuração, o mesmo código do aplicativo de amostra JAX-WS 2.x usado em "JAXB and JAX-WS in Axis2" também funciona com o Metro. As únicas mudanças necessárias dizem respeito a como o código é compactado e implementado no lado do servidor e, nisso, o Metro e o Axis2 são significantemente diferentes. O Metro usa uma abordagem de integração na qual você cria um aplicativo da Web para cada serviço ou grupo de serviços (e nenhuma função de controle ou monitoramento é fornecida). Normalmente o Axis2 usa um único aplicativo da Web dedicado como o host para qualquer número de serviços individuais (com funções de controle e monitoramento básicas fornecidas diretamente por meio de uma interface de página da Web).

Além do básico da troca de mensagens do serviço da Web, o Metro também suporta extensões SOAP como WS-Security. Assim como com a questão de serviço-compactação, o Metro e o Axis2 assumem abordagens diferentes para requisitos muito similares nesta área. No próximo artigo, você verá como o Metro manipula os mesmos exemplos de WS-Security previamente usados nesta série com o Axis2.


Download

DescriçãoNomeTamanho
Source code for this articlej-jws9.zip13KB

Recursos

Aprender

Obter produtos e tecnologias

Discutir

Comentários

developerWorks: Conecte-se

Los campos obligatorios están marcados con un asterisco (*).


Precisa de um ID IBM?
Esqueceu seu ID IBM?


Esqueceu sua senha?
Alterar sua senha

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


A primeira vez que você entrar no developerWorks, um perfil é criado para você. Informações no seu perfil (seu nome, país / região, e nome da empresa) é apresentado ao público e vai acompanhar qualquer conteúdo que você postar, a menos que você opte por esconder o nome da empresa. Você pode atualizar sua conta IBM a qualquer momento.

Todas as informações enviadas são seguras.

Elija su nombre para mostrar



Ao se conectar ao developerWorks pela primeira vez, é criado um perfil para você e é necessário selecionar um nome de exibição. O nome de exibição acompanhará o conteúdo que você postar no developerWorks.

Escolha um nome de exibição de 3 - 31 caracteres. Seu nome de exibição deve ser exclusivo na comunidade do developerWorks e não deve ser o seu endereço de email por motivo de privacidade.

Los campos obligatorios están marcados con un asterisco (*).

(Escolha um nome de exibição de 3 - 31 caracteres.)

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


Todas as informações enviadas são seguras.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=80
Zone=Tecnologia Java, Software livre
ArticleID=447769
ArticleTitle=Serviços da Web Java: Apresentando o Metro
publish-date=11182009