SOAP Intermediaries Forwarding Intermediaries Active Intermediaries

Transcription

1 SOAP Intermediaries Provide a mechanism for allowing distributed systems to easily scale in response to changes, and to provide valueadded services along the message path (like security, transactions, routing, and message persistence). Provide another mechanism for extending SOAP that is referred to as horizontal extensibility. You can add more intermediaries to the message path and extend the message path horizontally, thereby adding functionality. Forwarding Intermediaries do processing that is defined by the contents of the inbound message but do not modify the message, and then forward the message on to another node in the message path. Active Intermediaries modifies the SOAP message in ways that are not described by the contents (header blocks) of the inbound message.

2 SOAP Body Element Mandatory, and must be the first child element of the Envelope element, unless a Header element is present, in which case the Body element must follow the Header element. May contain either application-specific XML or a Fault element, but not both. The Body element is just a wrapper for the XML document that we want to exchange. The Fault element is used only when an error occurs. The ultimate SOAP receiver must be able to process the application-specific XML of the Body, otherwise it should generate a SOAP Fault. Unlike header blocks, the Body contents are intended only for the ultimate receiver, and thus should not be modified by intermediaries (but can be read by intermediaries).

3 SOAP Body Element, cont. <soap:envelope xmlns:soap=" <soap:body> <shp:trackingrequest xmlns:shp= > <shp:trackingnum>1z </shp:trackingnum> </shp:trackingrequest> </soap:body> </soap:envelope>

4 SOAP Fault Element A standard mechanism for handling errors. Analogous to the java.lang.exception. Receivers generate a Fault element when an error occurs, place it inside the Body element, and send the SOAP message back to the previous sender in the path. A receiver is only required to send a Fault upstream to a sender if the MEP being used is Request/Response. If a one-way MEP is being used, then the receiver must generate a Fault, but is not required to attempt to send the Fault to the sender. When the Fault element is used, the Body element must contain only the Fault as a single child element and no others. The presence of the Fault element indicates to a SOAP node that an error has occurred. A SOAP message containing a Fault element is called a fault message.

5 SOAP Fault Element, cont. The Fault element may contain the following elements to describe what the error was: Code (mandatory) Used to classify the SOAP Fault. Reason (mandatory) Contains one or more humanreadable explanations of the Fault. Node (optional) Used to provide information about which SOAP node on the message path generated the Fault. Role (optional) Used to identify the role the node was acting in when it generated the Fault. Detail (optional) Used to carry additional applicationspecific information (typically machine-readable) about the error, which is related to the fault code.

6 SOAP Fault Element, cont. <soap:envelope xmlns:soap=" " xmlns:xml=" " xmlns:shp=" "> <soap:body> <soap:fault> <soap:code> <soap:value>soap:sender</soap:value> <soap:subcode><soap:value>shp:invalidtrackingrequest</soap:value> </soap:subcode> </soap:code> <soap:reason> <soap:text xml:lang="en">tracking num incorrect format</soap:text> </soap:reason> <soap:detail> <shp:trackingnumsubmitted> </shp:trackingnumsubmitted> <shp:validtrackingnumformats> <shp:trackingnumformat>1z ### ### ## #### ### # </shp:trackingnumformat> </shp:validtrackingnumformats> </soap:detail> </soap:fault> </soap:body> </soap:envelope>

7 SOAP Code Element Used to classify faults, and to provide a context for the Detail element. Must contain a single mandatory child element called Value, which is restricted to containing one of the following set of XML QNames: soap:versionmismatch Indicates that the version of the SOAP message was different than the receiver expected. soap:mustunderstand Indicates that the receiver did not understand a mandatory header block. soap:dataencodingunknown Indicates that the receiver did not understand the data encoding of the SOAP message. soap:sender Indicates that something in the SOAP message was erroneous, but can possibly be corrected and resent. soap:receiver Indicates that the receiver encountered an error that was not related to the SOAP message. The Code element may also contain a single optional Subcode element as the second child element, which can provide further detail about what went wrong.

8 SOAP Code Element, cont. <soap:envelope xmlns:soap= xmlns:shp= > <soap:body> <soap:fault> <soap:code> <soap:value>soap:sender</soap:value> <soap:subcode> <soap:value>shp:invalidtrackingrequest</soap:value> </soap:subcode> </soap:code> <soap:reason> </soap:reason> <soap:detail> </soap:detail> </soap:fault> </soap:body> </soap:envelope>

9 SOAP Upgrade Header Block A standard mechanism for indicating which versions of SOAP a node supports when that node generates a Fault with the VersionMismatch code. Can only contain one or more SupportedEnvelope child elements. The SupportedEnvelope child element must contain an attribute with the name of qname, which is used to identify the XML QName of the SOAP namespace that the node supports. The SupportedEnvelope child elements should be ordered from the most preferred SOAP version to the least preferred.

10 SOAP Upgrade Header Block <soap:envelope xmlns:soap= xmlns:shp=" <soap:body> <soap:header> <soap:upgrade> <soap:supportedenvelope qname= s12:envelope xmlns:s12= /> <soap:supportedenvelope qname= s11:envelope xmlns:s11= /> </soap:upgrade> </soap:header> <soap:fault> <soap:code> <soap:value>soap:versionmismatch</soap:value> <soap:subcode><soap:value> </soap:value></soap:subcode> </soap:code> <soap:reason><soap:text> </soap:text></soap:reason> </soap:fault> </soap:body> </soap:envelope>

11 SOAP NotUnderstood Header Block A standard mechanism for indicating which mandatory header block was not understood when a node generates a Fault with the MustUnderstand code. Must contain an attribute called qname that contains the XML QName of the header block that wasn t understood. The SOAP receiver should include a NotUnderstood header block for each header block in the inbound message it did not understand.

12 SOAP NotUnderstood Header Block <soap:envelope xmlns:soap=" <soap:body> <soap:header> <soap:notunderstood qname= trns:transactions xmlns:trns= /> </soap:header> <soap:fault> <soap:code> <soap:value>soap:mustunderstand</soap:value> </soap:code> <soap:reason> <soap:text>header not understood</soap:text> </soap:reason> </soap:fault> </soap:body> </soap:envelope>

13 Example Use of Node and Role Elements <soap:envelope xmlns:soap=" xmlns:xml=" xmlns:shp=" <soap:body> <soap:fault> <soap:code> <soap:value>soap:receiver</soap:value> </soap:code> <soap:reason> <soap:text xml:lang= en > Unable to connect to the database </soap:text> </soap:reason> <soap:node> <soap:role> </soap:role> </soap:fault> </soap:body> </soap:envelope>