Сценарии обработки сообщений об ошибках

SOAP предоставляет модель обработки ситуаций, когда при обработке сообщения возникает ошибка. SOAP отдельно рассматривает условия, при которых ошибка возникла, и возможность указания на факт возникновения ошибки узлу, сгенерировавшему ошибку, либо любому другому узлу. Возможность указания на факт возникновения ошибки зависит от используемого механизма передачи сообщений, и одним из аспектов спецификации привязки SOAP к нижележащему протоколу является определение механизма оповещения об ошибках в случае их возникновения. В дальнейшей части этого раздела предполагается, что определенный механизм передачи сообщений уже используется для оповещения о возникающих ошибках во время обработки полученных сообщений, и дальнейшее внимание сосредотачивается на структуре SOAP-сообщения об ошибке.

SOAP-элемент env:Bodyимеет также еще одну характерную роль - он может содержать информацию об ошибке. Модель обработки ошибок SOAP (см.SOAP Часть 1 Раздел 2.6) требует, чтобы все специфичные для SOAP и приложений ошибки были описаны с использованиемединственногоспециального элементаenv:Fault, содержащегося в элементеenv:Body. Элементenv:Faultсодержит два обязательных субэлемента,env:Codeиenv:Reason, и (необязательно) специфичную для приложения информацию в субэлементеenv:Detail. Другой необязательный субэлементenv:Nodeпосредством URI определяет SOAP-узел, сгенерировавший ошибку. Отсутствие этого субэлемента означает, что ошибка была сгенерирована конечным получателем сообщения. Существует также еще один необязательный субэлемент,env:Role, определяющий роль, исполняемую сгенерировавшим ошибку узлом.

Субэлемент env:Codeэлементаenv:Faultсам по себе подобен обязательному субэлементуenv:Value, назначение которого определено в спецификации SOAP (см.SOAP Часть 1 Раздел 5.4.6), также как и назначение необязательного субэлементаenv:Subcode.

Пример 6aдемонстрирует SOAP-сообщение, присланное в ответ на RPCпримера 4, и указывающее на неудачное завершение обработки RPC.

Пример 6a

<?xml version='1.0' ?>

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"

xmlns:rpc='http://www.w3.org/2003/05/soap-rpc'>

<env:Body>

<env:Fault>

<env:Code>

<env:Value>env:Sender</env:Value>

<env:Subcode>

<env:Value>rpc:BadArguments</env:Value>

</env:Subcode>

</env:Code>

<env:Reason>

<env:Text xml:lang="en-US">Processing error</env:Text>

<env:Text xml:lang="cs">Chyba zpracovбnн</env:Text>

</env:Reason>

<env:Detail>

<e:myFaultDetails

xmlns:e="http://travelcompany.example.org/faults">

<e:message>Name does not match card number</e:message>

<e:errorcode>999</e:errorcode>

</e:myFaultDetails>

</env:Detail>

</env:Fault>

</env:Body>

</env:Envelope>

Пример SOAP-сообщения, указывающего на неудачное завершение обработки RPC примера 4

В примере 6aвысокоуровневый элементenv:Valueиспользует стандартизованное XML Qualified Name (принадлежащее типуxs:QName) для того, чтобы определить, что оно является ошибкойenv:Sender, указывающей на то, что ошибка является синтаксической либо сообщение содержит некорректную информацию. (Когда ошибкаenv:Senderполучена отправителем, предполагается, что будет сделано некоторое корректирующее действие, прежде чем аналогичное сообщение будет отправлено снова). Элементenv:Subcodeне является обязательным, но если он присутствует, как в приведенном примере, он уточняет родительское значение. Впримере 6a, элементenv:Subcodeуказывает на то, что специфичная ошибка RPC,rpc:BadArguments, определенная вSOAP Часть 2 Раздел 4.4, является причиной неудачного завершения обработки запроса.

Структура элемента env:Subcodeбыла создана иерархической - каждый дочерний элементenv:Subcodeимеет обязательный субэлементenv:Valueи необязательный субэлементenv:Subcode- для передачи кода, специфичного для конкретного приложения. Эта иерархическая структура элементаenv:Codeреализует единый механизм передачи кодов ошибок нескольких уровней. Высокоуровневый элементenv:Value- основная ошибка, описанная в спецификациях SOAP Версия 1.2 (см.SOAP Часть 1 Раздел 5.4.6), она должна быть понятна всем SOAP-узлам. Вложенный элементenv:Valueявляется специфичным для конкретного приложения и представляет собой дальнейшее развитие и улучшение описания вышеупомянутой основной ошибки с точки зрения приложения. Некоторые из этих значений могут быть хорошо стандартизованы SOAP (например коды RPC, стандартизованные в SOAP 1.2 (см.SOAP Часть 2 Раздел 4.4)) или в некоторых других стандартах, использующих SOAP в качестве инкапсулирующего протокола. Единственным требованием для определения подобных специфичных для приложения значений субкодов является их соответствие пространству имен при использовании любого пространства имен отличного от пространства имен SOAPenv, определяющего основную классификацию SOAP-ошибок. Со стороны SOAP не существует требований о том, что приложения должны понимать или хотя бы просматривать все уровни значений субкодов.

Субэлемент env:Reasonне важен для алгоритмической обработки. Он нужен скорее для лучшего понимания ситуации человеком, и хотя это обязательный элемент, его возможные значения не нуждаются в стандартизации. Все, что необходимо - достаточно точно описать ситуацию, в которой возникла ошибка. Субэлементenv:Text, иметь один или несколько субэлементовxml:langпозволяющий приложениям выдавать сообщения о причинах ошибки на различных языках. (Приложения могут согласовывать конкретный язык текста ошибки посредством встроенного механизма, использующего SOAP-заголовки, однако это находится вне рассмотрения спецификации SOAP.)

Отсутствие субэлемента env:Nodeвнутриenv:Faultвпримере 6aговорит о том, что сообщение было создано конечным получателем вызова. Содержимоеenv:Detail, как показано в примере, специфично для конкретного приложения.

Ошибка может быть также сгенерирована во время обработки SOAP-сообщения, если обязательный заголовочный элемент не был понят, либо информация, содержащаяся в нем, не может быть обработана. Ошибки в ходе обработки заголовочного блока могут быть также показаны с использованием элемента env:Faultвнутри элементаenv:Body, но со специальным заголовочным блоком -env:NotUnderstood, который идентифицирует вызывающий ошибку заголовочный блок.

Пример 6bдемонстрирует пример отклика на RPCпримера 4, показывающий неудачное завершение обработки заголовочного блокаt:transaction. Необходимо отметить присутствие кода ошибкиenv:MustUnderstandвenv:Body, а также идентификацию заголовка, который не был понят с помощью (неприспособленного для этого) атрибутаqnameв специальном (пустом) заголовочном блокеenv:NotUnderstood.

Пример 6b

<?xml version='1.0' ?>

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope>

<env:Header>

<env:NotUnderstood qname="t:transaction"

xmlns:t="http://thirdparty.example.org/transaction"/>

</env:Header>

<env:Body>

<env:Fault>

<env:Code>

<env:Value>env:MustUnderstand</env:Value>

</env:Code>

<env:Reason>

<env:Text xml:lang="en-US">Header not understood</env:Text>

<env:Text xml:lang="fr">En-tкte non compris</env:Text>

</env:Reason>

</env:Fault>

</env:Body>

</env:Envelope>

Пример SOAP-сообщения, показывающего неудачное завершение обработки заголовочного блока примера 4

Если не были поняты несколько обязательных заголовочных блоков, тогда каждый из них может быть определен своим атрибутом qnameв сериях таких заголовочных блоковenv:NotUnderstood.