Labs SD >

SOAP Handlers

Objectivos

Índice:

SOAP

O SOAP é o formato de mensagens para Web Services. Os envelopes podem ser transportados pela rede de diversas formas, mas a mais comum é através do protocolo HTTP. O SOAP é independente do protocolo de transporte.

Os documentos seguintes são mensagens SOAP correspondentes a um par pedido-resposta trocado por um cliente com um Web Service. 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
         xmlns:ns1="urn:hello">
    <soapenv:Body>
        <ns1:sayHello>
            <ns1:name>friend</ns1:name>
        </ns1:sayHello>
    </soapenv:Body>
</soapenv:Envelope>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                     xmlns:ns1="urn:hello">
    <soapenv:Body>
        <ns1:sayHelloResponse>
            <ns1:return>Hello friend!</ns1:return>
        </ns1:sayHelloResponse>
    </soapenv:Body>
</soapenv:Envelope>

Uma mensagem SOAP é um documento XML designado por envelope. O SOAP separa o cabeçalho, com dados de sistema para serem processados pelas bibliotecas de Web Services, do corpo, com dados de negócio para serem processados pelas aplicações.

O cabeçalho header permite a composição de protocolos, pois cada elemento de extensão indica a sua versão e a opcionalidade da sua interpretação.
O corpo (body) contém os dados de negócio da mensagem ou então o elemento Fault com informação de erro.

SAAJ

A SAAJ (SOAP with Attachments API for Java) é uma biblioteca que estende o XML DOM, adaptando-o para documentos XML que são mensagens SOAP. Isto significa que existem vários métodos específicos para tratar as mensagens.

Uma mensagem SOAP tem a seguinte estrutura:

SOAP Message

A SOAPMessage contém várias partes.
A primeira parte é uma SOAPPart, que contém um SOAPEnvelope.
Um SOAPEnvelope contém um SOAPBody e opcionalmente um SOAPHeader.
Dentro destes, podem ser colocados SOAPElement.

Numa mensagem SOAP, os elementos devem ser sempre especificados com espaço de nomes, para evitar conflitos.

Os objectos da biblioteca SAAJ estão no pacote javax.xml.soap.*
O exemplo seguinte mostra como se constrói uma mensagem simples. 

    ...

    MessageFactory mf = MessageFactory.newInstance();

    SOAPMessage soapMessage = mf.createMessage();
    SOAPPart soapPart = soapMessage.getSOAPPart();
    SOAPEnvelope soapEnvelope = soapPart.getEnvelope();
    SOAPBody soapBody = soapEnvelope.getBody();
    Name name = soapEnvelope.createName("HelloWorld", "hw", "urn:helloworld");
    SOAPElement element = soapBody.addChildElement(name);
    element.addTextNode( "hello text message" );

    ...

    soapMessage.writeTo(System.out);
    System.out.println();

    ...

Exemplos SOAP e XML

Os exemplos seguintes mostram como modificar as mensagens SOAP e como enviar mensagem SOAP directamente sem stubs.
Para complementar existem também exemplos das tecnologias base de XML: SAX, DOM, XSD, XPath.

 

SOAP Handlers

O JAX-WS é uma biblioteca para a plataforma Java que simplifica a invocação de Web Services, fazendo o mapeamento de tipos para Java para mensagens SOAP. Normalmente os programadores nem sequer precisam de "ver" as mensagens SOAP. No entanto, quando se quer implementar segurança ao nível das mensagens ou transportar informação adicional relativa a transacções distribuídas, é necessário ter uma forma de aceder às mensagens SOAP.

Os JAX-WS Handlers são objectos que podem ler e escrever dados nas mensagens SOAP geradas pelos Stubs e pelos Ties.

Handlers

Um Handler é uma classe Java que implementa a interface javax.xml.ws.handler.soap.SOAPHandler.

O seguinte exemplo é um Handler básico. O principal método é o handleMessage() que é invocado de cada vez que chega ou parte uma mensagem: 

package example.ws.handler;

import java.util.Set;
import javax.xml.namespace.QName;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.handler.soap.SOAPHandler;
import javax.xml.ws.handler.soap.SOAPMessageContext;

public class EmptyHandler implements SOAPHandler {

    public Set getHeaders() {
        return null;
    }

    public boolean handleMessage(SOAPMessageContext smc) {
        return true;
    }

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

    public void close(MessageContext messageContext) {
        return;
    }

}

O retorno do método handleMessage() determina de que forma prossegue o processamento da mensagem. Se for 'true' o processamento deve prosseguir; se for 'false' bloqueia o processamento da mensagem, mudando-lhe o sentido e fazendo-a voltar para o cliente.

A utilização de exceções permite modificar o normal processamento das mensagens SOAP:

Configuração

A configuração dos Handlers é efectuada num ficheiro que define a cadeia de handlers. 

<handler-chains xmlns="http://java.sun.com/xml/ns/javaee">
    <handler-chain>
        <handler>
            <handler-class>example.ws.handler.LoggingHandler</handler-class>
        </handler>
    </handler-chain>
</handler-chains>

A configuração os Handlers é diferente no servidor e no cliente. Em ambos os casos não são necessárias alterações aos pom.xml.

 

Biblioteca de Handlers

Esta biblioteca é um módulo Maven com Handlers que podem ser usados em servidores e clientes sem ter que copiar as mesmas classes por diversos projetos (o que é uma má prática a evitar).

 

Exemplo de Handlers de inspeção de mensagens

Este exemplo demonstra a forma como os SOAP Handlers acedem às mensagens XML dos Web Services.

 

Exemplo de Handlers estafetas de dados

Este exemplo demonstra os mecanismos de passagem de dados entre as diversas camadas de um Web Service:

  1. do cliente para o handler cliente (via contexto do pedido, que é obtido a partir do stub),
  2. do handler cliente para o handler servidor (via cabeçalho na mensagem SOAP),
  3. do handler servidor para o servidor (via contexto das mensagens que é fornecido como argumento),
  4. do servidor para o handler servidor (novamente via contexto das mensagens que é fornecido pela biblioteca através da anotação @Resource),
  5. do handler servidor para o handler cliente (via cabeçalho na mensagem SOAP),
  6. e finalmente, do handler cliente para o servidor (via contexto da resposta).

Consultar os exemplos seguindo os comentários numerados #1, #2, #3, ... que seguem a sequência de uma invocação remota começando no cliente, passando pelo servidor e voltando ao cliente. Pelo caminho o token vai sendo acrescentado com mais dados.

© Docentes de Sistemas Distribuídos, Dep. Eng. Informática, Técnico Lisboa