05 - SOAP Envelope

The Envelope is the root element for SOAP messages, it contains two child elements, an optional Header element and a mandatory Body element, both elements contains application defined information.

The SOAP envelope element has:

  • A local name for the Envelope element
  • A namespace definition of http://www.w3.org/2003/05/soap-envelope
  • Many optional namespace-qualified attributes
  • An optional Header element
  • A mandatory Body element.

The Envelope element is used for indicating when a message starts and when it ends, and it is mandatory as part of the SOAP message structure.

The following is a sample of a SOAP Envelope:

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

SOAP Header

The Header element is optional and provides mechanism for extending SOAP messages in a decentralized and modular way it contains header information related to how the message should be processed.

The SOAP header element has:

  • A local name for the Header element
  • A namespace definition of http://www.w3.org/2003/05/soap-envelope
  • Zero or many optional namespace-qualified attributes
  • Zero or many optional namespace-qualified elements defining header blocks.

SOAP Header Block

The SOAP header block represents a logical grouping of data.

 The SOAP header block has the following items:

  • A mandatory namespace name property with a value.
  • Zero or many optional character items.
  • Zero or many optional elements items, which may be namespace-qualified.
  • Zero or many optional of the following attributes:
    • encodyngStyle: indicates which encoding rules are used to serialize SOAP messages.
    • role: indicates the SOAP node to which a particular header block is targeted.
    • mustUnderstand: indicates if the processing of a particular header block is mandatory or not.
    • relay: indicates if the header block must be relayed if not processed by the SOAP receiver.

The following is a sample of a SOAP Header:

<env:Header>
    <n:alert xmlns:n = "http://yoursite.com/alerts">
        <n:priority>High</n:priority>
        <n:endDate>2001-06-22T14:00:00-05:00</n:endDate>
    </n:alert>
</env:Header>

SOAP Body

The SOAP Body is one of the mandatory elements in the SOAP Envelope element. It contains application specific XML data to be exchanged in the SOAP message. As mentioned before, it has to be contained within a SOAP envelope and it must follow any header defined in the message, if any header exists in the SOAP Envelope.

The SOAP Body element has:

All child elements of a Body element should have:

  • An optional namespace name property with a value.
  • Zero or many optional character items.
  • Zero or many optional elements items, which may be namespace-qualified.
  • Zero or many optional of the following attributes:
    • encodyngStyle: indicates which encoding rules are used to serialize SOAP messages.
    • role: indicates the SOAP node to which a particular header block is targeted.
    • mustUnderstand: indicates if the processing of a particular header block is mandatory or not.
    • relay: indicates if the header block must be relayed if not processed by the SOAP receiver.

The following is a sample of a SOAP Body:

<env:Body>
    <m:alert xmlns:m="http://yoursite.com/alert">
        <m:message>Do not foget to pick up your son</m:message>
    </m:alert>
</env:Body>

SOAP Fault

As part of the SOAP definition, there is a particular child element for the Body element used for reporting errors: the SOAP Fault element. This element is used for describing error information inside a SOAP message.

The SOAP Fault element has:

  • A local name for the Body element
  • A namespace definition of http://www.w3.org/2003/05/soap-envelope
  • A mandatory Code element
  • A mandatory Reason element
  • An optional Node element
  • An optional Role element
  • An optional Detail element

SOAP Code element

The Code element has:

SOAP Value element

The Value element has:

The value of the Value element should be one of the followings:

  • VersionMismatch: when a node has found an invalid element instead of the expected within the Envelope of the SOAP message. The namespace or the local name did not match the Envelope required by the WSDL recommendation.
  • MustUnderstand: when a child of the SOAP Header was not understood by a node and the mustUnderstand attribute is set to true in the SOAP message
  • DataEncodingUnknown: The SOAP message has a SOAP Header Block or a SOAP body child element that is scoped with an encoding that is not supported.
  • Sender: The SOAP message is incorrectly formed or it does not contain the correct information.
  • Receiver: The SOAP message could not be processed because of problems at the SOAP receiver and not because of any issue with the message itself.

SOAP Reason element

The Reason element is used for providing a human-readable explanation.

The Reason element has:

SOAP Text element

The Text element is used for actually providing the human-readable explanation of a fault.

The Text element has:

SOAP Node element

The Node element is intended to provide the information of which SOAP node caused the fault

The Node element has:

SOAP Role element

The Role element identifies the role of the SOAP node that is was operating when the fault occurred.

The Role element has:

SOAP Detail element

The Detail element is used for describing application specific error information

The Detail element has:

SOAP Detail Entry

The Detail Entry element is used for providing application specific information.

The Detail Entry has:

  • An optional namespace name property with a value.
  • Zero or many optional child elements.
  • Zero or many optional character items.
  • Zero or many optional attribute.

The following is an example of a Fault element:

<env:Body>
    <env:Fault>
        <env:Code>
            <env:Value>env:Sender</env:Value>
            <env:Subcode>
                <env:Value>m:MessageTimeout</env:Value>
            </env:Subcode>
        </env:Code>
        <env:Reason>
            <env:Text xml:lang = "en">Message Timeout at the Sender</env:Text>
        </env:Reason>
        <env:Detail>
            <m:MaxTime>60</m:MaxTime>
        </env:Detail>    
    </env:Fault>
</env:Body>


  

Like us on Facebook

Wideskills