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.
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.
@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
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.
<?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.
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;
}
}