Usando Manipuladores em Serviços da Web JAX-WS

O Java™ API for XML Web Services JAX-WS) fornece uma maneira padrão de desenvolver serviços da Web interoperáveis e móveis. Use manipuladores JAX-WS para customizar a manipulação de pedidos ou resposta de serviços da Web.

Antes de Iniciar

É necessário um arquivo EAR (Enterprise Archive) para os aplicativos que você deseja configurar. Se você estiver executando em um ambiente Thin Client para JAX-WS, não será necessário iniciar com um arquivo EAR. Para alguns usos de rotinas de tratamento, como logs ou rastreio, somente o aplicativo servidor ou cliente necessita ser configurado. Para outros usos de manipuladores, incluindo enviar informações em cabeçalhos SOAP, os aplicativos cliente e servidor precisam ser configurados com manipuladores simétricos.

Os módulos no arquivo EAR devem conter as classes do manipulador a serem configuradas. As classes do manipulador implementam a interface javax.xml.ws.handler.LogicalHandler<LogicalMessageContext>, ou a interface javax.xml.ws.handler.soap.SOAPHandler<SOAPMessageContext>.
Lembre-se: Se interceptar umaSOAPMessage de entrada e em seguida manipulá-la, como incluir uma parte de anexo, você deve usar a parte setmessage do SOAPMessageContext para assegurar que o anexo faça parte do SOAPMessageContext. Isso assegura que o tempo de execução JAX-WS possa acessar essa SOAPMessage mais recente para que ele possa acessar corretamente as partes do anexo. O exemplo a seguir demonstra esse processo:
 SOAPMessage m = context.getMessage(); 
 AttachmentPart ap1 = m.createAttachmentPart(); 
 ap1.setContent("abc", "text/plain");           
 m.addAttachmentPart(ap1);
 context.setMessage(m);                       

Sobre Esta Tarefa

Como no modelo de programação JAX-RPC (Java API for XML-based RPC), o modelo de programação JAX-WS fornece um recurso do manipulador de aplicativos que possibilita manipular uma mensagem em um fluxo de entrada ou de saída. É possível incluir os manipuladores no ambiente de tempo de execução JAX-WS para executar o processamento adicional de mensagens de pedido e resposta. É possível utilizar manipuladores para uma variedade de fins como capturar e registrar em log as informações e incluir a segurança ou outras informações em uma mensagem. Devido ao suporte para protocolos adicionais além do SOAP, o JAX-WS fornece duas classificações diferentes para os manipuladores. Um tipo de manipulador é um manipulador lógico que é o protocolo independente e pode obter a mensagem no fluxo como uma mensagem XML (Linguagem de Marcação Extensível). Os manipuladores lógicos operam sobre carga útil e propriedades de contexto de mensagens. Esses manipuladores devem implementar a interface javax.xml.ws.handler.LogicalHandler. Um manipulador lógico recebe um objeto LogicalMessageContext do qual o manipulador pode obter as informações de mensagens. Os manipuladores lógicos podem existir em configurações baseadas em SOAP e em XML/HTTP.

O segundo tipo de manipulador é um manipulador de protocolos. Os manipuladores de protocolos operam em propriedades de contexto da mensagem e mensagens específicas de protocolo. Os manipuladores de protocolos são limitados a configurações baseadas em SOAP e devem implementar a interface javax.xml.ws.handler.soap.SOAPHandler. Os manipuladores de protocolos recebem a mensagem como um javax.xml.soap.SOAPMessage para ler os dados da mensagem.

O tempo de execução JAX-WS não faz distinção entre as classes de manipulador do servidor e do cliente. O tempo de execução não distingue entre o fluxo de entrada ou de saída quando um método handleMessage(MessageContext) ou método handleFault(MessageContext) para um manipulador específico for chamado. Você deve configurar os manipuladores para o servidor ou cliente, e implementar a lógica suficiente nesses métodos para detectar a direção de entrada ou saída da mensagem atual.

Para usar os manipuladores com aplicativos do cliente de serviços da Web, é necessário configurar a anotação @HandlerChain na interface do terminal em serviço ou a classe de serviço gerada e fornecer o arquivo de configuração de cadeia do manipulador. A anotação @HandlerChain contém um atributo de arquivo que aponta para um arquivo de configuração de cadeia do manipulador que você cria. Para aplicativos de cliente de serviços da Web, também é possível configurar a cadeia do manipulador programaticamente usando a API Binding. Para modificar a classe de cadeia do manipulador programaticamente, utilize a implementação padrão ou uma implementação customizada do método HandlerResolver.

Para utilizar os manipuladores com seu aplicativo do servidor, é necessário configurar a anotação @HandlerChain na interface do terminal em serviço ou a classe de implementação do terminal e fornecer o arquivo de configuração de cadeia do manipulador associado. Os manipuladores para o servidor são configurados apenas ao definir a anotação @HandlerChain na implementação do terminal em serviço ou na classe de implementação. As classes do manipulador devem ser incluídas no arquivo EAR do aplicativo do servidor.

Para as implementações do servidor e do cliente dos manipuladores que utilizam a anotação @HandlerChain, você deve especificar o local da configuração do manipulador como um caminho relativo do arquivo anotado ou como uma URL absoluta. Por exemplo:
@HandlerChain(file="../../common/handlers/myhandlers.xml")
ou
@HandlerChain(file="http://foo.com/myhandlers.xml")
Para obter informações adicionais sobre o esquema do arquivo de configuração do manipulador, consulte a especificação JSR 181.

Para obter informações adicionais a respeito dos manipuladores JAX-WS, consulte o capítulo 9 da especificação JAX-WS.

Procedimento

  1. Determine se você deseja implementar os manipuladores JAX-WS no serviço ou no cliente.
  2. Configure os manipuladores do cliente, configurando a anotação @HandlerChain na instância de serviço ou na interface do terminal em serviço ou você pode modificar a cadeia do manipulador programaticamente para controlar como a cadeia do manipulador é construída no tempo de execução. Se você optar por modificar a cadeia do manipulador programaticamente, deve determinar se utilizará o resolvedor padrão ou se utilizará uma implementação customizada de um resolvedor do manipulador que é registrada na instância de serviço. Uma instância de serviço utiliza um resolvedor do manipulador ao criar os provedores de ligação. Quando os provedores de ligação são criados, o resolvedor do manipulador que é registrado em um serviço é utilizado para criar uma cadeia de manipulador e a cadeia do manipulador é utilizada subseqüentemente para configurar o provedor de ligação.
    1. Utilize a implementação padrão de um resolvedor do manipulador. O tempo de execução agora utiliza a anotação @HandlerChain e a implementação padrão da classe HandlerResolver para construir a cadeia do manipulador. É possível obter a cadeia de manipulador existente a partir da Ligação, incluir ou remover os manipuladores e, em seguida, retornar a cadeia do manipulador modificado para o objeto de Ligação.
    2. Para utilizar uma implementação customizada de um resolvedor do manipulador, configure a classe HandlerResolver customizada na instância de Serviço. O tempo de execução utiliza a sua implementação customizada da classe HandlerResolver para construir a cadeia do manipulador e a implementação de tempo de execução padrão não é utilizada. Neste cenário, a anotação @HandlerChain não é lida ao recuperar a cadeia do manipulador da ligação depois que a instância customizada do HandlerResolver for registrada na instância de Serviço. É possível obter a cadeia de manipulador existente a partir da Ligação, incluir ou remover os manipuladores e, em seguida, retornar a cadeia do manipulador modificado para o objeto de Ligação.
  3. Configure os manipuladores do servidor, configurando a anotação @HandlerChain na interface de terminal em serviço ou na classe de implementação. Quando a anotação @HandlerChain for configurada na interface de terminal em serviço e na classe de implementação, a classe de implementação terá prioridade.
  4. Crie o arquivo XML de configuração da cadeia do manipulador. É necessário criar um arquivo XML de configuração da cadeia do manipulador para @HandlerChain para referência.
  5. Inclua o arquivo XML de configuração da cadeia do manipulador no caminho da classe para a interface de terminal em serviço ao configurar os manipuladores do servidor ou do cliente utilizando a anotação @HandlerChain. Você também deve incluir as classes de manipulador contidas no arquivo XML de configuração em seu caminho de classe.
  6. Grave a implementação do manipulador.

Resultados

Você ativou o seu serviço da Web ou cliente dos serviços da Web JAX-WS para usar manipuladores para executar processamento adicional de troca de mensagens de pedido e resposta.

Exemplo

O exemplo a seguir ilustra as etapas necessárias para configurar os manipuladores JAX-WS em uma interface de terminal em serviço utilizando a anotação @HandlerChain.

A anotação @HandlerChain possui um atributo de arquivo que aponta para um arquivo XML de configuração de cadeia do manipulador que você cria. O arquivo a seguir ilustra um típico arquivo de configuração de manipulador. Os elementos protocol-bindings, port-name-pattern e service-name-pattern são todos filtros que são utilizados para restringir quais serviços podem aplicar os manipuladores.
<?xml version="1.0" encoding="UTF-8"?>

<jws:handler-chains xmlns:jws="http://java.sun.com/xml/ns/javaee">
<!-- Nota:  '*" denota um curinga. -->

	<jws:handler-chain name="MyHandlerChain">
		<jws:protocol-bindings>##SOAP11_HTTP ##ANOTHER_BINDING</jws:protocol-bindings>
		<jws:port-name-pattern 
              xmlns:ns1="http://handlersample.samples.ibm.com/">ns1:MySampl*</jws:port-name-pattern>
        <jws:service-name-pattern 
              xmlns:ns1="http://handlersample.samples.ibm.com/">ns1:*</jws:service-name-pattern>
		<jws:handler>
			<jws:handler-class>com.ibm.samples.handlersample.SampleLogicalHandler</jws:handler-class>
		</jws:handler>
		<jws:handler>
			<jws:handler-class>com.ibm.samples.handlersample.SampleProtocolHandler2</jws:handler-class>
		</jws:handler>
		<jws:handler>
			<jws:handler-class>com.ibm.samples.handlersample.SampleLogicalHandler</jws:handler-class>
		</jws:handler>
		<jws:handler>
			<jws:handler-class>com.ibm.samples.handlersample.SampleProtocolHandler2</jws:handler-class>
		</jws:handler>
	</jws:handler-chain>
	
</jws:handler-chains>

</jws:handler-chains>

Certifique-se de incluir o arquivo handler.xml e as classes manipuladoras contidas no arquivo handler.xml em seu caminho da classe.

O exemplo a seguir demonstra uma implementação do manipulador:
package com.ibm.samples.handlersample;

import java.util.Set;

import javax.xml.namespace.QName;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.handler.soap.SOAPMessageContext;

public class SampleProtocolHandler implements
        javax.xml.ws.handler.soap.SOAPHandler<SOAPMessageContext> {

    public void close(MessageContext messagecontext) {
    }

    public Set<QName> getHeaders() {
        return null;
    }

    public boolean handleFault(SOAPMessageContext messagecontext) {
        return true;
    }

    public boolean handleMessage(SOAPMessageContext messagecontext) {
        Boolean outbound = (Boolean) messagecontext.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
        if (outbound) {
            // Inclua suas etapas para o fluxo de saída.
        }
        return true;
    }

}

O que Fazer Depois

Implemente o seu aplicativo de serviços da Web.

Ícone que indica o tipo de tópico Tópico de Tarefa



Ícone de registro de data e hora Última atualização: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxwshandler
Nome do arquivo: twbs_jaxwshandler.html