Tratamento de Excees em Web Services - Sugesto de Uso de Tratamento de Erros do

Protocolo SOAP
Resumo
Neste trabalho ser apresentado um modelo de implementao para tratamento de erros em Web
Services utilizando o Protocolo Simples de Acesso a Objetos, Simple Object Access Protocol SOAP,
formalizando conceitos e boas prticas, visando a unificao no desenvolvimento de solues que
utilizem este protocolo em decorrncia da necessidade de interoperabilidade com sistemas
desenvolvidos para o governo federal. A grande flexibilidade do SOAP permite implementaes que
atendam a grande maioria das demandas de integrao entre sistemas mas em contra partida
dificulta a uniformizao e implementao das solues devido a generalizao das especificaes
do protocolo.
Tratamento de Erros
O amadurecimento dos padres de interoperabilidade do Governo Federal apresenta novas
demandas relativas a uma especificao em uma granularidade menor para atendimento das
demandas relativas a implementao de produtos de software. O uso de web services tem se
demonstrado como uma ferramenta muito adequada as implementaes das aplicaes ligadas as
atividades da gesto pblica, o que vem demandando novas necessidades de especificao mais
prximas da realidade das atividades de implementao. Este artigo apresenta critrios e
nomenclaturas padronizadas para oferecer informaes para proporcionar maior compreenso de
erros ocorridos nas trocas de informaes em Web Services que utilizam o protocolo SOAP.
Fornecer adequadamente as informaes quando ocorre um erro na troca de mensagens entre
aplicaes facilita no somente o desenvolvimento da aplicao mas proporciona facilidade na
identificao de falhas durante todo ciclo de vida do sistema. Informaes claras e fornecidas
adequadamente para cada tipo de erro que ocorra em uma transao pode ser determinante em
momentos crticos como falha na infraestrutura ou alteraes nas regras de negcios. Passar ao
usurio do sistema, humano ou aplicao, informaes adequadas permite o encaminhamento
adequado para o ator que pode solucionar a demanda quer seja ela uma falha em validao de erros
com a camada de visualizao de um sistema quer seja a indisposio de algum outro servio que
compreende a arquitetura da soluo de software.
Sempre que ocorre alguma falha no processamento das informaes no servidor gerada uma
resposta por meio de um tipo especial de marcador enviado no corpo do documento SOAP definido
no item 5.4 SOAP Fault da recomendao SOAP Version 1.2. O tratamento adequado das
informaes contidas nestes marcadores relevante para que o desenvolvedor que implementa o
consumidor do servio agregue qualidade ao produto que esta desenvolvendo. Outro fator relevante
que a clareza nos motivos que causaram a excesso evite a necessidade de solicitao de
informaes adicionais aos rgos responsveis pela manuteno do servio.
As definies do padres definidos para os tipos de falhas, na verso 1.2 da especificao do SOAP
esto definidos no namespace http://www.w3.org/2001/06/soap-envelope. Estas definies
fornecem um conjunto de informaes suficientes para o atendimento das necessidades de
compreenso de falhas em um sistema. No entanto para o atendimento das demandas de integrao
necessrias aos sistemas mantidos pelo Governo Federal Brasileiro as recomendaes apresentadas
no so suficientes para a produo dos sistemas com a qualidade exigida nos produtos. A proposta
de exteno do protocolo de falha apresentando a incluso de marcadores especficos proporciona
maior capacidade de compreender falhas ocorridas em uma transao de consumo de dados.
A extenso proposta neste documento prev incluso de marcadores no campo details do protocolo
Fault e padronizao dos valores enviados nos marcadores faultcode e faultsring das
recomendaes W3C para promover maior capacidade de interoperabilidade aos sistemas. Neste
modelo proposto o marcador details passa a ser obrigatrio e deve conter obrigatoriamente o
marcador application, contendo o cdigo da aplicao que provocou o erro, e opcionalmente o

marcador extradetail.
<s:Envelope xmlns:s="...">
<s:Body>
<s:Fault>
<faultcode>Client.Authentication</faultcode>
<faultstring>
Invalid credentials
</faultstring>
<details>
<application>
<name>Sigla da aplicacao</name>
<organization>Orgao responsavel pela manutencao do sistema<organization>
</application>
</details>
</s:Fault>
</s:Body>
</s:Envelope>

A padronizao das mensagens de erro foram divididas em trs categorias tratveis pela camada de
aplicao definida no padro OSI e so as seguintes:
Erros de Tipo
Erros de Negcio
Erros de Processamento
Para quaisquer categoria de erros o marcador faultcode dever ser preenchido com um identificador
nico do erro no sistema construdo utilizando o padro @@:NNNN onde @@ contm a
especificao do tipo de erro conforme a lista tipos de erros:
EN: erro no processamento de regras de negcio como por exemplo valores fora de intervalo
pr definido.
ET: erro no processamento de tipos onde o mtodo no pode ser executado pois os
parmetros no correspondem a assinatura do mtodo.
EP: erro de implementao no previsto como ponteiro que aponta para endereo invlido
ou falha no acesso a recursos.
Erros de Tipo
Apesar dos servidores de aplicao Web services implementarem tratamento de erros de tipo em sua
implementao, no existe uma padronizao de cdigos e mensagens em caso de falhas. A
promoo da interoperabilidade tem uma forte relao com a padronizao de troca de mensagens,
apresentando a necessidade de implementar uma camada de tratamento de validao na
transformao de tipos que interaja com o servidor fazendo a traduo das falhas conforme o padro
apresentado a seguir.
Exemplo de mensagens produzidas por erros de converso de tipos:
ET:001 No foi possvel converter o valor <dados>em<tipo>
ET:002 O valor <dados> tem tamanho maior que definido para o campo <tipo>[tamanho]
ET:003 O campo no existe.
ET:004 No existe assinatura de mtodo que em conformidade com os parmetros
informados.
[ET:005 ET:999] Livre para ser utilizada pela aplicao

<s:Envelope xmlns:s=http://www.w3.org/2001/06/soap-envelope
xmlns:br=http://www.w3.org/2001/06/soap-envelope>
<s:Body>
<s:Fault xmlns:br="urn:ePingFaults">
<faultcode>ET:001</faultcode>
<faultstring>Nao foi possivel converter o valor Teste' em Long!
</faultstring>
<details>
<application>SIGEPE<application>
</details>
</s:Fault>
</s:Body>
</s:Envelope>

Os erros de converso de tipo muitas vezes so difceis de serem tratados, especialmente em

algumas ferramentas que abstraem muito a implementao no sendo possvel controlar algumas
das etapas da interpretao do contedo do SOAP. Merecem especial ateno mtodos que tem
como parmetro de entrada tipos complexos como objetos que recebem valores com tipos que no
correspondem ao valor esperado. Nestes casos o mtodo que implementa o servio solicitado no
pode ser acionado pois sequer foi possvel construir o objeto a partir das informaes recebidas.
Nos casos em que esta transformao no acessvel ao implementador o tratamento de erro pode,
geralmente, ser implementado em uma camada de filtro.
Devido a complexidade do tratamento deste tipo de exceo recomenda-se que o sistema
implemente um tratamento genrico que informe a quem fez a solicitao do servio uma
mensagem informando a impossibilidade da converso. Esta resposta tem que ser devolvida na tag
fault do SOAP de resposta conforme as definies de resposta com erro. Por uma questo de
padronizao este documento prope que o contedo do campo faultcode seja definido com EPING-SOAP-Error:000 como faultstring "No foi possvel realizar a converso de tipo com os
parmetros informados" e adicionar o marcador details contendo informaes mais detalhadas do
erro.
Erros de Negcio
Os erros de negcios ocorrem quando o contedo de um determinado campo pode ser traduzido
para o formato correto do ponto de vista da tipagem na linguagem em que foi implementado, mas
no atende a seu papel na implementao. Uma campo que contm uma data anterior a data atual
para o processo de validao de tipos est correta, mas se a implementao s pode trabalhar com
datas futuras este campo foi passado incorretamente. Este um problema que tratado na
implementao e no no servidor, mas que ser tratado como erro para gerar claramente a quem
solicitou a informao que no possvel processar as informaes utilizado os parmetros
informados.
Como a possibilidade de erros relacionados a regras de negcios depender da aplicao no
possvel apresentar padres para todos os problemas no processamento das regras de negcios que
possam gerar erros. No entanto o envio de mensagens que deixem claro que ocorreu um erro no
processamento de uma regra de negcios tambm deve seguir um padro. Para alguns casos comuns
so apresentados os padres a seguir, para casos que no se encaixem no padro o usurio deve
utilizar a mensagem com o cdigo de erro EN:001, Erro no processamento dos dados do campo
<campo>, e obrigatoriamente enviar as informaes da regra que provocou o erro no campo
detalhe.
EN:001 Erro no processamento dos dados do campo <campo>
EN:002 A data <campo> tem que ser menor que a data atual
EN:003 A data <campo> tem que ser maior que a data atual
[EN:004 EN999] Livre para a aplicao

Erros de Processamento
Esta categoria de erros est relacionada a situaes imprevistas como indisponibilidade de um
recurso externo a aplicao tais como servidor de banco de dados, barramento, mainframe, etc ou
falhas relativas a limitaes originrias por permisso de acesso. A mensagem a ser repassada ao
usurio deve ser explicativa mas no apresentar detalhes que prejudiquem a segurana do sistema,
como falhas conhecidas o motivo da limitao do acesso.
EP:001 Problemas ao acessar o recurso , tente mais tarde.
EP:002 Usurio ou senha invlido.
EP:003 Permisso de acesso insuficiente para o servio.
[EP:004 EP999] Permisso de acesso insuficiente para o servio.