备忘录：SOAP 1.2

http://www.w3.org/TR/soap12-part0/

http://www.w3.org/TR/soap12-part1/

http://www.w3.org/TR/soap12-part2/

 

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

2, The simplest such exchange is a request-response pattern. Some early uses of [SOAP 1.1] emphasized the use of this pattern as means for conveying remote procedure calls (RPC), but it is important to note that not all SOAP request-response exchanges can or need to be modelled as RPCs. The latter is used when there is a need to model a certain programmatic behavior, with the exchanged messages conforming to a pre-defined description of the remote call and its return.

3, A much larger set of usage scenarios than that covered by the request-response pattern can be modeled simply as XML-based content exchanged in SOAP messages to form a back-and-forth "conversation", where the semantics are at the level of the sending and receiving applications.

4, the return value is identified by the element rpc:result, and contains the XML Qualified Name (of type xs:QName) of another element within the struct which is m:status. This, in turn, contains the actual return value, "confirmed". This technique allows the actual return value to be strongly typed according to some schema. If the rpc:result element is absent, the return value is not present or is of the type void.

5, Note that the env:Body element does not have a env:role attribute. The body element is always targeted at the SOAP node that assumes the "ultimateReceiver" role.

6, SOAP does not prescribe any structure for the env:Body element, except that it recommends that any sub-elements be XML namespace qualified.

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

Role absent "none" "next" "ultimateReceiver" Node         initial sender not applicable not applicable not applicable not applicable intermediary no no yes no ultimate receiver yes no yes yes

8, The following table summarizes how the processing actions for a header block are qualified by the env:mustUnderstand attribute with respect to a node that has been appropriately targeted (via the env:role attribute).

Node intermediary ultimate receiver mustUnderstand     "true" must process must process "false" may process may process absent may process may process

9, However, whether a generated fault can be propagated appropriately depends on the underlying protocol binding chosen for the SOAP message message exchange. The specification does not define what happens if faults are generated during the propagation of one-way messages. The only normative underlying protocol binding, which is the SOAP HTTP binding, offers the HTTP response as a means for reporting a fault in the incoming SOAP message.

10. SOAP Version 1.2 defines another optional attribute for header blocks, env:relay of type xs:boolean, which indicates if a header block targeted at a SOAP intermediary must be relayed if it is not processed. Note that if a header block is processed, the SOAP processing rules (see SOAP Part 1 section 2.7.2) requires that it be removed from the outbound message. (It may, however, be reinserted, either unchanged or with its contents altered, if the processing of other header blocks determines that the header block be retained in the forwarded message.) The default behavior for an unprocessed header block targeted at a role played by a SOAP intermediary is that it must be removed before the message is relayed.

11. The specification of a feature implemented using SOAP header blocks is called a SOAP module.

12. As the HTTP SOAP GET usage does not allow for a SOAP message in the request, applications that need features in the outbound interaction that can only be supported by a binding-specific expression within the SOAP infoset (i.e., as SOAP header blocks) obviously cannot make use of this message exchange pattern. Note that the HTTP POST binding is available for use in all cases.

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

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

15. It also requires the use of the SOAP Request-Response message exchange pattern implemented via a HTTP POST if the RPC description includes data (parameters) which are not resource-identifying. Even in this case, the HTTP POST with a SOAP message can be represented in a Web-friendly manner.

16. In other words, as seen from the above examples, the recommendation in the SOAP specifications is to use URIs in a Web-architecture compatible way - that is, as resource identifiers - whether or not it is GET or POST that is used.

 

17. Changes Between SOAP 1.1 and SOAP 1.2

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

Document structure

• The SOAP 1.2 specifications have been provided in two parts. [SOAP Part1] provides an abstract Infoset-based definition of the SOAP message structure, a processing model and an underlying protocol binding framework, while [SOAP Part2] provides serialization rules for conveying that infoset as well as a particular HTTP binding.
• SOAP 1.2 will not spell out the acronym.
• SOAP 1.2 has been rewritten in terms of XML infosets, and not as serializations of the form <?xml....?> required by SOAP 1.1.

Additional or changed syntax

• SOAP 1.2 does not permit any element after the body. The SOAP 1.1 schema definition allowed for such a possibility, but the textual description is silent about it.
• SOAP 1.2 does not allow the env:encodingStyle attribute to appear on the SOAP env:Envelope, whereas SOAP 1.1 allows it to appear on any element. SOAP 1.2 specifies specific elements where this attribute may be used.
• SOAP 1.2 defines the new env:NotUnderstood header element for conveying information on a mandatory header block which could not be processed, as indicated by the presence of an env:MustUnderstand fault code. SOAP 1.1 provided the fault code, but no details on its use.
• In the SOAP 1.2 infoset-based description, the env:mustUnderstand attribute in header elements takes the (logical) value "true" or "false", whereas in SOAP 1.1 they are the literal value "1" or "0" respectively.
• SOAP 1.2 provides a new fault code DataEncodingUnknown.
• The various namespaces defined by the two protocols are of course different.
• SOAP 1.2 replaces the attribute env:actor with env:role but with essentially the same semantics.
• SOAP 1.2 defines a new attribute, env:relay, for header blocks to indicate if unprocessed header blocks should be forwarded.
• SOAP 1.2 defines two new roles, "none" and "ultimateReceiver", together with a more detailed processing model on how these behave.
• SOAP 1.2 has removed the "dot" notation for fault codes, which are now simply an XML Qualified Name, where the namespace prefix is the SOAP envelope namespace.
• SOAP 1.2 replaces "client" and "server" fault codes with "Sender" and "Receiver".
• SOAP 1.2 uses the element names env:Code and env:Reason, respectively, for what used to be called faultcode and faultstring in SOAP 1.1. SOAP 1.2 also allows multiple env:Text child elements of env:Reason qualified by xml:lang to allow multiple language versions of the fault reason.
• SOAP 1.2 provides a hierarchical structure for the mandatory SOAP env:Code sub-element in the env:Fault element, and introduces two new optional subelements, env:Node and env:Role.
• SOAP 1.2 removes the distinction that was present in SOAP 1.1 between header and body faults as indicated by the presence of the env:Details element in env:Fault. In SOAP 1.2, the presence of the env:Details element has no significance as to which part of the fault SOAP message was processed.
• SOAP 1.2 uses XML Base [XML Base] for determining a base URI for relative URI references whereas SOAP 1.1 is silent about the matter.

SOAP HTTP binding

• In the SOAP 1.2 HTTP binding, the SOAPAction HTTP header defined in SOAP 1.1 has been removed, and a new HTTP status code 427 has been sought from IANA for indicating (at the discretion of the HTTP origin server) that its presence is required by the server application. The contents of the former SOAPAction HTTP header are now expressed as a value of an (optional) "action" parameter of the "application/soap+xml" media type that is signaled in the HTTP binding.
• In the SOAP 1.2 HTTP binding, the Content-type header should be "application/soap+xml" instead of "text/xml" as in SOAP 1.1. The IETF registration for this new media type is pending [SOAP MediaType].
• SOAP 1.2 provides a finer grained description of use of the various 2xx, 3xx, 4xx HTTP status codes.
• Support of the HTTP extensions framework has been removed from SOAP 1.2.
• SOAP 1.2 provides an additional message exchange pattern which may be used as a part of the HTTP binding that allows the use of HTTP GET for safe and idempotent information retrievals.

RPC

• SOAP 1.2 provides a rpc:result element accessor for RPCs.
• SOAP 1.2 provides several additional fault codes in the RPC namespace.
• SOAP 1.2 offers guidance on a Web-friendly approach to defining RPCs where the procedure's purpose is purely "safe" informational retrieval.

SOAP encodings

• An abstract data model based on a directed edge labeled graph has been formulated for SOAP 1.2. The SOAP 1.2 encodings are dependent on this data model. The SOAP RPC conventions are dependent on this data model, but have no dependencies on the SOAP encoding. Support of the SOAP 1.2 encodings and SOAP 1.2 RPC conventions are optional.
• The syntax for the serialization of an array has been changed in SOAP 1.2 from that in SOAP 1.1.
• The support provided in SOAP 1.1 for partially transmitted and sparse arrays is not available in SOAP 1.2.
• SOAP 1.2 allows the inline (embedded) serialization of multiref values.
• The href attribute in SOAP 1.1 (of type xs:anyURI) is called enc:ref in SOAP 1.2 and is of type IDREF.
• In SOAP 1.2, omitted accessors of compound types are made equal to NILs.
• SOAP 1.2 provides several fault sub-codes for indicating encoding errors.
• Types on nodes are made optional in SOAP 1.2.
• SOAP 1.2 has removed generic compound values from the SOAP Data Model.
• SOAP 1.2 has added an optional attribute enc:nodeType to elements encoded using SOAP encoding that identifies its structure (i.e., a simple value, a struct or an array).