Movatterモバイル変換

Status of this Document

This section describes the status of this document at the time of itspublication. Other documents may supersede this document. The latest statusof this document series is maintained at the W3C.

This document is aRecommendation of the W3C. This document has been produced by theXML Protocol Working Group, which is part of theWeb Services Activity. It has been reviewed by W3C Members and otherinterested parties, and has been endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as referencematerial or cited as a normative reference from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionalityand interoperability of the Web.

Comments on this document are welcome. Please send them tothe public mailing-listxmlp-comments@w3.org (archive). It is inappropriate to send discussion email to this address.

Information about implementations relevant to this specification canbe found in the Implementation Report athttp://www.w3.org/2000/xp/Group/2/03/soap1.2implementation.html.

Patent disclosures relevant to this specification may be found on the Working Group'spatent disclosure page, in conformance with W3C policy.

A list of currentW3C Recommendations and other technical reports can be found at http://www.w3.org/TR.

1. Introduction

SOAP Version 1.2 Part 0: Primer is a non-normative document intended toprovide an easily understandable tutorial on the features of the SOAP Version1.2 specifications. Its purpose is to help a technically competent personunderstand how SOAP may be used, by describing representative SOAP messagestructures and message exchange patterns.

It is expected that the reader has some familiarity with the basic syntaxof XML, including the use of XML namespaces and infosets, and Web conceptssuch as URIs and HTTP. It is intended primarily for users of SOAP, such asapplication designers, rather than implementors of the SOAP specifications,although the latter may derive some benefit. This primer aims at highlightingthe essential features of SOAP Version 1.2, not at completeness in describingevery nuance or edge case. Therefore, there is no substitute for the mainspecifications to obtain a fuller understanding of SOAP. To that end, thisprimer provides extensive links to the main specifications wherever newconcepts are introduced or used.

[SOAP Part1] defines the SOAP envelope, which is aconstruct that defines an overall framework for representing the contents ofa SOAP message, identifying who should deal with all or part of it, andwhether handling such parts are optional or mandatory. It also defines aprotocol binding framework, which describes how the specification for abinding of SOAP onto another underlying protocol may be written.

[SOAP Part2] defines a data model for SOAP, aparticular encoding scheme for data types which may be used for conveyingremote procedure calls (RPC), as well as one concrete realization of theunderlying protocol binding framework defined in[SOAPPart1]. This binding allows the exchange of SOAP messages either aspayload of a HTTP POST request and response, or as a SOAP message in theresponse to a HTTP GET.

This document (the primer) is not normative, which means that it does notprovide the definitive specification of SOAP Version 1.2. The examplesprovided here are intended to complement the formal specifications, and inany question of interpretation the formal specifications naturally takeprecedence. The examples shown here provide a subset of the uses expected forSOAP. In actual usage scenarios, SOAP will most likely be a part of anoverall solution, and there will no doubt be other application-specificrequirements which are not captured in these examples.

1.1 Overview

SOAP Version 1.2 provides the definition of the XML-based informationwhich can be used for exchanging structured and typed information betweenpeers in a decentralized, distributed environment.[SOAPPart1] explains that a SOAP message is formally specified as an XMLInfoset [XML Infoset], which provides an abstractdescription of its contents. Infosets can have different on-the-wirerepresentations, one common example of which is as an XML 1.0 [XML 1.0] document.

SOAP is fundamentally a stateless, one-way message exchange paradigm, butapplications can create more complex interaction patterns (e.g.,request/response, request/multiple responses, etc.) by combining such one-wayexchanges with features provided by an underlying protocol and/orapplication-specific information. SOAP is silent on the semantics of anyapplication-specific data it conveys, as it is on issues such as the routingof SOAP messages, reliable data transfer, firewall traversal, etc. However,SOAP provides the framework by which application-specific information may beconveyed in an extensible manner. Also, SOAP provides a full description ofthe required actions taken by a SOAP node on receiving a SOAP message.

Section 2 of this document provides an introductionto the basic features of SOAP starting with the simplest usage scenarios,namely a one-way SOAP message, followed by various request-response typeexchanges, including RPCs. Fault situations are also described.

Section 3 provides an overview of the SOAP processingmodel, which describes the rules for initial construction of a message, rulesby which messages are processed when received at an intermediary or ultimatedestination, and rules by which portions of the message can be inserted,deleted or modified by the actions of an intermediary.

Section 4 of this document describes the ways inwhich SOAP messages may be transported to realize various usage scenarios. Itdescribes the SOAP HTTP binding specified in[SOAPPart2], as well as an example of how SOAP messages may be conveyed inemail messages. As a part of the HTTP binding, it introduces two messageexchange patterns which are available to an application, one of which usesthe HTTP POST method, while the other uses HTTP GET. Examples are alsoprovided on how RPCs, in particular those that represent "safe" informationretrieval, may be represented in SOAP message exchanges in a manner that iscompatible with the architectural principles of the World Wide Web .

Section 5 of this document provides a treatment ofvarious aspects of SOAP that can be used in more complex usage scenarios.These include the extensibility mechanism offered through the use of headerelements, which may be targeted at specific intermediate SOAP nodes toprovide value-added services to communicating applications, and using variousencoding schemes to serialize application-specific data in SOAP messages.

For ease of reference, terms and concepts used in this primer arehyper-linked to their definition in the main specifications.

1.2 Notational Conventions

Throughout this primer, sample SOAP envelopes and messages are shown as[XML 1.0] documents.[SOAP Part1]explains that a SOAP message is formally specified as an [XMLInfoSet], which is an abstract description of its contents. Thedistinction between the SOAP XML Infosets and the documents is unlikely tobe of interest to those using this primer as an introduction to SOAP; thosewho do care (typically those who port SOAP to new protocol bindings where themessages may have alternative representations) should understand theseexamples as referring to the corresponding XML infosets. Further elaborationof this point is provided inSection 4 of thisdocument.

The namespace prefixes "xs" and "xsi" used in the prose sections of thisdocument are associated with the namespace names"http://www.w3.org/2001/XMLSchema" and"http://www.w3.org/2001/XMLSchema-instance" respectively, both of which aredefined in the XML Schema specifications[XML SchemaPart1],[XML Schema Part2].

Note that the choice of any other namespace prefix is arbitrary and notsemantically significant.

Namespace URIs of the general form "http://example.org/..." and"http://example.com/..." represent an application-dependent orcontext-dependent URI[RFC 2396].

2. Basic Usage Scenarios

ASOAP message is fundamentally a one-way transmission between SOAPnodes, from aSOAP sender to aSOAP receiver, but SOAP messages are expected to be combined byapplications to implement more complex interaction patterns ranging fromrequest/response to multiple, back-and-forth "conversational" exchanges.

The primer starts by exposing the structure of a SOAP message and itsexchange in some simple usage scenarios based on a travel reservationapplication. Various aspects of this application scenario will be usedthroughout the primer. In this scenario, the travel reservation applicationfor an employee of a company negotiates a travel reservation with a travelbooking service for a planned trip. The information exchanged between thetravel reservation application and the travel service application is in theform of SOAP messages.

The ultimate recipient of a SOAP message sent from the travel reservationapplication is the travel service application, but it is possible that theSOAP message may be "routed" through one or moreSOAP intermediaries which act in some way on the message. Some simpleexamples of such SOAP intermediaries might be ones that log, audit or,possibly, amend each travel request. Examples, and a more detailed discussionof the behavior and role of SOAP intermediaries, is postponed tosection 5.1.

Section 2.1 describes a travel reservation requestexpressed as a SOAP message, which offers the opportunity to describe thevarious "parts" of a SOAP message.

Section 2.2.1 continues the same scenario to show aresponse from the travel service in the form of another SOAP message, whichforms a part of a conversational message exchange as the various choicesmeeting the constraints of the travel request are negotiated.

Section 2.2.2 assumes that the various parameters ofthe travel reservation have been accepted by the traveller, and an exchange -modelled as a remote procedure call (RPC) - between the travel reservationand the travel service applications confirms the payment for thereservation.

2.1 SOAP Messages

Example 1

<?xml version='1.0' ?><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">  <env:Header>  <m:reservation xmlns:m="http://travelcompany.example.org/reservation"           env:role="http://www.w3.org/2003/05/soap-envelope/role/next"           env:mustUnderstand="true">   <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference>   <m:dateAndTime>2001-11-29T13:20:00.000-05:00</m:dateAndTime>  </m:reservation>  <n:passenger xmlns:n="http://mycompany.example.com/employees"          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"           env:mustUnderstand="true">   <n:name>Åke Jógvan Øyvind</n:name>  </n:passenger> </env:Header> <env:Body>  <p:itinerary    xmlns:p="http://travelcompany.example.org/reservation/travel">   <p:departure>     <p:departing>New York</p:departing>     <p:arriving>Los Angeles</p:arriving>     <p:departureDate>2001-12-14</p:departureDate>     <p:departureTime>late afternoon</p:departureTime>     <p:seatPreference>aisle</p:seatPreference>   </p:departure>   <p:return>     <p:departing>Los Angeles</p:departing>     <p:arriving>New York</p:arriving>     <p:departureDate>2001-12-20</p:departureDate>     <p:departureTime>mid-morning</p:departureTime>     <p:seatPreference/>   </p:return>  </p:itinerary>  <q:lodging   xmlns:q="http://travelcompany.example.org/reservation/hotels">   <q:preference>none</q:preference>  </q:lodging> </env:Body></env:Envelope>

Sample SOAP message for a travel reservation containing header blocks and abody

The SOAP message inExample 1 contains twoSOAP-specific sub-elements within the overallenv:Envelope,namely anenv:Headerand anenv:Body.The contents of these elements are application defined and not a part of theSOAP specifications, although the latter do have something to say about howsuch elements must be handled.

ASOAP header element is optional, but it has been included in the exampleto explain certain features of SOAP. A SOAP header is an extension mechanismthat provides a way to pass information in SOAP messages that is notapplication payload. Such "control" information includes, for example,passing directives or contextual information related to the processing of themessage. This allows a SOAP message to be extended in an application-specificmanner. The immediate child elements of theenv:Header elementare calledheader blocks, and represent a logical grouping of data which, as shownlater, can individually be targeted at SOAP nodes that might be encounteredin the path of a message from a sender to an ultimate receiver.

SOAP headers have been designed in anticipation of various uses for SOAP,many of which will involve the participation of other SOAP processing nodes -calledSOAP intermediaries - along a message's path from aninitialSOAP sender to anultimateSOAP receiver. This allows SOAP intermediaries to provide value-addedservices. Headers, as shown later, may be inspected, inserted, deleted orforwarded by SOAP nodes encountered along aSOAPmessage path. (It should be kept in mind, though, that the SOAPspecifications do not deal with what the contents of header elements are, orhow SOAP messages are routed between nodes, or the manner by which the routeis determined and so forth. These are a part of the overall application, andcould be the subject of other specifications.)

TheSOAP body is the mandatory element within the SOAPenv:Envelope,which implies that this is where the main end-to-end information conveyed ina SOAP message must be carried.

InExample 1, the header contains two headerblocks, each of which is defined in its own XML namespace and which representsome aspect pertaining to the overall processing of the body of the SOAPmessage. For this travel reservation application, such "meta" informationpertaining to the overall request is areservation header blockwhich provides a reference and time stamp for this instance of a reservation,and the traveller's identity in thepassenger block.

The header blocksreservation andpassenger mustbe processed by the next SOAP intermediary encountered in the message pathor, if there is no intermediary, by the ultimate recipient of the message.The fact that it is targeted at the next SOAP node encounteredenroute is indicated by the presence of the attributeenv:rolewith the value "http://www.w3.org/2003/05/soap-envelope/role/next" (hereaftersimply "next"), which is a rolethat all SOAP nodes must be willing to play. The presence of anenv:mustUnderstand attribute with value "true" indicates thatthe node(s) processing the header must absolutely process these header blocksin a manner consistent with their specifications, or else not process themessage at all and throw a fault. Note that whenever a header block isprocessed, either because it is markedenv:mustUnderstand="true"or for another reason, the block must be processed in accordance with thespecifications for that block. Such header block specifications areapplication defined and not a part of SOAP.Section 3will elaborate further on SOAP message processing based on the values ofthese attributes.

The choice of what data is placed in a header block and what goes in theSOAP body are decisions taken at the time of application design. The mainpoint to keep in mind is that header blocks may be targeted at various nodesthat might be encountered along a message's path from a sender to theultimate recipient. Such intermediate SOAP nodes may provide value-addedservices based on data in such headers. InExample 1,the passenger data is placed in a header block to illustrate the use of thisdata at a SOAP intermediary to do some additional processing. For example, asshown later insection 5.1, the outbound message isaltered by the SOAP intermediary by having the travel policies pertaining tothis passenger appended to the message as another header block.

Theenv:Bodyelement and its associated child elements,itinerary andlodging, are intended for exchange of information between theinitial SOAP sender and the SOAP node which assumes the role of theultimate SOAP receiver in the message path, which is the travel serviceapplication. Therefore, theenv:Body and its contents areimplicitly targeted and are expected to be understood by the ultimatereceiver. The means by which a SOAP node assumes such a role is not definedby the SOAP specification, and is determined as a part of the overallapplication semantics and associated message flow.

Note that a SOAP intermediary may decide to play the role of the ultimateSOAP receiver for a given message transfer, and thus process theenv:Body. However, even though this sort of a behavior cannot beprevented, it is not something that should be done lightly as it may pervertthe intentions of the message's sender, and have undesirable side effects(such as not processing header blocks that might be targeted atintermediaries further along the message path).

A SOAP message such as that inExample 1 may betransferred by different underlying protocols and used in a variety of messageexchange patterns. For example, for a Web-based access to a travelservice application, it could be placed in the body of a HTTP POST request.In another protocol binding, it might be sent in an email message (seesection 4.2). Section 4 willdescribe how SOAP messages may be conveyed by a variety of underlyingprotocols. For the time being, it is assumed that a mechanism exists formessage transfer and the remainder of this section concentrates on thedetails of the SOAP messages and their processing.

2.2 SOAP Message Exchange

SOAP Version 1.2 is a simple messaging framework for transferringinformation specified in the form of an XML infoset between an initial SOAPsender and an ultimate SOAP receiver. The more interesting scenariostypically involve multiple message exchanges between these two nodes. Thesimplest such exchange is a request-response pattern. Some early uses of [SOAP 1.1] emphasized the use of this pattern as means forconveying remote procedure calls (RPC), but it is important to note that notall SOAP request-response exchanges can or need to be modelled as RPCs. Thelatter is used when there is a need to model a certain programmatic behavior,with the exchanged messages conforming to a pre-defined description of theremote call and its return.

A much larger set of usage scenarios than that covered by therequest-response pattern can be modeled simply as XML-based content exchangedin SOAP messages to form a back-and-forth "conversation", where the semanticsare at the level of the sending and receiving applications.Section 2.2.1 covers the case of XML-based content exchangedin SOAP messages between the travel reservation application and the travelservice application in a conversational pattern, whilesection 2.2.2 provides an example of an exchange modeled asan RPC.

2.2.1 Conversational Message Exchanges

Continuing with the travel request scenario,Example2 shows a SOAP message returned from the travel service in response tothe reservation request message inExample 1. Thisresponse seeks to refine some information in the request, namely the choiceof airports in the departing city.

Example 2

<?xml version='1.0' ?><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">  <env:Header>  <m:reservation xmlns:m="http://travelcompany.example.org/reservation"       env:role="http://www.w3.org/2003/05/soap-envelope/role/next"           env:mustUnderstand="true">   <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference>   <m:dateAndTime>2001-11-29T13:35:00.000-05:00</m:dateAndTime>  </m:reservation>  <n:passenger xmlns:n="http://mycompany.example.com/employees"      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"           env:mustUnderstand="true">   <n:name>Åke Jógvan Øyvind</n:name>  </n:passenger> </env:Header> <env:Body>  <p:itineraryClarification     xmlns:p="http://travelcompany.example.org/reservation/travel">   <p:departure>     <p:departing>       <p:airportChoices>          JFK LGA EWR        </p:airportChoices>     </p:departing>   </p:departure>   <p:return>     <p:arriving>       <p:airportChoices>         JFK LGA EWR        </p:airportChoices>     </p:arriving>   </p:return>    </p:itineraryClarification> </env:Body></env:Envelope>

SOAP message sent in response to the message inExample1

As described earlier, theenv:Body contains the primarycontent of the message, which in this example includes a list of the variousalternatives for the airport, conforming to a schema definition in the XMLnamespace http://travelcompany.example.org/reservation/travel. In thisexample, the header blocks fromExample 1 are returned(with some sub-element values altered) in the response. This could allowmessage correlation at the SOAP level, but such headers are very likely toalso have other application-specific uses.

The message exchange in Examples 1 and 2 are cases where XML-based contentconforming to some application-defined schema are exchanged via SOAPmessages. Once again, a discussion of the means by which such messages aretransferred is deferred tosection 4.

It is easy enough to see how such exchanges can build up to a multipleback-and-forth "conversational" message exchange pattern.Example 3 shows a SOAP message sent by the travelreservation application in response to that inExample2 choosing one from the list of available airports. The header blockreservation with the same value of thereferencesub-element accompanies each message in this conversation, thereby offering away, should it be needed, to correlate the messages exchanged between them atthe application level.

Example 3

<?xml version='1.0' ?><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">  <env:Header>  <m:reservation      xmlns:m="http://travelcompany.example.org/reservation"       env:role="http://www.w3.org/2003/05/soap-envelope/role/next"           env:mustUnderstand="true">    <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference>    <m:dateAndTime>2001-11-29T13:36:50.000-05:00</m:dateAndTime>  </m:reservation>  <n:passenger xmlns:n="http://mycompany.example.com/employees"      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"           env:mustUnderstand="true">   <n:name>Åke Jógvan Øyvind</n:name>  </n:passenger> </env:Header> <env:Body>  <p:itinerary    xmlns:p="http://travelcompany.example.org/reservation/travel">   <p:departure>     <p:departing>LGA</p:departing>   </p:departure>   <p:return>     <p:arriving>EWR</p:arriving>   </p:return>  </p:itinerary> </env:Body></env:Envelope>

Response to the message inExample 2 continuing aconversational message exchange

2.2.2 Remote Procedure Calls

One of the design goals of SOAP Version 1.2 is to encapsulate remoteprocedure call functionality using the extensibility and flexibility of XML.SOAP Part 2 section 4 has defined a uniform representation for RPCinvocations and responses carried in SOAP messages. This section continueswith the travel reservation scenario to illustrate the use of SOAP messagesto convey remote procedure calls and their return.

To that end, the next example shows the payment for the trip using acredit card. (It is assumed that the conversational exchanges described insection 2.2.1 have resulted in a confirmed itinerary.) Here,it is further assumed that the payment happens in the context of an overalltransaction where the credit card is charged only when the travel and thelodging (not shown in any example, but presumably reserved in a similarmanner) are both confirmed. The travel reservation application providescredit card information and the successful completion of the differentactivities results in the card being charged and a reservation code returned.This reserve-and-charge interaction between the travel reservationapplication and the travel service application is modeled as a SOAP RPC.

Such information may be expressed by a variety of means, including formalInterface Definition Languages (IDL). Note that SOAP does not provide anyIDL, formal or informal. Note also that the above information differs insubtle ways from information generally needed to invoke other, non-SOAPRPCs.

RegardingItem 1 above, there is, from a SOAPperspective, a SOAP node which "contains" or "supports" the target of theRPC. It is the SOAP node which (appropriately) adopts the role of theultimate SOAP receiver. As required byItem 1,the ultimate recipient can identify the target of the named procedure ormethod by looking for its URI. The manner in which the target URI is madeavailable depends on the underlying protocol binding. One possibility is thatthe URI identifying the target is carried in a SOAP header block. Someprotocol bindings, such as the SOAP HTTP binding defined in [SOAP Part2], offer a mechanism for carrying the URI outsidethe SOAP message. In general, one of the properties of a protocol bindingspecification must be a description of how the target URI is carried as apart of the binding.Section 4.1 provides some concreteexamples of how the URI is carried in the case of the standardized SOAPprotocol binding to HTTP.

Item 4 andItem 5 above arerequired to ensure that RPC applications that employ SOAP can do so in amanner which is compatible with the architectural principles of the WorldWide Web.Section 4.1.3 discusses how the informationprovided by items 4 and 5 are utilized.

For the remainder of this section, it is assumed that the RPC conveyed ina SOAP message as shown inExample 4 is appropriatelytargeted and dispatched. The purpose of this section is to highlight thesyntactical aspects of RPC requests and returns carried within a SOAPmessage.

Example 4

<?xml version='1.0' ?><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" > <env:Header>   <t:transaction           xmlns:t="http://thirdparty.example.org/transaction"           env:encodingStyle="http://example.com/encoding"           env:mustUnderstand="true" >5</t:transaction> </env:Header>   <env:Body>  <m:chargeReservation      env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"         xmlns:m="http://travelcompany.example.org/">   <m:reservation xmlns:m="http://travelcompany.example.org/reservation">    <m:code>FT35ZBQ</m:code>   </m:reservation>     <o:creditCard xmlns:o="http://mycompany.example.com/financial">    <n:name xmlns:n="http://mycompany.example.com/employees">           Åke Jógvan Øyvind    </n:name>        <o:number>123456789099999</o:number>    <o:expiration>2005-02</o:expiration>   </o:creditCard>  </m:chargeReservation> </env:Body></env:Envelope>

SOAP RPC request with a mandatory header and two input (or "in")parameters

The RPC itself is carried as a child of theenv:Body element,and is modelled as astruct which takes the name of theprocedure or method, in this casechargeReservation. (Astruct isa conceptfrom the SOAP Data Model defined in [SOAP Part2]that models a structure or record type that occurs in some common programminglanguages.) The design of the RPC in the example (whose formal descriptionhas not been explicitly provided) takes two input (or "in") parameters, thereservation corresponding to the planned trip identified by thereservationcode, and thecreditCard information.The latter is also astruct, which takes three elements, thecard holder'sname, the cardnumber and anexpiration date.

In this example, theenv:encodingStyle attribute with thevaluehttp://www.w3.org/2003/05/soap-encodingshows that the contents of thechargeReservation structure havebeen serialized according to the SOAP encoding rules, i.e., the particularrules defined in SOAP Part2 section 3.Even though SOAP specifies this particular encoding scheme, its use isoptional and the specification makes clear that other encoding schemes may beused for application-specific data within a SOAP message. It is for thispurpose that it provides theenv:encodingStyle attribute toqualify header blocks and body sub-elements. The choice of the value for thisattribute is an application-specific decision and the ability of a caller andcallee to interoperate is assumed to have been settled "out-of-band".Section 5.2 shows an example of using another encodingscheme.

As noted inItem 6 above, RPCs may also requireadditional information to be carried, which can be important for theprocessing of the call in a distributed environment, but which are not a partof the formal procedure or method description. (Note, however, that providingsuch additional contextual information is not specific to RPCs, but may berequired in general for the processing of any distributed application.) Inthe example, the RPC is carried out in the context of an overall transactionwhich involves several activities which must all complete successfully beforethe RPC returns successfully.Example 4 shows how aheader blocktransaction directed at the ultimate recipient(implied by the absence of theenv:role attribute) is used tocarry such information. (The value "5" is some transaction identifier set byand meaningful to the application. No further elaboration of theapplication-specific semantics of this header are provided here, as it is notgermane to the discussion of the syntactical aspects of SOAP RPCmessages.)

Let us assume that the RPC in the charging example has been designed tohave the procedure description which indicates that there are two output (or"out") parameters, one providing the reference code for the reservation andthe other a URL where the details of the reservation may be viewed. The RPCresponse is returned in theenv:Body element of a SOAP message,which is modeled as astruct taking the procedure namechargeReservation and, as a convention, the word "Response"appended. The two output (or "out") parameters accompanying the response arethe alphanumericcode identifying the reservation in question,and a URI for the location,viewAt, from where the reservationmay be retrieved.

This is shown inExample 5a, where the headeragain identifies the transaction within which this RPC is performed.

RPCs often have descriptions where a particular output parameter isdistinguished, the so-called "return" value. The SOAPRPC convention offers a way to distinguish this "return" value from theother output parameters in the procedure description. To show this, thecharging example is modified to have an RPC description that is almost thesame as that forExample 5a, i.e, with the same two"out" parameters, but in addition it also has a "return" value, which is anenumeration with potential values of "confirmed" and "pending". The RPCresponse conforming to this description is shown inExample 5b, where the SOAP header, as before,identifies the transaction within which this RPC is performed.

Example 5b

<?xml version='1.0' ?><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" > <env:Header>    <t:transaction       xmlns:t="http://thirdparty.example.org/transaction"         env:encodingStyle="http://example.com/encoding"          env:mustUnderstand="true">5</t:transaction> </env:Header>   <env:Body>    <m:chargeReservationResponse        env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"           xmlns:rpc="http://www.w3.org/2003/05/soap-rpc"             xmlns:m="http://travelcompany.example.org/">       <rpc:result>m:status</rpc:result>       <m:status>confirmed</m:status>       <m:code>FT35ZBQ</m:code>       <m:viewAt>        http://travelcompany.example.org/reservations?code=FT35ZBQ       </m:viewAt>    </m:chargeReservationResponse> </env:Body></env:Envelope>

RPC response with a "return" value and two "out" parameters for the callshown inExample 4

InExample 5b, the return value is identified bythe elementrpc:result, and contains the XML Qualified Name (oftypexs:QName) of another element within thestructwhich ism:status. This, in turn, contains the actual returnvalue, "confirmed". This technique allows the actual return value to bestrongly typed according to some schema. If therpc:resultelement is absent, as is the case inExample 5a, thereturn value is not present or is of the typevoid.

While, in principle, using SOAP for RPC is independent of the decision touse a particular means for transferring the RPC call and its return, certainprotocol bindings that support the SOAPRequest-Response message exchange pattern may be more naturally suitedfor such purposes. A protocol binding supporting this message exchangepattern can provide the correlation between a request and a response. Ofcourse, the designer of an RPC-based application could choose to put acorrelation ID relating a call and its return in a SOAP header, therebymaking the RPC independent of any underlying transfer mechanism. In any case,application designers have to be aware of all the characteristics of theparticular protocols chosen for transferring SOAP RPCs, such as latency,synchrony, etc.

In the commonly used case, standardized in SOAPPart 2 section 7, of using HTTP as the underlying transfer protocol, anRPC invocation maps naturally to the HTTP request and an RPC response maps tothe HTTP response.Section 4.1 provides examples ofcarrying RPCs using the HTTP binding.

However, it is worth keeping in mind that even though most examples ofSOAP for RPC use the HTTP protocol binding, it is not limited to that meansalone.

2.3 Fault Scenarios

SOAP provides a model for handling situations when faults arise in theprocessing of a message. SOAP distinguishes between the conditions thatresult in a fault, and the ability to signal that fault to the originator ofthe faulty message or another node. The ability to signal the fault dependson the message transfer mechanism used, and one aspect of the bindingspecification of SOAP onto an underlying protocol is to specify how faultsare signalled, if at all. The remainder of this section assumes that atransfer mechanism is available for signalling faults generated whileprocessing received messages, and concentrates on the structure of the SOAPfault message.

The SOAPenv:Body element has another distinguished role inthat it is the place where such fault information is placed. The SOAP faultmodel (see SOAPPart 1, section 2.6) requires that all SOAP-specific andapplication-specific faults be reported using asingle distinguishedelement,env:Fault, carried within theenv:Body element. Theenv:Fault element contains two mandatory sub-elements,env:Codeandenv:Reason,and (optionally) application-specific information in theenv:Detailsub-element. Another optional sub-element,env:Node, identifies via a URI the SOAP node which generated thefault, its absence implying that it was the ultimate recipient of the messagewhich did so. There is yet another optional sub-element,env:Role,which identifies the role being played by the node which generated thefault.

Theenv:Code sub-element ofenv:Fault is itselfmade up of a mandatoryenv:Valuesub-element, whose content is specified in the SOAP specification (see SOAPPart 1 section 5.4.6) as well as an optionalenv:Subcodesub-element.

Example 6a shows a SOAP message returned inresponse to the RPC request inExample 4, andindicating a failure to process the RPC.

InExample 6a, the top-levelenv:Value uses a standardized XML Qualified Name (of typexs:QName) to identify that it is anenv:Senderfault, which indicates that it is related to some syntactical error orinappropriate information in the message. (When aenv:Senderfault is received by the sender, it is expected that some corrective actionis taken before a similar message is sent again.) Theenv:Subcode element is optional, and, if present, as it is inthis example, qualifies the parent value further. InExample 6a, theenv:Subcode denotes that anRPC specific fault,rpc:BadArguments, defined inSOAPPart 2 section 4.4, is the cause of the failure to process therequest.

The structure of theenv:Subcodeelement has been chosen to be hierarchical - each childenv:Subcode element has a mandatoryenv:Valueand an optionalenv:Subcode sub-element - to allowapplication-specific codes to be carried. This hierarchical structure of theenv:Code element allows for an uniform mechanism for conveyingmultiple level of fault codes. The top-levelenv:Valueis a base fault that is specified in the SOAP Version 1.2 specifications (seeSOAPPart 1 section 5.4.6) and must be understood by all SOAP nodes. Nestedenv:Values are application-specific, and represent furtherelaboration or refinement of the base fault from an application perspective.Some of these values may well be standardized, such as the RPC codesstandardized in SOAP 1.2 (see SOAPPart 2 section 4.4), or in some other standards that use SOAP as anencapsulation protocol. The only requirement for defining suchapplication-specific subcode values is that they be namespace qualified usingany namespace other than the SOAPenv namespace whichdefines the main classifications for SOAP faults. There is no requirementfrom a SOAP perspective that applications need to understand, or even look atall levels of the subcode values.

Theenv:Reasonsub-element is not meant for algorithmic processing, but rather for humanunderstanding; so, even though this is a mandatory item, the chosen valueneed not be standardized. Therefore all that is required is that itreasonably accurately describe the fault situation. It must have one or moreenv:Textsub-elements, each with a uniquexml:lang attribute, whichallows applications to make the fault reason available in multiple languages.(Applications could negotiate the language of the fault text using amechanism built using SOAP headers; however this is outside the scope of theSOAP specifications.)

The absence of aenv:Node sub-element withinenv:Fault inExample 6a implies that itis generated by the ultimate receiver of the call. The contents ofenv:Detail, as shown in the example, areapplication-specific.

During the processing of a SOAP message, a fault may also be generated ifa mandatory header element is not understood or the information contained init cannot be processed. Errors in processing a header block are alsosignalled using aenv:Fault element within theenv:Body, but with a particular distinguished header block,env:NotUnderstood,that identifies the offending header block.

Example 6b shows an example of a response to theRPC inExample 4 indicating a failure to process thet:transaction header block. Note the presence of theenv:MustUnderstandfault code in theenv:Body, and the identification of the headernot understood using an (unqualified) attribute,qname, in thespecial (empty) header blockenv:NotUnderstood.

If there were several mandatory header blocks that were not understood,then each could be identified by itsqname attribute in a seriesof suchenv:NotUnderstood header blocks.

3. SOAP Processing Model

Having established the various syntactical aspects of a SOAP message aswell as some basic message exchange patterns, this section provides a generaloverview of the SOAP processing model (specified in SOAPPart 1, section 2). The SOAP processing model describes the actions takenby a SOAP node on receiving a SOAP message.

Example 7a shows a SOAP message with severalheader blocks (with their contents omitted for brevity). Variations of thiswill be used in the remainder of this section to illustrate various aspectsof the processing model.

The SOAP processing model describes the (logical) actions taken by a SOAPnode on receiving a SOAP message. There is a requirement for the node toanalyze those parts of a message that are SOAP-specific, namely thoseelements in the SOAP "env" namespace. Suchelements are the envelope itself, the header element and the body element. Afirst step is, of course, the overall check that the SOAP message issyntactically correct. That is, it conforms to the SOAP XML infoset subjectto the restrictions on the use of certain XML constructs - ProcessingInstructions and Document Type Definitions - as defined in SOAP Part1, section 5.

3.1 The "role" Attribute

Further processing of header blocks and the body depend on therole(s) assumed by the SOAP node for the processing of a given message.SOAP defines the (optional)env:role attribute - syntactically,xs:anyURI - that may be present in a header block, whichidentifies the role played by the intended target of that header block. ASOAP node is required to process a header block if it assumes the roleidentified by the value of the URI. How a SOAP node assumes a particular roleis not a part of the SOAP specifications.

InExample 7a, the header blockoneBlock is targeted at any SOAP node that plays theapplication-defined role defined by the URI http://example.com/Log. Forpurposes of illustration, it is assumed that the specification for such aheader block requires that any SOAP node adopting this role log the entiremessage.

Every SOAP node receiving a message with a header block that has aenv:role attribute of "next" must be capable of processing thecontents of the element, as this is a standardized role that every SOAP nodemust be willing to assume. A header block thus attributed is one which isexpected to be examined and (possibly) processed by the next SOAP node alongthe path of a message, assuming that such a header has not been removed as aresult of processing at some node earlier in the message path.

InExample 7a, the header blockanotherBlock is targeted at the next node in the message path.Inthis case, the SOAP message received by the nodeplaying the application-defined role of "http://example.com/Log", must alsobe willing to play the SOAP-defined role of "next". This is also true for thenode which is the ultimate recipient of the message, as it obviously (andimplicitly) also plays the "next" role by virtue of being next in the messagepath.

The third header block,aThirdBlock, inExample 7a does not have theenv:roleattribute. It is targeted at a SOAP node which assumes the "ultimateReceiver"role. The "ultimateReceiver" role (which can be explicitly declared or isimplicit if theenv:role attribute is absent in a header block)is played by a SOAP node that assumes the role of the ultimate recipient of aparticular SOAP message. The absence of aenv:role attribute intheaThirdBlock header block means that this header element istargeted at the SOAP node that assumes the "ultimateReceiver" role.

Note that theenv:Body element does not have aenv:role attribute. The body element isalways targetedat the SOAP node that assumes the "ultimateReceiver" role. In that sense, thebody element is just like a header block targeted at the ultimate receiver,but it has been distinguished to allow for SOAP nodes (typically SOAPintermediaries) to skip over it if they assume roles other than that of theultimate receiver. SOAP does not prescribe any structure for theenv:Body element, except that it recommends that anysub-elements be XML namespace qualified. Some applications, such as that inExample 1, may choose to organize the sub-elements ofenv:Body in blocks, but this is not of concern to the SOAPprocessing model.

The other distinguished role for theenv:Body element, as thecontainer where information on SOAP-specific faults, i.e., failure to processelements of a SOAP message, is placed has been described previously insection 2.3.

If a header element has the standardizedenv:role attributewith value "none", it means that no SOAP node should process the contents,although a node may need to examine it if the content are data referenced byanother header element that is targeted at the particular SOAP node.

If theenv:role attribute has an empty value, i.e.,env:role="", it means that the relative URI identifying therole is resolved to the base URI for the SOAP message in question. SOAPVersion 1.2 does not define a base URI for a SOAP message, but defers to themechanisms defined in [XMLBase] for deriving the baseURI, which can be used to make any relative URIs absolute. One suchmechanism is for the protocol binding to establish a base URI, possibly byreference to the encapsulating protocol in which the SOAP message isembedded for transport. (In fact, when SOAP messages are transported usingHTTP,SOAP Part2 section 7.1.2 defines the base URI as the Request-URI of the HTTPrequest, or the value of the HTTP Content-Location header.)

The following table summarizes the applicable standardized roles that maybe assumed at various SOAP nodes. ("Yes" and "No" means that thecorresponding node does or does not, respectively, play the named role.)

3.2 The "mustUnderstand"Attribute

Example 7b augments the previous example byintroducing another (optional) attribute for header blocks, theenv:mustUnderstandattribute.

After a SOAP node has correctly identified the header blocks (and possiblythe body) targeted at itself using theenv:role attribute, theadditional attribute,env:mustUnderstand, in the header elementsdetermines further processing actions that have to be taken. In order toensure that SOAP nodes do not ignore header blocks which are important to theoverall purpose of the application, SOAP header blocks also provide for theadditional optional attribute,env:mustUnderstand, which, if"true", means that the targeted SOAP nodemust process theblock according to the specification of that block. Such a block iscolloquially referred to as a mandatory header block. In fact, processing ofthe SOAP message must not even start until the node has identified all themandatory header blocks targeted at itself, and "understood" them.Understanding a header means that the node must be prepared to do whatever isdescribed in the specification of that block. (Keep in mind that thespecifications of header blocks are not a part of the SOAPspecifications.)

InExample 7b, the header blockoneBlock is marked with aenv:mustUnderstand valueset to "true", which means that it is mandatory to process this block if theSOAP node plays the role identified by "http://example.com/Log". The othertwo header blocks are not so marked, which means that SOAP node at whichthese blocks are targeted need not process them. (Presumably thespecifications for these blocks allow for this.)

Aenv:mustUnderstand value of "true" means that the SOAP nodemust process the header with the semantics described in that header'sspecification, or else generate a SOAP fault. Processing the headerappropriately may include removing the header from any generated SOAPmessage, reinserting the header with the same or altered value, or insertinga new header. The inability to process a mandatory header requires that allfurther processing of the SOAP message cease, and a SOAP fault be generated.The message is not forwarded any further.

Theenv:Body element has noenv:mustUnderstandattribute but itmust be processed by the ultimate recipient. InExample 7b, the ultimate recipient of the message - theSOAP node which plays the "ultimateReceiver" role - must process theenv:Body and may process the header blockaThirdBlock. It may also process the header blockanotherBlock, as it is targeted at it (in the role of "next")but it is not mandatory to do so if the specifications for processing theblocks do not demand it. (If the specification foranotherBlockdemanded that it must be processed at the next recipient, it would haverequired that it be marked with aenv:mustUnderstand="true".)

The role(s) a SOAP node plays when processing a SOAP message can bedetermined by many factors. The role could be known a priori, or setby some out-of-band means, or a node can inspect all parts of a receivedmessage to determine which roles it will assume before processing themessage. An interesting case arises when a SOAP node, during the course ofprocessing a message, decides that there are additional roles that it needsto adopt. No matter when this determination is made, externally it mustappear as though the processing model has been adhered to. That is, it mustappear as though the role had been known from the start of the processing ofthe message. In particular, the external appearance must be that theenv:mustUnderstand checking of any headers with those additionalroles assumed was performed before any processing began. Also, if a SOAP nodeassumes such additional roles, it must ensure that it is prepared to doeverything that the specifications for those roles require.

The following table summarizes how the processing actions for a headerblock are qualified by theenv:mustUnderstand attribute withrespect to a node that has been appropriately targeted (via theenv:role attribute).

As a result of processing a SOAP message, a SOAP node may generate asingle SOAP fault if it fails to process a message, or, depending on theapplication, generate additional SOAP messages for consumption at other SOAPnodes.SOAPPart 1 section 5.4 describes the structure of the fault message while theSOAPprocessing model defines the conditions under which it is generated. Asillustrated previously insection 2.3, a SOAP fault isa SOAP message with a standardizedenv:Body sub-element namedenv:Fault.

SOAP makes a distinction between generating a fault and ensuring that thefault is returned to the originator of the message or to another appropriatenode which can benefit from this information. However, whether a generatedfault can be propagated appropriately depends on the underlying protocolbinding chosen for the SOAP message message exchange. The specification doesnot define what happens if faults are generated during the propagation ofone-way messages. The only normative underlying protocol binding, which isthe SOAP HTTP binding, offers the HTTP response as a means for reporting afault in the incoming SOAP message. (SeeSection 4for more details on SOAP protocol bindings.)

3.3 The "relay" Attribute

SOAP Version 1.2 defines another optional attribute for header blocks,env:relayof typexs:boolean, which indicates if a header block targetedat a SOAP intermediary must be relayed if it isnot processed.

Note that if a header blockis processed, the SOAP processingrules (seeSOAPPart 1 section 2.7.2) requires that it be removed from the outboundmessage. (It may, however, be reinserted, either unchanged or with itscontents altered, if the processing of other header blocks determines thatthe header block be retained in the forwarded message.) The default behaviorforan unprocessed header block targeted at a role played by a SOAPintermediary is that it must be removed before the message is relayed.

The reason for this choice of default is to lean on the side of safety byensuring that a SOAP intermediary make no assumptions about the survivabilitypast itself of a header block targeted at a role it assumes, and representingsome value-added feature, particularly if it chooses not to process theheader block, very likely because it does not "understand" it. That isbecause certain header blocks represent hop-by-hop features, and it may notmake sense to unknowingly propagate it end-to-end. As an intermediary may notbe in a position to make this determination, it was thought that it would besafer if unprocessed header blocks were removed before the message wasrelayed.

However, there are instances when an application designer would like tointroduce a new feature, manifested through a SOAP header block, targeted atany capable intermediary which might be encountered in the SOAPmessage path. Such a header block would be available to those intermediariesthat "understood" it, but ignored and relayed onwards by those that did not.Being a new feature, the processing software for this header block may beimplemented, at least initially, in some but not all SOAP nodes. Marking sucha header block withenv:mustUnderstand = "false" is obviouslyneeded, so that intermediaries that have not implemented the feature do notgenerate a fault. To circumvent the default rule of the processing model,marking a header block with the additional attributeenv:relaywith the value "true" allows the intermediary to forward the header blocktargeted at itself in the event that it chooses not to process it.

Targeting the header block at the role "next" together with theenv:relay attribute set to "true" can always serve to ensurethat each intermediary has a chance to examine the header, because one of theanticipated uses of the "next" role is with header blocks that carryinformation that are expected to persist along a SOAP message path. Ofcourse, the application designer can always define a custom role that allowstargetting at specific intermediaries that assume this role. Therefore, thereis no restriction on the use of theenv:relay attribute with anyrole except of course the roles of "none" and "ultimateReceiver", for whichit is meaningless.

The header blockq:anotherBlock, targeted at the "next" nodein the message path, has the additional attributeenv:relay="true". A SOAP node receiving this message may processthis header block if it "understands" it, but if it does so the processingrules require that this header block be removed before forwarding. However,if the SOAP node chooses to ignore this header block, which it can because itis not mandatory to process it, as indicated by the absence of theenv:mustUnderstand attribute, then it must forward it.

Processing the header blockp:oneBlock is mandatory and theSOAP processing rules require that it not be relayed, unless the processingof some other header block requires that it be present in the outboundmessage. The header blockr:aThirdBlock does not have anenv:relay attribute, which is equivalent to having it with thevalueenv:relay="false". Hence, this header is not forwarded ifit is not processed.

SOAP1.2 Part 1 Table 3 summarizes the conditions which determine when a SOAPintermediary assuming a given role is allowed to forward unprocessed headerblocks.

4. Using Various ProtocolBindings

SOAP messages may be exchanged using a variety of "underlying" protocols,including other application layer protocols. The specification of how SOAPmessages may be passed from one SOAP node to another using an underlyingprotocol is called aSOAPbinding.[SOAP Part1] defines a SOAP message in theform of an [XML Infoset], i.e., in terms of element andattribute information items of an abstract "document" called theenv:Envelope (see SOAP Part1, section 5). Any SOAPenv:Envelope infoset representationwill be made concrete through a protocol binding, whose task, among otherthings, it is to provide a serialized representation of the infoset that canbe conveyed to the next SOAP node in the message path in a manner such thatthe infoset can be reconstructed without loss of information. In typicalexamples of SOAP messages, and certainly in all the examples in this primer,the serialization shown is that of a well-formed [XML1.0 ] document. However, there may be other protocolbindings - for example a protocol binding between two SOAP nodes over alimited bandwidth interface - where an alternative, compressed serializationof the same infoset may be chosen. Another binding, chosen for a differentpurpose, may provide a serialization which is an encrypted structurerepresenting the same infoset.

In addition to providing a concrete realization of a SOAP infoset betweenadjacent SOAP nodes along a SOAP message path, a protocol binding providesthe mechanisms to supportfeaturesthat are needed by a SOAP application. A feature is a specification of acertain functionality provided by a binding. A feature description isidentified by a URI, so that all applications referencing it are assured ofthe same semantics. For example, a typical usage scenario might require manyconcurrent request-response exchanges between adjacent SOAP nodes, in whichcase the feature that is required is the ability to correlate a request witha response. Other examples includes "an encrypted channel" feature, or a"reliable delivery channel" feature, or a particularSOAPmessage exchange pattern feature.

A SOAP binding specification (seeSOAPPart 1 section 4) describes, among other things, which (if any) featuresit provides. Some features may be provided natively by the underlyingprotocol. If the feature is not available through the binding, it may beimplemented within the SOAP envelope, using SOAP header blocks. Thespecification of a feature implemented using SOAP header blocks is called aSOAPmodule.

For example, if SOAP message exchanges were being transported directlyover a datagram protocol like UDP, obviously the message correlation featurewould have to be provided elsewhere, either directly by the application ormore likely as a part of the SOAP infosets being exchanged. In the lattercase, the message correlation feature has a binding-specific expressionwithin the SOAP envelope, i.e., as a SOAP header block, defined in a"Request-Response Correlation" module identified by a URI. However, if theSOAP infosets were being exchanged using an underlying protocol that wasitself request/response, the application could implicitly "inherit" thisfeature provided by the binding, and no further support need be provided atthe application or the SOAP level. (In fact, the HTTP binding for SOAP takesadvantage of just this feature of HTTP.)

However, a SOAP message may travel over several hops between a sender andthe ultimate receiver, where each hop may be a different protocol binding. Inother words, a feature (e.g., message correlation, reliability etc.) that issupported by the protocol binding in one hop may not be supported by anotheralong the message path. SOAP itself does not provide any mechanism for hidingthe differences in features provided by different underlying protocols.However, any feature that is required by a particular application, but whichmay not be available in the underlying infrastructure along theanticipated message path, can be compensated for by being carried asa part of the SOAP message infoset, i.e., as a SOAP header block specified insome module.

Thus it is apparent that there are a number of issues that have to betackled by an application designer to accomplish particular applicationsemantics, including how to take advantage of the native features ofunderlying protocols that are available for use in the chosen environment.SOAP Part 1section 4.2 provides a general framework for describing how SOAP-basedapplications may choose to use the features provided by an underlyingprotocol binding to accomplish particular application semantics. It isintended to provide guidelines for writing interoperable protocol bindingspecifications for exchanging SOAP messages.

Among other things, a binding specification must define one particularfeature, namely the message exchange pattern(s) that it supports.[SOAP Part2] defines two such message exchange patterns,namely aSOAP Request-Response message exchange pattern where one SOAP message isexchanged in each direction between two adjacent SOAP nodes, and a SOAPResponse message exchange pattern which consists of a non-SOAP messageacting as a request followed by a SOAP message included as a part of theresponse.

[SOAP Part2] also offers the application designer ageneral feature called theSOAP Web Method feature that allows applications full control over thechoice of the so-called "Web method" - one of GET, POST, PUT, DELETE whosesemantics are as defined in the [HTTP 1.1]specifications - that may be used over the binding. This feature is definedto ensure that applications using SOAP can do so in a manner which iscompatible with the architectural principles of the World Wide Web. (Verybriefly, the simplicity and scalability of the Web is largely due to the factthat there are a few "generic" methods (GET, POST, PUT, DELETE) which can beused to interact with any resource made available on the Web via a URI.) TheSOAPWeb Method feature is supported by the SOAP HTTP binding, although, inprinciple, it is available to all SOAP underlying protocol bindings.

SOAPPart 2 section 7 specifies one standardizedprotocol binding using the binding framework of[SOAPPart1], namely how SOAP is used in conjunction with HTTP as theunderlying protocol. SOAP Version 1.2 restricts itself to the definition of aHTTP binding allowing only the use of the POST method in conjunction with theRequest-Response message exchange pattern and the GET method with the SOAPResponse message exchange pattern. Other specifications in future coulddefine SOAP bindings to HTTP or other transports that make use of the otherWeb methods (i.e., PUT, DELETE).

The next sections show examples of two underlying protocol bindings forSOAP, namely those to [HTTP 1.1] and email. It should beemphasized again that the only normative binding for SOAP 1.2 messages is to[HTTP 1.1]. The examples insection4.2 showing email as a transport mechanism for SOAP is simply meant tosuggest that other choices for the transfer of SOAP messages are possible,although not standardized at this time. A W3C Note [SOAPEmail Binding] offers an application of the SOAP protocol bindingframework of[SOAP Part1] by describing an experimentalbinding of SOAP to email transport, specifically [RFC2822]-based message transport.

4.1 The SOAP HTTP Binding

HTTP has a well-known connection model and a message exchange pattern. Theclient identifies the server via a URI, connects to it using the underlyingTCP/IP network, issues a HTTP request message and receives a HTTP responsemessage over the same TCP connection. HTTP implicitly correlates its requestmessage with its response message; therefore, an application using thisbinding can chose to infer a correlation between a SOAP message sent in thebody of a HTTP request message and a SOAP message returned in the HTTPresponse. Similarly, HTTP identifies the server endpoint via a URI, theRequest-URI,which can also serve as the identification of a SOAP node at the server.

HTTP allows for multiple intermediaries between the initial client and theoriginserver identified by the Request-URI, in which case the request/responsemodel is a series of such pairs. Note, however, that HTTP intermediaries aredistinct from SOAP intermediaries.

The HTTP binding in[SOAPPart2] makes use of theSOAPWeb Method featureto allow applications to choose the so-called Webmethod - restricting it to one of GET or POST - to use over the HTTP messageexchange. In addition, it makes use of two message exchange patterns thatoffer applications two ways of exchanging SOAP messages via HTTP: 1)the use of theHTTP POST method for conveying SOAP messages inthe bodies ofHTTP requestand responsemessages, and 2)the use of the HTTP GETmethod in a HTTP request to return a SOAP message in the body of a HTTPresponse. The first usage pattern is the HTTP-specific instantiation of abinding feature called theSOAP request-response message exchangepattern, while the second uses a featurecalled theSOAP response message exchange pattern.

The purpose of providing these two types of usages isto accommodate the two interaction paradigms which are well established onthe World Wide Web. The first type of interaction allows for the use of datawithin the body of a HTTP POST to create or modify the state of a resourceidentified by the URI to which the HTTP request is destined. The second typeof interaction pattern offers the ability to use a HTTP GET request to obtaina representation of a resource without altering its state in any way. In thefirst case, the SOAP-specific aspect of concern is that the body of the HTTPPOST request is a SOAP message which has to be processed (per the SOAPprocessing model) as a part of the application-specific processing requiredto conform to the POST semantics. In the second case, the typical usage thatis forseen is the case where the representation of the resource that is beingrequested is returned not as a HTML, or indeed a generic XML document, but asa SOAP message. That is, the HTTP content type header of the response messageidentifies it as being of media type "application/soap+xml". Presumably,there will be publishers of resources on the Web who determine that suchresources are best retrieved and made available in the form of SOAP messages.Note, however, that resources can, in general, be made available in multiplerepresentations, and the desired or preferred representation is indicated bythe requesting application using the HTTPAcceptheader.

One further aspect ofthe SOAP HTTP binding is the question of how an application determines whichof these two types of message exchange patterns to use.[SOAP Part2] offers guidance oncircumstances when applications may use one of the two specified messageexchange patterns. (It is guidance - albeit a strong one - as it is phrasedin the form of a "SHOULD" in thespecifications rather than an absolute requirement identified by the word"MUST", where thesewords are interpreted as defined in the IETF [RFC2119].) The SOAP response message exchange pattern with the HTTP GETmethod is used when an application is assured that the message exchange isfor the purposes of information retrieval, where the information resource is"untouched" as a result of the interaction. Such interactions are referred toassafe andidempotentin the HTTP specification. As theHTTP SOAP GET usage does not allow for a SOAP message in the request,applications that need features in the outbound interaction that can only besupported by a binding-specific expression within the SOAP infoset (i.e., asSOAP header blocks) obviously cannot make use of this message exchangepattern. Note that the HTTP POST binding is available for use in allcases.

The followingsubsections provide examples of the use of these two message exchangepatterns defined for the HTTP binding.

4.1.1. SOAP HTTP GET Usage

Using the HTTP binding with theSOAP Response message exchange patternis restricted to the HTTP GET method. This means thatthe response to a HTTP GET request from a requesting SOAP node is a SOAPmessage in the HTTP response.

Example 8a shows a HTTP GET directed by thetraveller's application (in the continuing travel reservation scenario) atthe URIhttp://travelcompany.example.org/reservations?code=FT35ZBQwhere the traveler's itinerary may be viewed. (Howthis URL was made available can be seen inExample 5a.)

The HTTPAcceptheader is used to indicate the preferred representation of the resource beingrequested, which in this example is an "application/soap+xml" media type forconsumption by a machine client, rather than the "text/html" media type forrendition by a browser client for consumption by a human.

Example 8b shows the HTTPresponse to the GET inExample 8a. The bodyof the HTTP response contains a SOAP message showing the travel details. Adiscussion of the contents of the SOAP message is postponed untilsection 5.2 , as it is not relevant, at this point, tounderstanding the HTTP GET binding usage.

Example 8b

HTTP/1.1 200 OKContent-Type: application/soap+xml; charset="utf-8"Content-Length: nnnn<?xml version='1.0' ?><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">  <env:Header>  <m:reservation xmlns:m="http://travelcompany.example.org/reservation"        env:role="http://www.w3.org/2003/05/soap-envelope/role/next"           env:mustUnderstand="true">   <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference>   <m:dateAndTime>2001-11-30T16:25:00.000-05:00</m:dateAndTime>  </m:reservation> </env:Header> <env:Body>  <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"            xmlns:x="http://travelcompany.example.org/vocab#"     env:encodingStyle="http://www.w3.org/1999/02/22-rdf-syntax-ns#">   <x:ReservationRequest  rdf:about="http://travelcompany.example.org/reservations?code=FT35ZBQ">      <x:passenger>Åke Jógvan Øyvind</x:passenger>      <x:outbound>       <x:TravelRequest>        <x:to>LAX</x:to>        <x:from>LGA</x:from>        <x:date>2001-12-14</x:date>       </x:TravelRequest>      </x:outbound>      <x:return>       <x:TravelRequest>        <x:to>JFK</x:to>        <x:from>LAX</x:from>        <x:date>2001-12-20</x:date>       </x:TravelRequest>      </x:return>    </x:ReservationRequest>  </rdf:RDF> </env:Body></env:Envelope>

SOAP message returned as a response to the HTTP GET inExample 8a

Note that thereservation details could well have been returned as an (X)HTML document, butthis example wanted to show a case where the reservation application isreturning the state of the resource (the reservation) in a data-centric mediaform (a SOAP message) which can be machine processed, instead of (X)HTMLwhich would be processed by a browser. Indeed, in the most likely anticipateduses of SOAP, the consuming application will not be a browser.

Also, as shown in the example, the use ofSOAP in the HTTP response body offers the possibility of expressing someapplication-specific feature through the use of SOAP headers. By using SOAP,the application is provided with a useful and consistent framework andprocessing model for expressing such features.

4.1.2 SOAP HTTPPOST Usage

Using the HTTP binding with theSOAP Request-Response message exchange pattern is restricted to the HTTPPOST method. Note that the use of this message exchange pattern in the SOAPHTTP binding is available to all applications, whether they involve theexchange of general XML data or RPCs (as in the following examples)encapsulated in SOAP messages.

Examples9 and10 show an example of a HTTP bindingusing the SOAP Request-Response message exchangepattern, using the same scenario as thatforExample 4andExample 5a, respectively, namely conveying an RPC and its returnin the body of a SOAP message. The examples and discussion in this sectiononly concentrate on the HTTP headers and their role.

Example 9

POST /Reservations HTTP/1.1Host: travelcompany.example.orgContent-Type: application/soap+xml; charset="utf-8"Content-Length: nnnn<?xml version='1.0' ?><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" > <env:Header>   <t:transaction           xmlns:t="http://thirdparty.example.org/transaction"           env:encodingStyle="http://example.com/encoding"           env:mustUnderstand="true" >5</t:transaction> </env:Header>   <env:Body><m:chargeReservation     env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"          xmlns:m="http://travelcompany.example.org/">   <m:reservation xmlns:m="http://travelcompany.example.org/reservation">    <m:code>FT35ZBQ</m:code>   </m:reservation>       <o:creditCard xmlns:o="http://mycompany.example.com/financial"> <n:name xmlns:n="http://mycompany.example.com/employees">           Åke Jógvan Øyvind     </n:name>        <o:number>123456789099999</o:number>     <o:expiration>2005-02</o:expiration>    </o:creditCard>   </m:chargeReservation>  </env:Body></env:Envelope>

RPC inExample 4 carried in an HTTP POST Request

Example 9 shows an RPC request directed atthe travel service application. The SOAP message is sent in the body of aHTTP POST method directed at the URI identifying the "Reservations" resourceon the server travelcompany.example.org. When using HTTP, the Request-URIindicates the resource to which the invocation is "posted". Other thanrequiring that it be a valid URI, SOAP places noformal restrictionon the form of the request URI (see[RFC 2396] for moreinformation on URIs). However, one of the principles of the Web architectureis that all important resources be identified by URIs. This implies that mostwell-architected SOAP services will be embodied as a large number ofresources, each with its own URI. Indeed, many such resources are likely tobe created dynamically during the operation of a service, such as, forinstance, the specific travel reservation shown in the example. So, awell-architected travel service application should have different URIs foreach reservation, and SOAP requests to retrieve or manipulate thosereservations will be directed at their URIs, and not at a single monolithic"Reservations" URI, as shown inExample 9. Example 13 insection 4.1.3shows the preferred way to address resources such as a particular travelreservation. Therefore, we defer untilsection 4.1.3further discussion of Web architecture compatible SOAP/HTTP usage.

When placing SOAP messages in HTTP bodies, the HTTP Content-type headermust be chosen as "application/soap+xml". (Theoptional charset parameter, which can take the value of "utf-8" or "utf-16", is shown in thisexample, but if it is absent the character set rules for freestanding [XML 1.0] apply to the body of the HTTP request.)

Example 10 shows the RPC return (withdetails omitted) sent by the travel service application in the correspondingHTTP response to the request fromExample 5a. SOAP,using HTTP transport, follows the semantics of the HTTP status codes forcommunicating status information in HTTP. For example, the 2xx series of HTTPstatus codes indicate that the client's request (including the SOAPcomponent) was successfully received, understood, and accepted etc.

If an error occurs processing the request, the HTTP binding specificationrequires that a HTTP 500 "Internal Server Error" be used with an embeddedSOAP message containing a SOAP fault indicating the server-side processingerror.

Example 11 is the same SOAP fault message asExample 6a, but this time with the HTTP headersadded.

Example 11

HTTP/1.1 500 Internal Server ErrorContent-Type: application/soap+xml; charset="utf-8"Content-Length: nnnn<?xml version='1.0' ?><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">  <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>

Sample SOAP message in a HTTP Response indicating failureto handle the SOAP Body inExample4

SOAPPart 2 Table 16 provides detailed behavior for handling the variouspossible HTTP response codes, i.e., the 2xx (successful), 3xx (redirection),4xx (client error) and 5xx (server error).

4.1.3 WebArchitecture Compatible SOAP Usage

One of the most central concepts of the World Wide Web is that of a URI asa resource identifier. SOAP services that use the HTTP binding and wish tointeroperate with other Web software should use URIs to address all importantresources in their service. For example, a very important - indeedpredominant - use of the World Wide Web is pure information retrieval, wherethe representation of an available resource, identified by a URI, is fetchedusing a HTTP GET request without affecting the resource in any way. (This iscalled asafe andidempotent methodin HTTP terminology.) Thekey point is that the publisher of a resource makes available its URI, whichconsumers may "GET".

There are manyinstances when SOAP messages are designed for uses which are purely forinformation retrieval, such as when the state of some resource (or object, inprogramming terms) is requested, as opposed to uses that perform resourcemanipulation. In such instances, the use of a SOAP body to carry the requestfor the state, with an element of the body representing the object inquestion, is seen as counter to the spirit of the Web because the resource isnot identified by the Request-URI of the HTTP GET. (In some SOAP/RPCimplementations, the HTTP Request-URI is often not the identifier of theresource itself but some intermediate entity which has to evaluate the SOAPmessage to identify the resource.)

To highlight the changes needed,Example 12a shows the way that isnotrecommended for doing safe information retrieval on the Web. This is anexample of an RPC carried in a SOAP message, again using the travelreservation theme, where the request is to retrieve the itinerary for aparticular reservation identified by one of the parameters,reservationCode, of the RPC. (For purposes of this discussion,it is assumed that the application using this RPC request does not needfeatures which require the use of SOAP headers.)

Note that the resource to be retrieved is notidentified by the target URI in the HTTP request but has to be obtained bylooking within the SOAP envelope. Thus, it is not possible, as would be thecase with other "gettable" URIs on the Web, to make this available via HTTPalone to consumers on the World Wide Web.

SOAP Part2 section 4.1 offers recommendations on how RPCs that constitute safe andidempotent information retrievals may be defined in a Web-friendly manner. Itdoes so by distinguishing aspects of the method and specific parameters in anRPC definition that serve to identify resources from those that serve otherpurposes. InExample 12a, the resource to beretrieved is identified by two things: the first is that it is an itinerary(part of the method name), and the second is the reference to a specificinstance (a parameter to the method). In such a case, the recommendation isthat these resource-identifying parts be made available in the HTTPRequest-URI identifying the resource, as for example, as follows:http://travelcompany.example.org/reservations/itinerary?reservationCode=FT35ZBQ.

Furthermore, when an RPC definition is such thatall parts of its method description can be described as resource-identifying,the entire target of the RPC may be identified by a URI. In this case, if thesupplier of the resource can also assure that a retrieval request is safe,then SOAP Version 1.2 recommends that the choice of the Web method propertyof GET and the use of the SOAPResponse message exchange pattern be used as described insection 4.1.1. This will ensure that the SOAP RPC isperformed in a Web architecture compatible manner.Example 12bshows the preferred way for a SOAPnode to request the safe retrieval of a resource.

It should be noted that SOAP Version 1.2 does notspecify any algorithm on how to compute a URI from the definition of an RPCwhich has been determined to represent pure information retrieval.

Note, however, that ifthe application requires the use of features that can only have abinding-specific expression within the SOAP infoset, i.e., using SOAP headerblocks, then the application must choose HTTP POST method with a SOAP messagein the request body.

It also requires the use of theSOAP Request-Response message exchange pattern implemented via a HTTP POST if the RPC descriptionincludes data (parameters) which are not resource-identifying. Even in thiscase, the HTTP POST with a SOAP message can be represented in a Web-friendlymanner. As with the use of the GET,[SOAP Part2]recommends for the general case that any part of the SOAP message that servesto identify the resource to which the request is POSTed be identified in theHTTP Request-URI. The same parameters may, of course, be retained in theSOAPenv:Bodyelement. (The parameters must be retained in the Bodyin the case of a SOAP-based RPC as these are related to the procedure/methoddescription expected by the receiving application.)

Example 13 is the same as that inExample 9, except that the HTTP Request-URI hasbeen modified to include the reservationcode, which serves to identify theresource (the reservation in question, which is being confirmed and paidfor).

Example 13

POST /Reservations?code=FT35ZBQ HTTP/1.1Host: travelcompany.example.orgContent-Type: application/soap+xml; charset="utf-8"Content-Length: nnnn<?xml version='1.0'?><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" > <env:Header>   <t:transaction           xmlns:t="http://thirdparty.example.org/transaction"           env:encodingStyle="http://example.com/encoding"           env:mustUnderstand="true" >5</t:transaction> </env:Header>   <env:Body>  <m:chargeReservation      env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"         xmlns:m="http://travelcompany.example.org/">   <m:reservation xmlns:m="http://travelcompany.example.org/reservation">    <m:code>FT35ZBQ</m:code>   </m:reservation>     <o:creditCard xmlns:o="http://mycompany.example.com/financial">    <n:name xmlns:n="http://mycompany.example.com/employees">           Åke Jógvan Øyvind    </n:name>        <o:number>123456789099999</o:number>    <o:expiration>2005-02</o:expiration>   </o:creditCard>  </m:chargeReservation> </env:Body></env:Envelope>

RPC fromExample 4 carried in an HTTP POST Request ina Web-friendly manner

InExample 13, the resource to bemanipulated is identified by two things: the first is that it is areservation (part of the method name), and the second is the specificinstance of a reservation (which is the value of the parametercode to the method). The remainder of the parameters in the RPCsuch as thecreditCard number are not resource-identifying, butare ancillary data to be processed by the resource. It is the recommendationof [SOAP Part2] that resources that may be accessed bySOAP-based RPCs should, where practical, place any such resource-identifyinginformation as a part of the URI identifying the target of the RPC. Itshould be noted, however, that [SOAP Part2] does notoffer any algorithm to do so. Such algorithms may be developed in future.Note, however, that all the resource-identifying elements have been retainedas inExample 9 in their encoded form in theSOAPenv:Body element.

In other words, as seen from the aboveexamples, the recommendation in the SOAP specifications is to use URIs in aWeb-architecture compatible way - that is, as resource identifiers - whetheror not it is GET or POST that is used.

4.2 SOAP Over Email

Application developers can use the Internet email infrastructure to moveSOAP messages as either email text or attachments. The examples shown belowoffer one way to carry SOAP messages, and should not be construed as beingthe standard way of doing so. The SOAP Version 1.2 specifications do notspecify such a binding. However, there is anon-normative W3C Note[SOAP Email Binding] describing an email binding forSOAP, its main purpose being to demonstrate the application of the generalSOAP Protocol Binding Framework described in [SOAP Part1].

Example 14 shows the travel reservation requestmessage fromExample 1 carried as an email messagebetween a sending and receiving mail user agent. It is implied that thereceiver node has SOAP capabilities, to which the body of the email isdelivered for processing. (It is assumed that the sending node also has SOAPcapabilities so as to be able to process any SOAP faults received inresponse, or to correlate any SOAP messages received in response to thisone.)

Example 14

From: a.oyvind@mycompany.example.comTo: reservations@travelcompany.example.orgSubject: Travel to LADate: Thu, 29 Nov 2001 13:20:00 ESTMessage-Id: <EE492E16A090090276D208424960C0C@mycompany.example.com>Content-Type: application/soap+xml <?xml version='1.0' ?><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">  <env:Header>  <m:reservation xmlns:m="http://travelcompany.example.org/reservation"       env:role="http://www.w3.org/2003/05/soap-envelope/role/next"         env:mustUnderstand="true">   <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference>   <m:dateAndTime>2001-11-29T13:20:00.000-05:00</m:dateAndTime>  </m:reservation>  <n:passenger xmlns:n="http://mycompany.example.com/employees"      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"         env:mustUnderstand="true">   <n:name>Åke Jógvan Øyvind</n:name>  </n:passenger> </env:Header> <env:Body>  <p:itinerary      xmlns:p="http://travelcompany.example.org/reservation/travel">   <p:departure>     <p:departing>New York</p:departing>     <p:arriving>Los Angeles</p:arriving>     <p:departureDate>2001-12-14</p:departureDate>     <p:departureTime>late afternoon</p:departureTime>     <p:seatPreference>aisle</p:seatPreference>   </p:departure>   <p:return>     <p:departing>Los Angeles</p:departing>     <p:arriving>New York</p:arriving>     <p:departureDate>2001-12-20</p:departureDate>     <p:departureTime>mid morning</p:departureTime>     <p:seatPreference/>   </p:return>  </p:itinerary>  <q:lodging      xmlns:q="http://travelcompany.example.org/reservation/hotels">   <q:preference>none</q:preference>  </q:lodging> </env:Body></env:Envelope>

SOAP message fromExample 1 carried in a SMTPmessage

Although an email is a one-way message exchange, and no guarantee ofdelivery is provided, email infrastructures like the Simple Mail TransportProtocol (SMTP) specification [SMTP] offer a deliverynotification mechanism which, in the case of SMTP, are called Delivery StatusNotification (DSN) and Message Disposition Notification (MDN). Thesenotifications take the form of email messages sent to the email addressspecified in the mail header. Applications, as well as email end users, canuse these mechanisms to provide the status of an email transmission, butthese, if delivered, are notifications at the SMTP level. The applicationdeveloper must fully understand the capabilities and limitations of thesedelivery notifications or risk assuming a successful data delivery when noneoccurred.

SMTP delivery status messages are separate from message processing at theSOAP layer. Resulting SOAP responses to the contained SOAP data will bereturned through a new email message which may or may not have a link to theoriginal requesting email at the SMTP level. The use of the [RFC 2822]In-reply-to: header can achieve acorrelation at the SMTP level, but does not necessarily offer a correlationat the SOAP level.

Example 15 is exactly the same scenario asdescribed forExample 2, which shows the SOAP message(body details omitted for brevity) sent from the travel service applicationto the travel reservation application seeking clarification on somereservation details, except that it is carried as an email message. In thisexample, the original email's Message-Id is carried in theadditional email headerIn-reply-to:, which correlates emailmessages at the SMTP level, but cannot provide a SOAP-specific correlation.In this example, the application relies on thereservationheader block to correlate SOAP messages. Again, how such correlation isachieved is application-specific, and is not within the scope of SOAP.

Example 15

From: reservations@travelcompany.example.orgTo: a.oyvind@mycompany.example.comSubject: Which NY airport?Date: Thu, 29 Nov 2001 13:35:11 ESTMessage-Id: <200109251753.NAA10655@travelcompany.example.org>In-reply-to:<EE492E16A090090276D208424960C0C@mycompany.example.com>Content-Type: application/soap+xml<?xml version='1.0' ?><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">  <env:Header>  <m:reservation xmlns:m="http://travelcompany.example.org/reservation"      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"       env:mustUnderstand="true">   <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference>   <m:dateAndTime>2001-11-29T13:35:00.000-05:00</m:dateAndTime>  </m:reservation>  <n:passenger xmlns:n="http://mycompany.example.com/employees"      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"        env:mustUnderstand="true">   <n:name>Åke Jógvan Øyvind</n:name>  </n:passenger> </env:Header> <env:Body>  <p:itinerary     xmlns:p="http://travelcompany.example.org/reservation/travel">   <p:itineraryClarifications>      ...      ...   </p:itineraryClarifications>  </p:itinerary> </env:Body></env:Envelope>

SOAP message fromExample 2 carried in an emailmessage with a header correlating it to a previous message.

5. Advanced Usage Scenarios

5.1 Using SOAP Intermediaries

The travel reservation scenario used throughout the primer offers anopportunity to expose some uses of SOAP intermediaries. Recall that the basicexchange was the exchange of a travel reservation request between a travelreservation application and a travel service application. SOAP does notspecify how such a message path is determined and followed. That is outsidethe scope of the SOAP specification. It does describe, though, how a SOAPnode should behave if it receives a SOAP message for which it is not theultimate receiver. SOAP Version 1.2 describes two types of intermediaries:forwardingintermediaries andactiveintermediaries.

Aforwardingintermediary is a SOAP node which, based on the semantics of a headerblock in a received SOAP message or based on the message exchange pattern inuse, forwards the SOAP message to another SOAP node. For example, processinga "routing" header block describing a message path feature in an incomingSOAP message may dictate that the SOAP message be forwarded to another SOAPnode identified by data in that header block. The format of the SOAP headerof the outbound SOAP message, i.e., the placement of inserted or reinsertedheader blocks, is determined by the overall processing at thisforwarding intermediary based on the semantics of the processedheader blocks.

Anactiveintermediary is one that does additional processing on an incoming SOAPmessage before forwarding the message using criteria that are not describedby incoming SOAP header blocks, or by the message exchange pattern in use.Some examples of such active intervention at a SOAP node could be, forinstance, encrypting some parts of a SOAP message and providing theinformation on the cipher key in a header block, or including some additionalinformation in a new header block in the outbound message providing atimestamp or an annotation, for example, for interpretation by appropriatelytargeted nodes downstream.

One mechanism by which an active intermediary can describe themodifications performed on a message is by inserting header blocks into theoutbound SOAP message. These header blocks can inform downstream SOAP nodesacting in roles whose correct operation depends on receiving suchnotification. In this case, the semantics of such inserted header blocksshould also call for either the same or other header blocks to be(re)inserted at subsequent intermediaries as necessary to ensure that themessage can be safely processed by nodes yet further downstream. For example,if a message with header blocks removed for encryption passes through asecond intermediary (without the original header blocks being decrypted andreconstructed), then indication that the encryption has occurred must beretained in the second relayed message.

In the following example, a SOAP node is introduced in the message pathbetween the travel reservation and travel service applications, whichintercepts the message shown inExample 1. An exampleof such a SOAP node is one which logs all travel requests for off-line reviewby a corporate travel office. Note that the header blocksreservation andpassenger in that example areintended for the node(s) that assume the role "next", which means that it istargeted at the next SOAP node in the message path that receives the message.The header blocks are mandatory (themustUnderstand attribute isset to "true"), which means that the node must have knowledge (through anexternal specification of the header blocks' semantics) of what to do. Alogging specification for such header blocks might simply require thatvarious details of the message be recorded at every node that receives such amessage, and that the message be relayed along the message path unchanged.(Note that the specifications of the header blocks must require that the sameheader blocks be reinserted in the outbound message, because otherwise, theSOAP processing model would require that they be removed.) In this case, theSOAP node acts as a forwarding intermediary.

A more complex scenario is one where the received SOAP message is amendedin some way not anticipated by the initial sender. In the following example,it is assumed that a corporate travel application at the SOAP intermediaryattaches a header block to the SOAP message fromExample1 before relaying it along its message path towards the travel serviceapplication - the ultimate recipient. The header block contains theconstraints imposed by a travel policy for this requested trip. Thespecification of such a header block might require that the ultimaterecipient (and only the ultimate recipient, as implied by the absence of therole attribute) make use of the information conveyed by it whenprocessing the body of the message.

Example 16 shows an active intermediary insertingan additional header block,travelPolicy, intended for theultimate recipient which includes information that qualifies theapplication-level processing of this travel request.

Example 16

<?xml version='1.0' ?><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">  <env:Header>  <m:reservation xmlns:m="http://travelcompany.example.org/reservation"      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"        env:mustUnderstand="true">   <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference>   <m:dateAndTime>2001-11-29T13:20:00.000-05:00</m:dateAndTime>  </m:reservation>  <n:passenger xmlns:n="http://mycompany.example.com/employees"     env:role="http://www.w3.org/2003/05/soap-envelope/role/next"       env:mustUnderstand="true">   <n:name>Åke Jógvan Øyvind</n:name>  </n:passenger><z:travelPolicy     xmlns:z="http://mycompany.example.com/policies"       env:mustUnderstand="true">   <z:class>economy</z:class>   <z:fareBasis>non-refundable<z:fareBasis>   <z:exceptions>none</z:exceptions></z:travelPolicy> </env:Header> <env:Body>  <p:itinerary     xmlns:p="http://travelcompany.example.org/reservation/travel">   <p:departure>     <p:departing>New York</p:departing>     <p:arriving>Los Angeles</p:arriving>     <p:departureDate>2001-12-14</p:departureDate>     <p:departureTime>late afternoon</p:departureTime>     <p:seatPreference>aisle</p:seatPreference>   </p:departure>   <p:return>     <p:departing>Los Angeles</p:departing>     <p:arriving>New York</p:arriving>     <p:departureDate>2001-12-20</p:departureDate>     <p:departureTime>mid morning</p:departureTime>     <p:seatPreference/>   </p:return>  </p:itinerary>  <q:lodging     xmlns:q="http://travelcompany.example.org/reservation/hotels">   <q:preference>none</q:preference>  </q:lodging> </env:Body></env:Envelope>

SOAP message fromExample 1 for a travel reservationafter an active intermediary has inserted a mandatory header intended for theultimate recipient of the message

5.2 Using Other Encoding Schemes

Even though SOAP Version 1.2 defines a particular encoding scheme (see SOAP Part2 section 3), its use is optional and the specification makes clear thatother encoding schemes may be used for application-specific data within aSOAP message. For this purpose it provides the attributeenv:encodingStyle, of typexs:anyURI, toqualify header blocks, any child elements of the SOAPenv:Body,and any child elements of theenv:Detail element and theirdescendants. It signals a serialization scheme for the nested contents, or atleast the one in place until another element is encountered which indicatesanother encoding style for its nested contents. The choice of the value fortheenv:encodingStyle attribute is an application-specificdecision and the ability to interoperate is assumed to have been settled"out-of-band". If this attribute is not present, then no claims are beingmade about the encoding being used.

The use of an alternative encoding scheme is illustrated inExample 17. Continuing with the travel reservationtheme, this example shows a SOAP message which is sent to the passenger fromthe travel service after the reservation is confirmed, showing the traveldetails.(The same message was used inExample 8b in another context.)

Example 17

<?xml version='1.0' ?><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">  <env:Header>  <m:reservation xmlns:m="http://travelcompany.example.org/reservation"      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"        env:mustUnderstand="true">   <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference>   <m:dateAndTime>2001-11-30T16:25:00.000-05:00</m:dateAndTime>  </m:reservation> </env:Header> <env:Body>  <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"            xmlns:x="http://travelcompany.example.org/vocab#"env:encodingStyle="http://www.w3.org/1999/02/22-rdf-syntax-ns#">   <x:ReservationRequest  rdf:about="http://travelcompany.example.org/reservations?code=FT35ZBQ">      <x:passenger>Åke Jógvan Øyvind</x:passenger>      <x:outbound>       <x:TravelRequest>        <x:to>LAX</x:to>        <x:from>LGA</x:from>        <x:date>2001-12-14</x:date>       </x:TravelRequest>      </x:outbound>      <x:return>       <x:TravelRequest>        <x:to>JFK</x:to>        <x:from>LAX</x:from>        <x:date>2001-12-20</x:date>       </x:TravelRequest>      </x:return>    </x:ReservationRequest>  </rdf:RDF> </env:Body></env:Envelope>

SOAP message showing the use of an alternative encoding for theBody element

InExample 17, the body of the SOAP messagecontains a description of the itinerary using the encoding of a graph ofresources and their properties using the syntax of the Resource DescriptionFramework (RDF) [RDF]. (Very briefly, as RDF syntax orusage is not the subject of this primer, an RDF graph relates resources -such as the travel reservation resource available athttp://travelcompany.example.org/reservations?code=FT35ZBQ - toother resources (or values) via properties, such as thepassenger, theoutbound andreturndates of travel. The RDF encoding for the itinerary might have been chosen,for example, to allow the passenger's travel application to store it in anRDF-capable calendar application, which could then be queried in complexways.)

6. Changes Between SOAP 1.1 and SOAP1.2

SOAP Version 1.2 has a number of changes in syntax and provides additional(or clarified) semantics from those described in [SOAP1.1]. The following is a list of features where the two specificationsdiffer. The purpose of this list is to provide the reader with a quick andeasily accessible summary of the differences between the two specifications.The features have been put in categories purely for ease of reference, and insome cases, an item might equally well have been placed in anothercategory.

SOAPPart 1 Appendix A provides version management rules for a SOAP node thatcan support the version transition from [SOAP 1.1] to SOAPVersion 1.2. In particular, in defines anenv:Upgradeheader block which can be used by a SOAP 1.2 node on receipt of a [SOAP 1.1] message to send a SOAP fault message to theoriginator to signal which version of SOAP it supports.

7. References

[SOAP Part1] W3C Recommendation "SOAP 1.2 Part 1:Messaging Framework", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau,Henrik Frystyk Nielsen, 24 June 2003 (Seehttp://www.w3.org/TR/2003/REC-soap12-part1-20030624/.)

[SOAP Part2] W3C Recommendation "SOAP 1.2 Part 2:Adjuncts", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, HenrikFrystyk Nielsen, 24 June 2003 (Seehttp://www.w3.org/TR/2003/REC-soap12-part2-20030624.)

[RFC 2396] IETF"RFC2396: Uniform Resource Identifiers (URI): Generic Syntax", T.Berners-Lee, R. Fielding, L. Masinter, August 1998. (Seehttp://www.ietf.org/rfc/rfc2396.txt.)

[HTTP 1.1] IETF"RFC2616: Hypertext Transfer Protocol -- HTTP/1.1", R. Fielding, J. Gettys,J. C. Mogul, H. Frystyk, T. Berners-Lee, January 1997. (Seehttp://www.ietf.org/rfc/rfc2616.txt.)

[XML 1.0] W3CRecommendation "Extensible Markup Language(XML) 1.0 (Second Edition)", Tim Bray, Jean Paoli, C. M.Sperberg-McQueen, Eve Maler, 6 October 2000. (Seehttp://www.w3.org/TR/2000/REC-xml-20001006.

[Namespaces in XML] W3C Recommendation "Namespaces inXML", Tim Bray, Dave Hollander, Andrew Layman, 14 January 1999. (Seehttp://www.w3.org/TR/1999/REC-xml-names-19990114/.)

[XML Schema Part1] W3CRecommendation "XML Schema Part1: Structures", Henry S. Thompson, David Beech, Murray Maloney, NoahMendelsohn, 2 May 2001. (Seehttp://www.w3.org/TR/2001/REC-xmlschema-1-20010502/)

[XML Schema Part2] W3CRecommendation "XML Schema Part2: Datatypes", Paul V. Biron, Ashok Malhotra, 2 May 2001. (Seehttp://www.w3.org/TR/2001/REC-xmlschema-2-20010502/)

[SMTP] SMTP is defined in aseries of RFCs:

RFC 2822 Internet Message Format. (Seehttp://www.ietf.org/rfc/rfc2822.txt.)
RFC 2045 Multipurpose Internet Mail Extensions (MIME) Part One:Format of Internet Message Bodies. (Seehttp://www.ietf.org/rfc/rfc2045.txt.)
RFC 2046 Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. (Seehttp://www.ietf.org/rfc/rfc2046.txt.)
RFC 1894 An Extensible Message Format for Delivery Status Notifications. (Seehttp://www.ietf.org/rfc/rfc1894.txt.)
RFC 2852 Deliver By SMTP Service Extension. (Seehttp://www.ietf.org/rfc/rfc2852.txt.)
RFC 2298 An Extensible Message Format for Message Disposition Notifications. (Seehttp://www.ietf.org/rfc/rfc2298.txt.)

[RDF] W3C Recommendation"ResourceDescription Framework (RDF) Model and Syntax Specification", O. Lassilaand R. Swick, Editors. World Wide Web Consortium. 22 February 1999. (Seehttp://www.w3.org/TR/REC-rdf-syntax.)

[SOAP 1.1] W3C Note "Simple Object Access Protocol (SOAP)1.1", Don Boxet al., 8 May, 2000 (Seehttp://www.w3.org/TR/SOAP/)

[XML Infoset] W3CRecommendation "XML InformationSet", John Cowan, Richard Tobin, 24 October 2001. (Seehttp://www.w3.org/TR/xml-infoset/)

[SOAP MediaType] IETF InternetDraft "The 'application/soap+xml' media type", M. Baker, M. Nottingham,"draft-baker-soap-media-reg-03.txt", May 29, 2003. (Seehttp://www.ietf.org/internet-drafts/draft-baker-soap-media-reg-03.txt, note that this Internet Draft expires in November 2003)

[SOAP Email Binding] W3CNote "SOAPVersion 1.2 Email Binding", Highland Mary Mountain et al, draft June 13,2002. (Seehttp://www.w3.org/TR/2002/NOTE-soap12-email-20020626.)

[XML Base] W3CRecommendation "XMLBase", Jonathan Marsh, 27 June 2001. (Seehttp://www.w3.org/TR/2001/REC-xmlbase-20010627/)

[RFC 2119] IETF "RFC 2119: Key wordsfor use in RFCs to Indicate Requirement Levels", S. Bradner, March 1997. (Seehttp://www.ietf.org/rfc/rfc2119.txt.)

A. Acknowledgements

Highland Mary Mountain (Intel) provided the initial material for thesection on the SMTP binding. Paul Denning provided material for a usagescenario, which has since been moved to the SOAP Version 1.2 Usage ScenariosWorking Draft. Stuart Williams, Oisin Hurley, Chris Ferris, Lynne Thompson,John Ibbotson, Marc Hadley, Yin-Leng Husband and Jean-Jacques Moreau provideddetailed comments on earlier versions of this document, as did many othersduring the Last Call Working Draft review. Jacek Kopecky provided a list ofRPC and SOAP encoding changes.

Participants in the Working Group are (at the time of writing, and byalphabetical order): Carine Bournez (W3C), Michael Champion (Software AG),Glen Daniels (Macromedia, formerly of Allaire), David Fallside (IBM, Chair), Dietmar Gaertner (Software AG), Tony Graham (Sun Microsystems), Martin Gudgin(Microsoft Corporation, formerly of DevelopMentor), Marc Hadley (SunMicrosystems), Gerd Hoelzing (SAP AG), Oisin Hurley (IONA Technologies), JohnIbbotson (IBM), Ryuji Inoue (Matsushita Electric), Kazunori Iwasa (FujitsuLimited), Mario Jeckle (DaimlerChrysler R. & Tech), Mark Jones(AT&T), Anish Karmarkar (Oracle), Jacek Kopecky (Systinet/Idoox), YvesLafon (W3C), Michah Lerner (AT&T), Noah Mendelsohn (IBM, formerly ofLotus Development), Jeff Mischkinsky (Oracle), Nilo Mitra (Ericsson),Jean-Jacques Moreau (Canon), Masahiko Narita (FujitsuLimited), Eric Newcomer (IONA Technologies), Mark Nottingham (BEA Systems,formerly of Akamai Technologies), David Orchard (BEA Systems, formerly ofJamcracker), Andreas Riegg (DaimlerChrysler R. & Tech), Hervé Ruellan(Canon), Jeff Schlimmer (Microsoft Corporation), Miroslav Simek(Systinet/Idoox), Pete Wenzel (SeeBeyond), Volker Wiechers (SAP AG).

Previous participants were: Yasser alSafadi (Philips Research), BillAnderson (Xerox), Vidur Apparao (Netscape), Camilo Arbelaez (WebMethods),Mark Baker (Idokorro Mobile (Planetfred), formerly of Sun Microsystems),Philippe Bedu (EDF (Electricité de France)), Olivier Boudeville (EDF(Electricité de France)), Don Box (Microsoft Corporation, formerly ofDevelopMentor), Tom Breuel (Xerox), Dick Brooks (Group 8760), Winston Bumpus(Novell), David Burdett (Commerce One), Charles Campbell (Informix Software),Alex Ceponkus (Bowstreet), David Chappell (Sonic Software), Miles Chaston (Epicentric), David Clay (Oracle),David Cleary (Progress Software), Conleth O'Connell (Vignette), Ugo Corda(Xerox), Paul Cotton (Microsoft Corporation), Fransisco Cubera (IBM), Jimd'Augustine (eXcelon), Ron Daniel (Interwoven), Dug Davis (IBM), RayDenenberg (Library of Congress), Paul Denning (MITRE), Frank DeRose (Tibco),Mike Dierken (DataChannel), Andrew Eisenberg (Progress Software), BrianEisenberg (DataChannel), Colleen Evans (Sonic Software), John Evdemon (XMLSolutions), David Ezell(Hewlett-Packard), Eric Fedok (Active Data Exchange), Chris Ferris (SunMicrosystems), Daniela Florescu (Propel), Dan Frantz (BEA Systems), MichaelFreeman (Engenia Software), Scott Golubock (Epicentric), Rich Greenfield(Library of Congress), Hugo Haas (W3C), Mark Hale (Interwoven), Randy Hall(Intel), Bjoern Heckel (Epicentric), Erin Hoffman (Tradia), Steve Hole(MessagingDirect Ltd.), Mary Holstege (Calico Commerce), Jim Hughes (FujitsuSoftware Corporation), Yin-Leng Husband (Hewlett-Packard, formerly ofCompaq), Scott Isaacson (Novell), Murali Janakiraman (Rogue Wave), EricJenkins (Engenia Software), Jay Kasi (Commerce One), Jeffrey Kay (EngeniaSoftware), Richard Koo (Vitria Technology Inc.), Alan Kropp (Epicentric),Julian Kumar (Epicentric), Peter Lecuyer (Progress Software), Tony Lee(Vitria Technology Inc.), Amy Lewis (TIBCO), Bob Lojek (Intalio), Henry Lowe(OMG), Brad Lund (Intel), Matthew MacKenzie (XMLGlobal Technologies), MurrayMaloney (Commerce One), Richard Martin (Active Data Exchange), Highland MaryMountain (Intel), Alex Milowski (Lexica), Kevin Mitchell (XMLSolutions), EdMooney (Sun Microsystems), Dean Moses (Epicentric), Don Mullen (TIBCO), Rekha Nagarajan (CalicoCommerce), Raj Nair (Cisco), Mark Needleman (Data Research Associates), ArtNevarez (Novell), Henrik Nielsen (Microsoft Corporation), Kevin Perkins(Compaq), Jags Ramnaryan (BEA Systems), Vilhelm Rosenqvist (NCR), MarwanSabbouh (MITRE), Waqar Sadiq (Vitria Technology Inc.), Rich Salz (Zolera),Krishna Sankar (Cisco), George Scott (Tradia), Shane Sesta (Active DataExchange), Lew Shannon (NCR), John-Paul Sicotte (MessagingDirect Ltd.),Simeon Simeonov (Allaire), Simeon Simeonov (Macromedia), Aaron Skonnard(DevelopMentor), Nick Smilonich (Unisys), Soumitro Tagore (Informix Software), James Tauber(Bowstreet), Lynne Thompson (Unisys), Patrick Thompson (Rogue Wave), Jim Trezzo (Oracle), AsirVedamuthu (WebMethods), Randy Waldrop (WebMethods), Fred Waskiewicz (OMG),David Webber (XMLGlobal Technologies), Ray Whitmer (Netscape), StuartWilliams (Hewlett-Packard), Yan Xu (DataChannel), Amr Yassin (PhilipsResearch), Susan Yee (Active Data Exchange), Jin Yu (Martsoft).

We also wish to thank all the people who have contributed to discussionsonxml-dist-app@w3.org.