4. Estrutura Avançada
Vista a estrutura básica de uma mensagem SOAP, será analisada agora a estrutura completa, ora chamada de estrutura avançada.
Exemplo
Nesse novo exemplo, foram incluídos um cabeçalho HTTP, um cabeçalho opcional SOAP e uma mensagem de erro de exemplo.
Pedido (Request):
POST /InStock HTTP/1.1
Host: www.dre.ufrj.br
Content-Type: application/soap+xml; charset=utf-8
Content-Length: nnn
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap- envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding" xmlns:tiposns="http://www.w3.org/2001/XMLSchema">
       <soap:Header>
             <m:atenticacao xmlns:m="http://www.dre.ufrj.br/ws/dre">21423edf69fgs</m:atenticacao>
       </soap:Header>
       <soap:Body>
             <m:retornaNome xmlns:m="http://www.dre.ufrj.br/ws/dre">
                    <numdre type="tiposns:int">106017797</drenum>
             </m:retornaNome>
       </soap:Body>
</soap:Envelope>
-----------------------------------------------------------------------------------------------------------------------------------------------
Resposta (Response):
HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: nnn
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap- envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding" xmlns:tiposns="http://www.w3.org/2001/XMLSchema">
       <soap:Header>
             <m:atenticacao xmlns:m="http://www.dre.ufrj.br/ws/dre">2kg469fgs</m:atenticacao>
       </soap:Header>
       <soap:Body>
             <m:retornaNomeResponse xmlns:m="http://www.dre.ufrj.br/ws/dre">
                    <nome type="tiposns:string">Leonardo Bentes Arnt</nome>
             </m:retornaNomeResponse>
             <soap:Fault>
             </soap:Fault>
       </soap:Body>
</soap:Envelope>
Cabeçalho
O cabeçalho (Header) do SOAP é um elemento opcional que contém informações específicas da aplicação. Se uma mensagem SOAP possui Header, esse elemento deve ser o primeiro filho do nó Envelope. No exemplo dado, uma informação comum em cabeçalhos SOAP é acrescentada: uma chave de autenticação.
De modo geral, o Header do SOAP contém meta-informações da mensagem.
Tratamento de Erro
Mensagens de erro devem ser contextualizadas como tal para que possam ser processadas de maneira correta pelo seu receptor. Em outras palavras, é necessário criar no SOAP um elemento exclusivamente para carregar as informações do erro. O nome desse elemento é Fault. Se esse elemento fizer parte da mensagem, ele deve, obrigatoriamente, ser posicionado como filho do elemento Body. Além disso, não pode haver mais de um elemento Fault em uma mensagem SOAP.
A definição padrão do elemento Fault (contida no documento para onde aponta o namespace "soap" do exemplo) possui quatro sub-elementos definidos:
- "<faultcode>" -> Código identificador do erro (versão errada, erro de construção da mensagem no cliente, erro de processamento da mensagem no servidor etc);
- "<faultstring>" -> Explicação compreensível do erro;
- "<faultactor>" -> Informações referentes ao autor do erro;
- "<detail>" -> Fornece informações sobre erro que sejam específicas da aplicação.
Protocolo de Transporte
Como SOAP é simplesmente uma especificação de restrições em cima de um texto XML, mensagens desse protocolo podem ser carregadas por qualquer protocolo capaz de transportar texto. Os mais usados são o SMTP (Simple Mail Transfer Protocol) e o HTTP (Hypertext Transfer Protocol), basicamente por serem os mais populares de modo geral, mas uma mensagem SOAP poderia ser enviada por FTP ou mesmo por sockets TCP/IP puros [7].
A figura a seguir, adaptada de [11], deixa claro que o SOAP não substitui protocolos de transporte nem de comunicação a nível de aplicação, complementando o que foi dito acima. Ao invés disso, uma aplicação SOAP usa protocolos já existentes nessas camadas para transmitir suas mensagens.
graphic
SOAP usando HTTP
Como visto no exemplo dado, para uma mensagem SOAP ser transportada usando o HTTP, basta que o cabeçalho desse último protocolo seja preenchido corretamente e o corpo seja constituido da própria mensagem SOAP. Sobre o preenchimento do cabeçalho HTTP para transporte de mensagens SOAP, é importante frisar duas coisas.
A primeira é referente ao atributo "Content-Type". Esse atributo especifica o tipo de interpretação que a mensagem HTTP deve receber. Um exemplo de valor para esse campo é o popular "text/html", usado para arquivos html como este sendo lido. Para aplicações SOAP, deve-se usar o valor "application/soap+xml".
A segunda é referente aos métodos POST e GET do protocolo HTTP. Qualquer um deles pode ser usado para transmitir uma mensagem SOAP, ainda que nenhum deles tenha sido projetado para isso.
Usar HTTP dá ao SOAP mais uma vantagem: como quase todos os firewalls permitem o tráfego HTTP (normalmente na porta 80), o uso desse protocolo garante livre fluxo de mensagens SOAP por plataformas distintas.
SOAP usando SMTP
Quando usa-se o SMTP para transmitir mensagens SOAP, algumas abstrações dos atributos do cabeçalho SMTP precisam ser feitas e o servidor SMTP em questão deve ser configurado para lidar com o protocolo. As mensagens do exemplo, usando SMTP, ficariam assim:
Pedido (Request):
To: <dre@ws.dre.ufrj.br>
From: <cliente@cliente.com>
Reply-To: <cliente@cliente.com>
Date: Tue, 15 Nov 2001 23:27:00 -0700
Message-Id: <1F75D4D515C3EC3F34FEAB51237675B5@cliente.com>
MIME-Version: 1.0
Content-Type: text/xml; charset=utf-8
Content-Transfer-Encoding: QUOTED-PRINTABLE
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap- envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding" xmlns:tiposns="http://www.w3.org/2001/XMLSchema">
       <soap:Header>
             <m:atenticacao xmlns:m="http://www.dre.ufrj.br/ws/dre">21423edf69fgs</m:atenticacao>
       </soap:Header>
       <soap:Body>
             <m:retornaNome xmlns:m="http://www.dre.ufrj.br/ws/dre">
                    <numdre type="tiposns:int">106017797</drenum>
             </m:retornaNome>
       </soap:Body>
</soap:Envelope>
------------------------------------------------------------------------------------------------------------------------------------
Resposta (Response):
To: <cliente@cliente.com>
From: <dre@ws.dre.ufrj.br>
Date: Tue, 13 Nov 2001 23:27:00 -0700
In-Reply-To: <1F75D4D515C3EC3F34FEAB51237675B5@cliente.com>
Message-Id: <FF75D4D515C3EC3F34FEAB51237675B5@ws.dre.ufrj.br>
MIME-Version: 1.0
Content-Type: TEXT/XML; charset=utf-8
Content-Transfer-Encoding: QUOTED-PRINTABLE
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap- envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding" xmlns:tiposns="http://www.w3.org/2001/XMLSchema">
       <soap:Header>
             <m:atenticacao xmlns:m="http://www.dre.ufrj.br/ws/dre">2kg469fgs</m:atenticacao>
       </soap:Header>
       <soap:Body>
             <m:retornaNomeResponse xmlns:m="http://www.dre.ufrj.br/ws/dre">
                    <nome type="tiposns:string">Leonardo Bentes Armt</nome>
             </m:retornaNomeResponse>
             <soap:Fault>
             </soap:Fault>
       </soap:Body>
</soap:Envelope>
Anexos
Mensagens SOAP também podem transportar anexos binários ou textuais. Para tal, o anexo deve transportado no elemento Body. Caso o anexo seja textual,