You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
3952 lines
203 KiB
3952 lines
203 KiB
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>SOAP Version 1.2 Part 0: Primer (Second Edition)</title><style type="text/css">
|
|
code { font-family: monospace; }
|
|
|
|
div.constraint,
|
|
div.issue,
|
|
div.note,
|
|
div.notice { margin-left: 2em; }
|
|
|
|
|
|
|
|
.diff-chg { background-color: #E47833;; }
|
|
.diff-del { background-color: red; text-decoration: line-through;}
|
|
.diff-add { background-color: lime; }
|
|
|
|
table { empty-cells: show; }
|
|
|
|
|
|
div.exampleInner pre { margin-left: 1em;
|
|
margin-top: 0em; margin-bottom: 0em}
|
|
div.exampleOuter {border: 4px double gray;
|
|
margin: 0em; padding: 0em}
|
|
div.exampleInner { background-color: #d5dee3;
|
|
border-top-width: 4px;
|
|
border-top-style: double;
|
|
border-top-color: #d3d3d3;
|
|
border-bottom-width: 4px;
|
|
border-bottom-style: double;
|
|
border-bottom-color: #d3d3d3;
|
|
padding: 4px; margin: 0em }
|
|
div.exampleWrapper { margin: 4px }
|
|
div.exampleHeader { font-weight: bold;
|
|
margin: 4px}
|
|
</style><link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-REC.css"></head><body>
|
|
<div class="head"><p><a href="http://www.w3.org/"><img src="http://www.w3.org/Icons/w3c_home" alt="W3C" height="48" width="72"></a></p>
|
|
<h1>SOAP Version 1.2 Part 0: Primer (Second Edition)</h1>
|
|
<h2>W3C Recommendation 27 April 2007</h2><dl><dt>This version:</dt><dd><a href="http://www.w3.org/TR/2007/REC-soap12-part0-20070427/">http://www.w3.org/TR/2007/REC-soap12-part0-20070427/</a></dd><dt>Latest version:</dt><dd><a href="http://www.w3.org/TR/soap12-part0/">http://www.w3.org/TR/soap12-part0/</a></dd><dt>Previous versions:</dt><dd><a href="http://www.w3.org/TR/2006/PER-soap12-part0-20061219/">http://www.w3.org/TR/2006/PER-soap12-part0-20061219/</a></dd><dt>Editors:</dt>
|
|
<dd>Nilo Mitra, Ericsson</dd>
|
|
<dd>Yves Lafon, W3C</dd>
|
|
</dl><p>Please refer to the <a href="http://www.w3.org/2007/04/REC-soap12-part0-20070427-errata.html"><strong>errata</strong></a> for this document, which may
|
|
include normative corrections.</p>
|
|
<p>See also <a href="http://www.w3.org/2003/03/Translations/byTechnology?technology=soap12-part0"> translations</a>.</p>
|
|
<p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2007 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.org/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p></div><hr><div>
|
|
<h2><a name="abstract">Abstract</a></h2>
|
|
|
|
|
|
|
|
<p>SOAP Version 1.2 Part 0: Primer (Second Edition) is a non-normative document intended to
|
|
provide an easily understandable tutorial on the features of SOAP Version
|
|
1.2. In particular, it describes the features through various usage
|
|
scenarios, and is intended to complement the normative text contained in <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427">Part 1</a> and <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427">Part 2</a> of the
|
|
SOAP 1.2 specifications. This second edition includes additional material on
|
|
the SOAP Message Transmission Optimization Mechanism (MTOM), the XML-binary
|
|
Optimized Packaging (XOP) and the Resource Representation SOAP Header Block
|
|
(RRSHB) specifications.</p>
|
|
</div><div>
|
|
<h2><a name="status">Status of this Document</a></h2>
|
|
|
|
<p><em>This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/">W3C technical reports index</a> at http://www.w3.org/TR/.</em></p>
|
|
|
|
<p>This document is a <a href="http://www.w3.org/2005/10/Process-20051014/tr.html#RecsW3C">W3C Recommendation</a>. It has been produced by the <a href="http://www.w3.org/2000/xp/Group/">XML Protocol Working Group</a>, which
|
|
is part of the <a href="http://www.w3.org/2002/ws/Activity">Web Services
|
|
Activity</a>.
|
|
This second edition is not a new version of the SOAP1.2 Primer. Rather, as a convenience to readers, it incorporates the changes reflected in the accumulated <a href="http://www.w3.org/2003/06/REC-soap12-20030624-errata.html#Errata0">errata</a> to the <a href="http://www.w3.org/TR/2003/REC-soap12-part0-20030624/">original Recommendation</a>. Additionally, it incorporates changes to incorporate an overview of the <a href="http://www.w3.org/TR/2005/REC-xop10-20050125/">XML-binary Optimized Packaging</a>, <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/">SOAP Message Transmission Optimization Mechanism</a> and <a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/">Resource Representation SOAP Header Block</a> specifications and their usage. Changes between these two versions are described in a
|
|
<a href="diff-part0.html">diff document</a>.</p>
|
|
|
|
<p>This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited 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 functionality and interoperability of the Web.</p>
|
|
|
|
<p>Please report errors in this document to the public mailing list <a href="mailto:xmlp-comments@w3.org">xmlp-comments@w3.org</a>
|
|
(<a href="http://lists.w3.org/Archives/Public/xmlp-comments/">archive</a>).
|
|
It is inappropriate to send discussion email to this address.</p>
|
|
|
|
<p>Since the primary purpose of this specification is to present a set of
|
|
SOAP Version 1.2 specifications and fonctionalities, no implementation report is provided. However, the SOAP 1.2 Implementation Report can be found at <a href="http://www.w3.org/2000/xp/Group/2/03/soap1.2implementation.html">
|
|
http://www.w3.org/2000/xp/Group/2/03/soap1.2implementation.html</a> and the
|
|
SOAP MTOM/XOP/RRSHB Implementation/Interop Summary can be found at <a href="http://www.w3.org/2000/xp/Group/4/08/implementation.html">http://www.w3.org/2000/xp/Group/4/08/implementation.html</a>.</p>
|
|
|
|
<p> This document is governed by the <a href="http://www.w3.org/TR/2002/NOTE-patent-practice-20020124">24 January 2002 CPP</a> as amended by the <a href="http://www.w3.org/2004/02/05-pp-transition">W3C Patent Policy Transition Procedure</a>. This document is informative only. W3C maintains a <a rel="disclosure" href="http://www.w3.org/2000/xp/Group/2/10/16-IPR-statements.html">public list of any patent disclosures</a> made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the W3C Patent Policy</a>. </p>
|
|
|
|
<p>A list of current <a href="http://www.w3.org/TR/">W3C Recommendations and
|
|
other technical reports</a> can be found at <a href="http://www.w3.org/TR">http://www.w3.org/TR</a>.</p>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
<hr><div class="toc">
|
|
<h2><a name="shortcontents">Short Table of Contents</a></h2><p class="toc">1. <a href="#intro">Introduction</a><br>2. <a href="#L1161">Basic Usage Scenarios</a><br>3. <a href="#L1244">SOAP Processing Model</a><br>4. <a href="#transport">Using Various Protocol Bindings</a><br>5. <a href="#L579">Advanced Usage Scenarios</a><br>6. <a href="#L4697">Changes Between SOAP 1.1 and SOAP 1.2</a><br>7. <a href="#L810">References</a><br>A. <a href="#L10313">Acknowledgements</a> (Non-Normative)<br></p></div><hr><div class="toc">
|
|
<h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#intro">Introduction</a><br> 1.1 <a href="#L1153">Overview</a><br> 1.2 <a href="#L1157">Notational Conventions</a><br>2. <a href="#L1161">Basic Usage Scenarios</a><br> 2.1 <a href="#L1165">SOAP Messages</a><br> 2.2 <a href="#L1177">SOAP Message Exchange</a><br> 2.2.1 <a href="#L977">Conversational Message Exchanges</a><br> 2.2.2 <a href="#L1185">Remote Procedure Calls</a><br> 2.3 <a href="#L11549">Fault Scenarios</a><br>3. <a href="#L1244">SOAP Processing Model</a><br> 3.1 <a href="#L1271">The "role" Attribute</a><br> 3.2 <a href="#L1474">The "mustUnderstand" Attribute</a><br> 3.3 <a href="#LL10047">The "relay" Attribute</a><br>4. <a href="#transport">Using Various Protocol Bindings</a><br> 4.1 <a href="#L10309">The SOAP HTTP Binding</a><br> 4.1.1 <a href="#L26854">SOAP HTTP GET Usage</a><br> 4.1.2 <a href="#L26866">SOAP HTTP POST Usage</a><br> 4.1.3 <a href="#L3677">Web Architecture Compatible SOAP Usage</a><br> 4.2 <a href="#SMTP">SOAP Over Email</a><br>5. <a href="#L579">Advanced Usage Scenarios</a><br> 5.1 <a href="#L635">Using SOAP Intermediaries</a><br> 5.2 <a href="#L3374">Using Other Encoding Schemes</a><br> 5.3 <a href="#L3360">Optimized serialization of SOAP messages</a><br> 5.3.1 <a href="#L3785">The Abstract SOAP Transmission Optimization Feature</a><br> 5.3.2 <a href="#L3787">The Optimized Transmission Serialization Format</a><br> 5.3.3 <a href="#L3791">Using the Resource Representation SOAP Header Block</a><br>6. <a href="#L4697">Changes Between SOAP 1.1 and SOAP 1.2</a><br>7. <a href="#L810">References</a><br></p>
|
|
<h3><a name="appendix" id="appendix">Appendix</a></h3><p class="toc">A. <a href="#L10313">Acknowledgements</a> (Non-Normative)<br></p></div><hr><div class="body">
|
|
<div class="div1">
|
|
|
|
<h2><a name="intro"></a>1. Introduction</h2>
|
|
|
|
<p>SOAP Version 1.2 Part 0: Primer (Second Edition) is a non-normative document intended to
|
|
provide an easily understandable tutorial on the features of the SOAP Version
|
|
1.2 specifications. Its purpose is to help a technically competent person
|
|
understand how SOAP may be used, by describing representative SOAP message
|
|
structures and message exchange patterns.</p>
|
|
|
|
<p>In particular, this primer describes the features of SOAP through various
|
|
usage scenarios, and is intended to complement the normative text contained
|
|
in <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/">SOAP
|
|
Version 1.2 Part 1: Messaging Framework</a> (hereafter <a href="#L1092">[SOAP
|
|
Part1]</a>), <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/">SOAP Version 1.2
|
|
Part 2: Adjuncts</a> (hereafter <a href="#L1098">[SOAP Part2]</a>), the <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/">SOAP Message
|
|
Transmission Optimization Mechanism</a> (MTOM) (hereafter <a href="#L9527">[MTOM]</a>), XML-binary Optimized Packaging <a href="#L3777">[XOP]</a> and the Resource Representation SOAP Header Block <a href="#L4299">[ResRep]</a> specifications.</p>
|
|
|
|
<p>It is expected that the reader has some familiarity with the basic syntax
|
|
of XML, including the use of XML namespaces and infosets, and Web concepts
|
|
such as URIs and HTTP. It is intended primarily for users of SOAP, such as
|
|
application designers, rather than implementors of the SOAP specifications,
|
|
although the latter may derive some benefit. This primer aims at highlighting
|
|
the essential features of SOAP Version 1.2, not at completeness in describing
|
|
every nuance or edge case. Therefore, there is no substitute for the main
|
|
specifications to obtain a fuller understanding of SOAP. To that end, this
|
|
primer provides extensive links to the main specifications wherever new
|
|
concepts are introduced or used.</p>
|
|
|
|
<p><a href="#L1092">[SOAP Part1]</a> defines the SOAP envelope, which is a
|
|
construct that defines an overall framework for representing the contents of
|
|
a SOAP message, identifying who should deal with all or part of it, and
|
|
whether handling such parts are optional or mandatory. It also defines a
|
|
protocol binding framework, which describes how the specification for a
|
|
binding of SOAP onto another underlying protocol may be written.</p>
|
|
|
|
<p><a href="#L1098">[SOAP Part2]</a> defines a data model for SOAP, a
|
|
particular encoding scheme for data types which may be used for conveying
|
|
remote procedure calls (RPC), as well as one concrete realization of the
|
|
underlying protocol binding framework defined in <a href="#L1092">[SOAP
|
|
Part1]</a>. This binding allows the exchange of SOAP messages either as
|
|
payload of a HTTP POST request and response, or as a SOAP message in the
|
|
response to a HTTP GET.</p>
|
|
|
|
<p><a href="#L9527">[MTOM] </a>describes an abstract feature for optimizing
|
|
the wire format of a SOAP message for certain type of content, as well as a
|
|
concrete implementation of it realized in an HTTP binding, while still
|
|
maintaining the modeling of a SOAP message as a single XML Infoset.</p>
|
|
|
|
<p><a href="#L3777">[XOP]</a>defines a convention for serializing more
|
|
efficiently an XML Infoset that has binary content.
|
|
<a href="#L9527">[MTOM]</a> makes use of the
|
|
[<a href="#L3777">XOP</a>] format for optimizing the transmission of SOAP
|
|
messages.</p>
|
|
|
|
<p><a href="#L4299">[ResRep]</a> specifies a SOAP header block which carries a
|
|
representation of a Web resource, which is needed for processing a SOAP
|
|
message but which a receiver would prefer not to or cannot obtain by
|
|
dereferencing the URI for the resource carried within the message.</p>
|
|
|
|
<p>This document (the primer) is not normative, which means that it does not
|
|
provide the definitive specification of SOAP Version 1.2 or the other
|
|
specifications cited above. The examples provided here are intended to
|
|
complement the formal specifications, and in any question of interpretation
|
|
the formal specifications naturally take precedence. The examples shown here
|
|
provide a subset of the uses expected for SOAP. In actual usage scenarios,
|
|
SOAP will most likely be a part of an overall solution, and there will no
|
|
doubt be other application-specific requirements which are not captured in
|
|
these examples.</p>
|
|
|
|
<div class="div2">
|
|
|
|
<h3><a name="L1153"></a>1.1 Overview</h3>
|
|
|
|
<p>SOAP Version 1.2 provides the definition of the XML-based information
|
|
which can be used for exchanging structured and typed information between
|
|
peers in a decentralized, distributed environment. <a href="#L1092">[SOAP
|
|
Part1]</a> explains that a SOAP message is formally specified as an XML
|
|
Information Set [<a href="#R12">XML Infoset</a>] (henceforth often simply
|
|
infoset), which provides an abstract description of its contents. Infosets
|
|
can have different on-the-wire representations (aka serializations), one
|
|
common example of which is as an XML 1.0 [<a href="#L3532">XML 1.0</a>]
|
|
document. However, other serializations are also possible, and <a href="#L9527">[MTOM]</a> using the [<a href="#L3777">XOP</a>] format offers
|
|
one mechanism for doing so for the cases where there is a need to optimize
|
|
the processing and size of the transmitted message.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p><a href="#L1161">Section 2</a> of this document provides an introduction
|
|
to the basic features of SOAP starting with the simplest usage scenarios,
|
|
namely a one-way SOAP message, followed by various request-response type
|
|
exchanges, including RPCs. Fault situations are also described.</p>
|
|
|
|
<p><a href="#L3631">Section 3</a> provides an overview of the SOAP processing
|
|
model, which describes the rules for initial construction of a message, rules
|
|
by which messages are processed when received at an intermediary or ultimate
|
|
destination, and rules by which portions of the message can be inserted,
|
|
deleted or modified by the actions of an intermediary.</p>
|
|
|
|
<p><a href="#transport">Section 4</a> of this document describes the ways in
|
|
which SOAP messages may be transported to realize various usage scenarios. It
|
|
describes the SOAP HTTP binding specified in <a href="#L1098">[SOAP
|
|
Part2]</a>, as well as an example of how SOAP messages may be conveyed in
|
|
email messages. As a part of the HTTP binding, it introduces two message
|
|
exchange patterns which are available to an application, one of which uses
|
|
the HTTP POST method, while the other uses HTTP GET. Examples are also
|
|
provided on how RPCs, in particular those that represent "safe" information
|
|
retrieval, may be represented in SOAP message exchanges in a manner that is
|
|
compatible with the architectural principles of the World Wide Web .</p>
|
|
|
|
<p><a href="#L579">Section 5</a> of this document provides a treatment of
|
|
various aspects of SOAP that can be used in more complex usage scenarios.
|
|
These include the extensibility mechanism offered through the use of header
|
|
elements, which may be targeted at specific intermediate SOAP nodes to
|
|
provide value-added services to communicating applications, using various
|
|
encoding schemes to serialize application-specific data in SOAP messages, and
|
|
the means to provide a more optimized serialization of a SOAP message under
|
|
certain circumstances.</p>
|
|
|
|
<p><a id="Section" href="#L4697" name="Section">Section 6</a> of this
|
|
document describes the changes from <a href="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/">SOAP Version 1.1</a> [<a href="#R11">SOAP 1.1</a>].</p>
|
|
|
|
<p><a href="#L810">Section 7</a> of this document provides references.</p>
|
|
|
|
<p>For ease of reference, terms and concepts used in this primer are
|
|
hyper-linked to their definition in the main specifications.</p>
|
|
|
|
</div>
|
|
|
|
<div class="div2">
|
|
|
|
<h3><a name="L1157"></a>1.2 Notational Conventions</h3>
|
|
|
|
<p>Throughout this primer, sample SOAP envelopes and messages are shown as
|
|
[<a href="#L3532">XML 1.0</a>] documents. <a href="#L1092">[SOAP Part1]</a>
|
|
explains that a SOAP message is formally specified as an [<a href="#R12">XML
|
|
InfoSet</a>], which is an abstract description of its contents. The
|
|
distinction between the SOAP message infosets and their representation as XML
|
|
documents is unlikely to be of interest to those using this primer as an
|
|
introduction to SOAP; those who do care (typically those who port SOAP to new
|
|
protocol bindings where the messages may have alternative representations)
|
|
should understand these examples as referring to the corresponding XML
|
|
infosets. Further elaboration of this point is provided in <a href="#transport">Section 4</a> of this document.</p>
|
|
|
|
<p>The namespace prefixes "env", "enc", "rpc", "rep", "xop" and "xmime"
|
|
used in the prose sections of this document are associated with the namespace
|
|
names "<a href="http://www.w3.org/2003/05/soap-envelope">http://www.w3.org/2003/05/soap-envelope</a>"
|
|
, "<a href="http://www.w3.org/2003/05/soap-encoding">http://www.w3.org/2003/05/soap-encoding</a>",
|
|
"<a href="http://www.w3.org/2003/05/soap-rpc">http://www.w3.org/2003/05/soap-rpc</a>",
|
|
<a href="http://www.w3.org/2004/08/representation">"http://www.w3.org/2004/08/representation",
|
|
"</a><a href="http://www.w3.org/2004/08/xop/include">http://www.w3.org/2004/08/xop/include</a>"
|
|
and "<a href="http://www.w3.org/2004/11/xmlmime">http://www.w3.org/2004/11/xmlmime</a>"
|
|
respectively.</p>
|
|
|
|
<p>The namespace prefixes "xs" and "xsi" used in the prose sections of this
|
|
document are associated with the namespace names
|
|
"http://www.w3.org/2001/XMLSchema" and
|
|
"http://www.w3.org/2001/XMLSchema-instance" respectively, both of which are
|
|
defined in the XML Schema specifications <a href="#R7">[XML Schema
|
|
Part1]</a>, <a href="#R8">[XML Schema Part2]</a>.</p>
|
|
|
|
<p>Note that the choice of any other namespace prefix is arbitrary and not
|
|
semantically significant.</p>
|
|
|
|
<p>Namespace URIs of the general form "http://example.org/..." and
|
|
"http://example.com/..." represent an application-dependent or
|
|
context-dependent URI <a href="#RFC3986">[RFC 3986]</a>.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="div1">
|
|
|
|
<h2><a name="L1161"></a>2. Basic Usage Scenarios</h2>
|
|
|
|
<p>A <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#encapsulation">
|
|
SOAP message</a> is fundamentally a one-way transmission between<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#concepts"> SOAP
|
|
nodes</a>, from a <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">
|
|
SOAP sender</a> to a <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">
|
|
SOAP receiver</a>, but SOAP messages are expected to be combined by
|
|
applications to implement more complex interaction patterns ranging from
|
|
request/response to multiple, back-and-forth "conversational" exchanges.</p>
|
|
|
|
<p>The primer starts by exposing the structure of a SOAP message and its
|
|
exchange in some simple usage scenarios based on a travel reservation
|
|
application. Various aspects of this application scenario will be used
|
|
throughout the primer. In this scenario, the travel reservation application
|
|
for an employee of a company negotiates a travel reservation with a travel
|
|
booking service for a planned trip. The information exchanged between the
|
|
travel reservation application and the travel service application is in the
|
|
form of SOAP messages.</p>
|
|
|
|
<p>The ultimate recipient of a SOAP message sent from the travel reservation
|
|
application is the travel service application, but it is possible that the
|
|
SOAP message may be "routed" through one or more <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">
|
|
SOAP intermediaries</a> which act in some way on the message. Some simple
|
|
examples of such SOAP intermediaries might be ones that log, audit or,
|
|
possibly, amend each travel request. Examples, and a more detailed discussion
|
|
of the behavior and role of SOAP intermediaries, is postponed to <a href="#L635">section 5.1</a>.</p>
|
|
|
|
<p><a href="#L1165">Section 2.1</a> describes a travel reservation request
|
|
expressed as a SOAP message, which offers the opportunity to describe the
|
|
various "parts" of a SOAP message.</p>
|
|
|
|
<p><a href="#L977">Section 2.2.1</a> continues the same scenario to show a
|
|
response from the travel service in the form of another SOAP message, which
|
|
forms a part of a conversational message exchange as the various choices
|
|
meeting the constraints of the travel request are negotiated.</p>
|
|
|
|
<p><a href="#L1185">Section 2.2.2</a> assumes that the various parameters of
|
|
the travel reservation have been accepted by the traveller, and an exchange -
|
|
modelled as a remote procedure call (RPC) - between the travel reservation
|
|
and the travel service applications confirms the payment for the
|
|
reservation.</p>
|
|
|
|
<p><a href="#L11549">Section 2.3</a> shows examples of fault handling.</p>
|
|
|
|
<div class="div2">
|
|
|
|
<h3><a name="L1165"></a>2.1 SOAP Messages</h3>
|
|
|
|
<p><a href="#Example">Example 1</a> shows data for a travel reservation
|
|
expressed in a <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#encapsulation">
|
|
SOAP message</a>.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Example" name="Example">Example 1</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre><?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></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
Sample SOAP message for a travel reservation containing header blocks and a
|
|
body</div>
|
|
</div>
|
|
|
|
<p>The SOAP message in <a href="#Example">Example 1</a> contains two
|
|
SOAP-specific sub-elements within the overall <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapenvelope">env:Envelope</a></code>,
|
|
namely an <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soaphead">env:Header</a></code>
|
|
and an <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapbody">env:Body</a></code>.
|
|
The contents of these elements are application defined and not a part of the
|
|
SOAP specifications, although the latter do have something to say about how
|
|
such elements must be handled.</p>
|
|
|
|
<p>A <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#encapsulation">
|
|
SOAP header</a> element is optional, but it has been included in the example
|
|
to explain certain features of SOAP. A SOAP header is an extension mechanism
|
|
that provides a way to pass information in SOAP messages that is not
|
|
application payload. Such "control" information includes, for example,
|
|
passing directives or contextual information related to the processing of the
|
|
message. This allows a SOAP message to be extended in an application-specific
|
|
manner. The immediate child elements of the <code>env:Header</code> element
|
|
are called<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#encapsulation">
|
|
header blocks</a>, and represent a logical grouping of data which, as shown
|
|
later, can individually be targeted at SOAP nodes that might be encountered
|
|
in the path of a message from a sender to an ultimate receiver.</p>
|
|
|
|
<p>SOAP headers have been designed in anticipation of various uses for SOAP,
|
|
many of which will involve the participation of other SOAP processing nodes -
|
|
called <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">
|
|
SOAP intermediaries</a> - along a message's path from an <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">initial
|
|
SOAP sender</a> to an <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">ultimate
|
|
SOAP receiver</a>. This allows SOAP intermediaries to provide value-added
|
|
services. Headers, as shown later, may be inspected, inserted, deleted or
|
|
forwarded by SOAP nodes encountered along a <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">SOAP
|
|
message path</a>. (It should be kept in mind, though, that the SOAP
|
|
specifications do not deal with what the contents of header elements are, or
|
|
how SOAP messages are routed between nodes, or the manner by which the route
|
|
is determined and so forth. These are a part of the overall application, and
|
|
could be the subject of other specifications.)</p>
|
|
|
|
<p>The<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#encapsulation">
|
|
SOAP body</a> is the mandatory element within the SOAP <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapenvelope">env:Envelope</a></code>,
|
|
which implies that this is where the main end-to-end information conveyed in
|
|
a SOAP message must be carried.</p>
|
|
|
|
<p>A pictorial representation of the SOAP message in <a href="#Example">Example 1</a> is as follows.</p>
|
|
|
|
<img src="primer-figure-1.png" alt="SOAP message structure">
|
|
<p align="center">Figure 1: SOAP message structure</p>
|
|
|
|
|
|
<p>In <a href="#Example">Example 1</a>, the header contains two header
|
|
blocks, each of which is defined in its own XML namespace and which represent
|
|
some aspect pertaining to the overall processing of the body of the SOAP
|
|
message. For this travel reservation application, such "meta" information
|
|
pertaining to the overall request is a <code>reservation</code> header block
|
|
which provides a reference and time stamp for this instance of a reservation,
|
|
and the traveller's identity in the <code>passenger</code> block.</p>
|
|
|
|
<p>The header blocks <code>reservation</code> and <code>passenger</code> must
|
|
be processed by the next SOAP intermediary encountered in the message path
|
|
or, if there is no intermediary, by the ultimate recipient of the message.
|
|
The fact that it is targeted at the next SOAP node encountered <em>en
|
|
route</em> is indicated by the presence of the attribute <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soaprole">env:role</a></code>
|
|
with the value "http://www.w3.org/2003/05/soap-envelope/role/next" (hereafter
|
|
simply "next"), which is a<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#concepts">
|
|
role</a> that all SOAP nodes must be willing to play. The presence of an
|
|
<code>env:mustUnderstand</code> attribute with value "true" indicates that
|
|
the node(s) processing the header must absolutely process these header blocks
|
|
in a manner consistent with their specifications, or else not process the
|
|
message at all and throw a fault. Note that whenever a header block is
|
|
processed, either because it is marked <code>env:mustUnderstand="true"</code>
|
|
or for another reason, the block must be processed in accordance with the
|
|
specifications for that block. Such header block specifications are
|
|
application defined and not a part of SOAP. <a href="#L1244">Section 3</a>
|
|
will elaborate further on SOAP message processing based on the values of
|
|
these attributes.</p>
|
|
|
|
<p>The choices of what data is placed in a header block and what goes in the
|
|
SOAP body are decisions made at the time of application design. The main
|
|
point to keep in mind is that header blocks may be targeted at various nodes
|
|
that might be encountered along a message's path from a sender to the
|
|
ultimate recipient. Such intermediate SOAP nodes may provide value-added
|
|
services based on data in such headers. In <a href="#Example">Example 1</a>,
|
|
the passenger data is placed in a header block to illustrate the use of this
|
|
data at a SOAP intermediary to do some additional processing. For example, as
|
|
shown later in <a href="#L635">section 5.1,</a> the outbound message is
|
|
altered by the SOAP intermediary by having the travel policies pertaining to
|
|
this passenger appended to the message as another header block.</p>
|
|
|
|
<p>The <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapbody">env:Body</a></code>
|
|
element and its associated child elements, <code>itinerary</code> and
|
|
<code>lodging</code>, are intended for exchange of information between the<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">
|
|
initial SOAP sender</a> and the SOAP node which assumes the role of the<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">
|
|
ultimate SOAP receiver</a> in the message path, which is the travel service
|
|
application. Therefore, the <code>env:Body</code> and its contents are
|
|
implicitly targeted and are expected to be understood by the ultimate
|
|
receiver. The means by which a SOAP node assumes such a role is not defined
|
|
by the SOAP specification, and is determined as a part of the overall
|
|
application semantics and associated message flow.</p>
|
|
|
|
<p>Note that a SOAP intermediary may decide to play the role of the ultimate
|
|
SOAP receiver for a given message transfer, and thus process the
|
|
<code>env:Body</code>. However, even though this sort of a behavior cannot be
|
|
prevented, it is not something that should be done lightly as it may pervert
|
|
the intentions of the message's sender, and have undesirable side effects
|
|
(such as not processing header blocks that might be targeted at
|
|
intermediaries further along the message path).</p>
|
|
|
|
<p>A SOAP message such as that in <a href="#Example">Example 1</a> may be
|
|
transferred by different underlying protocols and used in a variety of<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#concepts"> message
|
|
exchange patterns</a>. For example, for a Web-based access to a travel
|
|
service 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 (see <a href="#SMTP">section 4.2</a>). <a href="#transport"> Section 4</a> will
|
|
describe how SOAP messages may be conveyed by a variety of underlying
|
|
protocols. For the time being, it is assumed that a mechanism exists for
|
|
message transfer and the remainder of this section concentrates on the
|
|
details of the SOAP messages and their processing.</p>
|
|
|
|
</div>
|
|
<div class="div2">
|
|
|
|
<h3><a name="L1177"></a>2.2 SOAP Message Exchange</h3>
|
|
|
|
<p>SOAP Version 1.2 is a simple messaging framework for transferring
|
|
information specified in the form of an XML infoset between an initial SOAP
|
|
sender and an ultimate SOAP receiver. The more interesting scenarios
|
|
typically involve multiple message exchanges between these two nodes. The
|
|
simplest such exchange is a request-response pattern. Some early uses of [<a href="#R11">SOAP 1.1</a>] 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.</p>
|
|
|
|
<p>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. <a href="#L977">Section 2.2.1</a> covers the case of XML-based content exchanged
|
|
in SOAP messages between the travel reservation application and the travel
|
|
service application in a conversational pattern, while <a href="#L1185">section 2.2.2</a> provides an example of an exchange modeled as
|
|
an RPC.</p>
|
|
|
|
<div class="div3">
|
|
|
|
<h4><a name="L977"></a>2.2.1 Conversational Message Exchanges</h4>
|
|
|
|
<p>Continuing with the travel request scenario, <a href="#Example3">Example
|
|
2</a> shows a SOAP message returned from the travel service in response to
|
|
the reservation request message in <a href="#Example">Example 1</a>. This
|
|
response seeks to refine some information in the request, namely the choice
|
|
of airports in the departing city.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Example3" name="Example3">Example 2</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre><?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></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
SOAP message sent in response to the message in <a href="#Example">Example
|
|
1</a></div>
|
|
</div>
|
|
|
|
<p>As described earlier, the <code>env:Body</code> contains the primary
|
|
content of the message, which in this example includes a list of the various
|
|
alternatives for the airport, conforming to a schema definition in the XML
|
|
namespace http://travelcompany.example.org/reservation/travel. In this
|
|
example, the header blocks from <a href="#Example">Example 1</a> are returned
|
|
(with some sub-element values altered) in the response. This could allow
|
|
message correlation at the SOAP level, but such headers are very likely to
|
|
also have other application-specific uses.</p>
|
|
|
|
<p>The message exchange<span class="insert">s</span> in Examples 1 and 2 are
|
|
cases where XML-based contents conforming to some application-defined schema
|
|
are exchanged via SOAP messages. Once again, a discussion of the means by
|
|
which such messages are transferred is deferred to <a href="#transport">section 4</a>.</p>
|
|
|
|
<p>It is easy enough to see how such exchanges can build up to a multiple
|
|
back-and-forth "conversational" message exchange pattern. <a href="#Example4">Example 3</a> shows a SOAP message sent by the travel
|
|
reservation application in response to that in <a href="#Example3">Example
|
|
2</a> choosing one from the list of available airports. The header block
|
|
<code>reservation</code> with the same value of the <code>reference</code>
|
|
sub-element accompanies each message in this conversation, thereby offering a
|
|
way, should it be needed, to correlate the messages exchanged between them at
|
|
the application level.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Example4" name="Example4">Example 3</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre><?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></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
Response to the message in <a href="#Example3">Example 2</a> continuing a
|
|
conversational message exchange</div>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
|
|
<h4><a name="L1185"></a>2.2.2 Remote Procedure Calls</h4>
|
|
|
|
<p>One of the design goals of SOAP Version 1.2 is to encapsulate remote
|
|
procedure call functionality using the extensibility and flexibility of XML.
|
|
<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapforrpc">
|
|
SOAP Part 2 section 4</a> has defined a uniform representation for RPC
|
|
invocations and responses carried in SOAP messages. This section continues
|
|
with the travel reservation scenario to illustrate the use of SOAP messages
|
|
to convey remote procedure calls and their return.</p>
|
|
|
|
<p>To that end, the next example shows the payment for the trip using a
|
|
credit card. (It is assumed that the conversational exchanges described in <a href="#L977">section 2.2.1</a> have resulted in a confirmed itinerary.) Here,
|
|
it is further assumed that the payment happens in the context of an overall
|
|
transaction where the credit card is charged only when the travel and the
|
|
lodging (not shown in any example, but presumably reserved in a similar
|
|
manner) are both confirmed. The travel reservation application provides
|
|
credit card information and the successful completion of the different
|
|
activities results in the card being charged and a reservation code returned.
|
|
This reserve-and-charge interaction between the travel reservation
|
|
application and the travel service application is modeled as a SOAP RPC.</p>
|
|
|
|
<p>To invoke a SOAP RPC, the following information is needed:</p>
|
|
<ol>
|
|
<li id="underlying">The address of the target SOAP node.</li>
|
|
<li>The procedure or method name.</li>
|
|
<li>The identities and values of any arguments to be passed to the
|
|
procedure or method together with any output parameters and return
|
|
value.</li>
|
|
<li id="clear">A clear separation of the arguments
|
|
used to identify the Web resource which is the actual target for the RPC,
|
|
as contrasted with those that convey data or control information used for
|
|
processing the call by the target resource.</li>
|
|
<li id="message">The
|
|
message exchange pattern which will be employed to convey the RPC,
|
|
together with an identification of the so-called "Web Method" (on which
|
|
more later) to be used.</li>
|
|
<li id="Optionally">Optionally, data which may be carried as a part of
|
|
SOAP header blocks.</li>
|
|
</ol>
|
|
|
|
<p>Such information may be expressed by a variety of means, including formal
|
|
Interface Definition Languages (IDL). Note that SOAP does not provide any
|
|
IDL, formal or informal. Note also that the above information differs in
|
|
subtle ways from information generally needed to invoke other, non-SOAP
|
|
RPCs.</p>
|
|
|
|
<p>Regarding <a href="#underlying">Item 1</a> above, there is, from a SOAP
|
|
perspective, a SOAP node which "contains" or "supports" the target of the
|
|
RPC. It is the SOAP node which (appropriately) adopts the role of the <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">
|
|
ultimate SOAP receiver</a>. As required by <a href="#underlying">Item 1</a>,
|
|
the ultimate recipient can identify the target of the named procedure or
|
|
method by looking for its URI. The manner in which the target URI is made
|
|
available depends on the underlying protocol binding. One possibility is that
|
|
the URI identifying the target is carried in a SOAP header block. Some
|
|
protocol bindings, such as the SOAP HTTP binding defined in [<a href="#L1098">SOAP Part2</a>], offer a mechanism for carrying the URI outside
|
|
the SOAP message. In general, one of the properties of a protocol binding
|
|
specification must be a description of how the target URI is carried as a
|
|
part of the binding. <a href="#L10309">Section 4.1</a> provides some concrete
|
|
examples of how the URI is carried in the case of the standardized SOAP
|
|
protocol binding to HTTP.</p>
|
|
|
|
<p><a href="#clear">Item 4</a> and <a>Item 5</a> above are required to ensure
|
|
that RPC applications that employ SOAP can do so in a manner which is
|
|
compatible with the architectural principles of the World Wide Web. <a href="#L3677">Section 4.1.3</a> discusses how the information provided by
|
|
items 4 and 5 are utilized.</p>
|
|
|
|
<p>For the remainder of this section, it is assumed that the RPC conveyed in
|
|
a SOAP message as shown in <a href="#Example2">Example 4</a> is appropriately
|
|
targeted and dispatched. The purpose of this section is to highlight the
|
|
syntactical aspects of RPC requests and returns carried within a SOAP
|
|
message.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Example2" name="Example2">Example 4</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre><?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></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
SOAP RPC request with a mandatory header and two input (or "in")
|
|
parameters</div>
|
|
</div>
|
|
|
|
<p>The RPC itself is carried as a child of the <code>env:Body</code> element,
|
|
and is modelled as a <code>struct</code> which takes the name of the
|
|
procedure or method, in this case <code>chargeReservation</code>. (A
|
|
<code>struct</code> is <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#values">a concept
|
|
from the SOAP Data Model</a> defined in [<a href="#L1098">SOAP Part2</a>]
|
|
that models a structure or record type that occurs in some common programming
|
|
languages.) The design of the RPC in the example (whose formal description
|
|
has not been explicitly provided) takes two input (or "in") parameters, the
|
|
<code>reservation</code> corresponding to the planned trip identified by the
|
|
reservation <code>code</code>, and the <code>creditCard</code> information.
|
|
The latter is also a <code>struct</code>, which takes three elements, the
|
|
card holder's <code>name</code>, the card <code>number</code> and an
|
|
<code>expiration</code> date.</p>
|
|
|
|
<p>In this example, the <code>env:encodingStyle</code> attribute with the
|
|
value <a href="http://www.w3.org/2003/05/soap-encoding">http://www.w3.org/2003/05/soap-encoding</a>
|
|
shows that the contents of the <code>chargeReservation</code> structure have
|
|
been serialized according to the SOAP encoding rules, i.e., the particular
|
|
rules defined in<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapenc"> SOAP
|
|
Part 2 section 3</a>. Even though SOAP specifies this particular encoding
|
|
scheme, its use is optional and the specification makes clear that other
|
|
encoding schemes may be used for application-specific data within a SOAP
|
|
message. It is for this purpose that it provides the
|
|
<code>env:encodingStyle</code> attribute to qualify header blocks and body
|
|
sub-elements. The choice of the value for this attribute is an
|
|
application-specific decision and the ability of a caller and callee to
|
|
interoperate is assumed to have been settled "out-of-band". <a href="#L3374">Section 5.2</a> shows an example of using another encoding
|
|
scheme.</p>
|
|
|
|
<p>As noted in <a href="#Optionally">Item 6</a> above, RPCs may also require
|
|
additional information to be carried, which can be important for the
|
|
processing of the call in a distributed environment, but which are not a part
|
|
of the formal procedure or method description. (Note, however, that providing
|
|
such additional contextual information is not specific to RPCs, but may be
|
|
required in general for the processing of any distributed application.) In
|
|
the example, the RPC is carried out in the context of an overall transaction
|
|
which involves several activities which must all complete successfully before
|
|
the RPC returns successfully. <a href="#Example2">Example 4</a> shows how a
|
|
header block <code>transaction</code> directed at the ultimate recipient
|
|
(implied by the absence of the <code>env:role</code> attribute) is used to
|
|
carry such information. (The value "5" is some transaction identifier set by
|
|
and meaningful to the application. No further elaboration of the
|
|
application-specific semantics of this header are provided here, as it is not
|
|
germane to the discussion of the syntactical aspects of SOAP RPC
|
|
messages.)</p>
|
|
|
|
<p>Let us assume that the RPC in the charging example has been designed to
|
|
have the procedure description which indicates that there are two output (or
|
|
"out") parameters, one providing the reference code for the reservation and
|
|
the other a URL where the details of the reservation may be viewed. The RPC
|
|
response is returned in the <code>env:Body</code> element of a SOAP message,
|
|
which is modeled as a <code>struct</code> taking the procedure name
|
|
<code>chargeReservation</code> and, as a convention, the word "Response"
|
|
appended. The two output (or "out") parameters accompanying the response are
|
|
the alphanumeric <code>code</code> identifying the reservation in question,
|
|
and a URI for the location, <code>viewAt</code>, from where the reservation
|
|
may be retrieved.</p>
|
|
|
|
<p>This is shown in <a href="#Example5">Example 5a</a>, where the header
|
|
again identifies the transaction within which this RPC is performed.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Example5" name="Example5">Example 5a</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre><?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:m="http://travelcompany.example.org/">
|
|
<m:code>FT35ZBQ</m:code>
|
|
<m:viewAt>
|
|
http://travelcompany.example.org/reservations?code=FT35ZBQ
|
|
</m:viewAt>
|
|
</m:chargeReservationResponse>
|
|
</env:Body>
|
|
</env:Envelope></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
RPC response with two output (or "out") parameters for the call shown in <a href="#Example2">Example 4</a></div>
|
|
</div>
|
|
|
|
<p>RPCs often have descriptions where a particular output parameter is
|
|
distinguished, the so-called "return" value. The<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#rpcresponse"> SOAP
|
|
RPC convention</a> offers a way to distinguish this "return" value from the
|
|
other output parameters in the procedure description. To show this, the
|
|
charging example is modified to have an RPC description that is almost the
|
|
same as that for <a href="#Example5">Example 5a</a>, i.e, with the same two
|
|
"out" parameters, but in addition it also has a "return" value, which is an
|
|
enumeration with potential values of "confirmed" and "pending". The RPC
|
|
response conforming to this description is shown in <a href="#Example51">Example 5b</a>, where the SOAP header, as before,
|
|
identifies the transaction within which this RPC is performed.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Example51" name="Example51">Example 5b</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre><?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></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
RPC response with a "return" value and two "out" parameters for the call
|
|
shown in <a href="#Example2">Example 4</a></div>
|
|
</div>
|
|
|
|
<p>In <a href="#Example51">Example 5b</a>, the return value is identified by
|
|
the element <code>rpc:result</code>, and contains the XML Qualified Name (of
|
|
type <code>xs:QName</code>) of another element within the <code>struct</code>
|
|
which is <code>m:status</code>. 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 <code>rpc:result</code>
|
|
element is absent, as is the case in <a href="#Example5">Example 5a</a>, the
|
|
return value is not present or is of the type <code>void</code>.</p>
|
|
|
|
<p>While, in principle, using SOAP for RPC is independent of the decision to
|
|
use a particular means for transferring the RPC call and its return, certain
|
|
protocol bindings that support the SOAP<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#singlereqrespmep">
|
|
Request-Response message exchange pattern</a> may be more naturally suited
|
|
for such purposes. A protocol binding supporting this message exchange
|
|
pattern can provide the correlation between a request and a response. Of
|
|
course, the designer of an RPC-based application could choose to put a
|
|
correlation ID relating a call and its return in a SOAP header, thereby
|
|
making the RPC independent of any underlying transfer mechanism. In any case,
|
|
application designers have to be aware of all the characteristics of the
|
|
particular protocols chosen for transferring SOAP RPCs, such as latency,
|
|
synchrony, etc.</p>
|
|
|
|
<p>In the commonly used case, standardized in<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapinhttp"> SOAP
|
|
Part 2 section 7</a>, of using HTTP as the underlying transfer protocol, an
|
|
RPC invocation maps naturally to the HTTP request and an RPC response maps to
|
|
the HTTP response. <a href="#L10309">Section 4.1</a> provides examples of
|
|
carrying RPCs using the HTTP binding.</p>
|
|
|
|
<p>However, it is worth keeping in mind that even though most examples of
|
|
SOAP for RPC use the HTTP protocol binding, it is not limited to that means
|
|
alone.</p>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="div2">
|
|
|
|
<h3><a name="L11549"></a>2.3 Fault Scenarios</h3>
|
|
|
|
<p>SOAP provides a model for handling situations when faults arise in the
|
|
processing of a message. SOAP distinguishes between the conditions that
|
|
result in a fault, and the ability to signal that fault to the originator of
|
|
the faulty message or another node. The ability to signal the fault depends
|
|
on the message transfer mechanism used, and one aspect of the binding
|
|
specification of SOAP onto an underlying protocol is to specify how faults
|
|
are signalled, if at all. The remainder of this section assumes that a
|
|
transfer mechanism is available for signalling faults generated while
|
|
processing received messages, and concentrates on the structure of the SOAP
|
|
fault message.</p>
|
|
|
|
<p>The SOAP <code>env:Body</code> element has another distinguished role in
|
|
that it is the place where such fault information is placed. The SOAP fault
|
|
model (see<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#procsoapmsgs">
|
|
SOAP Part 1, section 2.6</a>) requires that all SOAP-specific and
|
|
application-specific faults be reported using a <em>single</em> distinguished
|
|
element, <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapfault">
|
|
env:Fault</a></code>, carried within the <code>env:Body</code> element. The
|
|
<code>env:Fault</code> element contains two mandatory sub-elements, <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultcodeelement">env:Code</a></code>
|
|
and <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultstringelement">env:Reason</a></code>,
|
|
and (optionally) application-specific information in the <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultdetailelement">env:Detail</a></code>
|
|
sub-element. Another optional sub-element,<code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultactorelement">
|
|
env:Node</a></code>, identifies via a URI the SOAP node which generated the
|
|
fault, its absence implying that it was the ultimate recipient of the message
|
|
which did so. There is yet another optional sub-element, <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultroleelement">env:Role</a></code>,
|
|
which identifies the role being played by the node which generated the
|
|
fault.</p>
|
|
|
|
<p>The <code>env:Code</code> sub-element of <code>env:Fault</code> is itself
|
|
made up of a mandatory <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultvalueelement">env:Value</a></code>
|
|
sub-element, whose content is specified in the SOAP specification (see<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultcodes"> SOAP
|
|
Part 1 section 5.4.6</a>) as well as an optional <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultsubcodeelement">env:Subcode</a></code>
|
|
sub-element.</p>
|
|
|
|
<p><a href="#Example7">Example 6a</a> shows a SOAP message returned in
|
|
response to the RPC request in <a href="#Example2">Example 4</a>, and
|
|
indicating a failure to process the RPC.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Example7" name="Example7">Example 6a</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre><?xml version='1.0' ?>
|
|
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
|
|
xmlns:rpc='http://www.w3.org/2003/05/soap-rpc'>
|
|
<env:Body>
|
|
<env:Fault>
|
|
<env:Code>
|
|
<env:Value>env:Sender</env:Value>
|
|
<env:Subcode>
|
|
<env:Value>rpc:BadArguments</env:Value>
|
|
</env:Subcode>
|
|
</env:Code>
|
|
<env:Reason>
|
|
<env:Text xml:lang="en-US">Processing error</env:Text>
|
|
<env:Text xml:lang="cs">Chyba zpracování</env:Text>
|
|
</env:Reason>
|
|
<env:Detail>
|
|
<e:myFaultDetails
|
|
xmlns:e="http://travelcompany.example.org/faults">
|
|
<e:message>Name does not match card number</e:message>
|
|
<e:errorcode>999</e:errorcode>
|
|
</e:myFaultDetails>
|
|
</env:Detail>
|
|
</env:Fault>
|
|
</env:Body>
|
|
</env:Envelope></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
Sample SOAP message indicating failure <span class="exampleWrapper">to
|
|
process the RPC in <a href="#Example2">Example 4</a></span></div>
|
|
</div>
|
|
|
|
<p>In <a href="#Example7">Example 6a</a>, the top-level
|
|
<code>env:Value</code> uses a standardized XML Qualified Name (of type
|
|
<code>xs:QName</code>) to identify that it is an <code>env:Sender</code>
|
|
fault, which indicates that it is related to some syntactical error or
|
|
inappropriate information in the message. (When a <code>env:Sender</code>
|
|
fault is received by the sender, it is expected that some corrective action
|
|
is taken before a similar message is sent again.) The
|
|
<code>env:Subcode</code> element is optional, and, if present, as it is in
|
|
this example, qualifies the parent value further. In <a href="#Example7">Example 6a</a>, the <code>env:Subcode</code> denotes that an
|
|
RPC specific fault, <code>rpc:BadArguments</code>, defined in <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#rpcfaults">SOAP
|
|
Part 2 section 4.4</a>, is the cause of the failure to process the
|
|
request.</p>
|
|
|
|
<p>The structure of the <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultsubcodeelement">env:Subcode</a></code>
|
|
element has been chosen to be hierarchical - each child
|
|
<code>env:Subcode</code> element has a mandatory <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultsubvalueelem">env:Value</a></code>
|
|
and an optional <code>env:Subcode</code> sub-element - to allow
|
|
application-specific codes to be carried. This hierarchical structure of the
|
|
<code>env:Code</code> element allows for an uniform mechanism for conveying
|
|
multiple level of fault codes. The top-level <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultvalueelement">env:Value</a></code>
|
|
is a base fault that is specified in the SOAP Version 1.2 specifications (see
|
|
<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultcodes">SOAP
|
|
Part 1 section 5.4.6</a>) and must be understood by all SOAP nodes. Nested
|
|
<code>env:Value</code>s are application-specific, and represent further
|
|
elaboration or refinement of the base fault from an application perspective.
|
|
Some of these values may well be standardized, such as the RPC codes
|
|
standardized in SOAP 1.2 (see<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#rpcfaults"> SOAP
|
|
Part 2 section 4.4</a>), or in some other standards that use SOAP as an
|
|
encapsulation protocol. The only requirement for defining such
|
|
application-specific subcode values is that they be namespace qualified using
|
|
any namespace other than the SOAP <code><a href="http://www.w3.org/2003/05/soap-envelope">env</a></code> namespace which
|
|
defines the main classifications for SOAP faults. There is no requirement
|
|
from a SOAP perspective that applications need to understand, or even look at
|
|
all levels of the subcode values.</p>
|
|
|
|
<p>The <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultstringelement">env:Reason</a></code>
|
|
sub-element is not meant for algorithmic processing, but rather for human
|
|
understanding; so, even though this is a mandatory item, the chosen value
|
|
need not be standardized. Therefore all that is required is that it
|
|
reasonably accurately describe the fault situation. It must have one or more
|
|
<code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#reasontextelement">env:Text</a></code>
|
|
sub-elements, each with a unique <code>xml:lang</code> attribute, which
|
|
allows applications to make the fault reason available in multiple languages.
|
|
(Applications could negotiate the language of the fault text using a
|
|
mechanism built using SOAP headers; however this is outside the scope of the
|
|
SOAP specifications.)</p>
|
|
|
|
<p>The absence of a <code>env:Node</code> sub-element within
|
|
<code>env:Fault</code> in <a href="#Example7">Example 6a</a> implies that it
|
|
is generated by the ultimate receiver of the call. The contents of
|
|
<code>env:Detail</code>, as shown in the example, are
|
|
application-specific.</p>
|
|
|
|
<p>During the processing of a SOAP message, a fault may also be generated if
|
|
a mandatory header element is not understood or the information contained in
|
|
it cannot be processed. Errors in processing a header block are also
|
|
signalled using a <code>env:Fault</code> element within the
|
|
<code>env:Body</code>, but with a particular distinguished header block,
|
|
<code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapnotunderstood">env:NotUnderstood</a></code>,
|
|
that identifies the offending header block.</p>
|
|
|
|
<p><a href="#Example12">Example 6b</a> shows an example of a response to the
|
|
RPC in <a href="#Example2">Example 4</a> indicating a failure to process the
|
|
<code>t:transaction</code> header block. Note the presence of the <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultcodes">env:MustUnderstand</a></code>
|
|
fault code in the <code>env:Body</code>, and the identification of the header
|
|
not understood using an (unqualified) attribute, <code>qname</code>, in the
|
|
special (empty) header block <code>env:NotUnderstood</code>.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a name="Example12" id="Example12">Example 6b</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre><?xml version='1.0' ?>
|
|
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
|
|
<env:Header>
|
|
<<span class="highlight">env:NotUnderstood</span> qname="t:transaction"
|
|
xmlns:t="http://thirdparty.example.org/transaction"/>
|
|
</env:Header>
|
|
<env:Body>
|
|
<env:Fault>
|
|
<env:Code>
|
|
<env:Value><span class="highlight">env:MustUnderstand</span></env:Value>
|
|
</env:Code>
|
|
<env:Reason>
|
|
<env:Text xml:lang="en-US">Header not understood</env:Text>
|
|
<env:Text xml:lang="fr">En-tête non compris</env:Text>
|
|
</env:Reason>
|
|
</env:Fault>
|
|
</env:Body>
|
|
</env:Envelope></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
Sample SOAP message indicating failure <span class="exampleWrapper">to
|
|
process the header block in <a href="#Example2">Example 4</a></span></div>
|
|
</div>
|
|
|
|
<p>If there were several mandatory header blocks that were not understood,
|
|
then each could be identified by its <code>qname</code> attribute in a series
|
|
of such <code>env:NotUnderstood</code> header blocks.</p>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="div1">
|
|
|
|
<h2><a name="L1244"></a>3. <span id="L3631">SOAP Processing Model</span></h2>
|
|
|
|
<p>Having established the various syntactical aspects of a SOAP message as
|
|
well as some basic message exchange patterns, this section provides a general
|
|
overview of the SOAP processing model (specified in<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#msgexchngmdl">
|
|
SOAP Part 1, section 2</a>). The SOAP processing model describes the actions
|
|
taken by a SOAP node on receiving a SOAP message.</p>
|
|
|
|
<p><a href="#Example1">Example 7a</a> shows a SOAP message with several
|
|
header blocks (with their contents omitted for brevity). Variations of this
|
|
will be used in the remainder of this section to illustrate various aspects
|
|
of the processing model.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Example1" name="Example1">Example 7a</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre><?xml version="1.0" ?>
|
|
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
|
|
<env:Header>
|
|
<p:oneBlock xmlns:p="http://example.com"
|
|
env:role="http://example.com/Log">
|
|
...
|
|
...
|
|
</p:oneBlock>
|
|
<q:anotherBlock xmlns:q="http://example.com"
|
|
env:role="http://www.w3.org/2003/05/soap-envelope/role/next">
|
|
...
|
|
...
|
|
</q:anotherBlock>
|
|
<r:aThirdBlock xmlns:r="http://example.com">
|
|
...
|
|
...
|
|
</r:aThirdBlock>
|
|
</env:Header>
|
|
<env:Body >
|
|
...
|
|
...
|
|
</env:Body>
|
|
</env:Envelope></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
SOAP message showing a variety of header blocks</div>
|
|
</div>
|
|
|
|
<p>The SOAP processing model describes the (logical) actions taken by a SOAP
|
|
node on receiving a SOAP message. There is a requirement for the node to
|
|
analyze those parts of a message that are SOAP-specific, namely those
|
|
elements in the SOAP "<a href="http://www.w3.org/2003/05/soap-envelope">env</a>" namespace. Such
|
|
elements are the envelope itself, the header element and the body element. A
|
|
first step is, of course, the overall check that the SOAP message is
|
|
syntactically correct. That is, it conforms to the SOAP XML infoset subject
|
|
to the restrictions on the use of certain XML constructs - Processing
|
|
Instructions and Document Type Definitions - as defined in <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapenv"> SOAP
|
|
Part 1, section 5.</a></p>
|
|
|
|
<div class="div2">
|
|
|
|
<h3><a name="L1271"></a>3.1 <span id="L6293">The "role" Attribute</span></h3>
|
|
|
|
<p>Further processing of header blocks and the body depend on the<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#concepts">
|
|
role</a>(s) assumed by the SOAP node for the processing of a given message.
|
|
SOAP defines the (optional) <code>env:role</code> attribute - syntactically,
|
|
<code>xs:anyURI</code> - that may be present in a header block, which
|
|
identifies the role played by the intended target of that header block. A
|
|
SOAP node is required to process a header block if it assumes the role
|
|
identified by the value of the URI. How a SOAP node assumes a particular role
|
|
is not a part of the SOAP specifications.</p>
|
|
|
|
<p>Three standardized roles have been defined (see<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soaproles"> SOAP
|
|
Part 1, section 2.2</a>), which are</p>
|
|
<ul>
|
|
<li>"http://www.w3.org/2003/05/soap-envelope/role/none" (hereafter simply
|
|
"none")</li>
|
|
<li>"http://www.w3.org/2003/05/soap-envelope/role/next" (hereafter simply
|
|
"next"), and</li>
|
|
<li>"http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver"
|
|
(hereafter simply "ultimateReceiver").</li>
|
|
</ul>
|
|
|
|
<p>In <a href="#Example1">Example 7a</a>, the header block
|
|
<code>oneBlock</code> is targeted at any SOAP node that plays the
|
|
application-defined role defined by the URI http://example.com/Log. For
|
|
purposes of illustration, it is assumed that the specification for such a
|
|
header block requires that any SOAP node adopting this role log the entire
|
|
message.</p>
|
|
|
|
<p>Every SOAP node receiving a message with a header block that has a
|
|
<code>env:role</code> attribute of "next" must be capable of processing the
|
|
contents of the element, as this is a standardized role that every SOAP node
|
|
must be willing to assume. A header block thus attributed is one which is
|
|
expected to be examined and (possibly) processed by the next SOAP node along
|
|
the path of a message, assuming that such a header has not been removed as a
|
|
result of processing at some node earlier in the message path.</p>
|
|
|
|
<p>In <a href="#Example1">Example 7a</a>, the header block
|
|
<code>anotherBlock</code> is targeted at the next node in the message path.
|
|
In <a href="#Example1"></a>this case, the SOAP message received by the node
|
|
playing the application-defined role of "http://example.com/Log", must also
|
|
be willing to play the SOAP-defined role of "next". This is also true for the
|
|
node which is the ultimate recipient of the message, as it obviously (and
|
|
implicitly) also plays the "next" role by virtue of being next in the message
|
|
path.</p>
|
|
|
|
<p>The third header block, <code>aThirdBlock</code>, in <a href="#Example1">Example 7a</a> does not have the <code>env:role</code>
|
|
attribute. It is targeted at a SOAP node which assumes the "ultimateReceiver"
|
|
role. The "ultimateReceiver" role (which can be explicitly declared or is
|
|
implicit if the <code>env:role</code> attribute is absent in a header block)
|
|
is played by a SOAP node that assumes the role of the ultimate recipient of a
|
|
particular SOAP message. The absence of a <code>env:role</code> attribute in
|
|
the <code>aThirdBlock</code> header block means that this header element is
|
|
targeted at the SOAP node that assumes the "ultimateReceiver" role.</p>
|
|
|
|
<p>Note that the <code>env:Body</code> element does not have a
|
|
<code>env:role</code> attribute. The body element is <em>always</em> targeted
|
|
at the SOAP node that assumes the "ultimateReceiver" role. In that sense, the
|
|
body element is just like a header block targeted at the ultimate receiver,
|
|
but it has been distinguished to allow for SOAP nodes (typically SOAP
|
|
intermediaries) to skip over it if they assume roles other than that of the
|
|
ultimate receiver. SOAP does not prescribe any structure for the
|
|
<code>env:Body</code> element, except that it recommends that any
|
|
sub-elements be XML namespace qualified. Some applications, such as that in
|
|
<a href="#Example">Example 1</a>, may choose to organize the sub-elements of
|
|
<code>env:Body</code> in blocks, but this is not of concern to the SOAP
|
|
processing model.</p>
|
|
|
|
<p>The other distinguished role for the <code>env:Body</code> element, as the
|
|
container where information on SOAP-specific faults, i.e., failure to process
|
|
elements of a SOAP message, is placed has been described previously in <a href="#L11549">section 2.3</a>.</p>
|
|
|
|
<p>If a header element has the standardized <code>env:role</code> attribute
|
|
with 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 by
|
|
another header element that is targeted at the particular SOAP node.</p>
|
|
|
|
<p>If the <code>env:role</code> attribute has an empty value, i.e.,
|
|
<code>env:role=""</code>, it means that the relative URI identifying the
|
|
role is resolved to the base URI for the SOAP message in question. SOAP
|
|
Version 1.2 does not define a base URI for a SOAP message, but defers to the
|
|
mechanisms defined in [<a href="#L2778">XMLBase</a>] for deriving the base
|
|
URI, which can be used to make any relative URIs absolute. One such
|
|
mechanism is for the protocol binding to establish a base URI, possibly by
|
|
reference to the encapsulating protocol in which the SOAP message is
|
|
embedded for transport. (In fact, when SOAP messages are transported using
|
|
HTTP, <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#httpuse">SOAP Part
|
|
2 section 7.1.2</a> defines the base URI as the Request-URI of the HTTP
|
|
request, or the value of the HTTP Content-Location header.)</p>
|
|
|
|
<p>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.)</p>
|
|
|
|
<a name="tabrolesnodes"></a><table border="1" summary="Table summarizing the applicable standardized roles that may be assumed at various SOAP nodes">
|
|
<tbody>
|
|
<tr>
|
|
<td align="right" rowspan="1" colspan="1"><em>Role</em></td>
|
|
<td align="center" rowspan="1" colspan="1">absent</td>
|
|
<td align="center" rowspan="1" colspan="1">"none"</td>
|
|
<td align="center" rowspan="1" colspan="1">"next"</td>
|
|
<td align="center" rowspan="1" colspan="1">"ultimateReceiver"</td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan="1" colspan="1"><em>Node</em></td>
|
|
<td align="center" rowspan="1" colspan="1"> </td>
|
|
<td align="center" rowspan="1" colspan="1"> </td>
|
|
<td align="center" rowspan="1" colspan="1"> </td>
|
|
<td align="center" rowspan="1" colspan="1"> </td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan="1" colspan="1">initial sender</td>
|
|
<td align="center" rowspan="1" colspan="1">not applicable</td>
|
|
<td align="center" rowspan="1" colspan="1">not applicable</td>
|
|
<td align="center" rowspan="1" colspan="1">not applicable</td>
|
|
<td align="center" rowspan="1" colspan="1">not applicable</td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan="1" colspan="1">intermediary</td>
|
|
<td align="center" rowspan="1" colspan="1">no</td>
|
|
<td align="center" rowspan="1" colspan="1">no</td>
|
|
<td align="center" rowspan="1" colspan="1">yes</td>
|
|
<td align="center" rowspan="1" colspan="1">no</td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan="1" colspan="1">ultimate receiver</td>
|
|
<td align="center" rowspan="1" colspan="1">yes</td>
|
|
<td align="center" rowspan="1" colspan="1">no</td>
|
|
<td align="center" rowspan="1" colspan="1">yes</td>
|
|
<td align="center" rowspan="1" colspan="1">yes</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
</div>
|
|
|
|
<div class="div2">
|
|
|
|
<h3><a name="L1474"></a>3.2 <span id="L3031">The "mustUnderstand" Attribute</span></h3>
|
|
|
|
<p><a href="#Example8">Example 7b</a> augments the previous example by
|
|
introducing another (optional) attribute for header blocks, the <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapmu">env:mustUnderstand</a></code>
|
|
attribute.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Example8" name="Example8">Example 7b</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre><?xml version="1.0" ?>
|
|
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
|
|
<env:Header>
|
|
<p:oneBlock xmlns:p="http://example.com"
|
|
env:role="http://example.com/Log"
|
|
<span class="highlight">env:mustUnderstand="true"</span>>
|
|
...
|
|
...
|
|
</p:oneBlock>
|
|
<q:anotherBlock xmlns:q="http://example.com"
|
|
env:role="http://www.w3.org/2003/05/soap-envelope/role/next">
|
|
...
|
|
...
|
|
</q:anotherBlock>
|
|
<r:aThirdBlock xmlns:r="http://example.com">
|
|
...
|
|
...
|
|
</r:aThirdBlock>
|
|
</env:Header>
|
|
<env:Body >
|
|
...
|
|
...
|
|
</env:Body>
|
|
</env:Envelope></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
SOAP message showing a variety of header blocks, one of which is mandatory
|
|
for processing</div>
|
|
</div>
|
|
|
|
<p>After a SOAP node has correctly identified the header blocks (and possibly
|
|
the body) targeted at itself using the <code>env:role</code> attribute, the
|
|
additional attribute, <code>env:mustUnderstand</code>, in the header elements
|
|
determines further processing actions that have to be taken. In order to
|
|
ensure that SOAP nodes do not ignore header blocks which are important to the
|
|
overall purpose of the application, SOAP header blocks also provide for the
|
|
additional optional attribute, <code>env:mustUnderstand</code>, which, if
|
|
"true", means that the targeted SOAP node <em>must</em> process the
|
|
block according to the specification of that block. Such a block is
|
|
colloquially referred to as a mandatory header block. In fact, processing of
|
|
the SOAP message must not even start until the node has identified all the
|
|
mandatory header blocks targeted at itself, and "understood" them.
|
|
Understanding a header means that the node must be prepared to do whatever is
|
|
described in the specification of that block. (Keep in mind that the
|
|
specifications of header blocks are not a part of the SOAP
|
|
specifications.)</p>
|
|
|
|
<p>In <a href="#Example8">Example 7b</a>, the header block
|
|
<code>oneBlock</code> is marked with a <code>env:mustUnderstand</code> value
|
|
set to "true", which means that it is mandatory to process this block if the
|
|
SOAP node plays the role identified by "http://example.com/Log". The other
|
|
two header blocks are not so marked, which means that SOAP node at which
|
|
these blocks are targeted need not process them. (Presumably the
|
|
specifications for these blocks allow for this.)</p>
|
|
|
|
<p>A <code>env:mustUnderstand</code> value of "true" means that the SOAP node
|
|
must process the header with the semantics described in that header's
|
|
specification, or else generate a SOAP fault. Processing the header
|
|
appropriately may include removing the header from any generated SOAP
|
|
message, reinserting the header with the same or altered value, or inserting
|
|
a new header. The inability to process a mandatory header requires that all
|
|
further processing of the SOAP message cease, and a SOAP fault be generated.
|
|
The message is not forwarded any further.</p>
|
|
|
|
<p>The <code>env:Body</code> element has no <code>env:mustUnderstand</code>
|
|
attribute but it <em>must</em> be processed by the ultimate recipient. In <a href="#Example8">Example 7b</a>, the ultimate recipient of the message - the
|
|
SOAP node which plays the "ultimateReceiver" role - must process the
|
|
<code>env:Body</code> and may process the header block
|
|
<code>aThirdBlock</code>. It may also process the header block
|
|
<code>anotherBlock</code>, as it is targeted at it (in the role of "next")
|
|
but it is not mandatory to do so if the specifications for processing the
|
|
blocks do not demand it. (If the specification for <code>anotherBlock</code>
|
|
demanded that it must be processed at the next recipient, it would have
|
|
required that it be marked with a <code>env:mustUnderstand=</code>"true".)</p>
|
|
|
|
<p>The role(s) a SOAP node plays when processing a SOAP message can be
|
|
determined by many factors. The role could be known<em> a priori</em>, or set
|
|
by some out-of-band means, or a node can inspect all parts of a received
|
|
message to determine which roles it will assume before processing the
|
|
message. An interesting case arises when a SOAP node, during the course of
|
|
processing a message, decides that there are additional roles that it needs
|
|
to adopt. No matter when this determination is made, externally it must
|
|
appear as though the processing model has been adhered to. That is, it must
|
|
appear as though the role had been known from the start of the processing of
|
|
the message. In particular, the external appearance must be that the
|
|
<code>env:mustUnderstand</code> checking of any headers with those additional
|
|
roles assumed was performed before any processing began. Also, if a SOAP node
|
|
assumes such additional roles, it must ensure that it is prepared to do
|
|
everything that the specifications for those roles require.</p>
|
|
|
|
<p>The following table summarizes how the processing actions for a header
|
|
block are qualified by the <code>env:mustUnderstand</code> attribute with
|
|
respect to a node that has been appropriately targeted (via the
|
|
<code>env:role</code> attribute).</p>
|
|
|
|
<a name="tabmustunderstand"></a><table border="1" summary="Table summarizing the use of the mustUnderstand attribute">
|
|
<tbody>
|
|
<tr>
|
|
<td align="right" rowspan="1" colspan="1"><em>Node</em></td>
|
|
<td align="center" rowspan="1" colspan="1">intermediary</td>
|
|
<td align="center" rowspan="1" colspan="1">ultimate receiver</td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan="1" colspan="1"><em>mustUnderstand</em></td>
|
|
<td align="center" rowspan="1" colspan="1"> </td>
|
|
<td align="center" rowspan="1" colspan="1"> </td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan="1" colspan="1">"true"</td>
|
|
<td align="center" rowspan="1" colspan="1">must process</td>
|
|
<td align="center" rowspan="1" colspan="1">must process</td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan="1" colspan="1">"false"</td>
|
|
<td align="center" rowspan="1" colspan="1">may process</td>
|
|
<td align="center" rowspan="1" colspan="1">may process</td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan="1" colspan="1">absent</td>
|
|
<td align="center" rowspan="1" colspan="1">may process</td>
|
|
<td align="center" rowspan="1" colspan="1">may process</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>As a result of processing a SOAP message, a SOAP node may generate a
|
|
single SOAP fault if it fails to process a message, or, depending on the
|
|
application, generate additional SOAP messages for consumption at other SOAP
|
|
nodes. <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapfault">SOAP
|
|
Part 1 section 5.4</a> describes the structure of the fault message while the
|
|
<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#msgexchngmdl">SOAP
|
|
processing model</a> defines the conditions under which it is generated. As
|
|
illustrated previously in <a href="#L11549">section 2.3</a>, a SOAP fault is
|
|
a SOAP message with a standardized <code>env:Body</code> sub-element named
|
|
<code>env:Fault</code>.</p>
|
|
|
|
<p>SOAP makes a distinction between generating a fault and ensuring that the
|
|
fault is returned to the originator of the message or to another appropriate
|
|
node which can benefit from this information. 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. (See <a href="#transport">Section 4</a>
|
|
for more details on SOAP protocol bindings.)</p>
|
|
|
|
</div>
|
|
<div class="div2">
|
|
|
|
<h3><a name="LL10047"></a>3.3 The "relay" Attribute</h3>
|
|
|
|
<p>SOAP Version 1.2 defines another optional attribute for header blocks,
|
|
<code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soaprelay">env:relay</a></code>
|
|
of type <code>xs:boolean</code>, which indicates if a header block targeted
|
|
at a SOAP intermediary must be relayed if it is <em>not</em> processed.</p>
|
|
|
|
<p>Note that if a header block <em>is</em> processed, the SOAP processing
|
|
rules (see <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#forwardinter">SOAP
|
|
Part 1 section 2.7.2</a>) 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 <em>an un</em>processed header block targeted at a role played by a SOAP
|
|
intermediary is that it must be removed before the message is relayed.</p>
|
|
|
|
<p>The reason for this choice of default is to lean on the side of safety by
|
|
ensuring that a SOAP intermediary make no assumptions about the survivability
|
|
past itself of a header block targeted at a role it assumes, and representing
|
|
some value-added feature, particularly if it chooses not to process the
|
|
header block, very likely because it does not "understand" it. That is
|
|
because certain header blocks represent hop-by-hop features, and it may not
|
|
make sense to unknowingly propagate it end-to-end. As an intermediary may not
|
|
be in a position to make this determination, it was thought that it would be
|
|
safer if unprocessed header blocks were removed before the message was
|
|
relayed.</p>
|
|
|
|
<p>However, there are instances when an application designer would like to
|
|
introduce a new feature, manifested through a SOAP header block, targeted at
|
|
<em>any</em> capable intermediary which might be encountered in the SOAP
|
|
message path. Such a header block would be available to those intermediaries
|
|
that "understood" it, but ignored and relayed onwards by those that did not.
|
|
Being a new feature, the processing software for this header block may be
|
|
implemented, at least initially, in some but not all SOAP nodes. Marking such
|
|
a header block with <code>env:mustUnderstand</code> = "false" is obviously
|
|
needed, so that intermediaries that have not implemented the feature do not
|
|
generate a fault. To circumvent the default rule of the processing model,
|
|
marking a header block with the additional attribute <code>env:relay</code>
|
|
with the value "true" allows the intermediary to forward the header block
|
|
targeted at itself in the event that it chooses not to process it.</p>
|
|
|
|
<p>Targeting the header block at the role "next" together with the
|
|
<code>env:relay</code> attribute set to "true" can always serve to ensure
|
|
that each intermediary has a chance to examine the header, because one of the
|
|
anticipated uses of the "next" role is with header blocks that carry
|
|
information that are expected to persist along a SOAP message path. Of
|
|
course, the application designer can always define a custom role that allows
|
|
targetting at specific intermediaries that assume this role. Therefore, there
|
|
is no restriction on the use of the <code>env:relay</code> attribute with any
|
|
role except of course the roles of "none" and "ultimateReceiver", for which
|
|
it is meaningless.</p>
|
|
|
|
<p><a href="#Example11">Example 7c</a> shows the use of the
|
|
<code>env:relay</code> attribute.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a name="Example11" id="Example11">Example 7c</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre><?xml version="1.0" ?>
|
|
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
|
|
<env:Header>
|
|
<p:oneBlock xmlns:p="http://example.com"
|
|
env:role="http://example.com/Log"
|
|
env:mustUnderstand="true">
|
|
...
|
|
...
|
|
</p:oneBlock>
|
|
<q:anotherBlock xmlns:q="http://example.com"
|
|
env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
|
|
<span class="highlight">env:relay="true"</span>>
|
|
...
|
|
...
|
|
</q:anotherBlock>
|
|
<r:aThirdBlock xmlns:r="http://example.com">
|
|
...
|
|
...
|
|
</r:aThirdBlock>
|
|
</env:Header>
|
|
<env:Body >
|
|
...
|
|
...
|
|
</env:Body>
|
|
</env:Envelope></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
SOAP message showing a variety of header blocks, one of which must be relayed
|
|
if unprocessed.</div>
|
|
</div>
|
|
|
|
<p>The header block <code>q:anotherBlock</code>, targeted at the "next" node
|
|
in the message path, has the additional attribute
|
|
<code>env:relay</code>="true". A SOAP node receiving this message may process
|
|
this header block if it "understands" it, but if it does so the processing
|
|
rules require that this header block be removed before forwarding. However,
|
|
if the SOAP node chooses to ignore this header block, which it can because it
|
|
is not mandatory to process it, as indicated by the absence of the
|
|
<code>env:mustUnderstand</code> attribute, then it must forward it.</p>
|
|
|
|
<p>Processing the header block <code>p:oneBlock</code> is mandatory and the
|
|
SOAP processing rules require that it not be relayed, unless the processing
|
|
of some other header block requires that it be present in the outbound
|
|
message. The header block <code>r:aThirdBlock</code> does not have an
|
|
<code>env:relay</code> attribute, which is equivalent to having it with the
|
|
value of <code>env:relay </code>= "false". Hence, this header is not
|
|
forwarded if it is not processed.</p>
|
|
|
|
<p><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#tabforwarding">SOAP
|
|
1.2 Part 1 Table 3</a> summarizes the conditions which determine when a SOAP
|
|
intermediary assuming a given role is allowed to forward unprocessed header
|
|
blocks.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="div1">
|
|
|
|
<h2><a name="transport"></a>4. Using Various Protocol Bindings</h2>
|
|
|
|
<p>SOAP messages may be exchanged using a variety of "underlying" protocols,
|
|
including other application layer protocols. The specification of how SOAP
|
|
messages may be passed from one SOAP node to another using an underlying
|
|
protocol is called a <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#concepts">SOAP
|
|
binding</a>. <a href="#L1092">[SOAP Part1]</a> defines a SOAP message in the
|
|
form of an [<a href="#R12">XML Infoset</a>], i.e., in terms of element and
|
|
attribute information items of an abstract "document" called the
|
|
<code>env:Envelope</code> (see<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapenv"> SOAP
|
|
Part 1, section 5</a>). Any SOAP <code>env:Envelope</code> infoset
|
|
representation will be made concrete through a protocol binding, whose task,
|
|
among other things, it is to provide a serialized representation of the
|
|
infoset that can be conveyed to the next SOAP node in the message path in a
|
|
manner such that the original infoset can be reconstructed without loss of
|
|
information.</p>
|
|
|
|
<p>In typical examples of SOAP messages, and certainly in all the examples in
|
|
this primer, the serialization shown is that of a well-formed [<a href="#L3532">XML 1.0</a>] document. However, there may be
|
|
other protocol bindings - for example a protocol binding between two SOAP
|
|
nodes over a limited bandwidth interface - where an alternative, compressed
|
|
serialization of the same infoset may be chosen. Another binding, chosen for
|
|
a different purpose, may provide a serialization which is an encrypted
|
|
structure representing the same infoset. The <a href="#L9527">[MTOM]</a>
|
|
specification provides a SOAP binding to HTTP that allows for an optimized
|
|
serialization of the SOAP message infoset under certain circumstances. A more
|
|
detailed discussion of this binding is deferred to <a href="#L3360">Section
|
|
5.3</a>.</p>
|
|
|
|
<p>In addition to providing a concrete realization of a SOAP infoset between
|
|
adjacent SOAP nodes along a SOAP message path, a protocol binding provides
|
|
the mechanisms to support <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#concepts">features</a>
|
|
that are needed by a SOAP application. A feature is a specification of a
|
|
certain functionality required in the interactions between two SOAP nodes,
|
|
which may be provided by a binding. A feature description is identified by a
|
|
URI, so that all applications referencing it are assured of the same
|
|
semantics. Features are qualified by <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#bindprops">properties</a>,
|
|
which provide additional information that help in the implementation of the
|
|
feature. For example, a typical usage scenario might require many concurrent
|
|
request-response exchanges between adjacent SOAP nodes, in which case the
|
|
feature that is required is the ability to correlate a request with a
|
|
response. The abstract property associated with this feature is a
|
|
"correlation ID". Other examples includes "an encrypted channel" feature, or
|
|
a "reliable delivery channel" feature, or a particular <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapmep">SOAP
|
|
message exchange pattern feature</a>. In particular, the <a href="#L9527">[MTOM]</a> specification defines an <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#feature">Abstract
|
|
SOAP Transmission Optimization feature</a> which may be used by SOAP bindings
|
|
to optimize the serialization of selected element information items of a SOAP
|
|
message infoset. (See <a href="#L3785">section 5.3.1</a> for details).</p>
|
|
|
|
<p>A SOAP binding specification (see <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#transpbindframew">SOAP
|
|
Part 1 section 4</a>) describes, among other things, which (if any) features
|
|
it provides. Some features may be provided natively by the underlying
|
|
protocol. If the feature is not available through the binding, it may be
|
|
implemented within the SOAP envelope, using SOAP header blocks. The
|
|
specification of a feature implemented using SOAP header blocks is called a
|
|
<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapmodules">SOAP
|
|
module</a>.</p>
|
|
|
|
<p>For example, if SOAP message exchanges were being transported directly
|
|
over a datagram protocol like UDP, obviously the message correlation feature
|
|
mentioned earlier would have to be provided by other means, either directly
|
|
by the application or more likely as a part of the SOAP infosets being
|
|
exchanged. In the latter case, the message correlation feature has a
|
|
binding-specific expression within the SOAP envelope, i.e., as a SOAP header
|
|
block, defined in a "Request-Response Correlation" module identified by a
|
|
URI. However, if the SOAP infosets were being exchanged using an underlying
|
|
protocol that was itself request/response, the application could implicitly
|
|
"inherit" this feature provided by the binding, and no further support need
|
|
be provided at the application or the SOAP level. (In fact, the HTTP binding
|
|
for SOAP takes advantage of just this feature of HTTP.) The Abstract SOAP
|
|
Transmission Optimization feature defined in <a href="#L9527" class="insert">[MTOM]</a> is similarly implemented as a part of an augmented
|
|
SOAP HTTP binding, by serializing particular nodes of a SOAP message infoset
|
|
in binary format together with a modified SOAP Envelope, which are then
|
|
carried in separate parts of a MIME Multipart/Related <a href="#L3362">[RFC
|
|
2387]</a> package (see <a href="#L3787">section 5.3.2</a> for details).</p>
|
|
|
|
<p>However, a SOAP message may travel over several hops between a sender and
|
|
the ultimate receiver, where each hop may be a different protocol binding. In
|
|
other words, a feature (e.g., message correlation, reliability etc.) that is
|
|
supported by the protocol binding in one hop may not be supported by another
|
|
along the message path. SOAP itself does not provide any mechanism for hiding
|
|
the differences in features provided by different underlying protocols.
|
|
However, any end-to-end or multi-hop feature that is required by a particular
|
|
application, but which may not be available in the underlying infrastructure
|
|
along the <em>anticipated</em> message path, can be compensated for by being
|
|
carried as a part of the SOAP message infoset, i.e., as a SOAP header block
|
|
specified in some module.</p>
|
|
|
|
<p>Thus it is apparent that there are a number of issues that have to be
|
|
tackled by an application designer to accomplish particular application
|
|
semantics, including how to take advantage of the native features of
|
|
underlying protocols that are available for use in the chosen environment. <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#bindfw">SOAP Part
|
|
1 section 4.2</a> provides a general framework for describing how SOAP-based
|
|
applications may choose to use the features provided by an underlying
|
|
protocol binding to accomplish particular application semantics. It is
|
|
intended to provide guidelines for writing interoperable protocol binding
|
|
specifications for exchanging SOAP messages.</p>
|
|
|
|
<p>Among other things, a binding specification must define one particular
|
|
feature, namely the message exchange pattern(s) that it supports. <a href="#L1098">[SOAP Part2]</a> defines two such message exchange patterns,
|
|
namely a <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#singlereqrespmep">
|
|
SOAP Request-Response message exchange pattern</a> where one SOAP message is
|
|
exchanged in each direction between two adjacent SOAP nodes, and a <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapresmep"> SOAP
|
|
Response message exchange pattern</a> which consists of a non-SOAP message
|
|
acting as a request followed by a SOAP message included as a part of the
|
|
response.</p>
|
|
|
|
<p><a href="#L1098">[SOAP Part2]</a> also offers the application designer a
|
|
general feature called the <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#WebMethodFeature">
|
|
SOAP Web Method feature</a> that allows applications full control over the
|
|
choice of the so-called "Web method" - one of GET, POST, PUT, DELETE whose
|
|
semantics are as defined in the [<a href="#L3133">HTTP 1.1</a>]
|
|
specifications - that may be used over the binding. This feature is defined
|
|
to ensure that applications using SOAP can do so in a manner which is
|
|
compatible with the architectural principles of the World Wide Web. (Very
|
|
briefly, the simplicity and scalability of the Web is largely due to the fact
|
|
that there are a few "generic" methods (GET, POST, PUT, DELETE) which can be
|
|
used to interact with any resource made available on the Web via a URI.) The
|
|
<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#WebMethodFeature">SOAP
|
|
Web Method feature</a> is supported by the SOAP HTTP binding, although, in
|
|
principle, it is available to all SOAP underlying protocol bindings. <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapinhttp"></a></p>
|
|
|
|
<p><a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapinhttp">SOAP
|
|
Part 2 section 7</a> specifies one standardized
|
|
protocol binding using the binding framework of <a href="#L1092">[SOAP
|
|
Part1]</a>, namely how SOAP is used in conjunction with HTTP as the
|
|
underlying protocol. SOAP Version 1.2 restricts itself to the definition of a
|
|
HTTP binding allowing only the use of the POST method in conjunction with the
|
|
Request-Response message exchange pattern and the GET method with the SOAP
|
|
Response message exchange pattern. Other specifications in future could
|
|
define SOAP bindings to HTTP or other transports that make use of the other
|
|
Web methods (i.e., PUT, DELETE).</p>
|
|
|
|
<p>The next sections show examples of two underlying protocol bindings for
|
|
SOAP, namely those to [<a href="#L3133">HTTP 1.1</a>] and email. It should be
|
|
emphasized again that the only normative binding for SOAP 1.2 messages is to
|
|
[<a href="#L3133">HTTP 1.1</a>]. The examples in <a href="#SMTP">section
|
|
4.2</a> showing email as a transport mechanism for SOAP is simply meant to
|
|
suggest that other choices for the transfer of SOAP messages are possible,
|
|
although not standardized at this time. A W3C Note [<a href="#L3215">SOAP
|
|
Email Binding</a>] offers an application of the SOAP protocol binding
|
|
framework of <a href="#L1092">[SOAP Part1]</a> by describing an experimental
|
|
binding of SOAP to email transport, specifically [<a href="#R9">RFC
|
|
2822</a>]-based message transport. The discussion of <a href="#L9527">[MTOM]</a> and its concrete realization in an HTTP binding is
|
|
provided in <a href="#L3360">section 5.3</a>.</p>
|
|
|
|
<div class="div2">
|
|
|
|
<h3><a name="L10309"></a>4.1 The SOAP HTTP Binding</h3>
|
|
|
|
<p>HTTP has a well-known connection model and a message exchange pattern. The
|
|
client identifies the server via a URI, connects to it using the underlying
|
|
TCP/IP network, issues a HTTP request message and receives a HTTP response
|
|
message over the same TCP connection. HTTP implicitly correlates its request
|
|
message with its response message; therefore, an application using this
|
|
binding can chose to infer a correlation between a SOAP message sent in the
|
|
body of a HTTP request message and a SOAP message returned in the HTTP
|
|
response. Similarly, HTTP identifies the server endpoint via a URI, the <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.1.2">Request-URI</a>,
|
|
which can also serve as the identification of a SOAP node at the server.</p>
|
|
|
|
<p>HTTP allows for multiple intermediaries between the initial client and the
|
|
<a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec1.html#sec1.3">origin
|
|
server</a> identified by the Request-URI, in which case the request/response
|
|
model is a series of such pairs. Note, however, that HTTP intermediaries are
|
|
distinct from SOAP intermediaries.</p>
|
|
|
|
<p>The HTTP binding in <a href="#L1098">[SOAP
|
|
Part2]</a> makes use of the<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#WebMethodFeature">SOAP
|
|
Web Method feature</a> to allow applications to choose the so-called Web
|
|
method - restricting it to one of GET or POST - to use over the HTTP message
|
|
exchange. In addition, it makes use of two message exchange patterns that
|
|
offer applications two ways of exchanging SOAP messages via HTTP: 1) the use of the
|
|
HTTP POST method for conveying SOAP messages in the bodies of HTTP request
|
|
and response messages, and 2) the use of the HTTP GET
|
|
method in a HTTP request to return a SOAP message in the body of a HTTP
|
|
response. The first usage pattern is the HTTP-specific instantiation of a
|
|
binding feature called the <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#singlereqrespmep">SOAP request-response message exchange pattern</a>, while the second uses a feature
|
|
called the <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapresmep">SOAP response message exchange pattern</a>.</p>
|
|
|
|
<p>The purpose of providing these two types of usages is
|
|
to accommodate the two interaction paradigms which are well established on
|
|
the World Wide Web. The first type of interaction allows for the use of data
|
|
within the body of a HTTP POST to create or modify the state of a resource
|
|
identified by the URI to which the HTTP request is destined. The second type
|
|
of interaction pattern offers the ability to use a HTTP GET request to obtain
|
|
a representation of a resource without altering its state in any way. In the
|
|
first case, the SOAP-specific aspect of concern is that the body of the HTTP
|
|
POST request is a SOAP message which has to be processed (per the SOAP
|
|
processing model) as a part of the application-specific processing required
|
|
to conform to the POST semantics. In the second case, the typical usage that
|
|
is forseen is the case where the representation of the resource that is being
|
|
requested is returned not as a HTML, or indeed a generic XML document, but as
|
|
a SOAP message. That is, the HTTP content type header of the response message
|
|
identifies it as being of media type "application/soap+xml"
|
|
[<a href="#r13">RFC 3902</a>]. Presumably,
|
|
there will be publishers of resources on the Web who determine that such
|
|
resources are best retrieved and made available in the form of SOAP messages.
|
|
Note, however, that resources can, in general, be made available in multiple
|
|
representations, and the desired or preferred representation is indicated by
|
|
the requesting application using the HTTP <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1">Accept</a>
|
|
header.</p>
|
|
|
|
<p>One further aspect of
|
|
the SOAP HTTP binding is the question of how an application determines which
|
|
of these two types of message exchange patterns to use.
|
|
<a href="#L1098">[SOAP Part2]</a> offers guidance on
|
|
circumstances when applications may use one of the two specified message
|
|
exchange patterns. (It is guidance - albeit a strong one - as it is phrased
|
|
in the form of a "<a href="http://www.ietf.org/rfc/rfc2119.txt">SHOULD</a>" in the
|
|
specifications rather than an absolute requirement identified by the word
|
|
"<a href="http://www.ietf.org/rfc/rfc2119.txt">MUST</a>", where these
|
|
words are interpreted as defined in the IETF [<a href="#L15789">RFC
|
|
2119</a>].) The SOAP response message exchange pattern with the HTTP GET
|
|
method is used when an application is assured that the message exchange is
|
|
for the purposes of information retrieval, where the information resource is
|
|
"untouched" as a result of the interaction. Such interactions are referred to
|
|
as <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1">safe and
|
|
idempotent</a> in the HTTP specification. 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.</p>
|
|
|
|
<p>The following
|
|
subsections provide examples of the use of these two message exchange
|
|
patterns defined for the HTTP binding.</p>
|
|
|
|
<div class="div3">
|
|
|
|
<h4><a name="L26854"></a>4.1.1 SOAP HTTP GET Usage</h4>
|
|
|
|
<p>Using the HTTP binding with the <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapresmep">SOAP Response message exchange pattern</a> is restricted to the HTTP GET method. This means that
|
|
the response to a HTTP GET request from a requesting SOAP node is a SOAP
|
|
message in the HTTP response.</p>
|
|
|
|
<p><a href="#Ref4774883961121">Example 8a</a> shows a HTTP GET directed by the
|
|
traveller's application (in the continuing travel reservation scenario) at
|
|
the URI<code>
|
|
http://travelcompany.example.org/reservations?code=FT35ZBQ</code> >where the traveler's itinerary may be viewed. (How
|
|
this URL was made available can be seen in
|
|
<a href="#Example5">Example 5a</a>.)</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Ref4774883961121" name="Ref4774883961121">Example 8a</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>GET /travelcompany.example.org/reservations?code=FT35ZBQ HTTP/1.1
|
|
Host: travelcompany.example.org
|
|
Accept: text/html;q=0.5, application/soap+xml</pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
HTTP GET Request</div>
|
|
</div>
|
|
|
|
<p>The HTTP <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1">Accept</a>
|
|
header is used to indicate the preferred representation of the resource being
|
|
requested, which in this example is an "application/soap+xml" media type for
|
|
consumption by a machine client, rather than the "text/html" media type for
|
|
rendition by a browser client for consumption by a human.</p>
|
|
|
|
<p><a href="#Example13">Example 8b</a> shows the HTTP
|
|
response to the GET in <a href="#Ref4774883961121">Example 8a</a>. The body
|
|
of the HTTP response contains a SOAP message showing the travel details. A
|
|
discussion of the contents of the SOAP message is postponed until <a href="#L3374">section 5.2</a> , as it is not relevant, at this point, to
|
|
understanding the HTTP GET binding usage.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a name="Example13" id="Example13">Example 8b</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>HTTP/1.1 200 OK
|
|
Content-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></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
SOAP message returned as a response to the HTTP GET in <a href="#Ref4774883961121">Example 8a</a></div>
|
|
</div>
|
|
|
|
<p>Note that the
|
|
reservation details could well have been returned as an (X)HTML document, but
|
|
this example wanted to show a case where the reservation application is
|
|
returning the state of the resource (the reservation) in a data-centric media
|
|
form (a SOAP message) which can be machine processed, instead of (X)HTML
|
|
which would be processed by a browser. Indeed, in the most likely anticipated
|
|
uses of SOAP, the consuming application will not be a browser.</p>
|
|
|
|
<p>Also, as shown in the example, the use of
|
|
SOAP in the HTTP response body offers the possibility of expressing some
|
|
application-specific feature through the use of SOAP headers. By using SOAP,
|
|
the application is provided with a useful and consistent framework and
|
|
processing model for expressing such features.</p>
|
|
|
|
</div>
|
|
<div class="div3">
|
|
|
|
<h4><a name="L26866"></a>4.1.2 SOAP HTTP POST Usage</h4>
|
|
|
|
<p>Using the HTTP binding with the<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#singlereqrespmep">
|
|
SOAP Request-Response message exchange pattern</a> is restricted to the HTTP
|
|
POST method. Note that the use of this message exchange pattern in the SOAP
|
|
HTTP binding is available to all applications, whether they involve the
|
|
exchange of general XML data or RPCs (as in the following examples)
|
|
encapsulated in SOAP messages.</p>
|
|
|
|
<p>Examples <a href="#Ref47748839611">9</a> and
|
|
<a href="#Ref47748860211">10</a> show an example of a HTTP binding
|
|
using the SOAP Request-Response message exchange
|
|
pattern, using the same scenario as that
|
|
for <a href="#Example2">Example 4</a> and <a href="#Example5">Example 5a</a>, respectively, namely conveying an RPC and its return
|
|
in the body of a SOAP message. The examples and discussion in this section
|
|
only concentrate on the HTTP headers and their role.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Ref47748839611" name="Ref47748839611">Example 9</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>POST /Reservations HTTP/1.1
|
|
Host: travelcompany.example.org
|
|
Content-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></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
RPC in <a href="#Example2">Example 4</a> carried in an HTTP POST Request</div>
|
|
</div>
|
|
|
|
<p><a href="#Ref47748839611">Example 9</a> shows an RPC request directed at
|
|
the travel service application. The SOAP message is sent in the body of a
|
|
HTTP POST method directed at the URI identifying the "Reservations" resource
|
|
on the server travelcompany.example.org. When using HTTP, the Request-URI
|
|
indicates the resource to which the invocation is "posted". Other than
|
|
requiring that it be a valid URI, SOAP places no <em>formal</em> restriction
|
|
on the form of the request URI (see <a href="#RFC3986">[RFC 3986]</a> for more
|
|
information on URIs). However, one of the principles of the Web architecture
|
|
is that all important resources be identified by URIs. This implies that most
|
|
well-architected SOAP services will be embodied as a large number of
|
|
resources, each with its own URI. Indeed, many such resources are likely to
|
|
be created dynamically during the operation of a service, such as, for
|
|
instance, the specific travel reservation shown in the example. So, a
|
|
well-architected travel service application should have different URIs for
|
|
each reservation, and SOAP requests to retrieve or manipulate those
|
|
reservations will be directed at their URIs, and not at a single monolithic
|
|
"Reservations" URI, as shown in <a href="#Ref47748839611">Example 9</a>. <a href="#Ref477488396111"> Example 13</a> in <a href="#L3677">section 4.1.3</a>
|
|
shows the preferred way to address resources such as a particular travel
|
|
reservation. Therefore, we defer until <a href="#L3677">section 4.1.3</a>
|
|
further discussion of Web architecture compatible SOAP/HTTP usage.</p>
|
|
|
|
<p>When placing SOAP messages in HTTP bodies, the HTTP Content-type header
|
|
must be chosen as "application/soap+xml" [<a href="#r13">RFC 3902</a>]. (The
|
|
optional charset parameter, which can take the value of "<a href="http://www.ietf.org/rfc/rfc2279.txt">utf-8</a>" or "<a href="http://www.ietf.org/rfc/rfc2781.txt">utf-16</a>", is shown in this
|
|
example, but if it is absent the character set rules for freestanding [<a href="#L3532">XML 1.0</a>] apply to the body of the HTTP request.)</p>
|
|
|
|
<p><a href="#Ref47748860211">Example 10</a> shows the RPC return (with
|
|
details omitted) sent by the travel service application in the corresponding
|
|
HTTP response to the request from <a href="#Example5">Example 5a</a>. SOAP,
|
|
using HTTP transport, follows the semantics of the HTTP status codes for
|
|
communicating status information in HTTP. For example, the 2xx series of HTTP
|
|
status codes indicate that the client's request (including the SOAP
|
|
component) was successfully received, understood, and accepted etc.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Ref47748860211" name="Ref47748860211">Example 10</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>HTTP/1.1 200 OK
|
|
Content-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>
|
|
...
|
|
...
|
|
</env:Header>
|
|
<env:Body>
|
|
...
|
|
...
|
|
</env:Body>
|
|
</env:Envelope></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
RPC return in <a href="#Example5">Example 5a</a> embedded in an HTTP Response
|
|
indicating a successful completion</div>
|
|
</div>
|
|
|
|
<p>If an error occurs processing the request, the HTTP binding specification
|
|
requires that a HTTP 500 "Internal Server Error" be used with an embedded
|
|
SOAP message containing a SOAP fault indicating the server-side processing
|
|
error.</p>
|
|
|
|
<p><a href="#Example10">Example 11</a> is the same SOAP fault message as <a href="#Example7">Example 6a</a>, but this time with the HTTP headers
|
|
added.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a name="Example10" id="Example10">Example 11</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>HTTP/1.1 500 Internal Server Error
|
|
Content-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></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
Sample SOAP message in a HTTP Response indicating failure <span class="exampleWrapper">to handle the SOAP Body in <a href="#Example2">Example
|
|
4</a></span></div>
|
|
</div>
|
|
|
|
<p><a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#http-reqbindwaitstate">SOAP
|
|
Part 2 Table 16</a> provides detailed behavior for handling the various
|
|
possible HTTP response codes, i.e., the 2xx (successful), 3xx (redirection),
|
|
4xx (client error) and 5xx (server error).</p>
|
|
|
|
</div>
|
|
<div class="div3">
|
|
|
|
<h4><a name="L3677"></a>4.1.3 Web Architecture Compatible SOAP Usage</h4>
|
|
|
|
<p>One of the most central concepts of the World Wide Web is that of a URI as
|
|
a resource identifier. SOAP services that use the HTTP binding and wish to
|
|
interoperate with other Web software should use URIs to address all important
|
|
resources in their service. For example, a very important - indeed
|
|
predominant - use of the World Wide Web is pure information retrieval, where
|
|
the representation of an available resource, identified by a URI, is fetched
|
|
using a HTTP GET request without affecting the resource in any way. (This is
|
|
called a <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1">safe and
|
|
idempotent method</a> in HTTP terminology.) The
|
|
key point is that the publisher of a resource makes available its URI, which
|
|
consumers may "GET".</p>
|
|
|
|
<p>There are many
|
|
instances when SOAP messages are designed for uses which are purely for
|
|
information retrieval, such as when the state of some resource (or object, in
|
|
programming terms) is requested, as opposed to uses that perform resource
|
|
manipulation. In such instances, the use of a SOAP body to carry the request
|
|
for the state, with an element of the body representing the object in
|
|
question, is seen as counter to the spirit of the Web because the resource is
|
|
not identified by the Request-URI of the HTTP GET. (In some SOAP/RPC
|
|
implementations, the HTTP Request-URI is often not the identifier of the
|
|
resource itself but some intermediate entity which has to evaluate the SOAP
|
|
message to identify the resource.)</p>
|
|
|
|
<p>To highlight the changes needed, <a href="#Example211">Example 12a</a> shows the way that is <em>not</em>
|
|
recommended for doing safe information retrieval on the Web. This is an
|
|
example of an RPC carried in a SOAP message, again using the travel
|
|
reservation theme, where the request is to retrieve the itinerary for a
|
|
particular reservation identified by one of the parameters,
|
|
<code>reservationCode</code>, of the RPC. (For purposes of this discussion,
|
|
it is assumed that the application using this RPC request does not need
|
|
features which require the use of SOAP headers.)</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Example211" name="Example211">Example 12a</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>POST /Reservations HTTP/1.1
|
|
Host: travelcompany.example.org
|
|
Content-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>
|
|
<m:retrieveItinerary
|
|
env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
|
|
xmlns:m="http://travelcompany.example.org/">
|
|
<m:reservationCode>FT35ZBQ</m:reservationCode>
|
|
</m:retrieveItinerary>
|
|
</env:Body>
|
|
</env:Envelope></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
This representation is discouraged in cases where the operation is a "safe"
|
|
retrieval (i.e., it has no side effects)</div>
|
|
</div>
|
|
|
|
<p>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.</p>
|
|
|
|
<p><a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#RPConWeb">SOAP
|
|
Part 2 section 4.1</a> offers recommendations on how RPCs that constitute
|
|
safe and idempotent information retrievals may be defined in a Web-friendly
|
|
manner. It does so by distinguishing aspects of the method and specific
|
|
parameters in an RPC definition that serve to identify resources from those
|
|
that serve other purposes. In <a href="#Example211">Example 12a</a>, the
|
|
resource to be retrieved 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
|
|
specific instance (a parameter to the method). In such a case, the
|
|
recommendation is that these resource-identifying parts be made available in
|
|
the HTTP Request-URI identifying the resource, as for example, as follows:
|
|
<code>http://travelcompany.example.org/reservations/itinerary?reservationCode=FT35ZBQ</code>.</p>
|
|
|
|
<p>Furthermore, when an RPC definition is such that
|
|
all 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 the
|
|
supplier 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 property
|
|
of GET and the use of the <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapresmep"> SOAP
|
|
Response message exchange pattern</a> be used as described in <a href="#L26854">section 4.1.1</a>. This will ensure that the SOAP RPC is
|
|
performed in a Web architecture compatible manner. <a href="#Ref4774883961111">Example 12b </a>shows the preferred way for a SOAP
|
|
node to request the safe retrieval of a resource.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Ref4774883961111" name="Ref4774883961111">Example 12b</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>GET /Reservations/itinerary?reservationCode=FT35ZBQ HTTP/1.1
|
|
Host: travelcompany.example.org
|
|
Accept: application/soap+xml</pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
The Web architecture compatible alternative to representing the RPC in <a href="#Example211">Example 12a</a></div>
|
|
</div>
|
|
|
|
<p>It should be noted that SOAP Version 1.2 does not
|
|
specify any algorithm on how to compute a URI from the definition of an RPC
|
|
which has been determined to represent pure information retrieval.</p>
|
|
|
|
<p>Note, however, that if
|
|
the application requires the use of features that can only have a
|
|
binding-specific expression within the SOAP infoset, i.e., using SOAP header
|
|
blocks, then the application must choose HTTP POST method with a SOAP message
|
|
in the request body.</p>
|
|
|
|
<p>It also requires the use of the <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#singlereqrespmep">SOAP Request-Response message exchange pattern</a> 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. As with the use of the GET, <a href="#L1098">[SOAP Part2]</a>
|
|
recommends for the general case that any part of the SOAP message that serves
|
|
to identify the resource to which the request is POSTed be identified in the
|
|
HTTP Request-URI. The same parameters may, of course, be retained in the
|
|
SOAP <code>env:Body</code> element. (The parameters must be retained in the Body
|
|
in the case of a SOAP-based RPC as these are related to the procedure/method
|
|
description expected by the receiving application.)</p>
|
|
|
|
<p><a href="#Ref477488396111">Example 13</a> is the same as that in <a href="#Ref47748839611">Example 9</a>, except that the HTTP Request-URI has
|
|
been modified to include the reservation <code>code</code>, which serves to identify the
|
|
resource (the reservation in question, which is being confirmed and paid
|
|
for).</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Ref477488396111" name="Ref477488396111">Example 13</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>POST /Reservations?code=FT35ZBQ HTTP/1.1
|
|
Host: travelcompany.example.org
|
|
Content-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></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
RPC from <a href="#Example2">Example 4</a> carried in an HTTP POST Request in
|
|
a Web-friendly manner</div>
|
|
</div>
|
|
|
|
<p>In <a href="#Ref477488396111">Example 13</a>, the resource to be
|
|
manipulated is identified by two things: the first is that it is a
|
|
reservation (part of the method name), and the second is the specific
|
|
instance of a reservation (which is the value of the parameter
|
|
<code>code</code> to the method). The remainder of the parameters in the RPC
|
|
such as the <code>creditCard</code> number are not resource-identifying, but
|
|
are ancillary data to be processed by the resource. It is the recommendation
|
|
of [<a href="#L1098">SOAP Part2</a>] that resources that may be accessed by
|
|
SOAP-based RPCs should, where practical, place any such resource-identifying
|
|
information as a part of the URI identifying the target of the RPC. It
|
|
should be noted, however, that [<a href="#L1098">SOAP Part2</a>] does not
|
|
offer any algorithm to do so. Such algorithms may be developed in future.
|
|
Note, however, that all the resource-identifying elements have been retained
|
|
as in <a href="#Ref47748839611">Example 9</a> in their encoded form in the
|
|
SOAP <code>env:Body</code> element.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="div2">
|
|
|
|
<h3><a name="SMTP"></a>4.2 SOAP Over Email</h3>
|
|
|
|
<p>Application developers can use the Internet email infrastructure to move
|
|
SOAP messages as either email text or attachments. The examples shown below
|
|
offer one way to carry SOAP messages, and should not be construed as being
|
|
the standard way of doing so. The SOAP Version 1.2 specifications do not
|
|
specify such a binding. However, there is a <em>non-normative</em> W3C Note
|
|
[<a href="#L3215">SOAP Email Binding</a>] describing an email binding for
|
|
SOAP, its main purpose being to demonstrate the application of the general
|
|
SOAP Protocol Binding Framework described in [<a href="#L1092">SOAP Part
|
|
1</a>].</p>
|
|
|
|
<p><a href="#Example14">Example 14</a> shows the travel reservation request
|
|
message from <a href="#Example">Example 1</a> carried as an email message
|
|
between a sending and receiving mail user agent. It is implied that the
|
|
receiver node has SOAP capabilities, to which the body of the email is
|
|
delivered for processing. (It is assumed that the sending node also has SOAP
|
|
capabilities so as to be able to process any SOAP faults received in
|
|
response, or to correlate any SOAP messages received in response to this
|
|
one.)</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Example14" name="Example14">Example 14</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>From: a.oyvind@mycompany.example.com
|
|
To: reservations@travelcompany.example.org
|
|
Subject: Travel to LA
|
|
Date: Thu, 29 Nov 2001 13:20:00 EST
|
|
Message-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</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></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
SOAP message from <a href="#Example">Example 1</a> carried in a SMTP
|
|
message</div>
|
|
</div>
|
|
|
|
<p>The header in <a href="#Example14">Example 14</a> is in the standard form
|
|
[<a href="#R9">RFC 2822</a>] for email messages.</p>
|
|
|
|
<p>Although an email is a one-way message exchange, and no guarantee of
|
|
delivery is provided, email infrastructures like the Simple Mail Transport
|
|
Protocol (SMTP) specification [<a href="#R9">SMTP</a>] offer a delivery
|
|
notification mechanism which, in the case of SMTP, are called Delivery Status
|
|
Notification (DSN) and Message Disposition Notification (MDN). These
|
|
notifications take the form of email messages sent to the email address
|
|
specified in the mail header. Applications, as well as email end users, can
|
|
use these mechanisms to provide the status of an email transmission, but
|
|
these, if delivered, are notifications at the SMTP level. The application
|
|
developer must fully understand the capabilities and limitations of these
|
|
delivery notifications or risk assuming a successful data delivery when none
|
|
occurred.</p>
|
|
|
|
<p>SMTP delivery status messages are separate from message processing at the
|
|
SOAP layer. Resulting SOAP responses to the contained SOAP data will be
|
|
returned through a new email message which may or may not have a link to the
|
|
original requesting email at the SMTP level. The use of the [<a href="#R9">RFC 2822</a>] <code>In-reply-to:</code> header can achieve a
|
|
correlation at the SMTP level, but does not necessarily offer a correlation
|
|
at the SOAP level.</p>
|
|
|
|
<p><a href="#Example31">Example 15</a> is exactly the same scenario as
|
|
described for <a href="#Example3">Example 2</a>, which shows the SOAP message
|
|
(body details omitted for brevity) sent from the travel service application
|
|
to the travel reservation application seeking clarification on some
|
|
reservation details, except that it is carried as an email message. In this
|
|
example, the original email's<code> Message-Id</code> is carried in the
|
|
additional email header <code>In-reply-to:</code>, which correlates email
|
|
messages at the SMTP level, but cannot provide a SOAP-specific correlation.
|
|
In this example, the application relies on the <code>reservation</code>
|
|
header block to correlate SOAP messages. Again, how such correlation is
|
|
achieved is application-specific, and is not within the scope of SOAP.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Example31" name="Example31">Example 15</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>From: reservations@travelcompany.example.org
|
|
To: a.oyvind@mycompany.example.com
|
|
Subject: Which NY airport?
|
|
Date: Thu, 29 Nov 2001 13:35:11 EST
|
|
Message-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</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:itinerary
|
|
xmlns:p="http://travelcompany.example.org/reservation/travel">
|
|
<p:itineraryClarifications>
|
|
...
|
|
...
|
|
</p:itineraryClarifications>
|
|
</p:itinerary>
|
|
</env:Body>
|
|
</env:Envelope></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
SOAP message from <a href="#Example3">Example 2</a> carried in an email
|
|
message with a header correlating it to a previous message.</div>
|
|
</div>
|
|
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
|
|
<h2><a name="L579"></a>5. Advanced Usage Scenarios</h2>
|
|
|
|
<div class="div2">
|
|
|
|
<h3><a name="L635"></a>5.1 Using SOAP Intermediaries</h3>
|
|
|
|
<p>The travel reservation scenario used throughout the primer offers an
|
|
opportunity to expose some uses of SOAP intermediaries. Recall that the basic
|
|
exchange was the exchange of a travel reservation request between a travel
|
|
reservation application and a travel service application. SOAP does not
|
|
specify how such a message path is determined and followed. That is outside
|
|
the scope of the SOAP specification. It does describe, though, how a SOAP
|
|
node should behave if it receives a SOAP message for which it is not the
|
|
ultimate receiver. SOAP Version 1.2 describes two types of intermediaries: <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#forwardinter">forwarding
|
|
intermediaries</a> and <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#activeinter">active
|
|
intermediaries</a>.</p>
|
|
|
|
<p>A <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#forwardinter">forwarding
|
|
intermediary</a> is a SOAP node which, based on the semantics of a header
|
|
block in a received SOAP message or based on the message exchange pattern in
|
|
use, forwards the SOAP message to another SOAP node. For example, processing
|
|
a "routing" header block describing a message path feature in an incoming
|
|
SOAP message may dictate that the SOAP message be forwarded to another SOAP
|
|
node identified by data in that header block. The format of the SOAP header
|
|
of the outbound SOAP message, i.e., the placement of inserted or reinserted
|
|
header blocks, is determined by the overall processing at this
|
|
<em>forwarding</em> intermediary based on the semantics of the processed
|
|
header blocks.</p>
|
|
|
|
<p>An <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#activeinter">active
|
|
intermediary</a> is one that does additional processing on an incoming SOAP
|
|
message before forwarding the message using criteria that are not described
|
|
by incoming SOAP header blocks, or by the message exchange pattern in use.
|
|
Some examples of such active intervention at a SOAP node could be, for
|
|
instance, encrypting some parts of a SOAP message and providing the
|
|
information on the cipher key in a header block, or including some additional
|
|
information in a new header block in the outbound message providing a
|
|
timestamp or an annotation, for example, for interpretation by appropriately
|
|
targeted nodes downstream.</p>
|
|
|
|
<p>One mechanism by which an active intermediary can describe the
|
|
modifications performed on a message is by inserting header blocks into the
|
|
outbound SOAP message. These header blocks can inform downstream SOAP nodes
|
|
acting in roles whose correct operation depends on receiving such
|
|
notification. In this case, the semantics of such inserted header blocks
|
|
should also call for either the same or other header blocks to be
|
|
(re)inserted at subsequent intermediaries as necessary to ensure that the
|
|
message can be safely processed by nodes yet further downstream. For example,
|
|
if a message with header blocks removed for encryption passes through a
|
|
second intermediary (without the original header blocks being decrypted and
|
|
reconstructed), then indication that the encryption has occurred must be
|
|
retained in the second relayed message.</p>
|
|
|
|
<p>In the following example, a SOAP node is introduced in the message path
|
|
between the travel reservation and travel service applications, which
|
|
intercepts the message shown in <a href="#Example">Example 1</a>. An example
|
|
of such a SOAP node is one which logs all travel requests for off-line review
|
|
by a corporate travel office. Note that the header blocks
|
|
<code>reservation</code> and <code>passenger</code> in that example are
|
|
intended for the node(s) that assume the role "next", which means that it is
|
|
targeted at the next SOAP node in the message path that receives the message.
|
|
The header blocks are mandatory (the <code>mustUnderstand</code> attribute is
|
|
set to "true"), which means that the node must have knowledge (through an
|
|
external specification of the header blocks' semantics) of what to do. A
|
|
logging specification for such header blocks might simply require that
|
|
various details of the message be recorded at every node that receives such a
|
|
message, and that the message be relayed along the message path unchanged.
|
|
(Note that the specifications of the header blocks must require that the same
|
|
header blocks be reinserted in the outbound message, because otherwise, the
|
|
SOAP processing model would require that they be removed.) In this case, the
|
|
SOAP node acts as a forwarding intermediary.</p>
|
|
|
|
<p>A more complex scenario is one where the received SOAP message is amended
|
|
in some way not anticipated by the initial sender. In the following example,
|
|
it is assumed that a corporate travel application at the SOAP intermediary
|
|
attaches a header block to the SOAP message from <a href="#Example">Example
|
|
1</a> before relaying it along its message path towards the travel service
|
|
application - the ultimate recipient. The header block contains the
|
|
constraints imposed by a travel policy for this requested trip. The
|
|
specification of such a header block might require that the ultimate
|
|
recipient (and only the ultimate recipient, as implied by the absence of the
|
|
<code>role</code> attribute) make use of the information conveyed by it when
|
|
processing the body of the message.</p>
|
|
|
|
<p><a href="#Example6">Example 16</a> shows an active intermediary inserting
|
|
an additional header block, <code>travelPolicy</code>, intended for the
|
|
ultimate recipient which includes information that qualifies the
|
|
application-level processing of this travel request.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Example6" name="Example6">Example 16</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre><?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>
|
|
<span class="highlight"><z:travelPolicy
|
|
xmlns:z="http://mycompany.example.com/policies"
|
|
env:mustUnderstand="true"></span>
|
|
<z:class>economy</z:class>
|
|
<z:fareBasis>non-refundable<z:fareBasis>
|
|
<z:exceptions>none</z:exceptions>
|
|
<span class="highlight"></z:travelPolicy></span>
|
|
</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></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
SOAP message from <a href="#Example">Example 1</a> for a travel reservation
|
|
after an active intermediary has inserted a mandatory header intended for the
|
|
ultimate recipient of the message</div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
|
|
<h3><a name="L3374"></a>5.2 Using Other Encoding Schemes</h3>
|
|
|
|
<p>Even though SOAP Version 1.2 defines a particular encoding scheme (see<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapenc"> SOAP
|
|
Part 2 section 3</a>), its use is optional and the specification makes clear
|
|
that other encoding schemes may be used for application-specific data within
|
|
a SOAP message. For this purpose it provides the attribute<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapencattr">
|
|
<code>env:encodingStyle</code></a>, of type <code>xs:anyURI</code>, to
|
|
qualify header blocks, any child elements of the SOAP <code>env:Body,</code>
|
|
and any child elements of the <code>env:Detail</code> element and their
|
|
descendants. It signals a serialization scheme for the nested contents, or at
|
|
least the one in place until another element is encountered which indicates
|
|
another encoding style for its nested contents. The choice of the value for
|
|
the <code>env:encodingStyle</code> attribute is an application-specific
|
|
decision and the ability to interoperate is assumed to have been settled
|
|
"out-of-band". If this attribute is not present, then no claims are being
|
|
made about the encoding being used.</p>
|
|
|
|
<p>The use of an alternative encoding scheme is illustrated in <a href="#Example9">Example 17</a>. Continuing with the travel reservation
|
|
theme, this example shows a SOAP message which is sent to the passenger from
|
|
the travel service after the reservation is confirmed, showing the travel
|
|
details. (The same message was used in <a href="#Example13">Example 8b</a> in another context.)</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a id="Example9" name="Example9">Example 17</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre><?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#"
|
|
<span class="highlight">env:encodingStyle="http://www.w3.org/1999/02/22-rdf-syntax-ns#"</span>>
|
|
<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></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
SOAP message showing the use of an alternative encoding for the
|
|
<code>Body</code> element</div>
|
|
</div>
|
|
|
|
<p>In <a href="#Example9">Example 17</a>, the body of the SOAP message
|
|
contains a description of the itinerary using the encoding of a graph of
|
|
resources and their properties using the syntax of the Resource Description
|
|
Framework (RDF) [<a href="#L4867">RDF</a>]. (Very briefly, as RDF syntax or
|
|
usage is not the subject of this primer, an RDF graph relates resources -
|
|
such as the travel reservation resource available at
|
|
<code>http://travelcompany.example.org/reservations?code=FT35ZBQ</code> - to
|
|
other resources (or values) via properties, such as the
|
|
<code>passenger</code>, the <code>outbound</code> and <code>return</code>
|
|
dates 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 an
|
|
RDF-capable calendar application, which could then be queried in complex
|
|
ways.)</p>
|
|
|
|
</div>
|
|
<div class="div2">
|
|
|
|
<h3><a name="L3360"></a>5.3 Optimized serialization of SOAP messages</h3>
|
|
|
|
There are many use cases where it is necessary for an application to send a
|
|
large amount of binary (i.e., non-textual) data (e.g., a JPEG image, binary
|
|
executable etc.) in a SOAP message. The conventional way of conveying binary
|
|
data in an XML document, such as the SOAP <code>env:Envelope</code>, is to
|
|
transform the binary data into a character representation of type <code><a href="http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#base64Binary">xs:base64Binary</a></code>
|
|
using the Base64 content-transfer-encoding scheme defined in <a href="#L3410">[RFC 2045]</a>. The disadvantages of this approach are that
|
|
there is a significant increase in message size, as well as a potential
|
|
processing overhead in encoding/decoding the binary data to/from its
|
|
character representation, which may create throughput problems in case of
|
|
message transmission over low bandwidth links or SOAP nodes with low
|
|
processing power.
|
|
|
|
<p>The [<a href="#L9527">MTOM</a>] specification provides a mechanism to
|
|
support such use cases. It should be noted, though, that the specification
|
|
does not address the general problem of handling the inclusion of non-XML
|
|
content in arbitrary XML documents, but confines itself to the specific case
|
|
of SOAP message transmission optimization for certain type of content.</p>
|
|
|
|
<p>In order to allow for independence from the underlying protocol binding,
|
|
so that the optimization mechanism may be available over a variety of
|
|
transports, as well as to retain the principal SOAP binding paradigm - that
|
|
the SOAP message infoset, however serialized, be transmitted unchanged
|
|
between adjacent nodes - [<a href="#L9527">MTOM</a>] defines an <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#feature">Abstract
|
|
SOAP Transmission Optimization feature</a>, of which <em class="insert">one</em> implementation is provided for the particular case of
|
|
HTTP-based transmission of an optimized SOAP message in a MIME
|
|
Multipart/Related [<a href="#L3362">RFC 2387</a>] package. This makes use of
|
|
the <a href="#L3777">[XOP]</a> format (on which more in <a href="#L3787">Section 5.3.2</a>) which is an alternative serialization of an
|
|
XML infoset geared towards a more eficient processing and representation of
|
|
Base64-encoded content.</p>
|
|
|
|
<div class="div3">
|
|
|
|
<h4><a name="L3785"></a>5.3.1 The Abstract SOAP Transmission Optimization Feature</h4>
|
|
|
|
<p>The <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#feature">Abstract
|
|
SOAP Transmission Optimization feature</a> is defined for certain <a href="http://www.w3.org/TR/2004/REC-xml-infoset-20040204/#infoitem.element">element
|
|
information item</a> in the SOAP message infoset which are identified as
|
|
potential candidates for optimization. XML infosets identify the structure
|
|
and content of XML documents, but not the data type of the contents of
|
|
elements and attributes. One way to identify these would require schema
|
|
validation of the infoset, something which is <em>not</em> a
|
|
requirement for SOAP. A more likely possibility is that the sending
|
|
application already "knows" the type of data - a binary stream, and perhaps
|
|
also the nature of the media type that it represents - that it wishes to
|
|
transmit because that is the way in which the data is already available to
|
|
it. The <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#feature">Abstract
|
|
SOAP Transmission Optimization feature</a> assumes that the type information
|
|
for those <a href="http://www.w3.org/TR/2004/REC-xml-infoset-20040204/#infoitem.element" class="insert">element information items</a> which are potential candidates
|
|
for optimization are somehow available to the sender of a SOAP message. This
|
|
feature is restricted to the optimization of character information items of
|
|
any element information item in the SOAP message infoset which is known to be
|
|
of type <a href="http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#base64Binary">xs:base64Binary</a>
|
|
in its canonical lexical form (see [<a href="#R8">Schema Part2</a>] <a href="http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#base64Binary">Section
|
|
3.2.16 base64Binary</a>). (The rationale for the restriction to the canonical
|
|
form of <code>xs:base64Binary</code> is provided at <a href="#important">the
|
|
end</a> of this section.)</p>
|
|
|
|
<p>To motivate the need for [<a href="#L9527">MTOM</a>], consider the example
|
|
of a SOAP message sent in response to the request for the travel itinerary in
|
|
<a href="#Ref4774883961111">Example 12b</a>. The travel reservation
|
|
application may wish to send, in addition to the information which can
|
|
readily be represented in XML, a corporate logo, a map of the destination and
|
|
other such information which is available in binary format (e.g., image
|
|
files). If there were only a small amount of non-XML data, it may be possible
|
|
to convert such data to its base64 encoding and convey the result in a SOAP
|
|
message sent in the HTTP response as shown in <a href="#Example15">Example
|
|
18</a> (with irrelevant content indicated by ellipses for brevity, and line
|
|
breaks added for clarity).</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a name="Example15">Example 18</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>HTTP/1.1 200 OK
|
|
Content-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: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:passenger>
|
|
</env:Header>
|
|
<env:Body>
|
|
<span class="highlight"><o:travelAgencyLogo xmlns:o="http://travelcompany.example.org/images"></span>HlkR4cT
|
|
YvAQLAcOAAAAAAQCAAgEAA0GAAEJAAYLAAoNAA8PAAAAJAQCJAgEJA0GJAEJJAYLJAoNJ
|
|
A8PJAAASAQCSAgESA0GSAEJSAYLSAoNSA8PSAAQbAQSbAgUbA0WbAEZbAYbbAodbA8fbAAQkAQSk
|
|
AgUkA0WkAEZkAYbkAodkA8fkAAgtAQitAgktA0mtAEptAYrtAottA8vtAAg2AQi2Agk2A0m2AEp2
|
|
:::
|
|
qG4dSiwpp2eK4LZLr6tuqTWump4H4xSz6G1dioPCqT5eWq5EtdUdJSSoYLAMjqasWYLZYmTOrz+o
|
|
7aJOt+aM9rWrxut4DAArILM9t0kShRgCFJaUk+uvAgshVRaPlXebGyv67APwKb9qw/r0di/a6Cxn
|
|
lELvZYABAsD==<span class="highlight"></o:travelAgencyLogo></span>
|
|
<p:itinerary
|
|
xmlns:p="http://travelcompany.example.org/reservation/travel">
|
|
<p:departure>
|
|
:::
|
|
</p:departure>
|
|
<p:return>
|
|
:::
|
|
</p:return>
|
|
</p:itinerary>
|
|
<q:lodging
|
|
xmlns:q="http://travelcompany.example.org/reservation/hotels">
|
|
<hotel>
|
|
:::
|
|
</hotel>
|
|
<span class="highlight"><r:areaMap xmlns:r="http://travelcompany.example.org/maps"></span>HlkR4kTYMCgoAQMAAAA
|
|
AA8///ru6q/8zPzMzM/7v/CLsw6pne+4jPCIgACHcwFWYhBFUQBEQABDM
|
|
AEBAsAAAAAAjAIKAAUw/gRRCFlmnopqrFHJvvNyyLw2Ji56789+/ADKcHia3OiMpSEoEobgKHDnS
|
|
:::
|
|
w83hCNkr0gECT1bgEaJigpDmwFEvYOkDCgYQLMus1QDgFUYOoGGN+gtPdYYgOMDZLhwyA+BHyDMR
|
|
qweAJoAgAcYHvzTQktoAsODhl4LYBIDMevgtHPUDiAmg5gSQTUB8ETxO1HKAJRj4OI70AMeKgriF
|
|
LOECAAwO=<span class="highlight"></r:areaMap></span>
|
|
</q:lodging>
|
|
</env:Body>
|
|
</env:Envelope></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
Sample SOAP message representing a travel itinerary showing non-XML data
|
|
carried using base64 encoding</div>
|
|
</div>
|
|
|
|
<p><a href="#Example15">Example 18</a> highlights two elements contained
|
|
within the SOAP <code>env:Body></code>, namely
|
|
<code>o:travelAgencyLogo</code> and <code>r:areaMap</code>, containing the
|
|
base64 encoding of binary data corresponding to a corporate logo and an area
|
|
map. While small amounts of binary data can be placed in a SOAP message using
|
|
the base64 encoding without incurring the performance overheads noted
|
|
earlier, binary data anticipated in typical use cases is typically quite
|
|
large, often many orders of magnitude larger than the XML content. To avoid
|
|
the performance penalty in such circumstances, <a href="#L9527">[MTOM]</a>
|
|
offers an optimization that avoids the need to base64-encode large binary
|
|
content. (Note that SOAP nodes that do not implement [<a href="#L9527">MTOM</a>] have no choice but to carry binary data re-encoded in
|
|
its base64 character representation, as in <a href="#Example15">Example
|
|
18</a>.)</p>
|
|
|
|
<p>The <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#feature">Abstract
|
|
SOAP Transmission Optimization feature</a> provides the optimization by
|
|
conceptually describing the binary data that needs to be conveyed as the
|
|
content of an element information item in the SOAP message infoset in terms
|
|
of its base64 encoding. While this character based representation is
|
|
conceptually present at the sender and receiver, [MTOM] works on the
|
|
optimistic assumption that the sending and receiving applications will not
|
|
actually need the character-based representation of the binary value, and
|
|
therefore there will be no real processing overhead in conversion between the
|
|
binary value and its base64 encoding. Similarly, the implementation of this
|
|
feature using the [XOP] format (more details are provided in <a href="#L3787">section 5.3.2</a>) employs a MIME Multipart/Related [<a href="#L3362">RFC 2387</a>] package to convey the binary data as an
|
|
"attachment" referenced from within a modified, serialized SOAP message;
|
|
therefore, there is also no overhead of increased message size.</p>
|
|
|
|
<p>As noted earlier, it is assumed that the sending implementation somehow
|
|
knows or determines the type information of the element information items
|
|
that are candidates for potential optimization; otherwise the optimization
|
|
feature does not work. The scope of <a href="#L9527">[MTOM]</a> is solely to
|
|
optimize the transmission of the SOAP message infoset for those element
|
|
information items that have base64 encoded binary data in canonical form as
|
|
their content.</p>
|
|
|
|
<p>As with all features, <a href="#L9527">[MTOM]</a> needs a SOAP protocol
|
|
binding to transfer the optimized serialization. Recall from <a href="#transport">Section 4</a> that a SOAP protocol binding must transfer
|
|
the SOAP message infoset in such a way that it can be reconstructed at the
|
|
receiver unchanged. An MTOM-aware binding is one where a sender can serialize
|
|
a SOAP message infoset by transmitting the actual value - that is, the actual
|
|
bits - of certain element information items known to be in the canonical
|
|
lexical representation of type <code>xs:base64Binary</code> rather than their
|
|
lexical character representation. A receiver supporting this binding can,
|
|
from the received value, reconstruct, at least conceptually, the lexical
|
|
character representation if that is required by the application.</p>
|
|
|
|
<p>[MTOM] provides an enhancement to the existing SOAP HTTP binding to
|
|
provide an implementation of the <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#feature">Abstract
|
|
SOAP Transmission Optimization feature</a>. It uses the <a href="#L3777">[XOP]</a>-based inclusion mechanism described in section 5.3.2,
|
|
and places the resulting MIME Multipart/Related package in the body of a HTTP
|
|
message.</p>
|
|
|
|
<p>As noted earlier, applications, in many implementations, will deal
|
|
directly with the binary values and there is no implication that a base64
|
|
encoded character representation of the received value needs to be created,
|
|
if there is no need to do so. However, there are instances when there may be
|
|
a need to obtain the character representation, for example at a SOAP
|
|
intermediary which has to forward the message on a non-MTOM-aware binding.</p>
|
|
|
|
<p><a name="important" id="important">One important subtlety</a> in ensuring
|
|
that the original message infoset can be reconstructed faithfully is to
|
|
mandate, as does <a href="#L9527">[MTOM]</a>, that the original base64
|
|
encoded characters be in their canonical form. <a href="#R8">[XML Schema
|
|
Part2]</a> allows for multiple lexical representations of the
|
|
<code>xs:base64Binary</code> data type, mainly in the handling of white
|
|
space, and therefore defines a canonical form which permits a 1-to-1
|
|
correspondence between a binary value and its lexical representation. By
|
|
restricting itself to optimization candidates which are in the canonical form
|
|
of <code>xs:base64Binary</code>, it can be ensured that the transferred
|
|
message infoset is reproduced unchanged.</p>
|
|
|
|
<p>Therefore, in the following sections, whenever we, for the sake of
|
|
brevity, refer to base64-encoded data, the reader should keep in mind that we
|
|
mean XML element content whose type is in the canonical lexical
|
|
representation of <code>xs:base64Binary</code><span class="insert">.</span></p>
|
|
|
|
</div>
|
|
<div class="div3">
|
|
|
|
<h4><a name="L3787"></a>5.3.2 The Optimized Transmission Serialization Format</h4>
|
|
|
|
<p>The next step in implementing the <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#feature">Abstract
|
|
SOAP Transmission Optimization feature</a> is to define the format in which
|
|
the SOAP message infoset (with potential optimization candidates identified,
|
|
as described in the previous section) is serialized in an optimal way for
|
|
transmission. The serialization technique is described in <a href="#L9527">[MTOM]</a> by making use of an "inclusion" technique specified
|
|
in the XML-binary Optimized Packaging <a href="#L3777">[XOP]</a>
|
|
specification together with a MIME Multipart/Related packaging ([RFC
|
|
2387]).</p>
|
|
|
|
<p><a href="#L3777">[XOP]</a> defines an <code><a href="http://www.w3.org/TR/2005/REC-xop10-20050125/#xop_include">xop:Include</a></code>
|
|
element that ties, at a SOAP binding level, the binary content for an element
|
|
to its infoset representation as base64-encoded character information items
|
|
in the [children] property of that element information item. A SOAP binding
|
|
that is capable of optimized serialization of an infoset containing such
|
|
binary data represented by their character information items uses this
|
|
<code><a href="http://www.w3.org/TR/2005/REC-xop10-20050125/#xop_include">xop:Include</a></code>
|
|
element in the SOAP envelope as a placeholder to link (using an
|
|
<code>href</code> attribute) to the optimized (i.e., binary) data carried
|
|
along with the SOAP envelope in an overall package.</p>
|
|
|
|
<p>The overall package chosen is the extensible MIME Multipart/Related <a href="#L3362">[RFC 2387]</a> format. The root body part of this MIME package
|
|
contains the XML 1.0 serialization of the SOAP <code>env:Envelope</code>,
|
|
modified by the presence of one (or more) <code>xop:Include</code>
|
|
element(s), while the other (related) body part(s) of the MIME package
|
|
contain the compact (i.e, binary) data referenced by the
|
|
<code>xop:Include</code> element(s).</p>
|
|
|
|
<p>The serialization of the SOAP message from <a href="#Example15">Example
|
|
18</a>, converted to this optimized format using [XOP], is shown in <a href="#Example16">Example 19a</a>.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a name="Example16">Example 19a</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>MIME-Version: 1.0
|
|
Content-Type: Multipart/Related; boundary=example-boundary;
|
|
type=application/xop+xml;
|
|
start="<itinerary123.xml@travelcompany.example.org>";
|
|
startinfo="application/soap+xml;action=\"http://travelcompany.example.org/Process\""
|
|
Content-Description: This is an example of an optimized SOAP message
|
|
|
|
--example-boundary
|
|
<span class="highlight">Content-Type: application/xop+xml;</span> charset=UTF-8
|
|
<span class="highlight">type="application/soap+xml;action=\"http://travelcompany.example.org/Process\""</span>
|
|
Content-Transfer-Encoding: 8bit
|
|
Content-ID: <itinerary123.xml@travelcompany.example.org>
|
|
|
|
<?xml version='1.0'?>
|
|
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
|
|
<span class="highlight">xmlns:xmime='http://www.w3.org/2004/06/xmlmime'</span>>
|
|
<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: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:passenger>
|
|
</env:Header>
|
|
<env:Body>
|
|
<o:travelAgencyLogo xmlns:o="http://travelcompany.example.org/images"
|
|
<span class="highlight">xmime:contentType='image/jpg'><xop:Include xmlns:xop='http://www.w3.org/2003/12/xop/include'
|
|
href="cid:logo.gif@travelcompany.example.org"/></span></o:travelAgencyLogo>
|
|
<p:itinerary
|
|
xmlns:p="http://travelcompany.example.org/reservation/travel">
|
|
<p:departure>
|
|
:::
|
|
</p:departure>
|
|
<p:return>
|
|
:::
|
|
</p:return>
|
|
</p:itinerary>
|
|
<q:lodging
|
|
xmlns:q="http://travelcompany.example.org/reservation/hotels">
|
|
<hotel>
|
|
:::
|
|
</hotel>
|
|
<r:areaMap xmlns:r="http://travelcompany.example.org/maps"
|
|
<span class="highlight">xmime:contentType="image/jpg"><xop:Include xmlns:xop='http://www.w3.org/2003/12/xop/include'
|
|
href="cid:map123.jpg@travelcompany.example.org"/></span></r:areaMap>
|
|
</q:lodging>
|
|
</env:Body>
|
|
</env:Envelope>
|
|
|
|
--example-boundary
|
|
Content-Type: image/jpg
|
|
Content-Transfer-Encoding: binary
|
|
Content-ID: <span class="highlight"><logo.gif@travelcompany.example.org></span>
|
|
|
|
::: the binary data :::
|
|
|
|
--example-boundary
|
|
Content-Type: image/jpg
|
|
Content-Transfer-Encoding: binary
|
|
Content-ID: <span class="highlight"><map123.jpg@travelcompany.example.org></span>
|
|
|
|
::: the binary data :::
|
|
|
|
--example-boundary--</pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
Sample SOAP message for a travel itinerary showing non-XML (binary) data
|
|
carried using the <a href="#L3777">[XOP]</a> format</div>
|
|
</div>
|
|
|
|
<p>In <a href="#Example16">Example 19a</a>, the conventional MIME
|
|
Multipart/Related package conveys a compound "object" broken up into multiple
|
|
inter-related body parts. The "start" parameter of the overall Content-Type
|
|
conveys, via a Content-ID, the body part which contains the compound object's
|
|
"root", while the media type parameter value of "<a href="http://www.iana.org/assignments/media-types/application/xop+xml">application/xop+xml</a>"
|
|
identifies the contents as an XML document serialized using the [XOP] format.
|
|
The "startinfo" parameter of the package shows that this root part is the XML
|
|
1.0 serialization of the SOAP <code>env:Envelope</code> modified by the
|
|
inclusion of <code>xop:Include</code> elements where appropriate.</p>
|
|
|
|
<p>Compared with <a href="#Example15">Example 18</a>, note, in <a href="#Example16">Example 19a</a>, the presence of the two <code><a href="http://www.w3.org/TR/2005/REC-xop10-20050125/#xop_include">xop:Include</a></code>
|
|
elements which replace the character representations of the binary data
|
|
corresponding to the company logo and the lodging area map. Each of these
|
|
elements provides via the <code>href</code> attribute the link by which the
|
|
binding knows which MIME body part contains the binary data that corresponds
|
|
to the (canonical form of the) equivalent base64-encoded character
|
|
representation.</p>
|
|
|
|
<p>Note also the presence of the additional attribute <code><a href="http://www.w3.org/TR/2005/NOTE-xml-media-types-20050504/#contentType">xmime:contentType</a></code>
|
|
(see [<a href="#L3991">MediaType</a>] <a href="http://www.w3.org/TR/2005/NOTE-xml-media-types-20050504/#contentType">Section
|
|
2.1 contentType Attribute</a>) in the <code>xop:Include</code> elements to
|
|
indicate the media type of the contents of the
|
|
<code>o:TravelAgencyLogo</code> and <code>r:AreaMap</code> elements.</p>
|
|
|
|
<p>When such an optimized MIME Multipart/Related package based on the [XOP]
|
|
format is sent in a HTTP message, [<a name="MTOM" id="MTOM" href="#L9527">MTOM</a>] <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#httpof-implementation">Section
|
|
4.3</a> requires that the resultant MIME headers are sent as HTTP headers,
|
|
while the remainder of the package is placed in the HTTP body. <a href="#Example161">Example 19b</a> shows the SOAP message from <a href="#Example16">Example 19a</a> returned in a HTTP response (with the
|
|
relevant HTTP headers highlighted).</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a name="Example161" id="Example161">Example 19b</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>HTTP/1.1 200 OK
|
|
<span class="highlight">Content-Type: Multipart/Related; boundary=example-boundary;
|
|
type=application/xop+xml;
|
|
start="<itinerary123.xml@travelcompany.example.org>";
|
|
startinfo="application/soap+xml;action=\"http://travelcompany.example.org/Process\""
|
|
Content-Description: This is an example of an optimized SOAP message</span>
|
|
Content-Length: nnnn
|
|
|
|
--example-boundary
|
|
Content-Type: application/xop+xml; charset=UTF-8
|
|
type="application/soap+xml;action=\"http://travelcompany.example.org/Process\""
|
|
Content-Transfer-Encoding: 8bit
|
|
Content-ID: <itinerary123.xml@travelcompany.example.org>
|
|
|
|
<?xml version='1.0'?>
|
|
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
|
|
xmlns:xmime='http://www.w3.org/2004/06/xmlmime'>
|
|
<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: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:passenger>
|
|
</env:Header>
|
|
<env:Body>
|
|
<o:travelAgencyLogo xmlns:o="http://travelcompany.example.org/images"
|
|
xmime:contentType='image/jpg'><xop:Include xmlns:xop='http://www.w3.org/2003/12/xop/include'
|
|
href="cid:logo.gif@travelcompany.example.org"/></o:travelAgencyLogo>
|
|
<p:itinerary
|
|
xmlns:p="http://travelcompany.example.org/reservation/travel">
|
|
<p:departure>
|
|
:::
|
|
</p:departure>
|
|
<p:return>
|
|
:::
|
|
</p:return>
|
|
</p:itinerary>
|
|
<q:lodging
|
|
xmlns:q="http://travelcompany.example.org/reservation/hotels">
|
|
<hotel>
|
|
:::
|
|
</hotel>
|
|
<r:areaMap xmlns:r="http://travelcompany.example.org/maps"
|
|
xmime:contentType="image/jpg"><xop:Include xmlns:xop='http://www.w3.org/2003/12/xop/include'
|
|
href="cid:map123.jpg@travelcompany.example.org"/></r:areaMap>
|
|
</q:lodging>
|
|
</env:Body>
|
|
</env:Envelope>
|
|
|
|
--example-boundary
|
|
Content-Type: image/jpg
|
|
Content-Transfer-Encoding: binary
|
|
Content-ID: <logo.gif@travelcompany.example.org>
|
|
|
|
::: the binary data :::
|
|
|
|
--example-boundary
|
|
Content-Type: image/jpg
|
|
Content-Transfer-Encoding: binary
|
|
Content-ID: <map123.jpg@travelcompany.example.org>
|
|
|
|
::: the binary data :::
|
|
|
|
--example-boundary--</pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
Sample SOAP message for a travel itinerary carried in a HTTP response,
|
|
showing the MIME Multipart/Related headers carried as HTTP headers</div>
|
|
</div>
|
|
|
|
<p>In <a name="Example20" id="Example20" href="#Example161">Example 19b</a>,
|
|
the MIME Multipart/Related headers arising from the [XOP] format (see <a href="#Example16">Example 19a</a>) are carried as HTTP headers in the HTTP
|
|
200 OK response.</p>
|
|
|
|
</div>
|
|
<div class="div3">
|
|
|
|
<h4><a name="L3791"></a>5.3.3 Using the Resource Representation SOAP Header Block</h4>
|
|
|
|
<p>Another optimization that has been identified as useful for processing a
|
|
SOAP message which includes URI-based references to Web resources is one
|
|
where the sender includes <em>a</em> representation of each such resource in
|
|
the SOAP message to either the ultimate receiver or an intermediary. This
|
|
helps in situations where the processing of the SOAP message depends on
|
|
dereferencing the URIs, but which may not be possible because the receiver is
|
|
not able or wishes to avoid the overhead of the network traffic needed to do
|
|
so. The gain is even greater if the same resource (the image of a logo, say)
|
|
is referenced multiple times within the message.</p>
|
|
|
|
<p>The Resource Representation SOAP Header Block [<a href="#L4299">ResRep</a>] specification describes a SOAP header block,
|
|
containing a <code><a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-representation">rep:Representation</a></code>
|
|
element, which defines how URI-based representations of resources referenced
|
|
within a SOAP message infoset may be carried and processed by an identified
|
|
receiver. Its use is illustrated by examples that follow.</p>
|
|
|
|
<p>Recall, from <a href="#Example15">Example 18</a>, that a base64-encoded
|
|
form of the travel agency logo was sent in the SOAP message. However, this
|
|
may well have been included by providing a HTTP URL link to the location from
|
|
which the (ultimate) receiver could retrieve the image as a part of
|
|
processing the message. This is shown, with all inessentials deleted, in <a href="#Example17">Example 20</a>.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a name="Example17">Example 20</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>HTTP/1.1 200 OK
|
|
Content-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>
|
|
:::
|
|
</env:Header>
|
|
<env:Body>
|
|
<span class="highlight"><o:travelAgencyLogo xmlns:o="http://travelcompany.example.org/images"></span>
|
|
<span class="highlight"><o:image o:source= "http://travelcompany.example.org/images/logo.jpg"/></span>
|
|
<span class="highlight"></o:travelAgencyLogo></span>
|
|
|
|
:::
|
|
:::
|
|
|
|
</env:Body>
|
|
</env:Envelope></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
Sample SOAP message based on <a href="#Example15">Example 18</a> showing the
|
|
travel agency logo element content as a link to a Web resource</div>
|
|
</div>
|
|
|
|
<p>In <a href="#Example17">Example 20</a>, the expectation is that the
|
|
contents of the <code>o:image</code> element would be obtained by
|
|
dereferencing the URL identified by the <code>o:source</code> attribute.
|
|
However, as identified earlier, if a situation were anticipated where the
|
|
processing overhead of dereferencing the URI were considered unacceptable, a
|
|
representation of the logo image can be sent using the <code><a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-representation">rep:Representation</a></code>
|
|
element, as shown in <a href="#Example18">Example 21</a> (with the header
|
|
highlighted).</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a name="Example18">Example 21</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>HTTP/1.1 200 OK
|
|
Content-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"
|
|
<span class="highlight">xmlns:rep='http://www.w3.org/2004/02/representation'
|
|
xmlns:xmime='http://www.w3.org/2004/06/xmlmime'</span>>
|
|
<env:Header>
|
|
<span class="highlight"><rep:Representation resource='http://travelcompany.example.org/images/logo.jpg'>
|
|
<rep:Data xmime:contentType='image/jpg'></span>HlkR4cTYvAQLAcOAAAAAAQCAAgEAA0GA
|
|
AEJAAYLAAoNAA8PAAAAJAQCJAgEJA0GJAEJJAYLJAoNJA8PJAAASAQCSAgESA0GSAEJSAYLSAoNSA
|
|
8PSAAQbAQSbAgUbA0WbAEZbAYbbAodbA8fbAAQkAQSkAgUkA0WkAEZkAYbkAodkA8fkAAgtAQitAgk
|
|
:::
|
|
qG4dSiwpp2eK4LZLr6tuqTWump4H4xSz6G1dioPCqT5eWq5EtdUdJSSoYLAMjqasWYLZYmTOrz+o
|
|
7aJOt+aM9rWrxut4DAArILM9t0kShRgCFJaUk+uvAgshVRaPlXebGyv67APwKb9qw/r0di/a6Cxn
|
|
lELvZYABAsD==<span class="highlight"></rep:Data>
|
|
</rep:Representation></span>
|
|
:::
|
|
</env:Header>
|
|
<env:Body>
|
|
<span class="highlight"><o:travelAgencyLogo xmlns:o="http://travelcompany.example.org/images"></span>
|
|
<span class="highlight"><o:image o:source= "http://travelcompany.example.org/images/logo.jpg"/></span>
|
|
<span class="highlight"></o:travelAgencyLogo></span>
|
|
|
|
:::
|
|
:::
|
|
|
|
</env:Body>
|
|
</env:Envelope></pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
Sample SOAP message based on <a href="#Example17">Example 20</a> showing a
|
|
representation of a Web resource (an image of the travel agency logo) carried
|
|
in the Representation header.</div>
|
|
</div>
|
|
|
|
<p><a>In </a><a href="#Example18">Example 21</a>, the <code><a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-representation">rep:Representation</a></code>
|
|
element contains a mandatory <code><a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-resource">resource</a></code>
|
|
attribute whose value is the URI identifying the Web resource, while the
|
|
<code><a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-data">rep:Data</a></code>
|
|
element is a base64-encoded representation of the resource. The optional
|
|
<code><a href="http://www.w3.org/TR/2005/NOTE-xml-media-types-20050504/#contentType">xmime:contentType</a></code>
|
|
attribute in <code><a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-data">rep:Data</a></code>
|
|
is used to identify the media type of the resource representation being
|
|
conveyed. The <code><a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-representation">rep:Representation</a></code>
|
|
element can make use of other attributes (see [<a href="#L4299">ResRep</a>]
|
|
<a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-construct">Section
|
|
2.2 Representation header block Constructs</a> for details) including the
|
|
SOAP-defined ones, <code>env:mustUnderstand</code> and <code>env:Role</code>,
|
|
described in section 3. The use of such additional headers allows the
|
|
targeted receiver to know that the resource representation is available to
|
|
it.</p>
|
|
|
|
<p>If the binary content representing the resource were available to the
|
|
sender, and sending the base64-encoded form of that (presumably large) binary
|
|
content was deemed inefficient, the use of the
|
|
<code>rep:Representation</code> element can be combined with [<a href="#L9527" class="insert">MTOM</a>] and the [<a href="#L3777">XOP</a>]
|
|
format to gain the efficiencies of that feature. This is shown in <a href="#Example19">Example 22</a>, with the <code>xop:Include</code> element
|
|
highlighted.</p>
|
|
|
|
<div class="exampleOuter">
|
|
|
|
<div class="exampleHead">
|
|
<a name="Example19">Example 22</a></div>
|
|
|
|
<div class="exampleInner">
|
|
<pre>HTTP/1.1 200 OK
|
|
Content-Type: mime/multipart-related; charset="utf-8"
|
|
Content-Length: nnnn
|
|
|
|
MIME-Version: 1.0
|
|
Content-Type: Multipart/Related; boundary=example-boundary;
|
|
type=application/xop+xml;
|
|
start="<itinerary123.xml@travelcompany.example.org>";
|
|
startinfo="application/soap+xml;action=\"http://travelcompany.example.org/Process\""
|
|
Content-Description: This is an example of an optimized SOAP message
|
|
|
|
--example-boundary
|
|
Content-Type: application/xop+xml; charset=UTF-8;
|
|
type="application/soap+xml;action=\"http://travelcompany.example.org/Process\""
|
|
Content-Transfer-Encoding: 8bit
|
|
Content-ID: <itinerary123.xml@travelcompany.example.org>
|
|
|
|
<?xml version='1.0' ?>
|
|
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
|
|
xmlns:rep='http://www.w3.org/2004/02/representation'
|
|
xmlns:xmime='http://www.w3.org/2004/06/xmlmime'>
|
|
<env:Header>
|
|
<rep:Representation resource='http://travelcompany.example.org/images/logo.jpg'>
|
|
<span class="highlight"><xop:Include xmlns:xop='http://www.w3.org/2003/12/xop/include'
|
|
href="cid:logo.gif@travelcompany.example.org"/></span></rep:Representation>
|
|
:::
|
|
</env:Header>
|
|
<env:Body>
|
|
<o:travelAgencyLogo xmlns:o="http://travelcompany.example.org/images">
|
|
<o:image o:source= "http://travelcompany.example.org/images/logo.jpg"/>
|
|
</o:travelAgencyLogo>
|
|
:::
|
|
:::
|
|
</env:Body>
|
|
</env:Envelope>
|
|
|
|
<span class="highlight">--example-boundary
|
|
Content-Type: image/jpg
|
|
Content-Transfer-Encoding: binary
|
|
Content-ID: <logo.gif@travelcompany.example.org>
|
|
|
|
::: the binary data for the travel agency logo :::</span>
|
|
|
|
--example-boundary
|
|
Content-Type: image/jpg
|
|
Content-Transfer-Encoding: binary
|
|
Content-ID: <map123.jpg@travelcompany.example.org>
|
|
|
|
::: the binary data :::
|
|
|
|
--example-boundary--</pre>
|
|
</div>
|
|
|
|
<div class="exampleWrapper">
|
|
Sample SOAP message based on <a href="#Example18">Example 21</a> showing the
|
|
representation of a Web resource (an image of the travel agency logo) carried
|
|
in the Representation header using the MTOM/XOP optimization.</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
|
|
<h2><a name="L4697"></a>6. Changes Between SOAP 1.1 and SOAP 1.2</h2>
|
|
|
|
<p>SOAP Version 1.2 has a number of changes in syntax and provides additional
|
|
(or clarified) semantics from those described in [<a href="#R11">SOAP
|
|
1.1]</a>. 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.</p>
|
|
|
|
<p><em>Document structure</em></p>
|
|
<ul>
|
|
<li>The SOAP 1.2 specifications have been provided in two parts. <a href="#L1092">[SOAP Part1]</a> provides an abstract Infoset-based
|
|
definition of the SOAP message structure, a processing model and an
|
|
underlying protocol binding framework, while <a href="#L1098">[SOAP
|
|
Part2]</a> provides serialization rules for conveying that infoset as
|
|
well as a particular HTTP binding.</li>
|
|
<li>SOAP 1.2 will not spell out the acronym.</li>
|
|
<li>SOAP 1.2 has been rewritten in terms of XML infosets, and not as
|
|
serializations of the form <?xml....?> required by SOAP 1.1.</li>
|
|
</ul>
|
|
|
|
<p><em>Additional or changed syntax</em></p>
|
|
<ul>
|
|
<li>SOAP 1.2 does not permit any element after the body. The SOAP 1.1 <a href="http://schemas.xmlsoap.org/soap/envelope/">schema definition</a>
|
|
allowed for such a possibility, but the textual description is silent
|
|
about it.</li>
|
|
<li>SOAP 1.2 does not allow the <code>env:encodingStyle</code> attribute to
|
|
appear on the SOAP <code>env:Envelope</code>, whereas SOAP 1.1 allows it
|
|
to appear on any element. SOAP 1.2 specifies specific elements where this
|
|
attribute may be used.</li>
|
|
<li>SOAP 1.2 defines the new <code>env:NotUnderstood</code> header element
|
|
for conveying information on a mandatory header block which could not be
|
|
processed, as indicated by the presence of an
|
|
<code>env:MustUnderstand</code> fault code. SOAP 1.1 provided the fault
|
|
code, but no details on its use.</li>
|
|
<li>In the SOAP 1.2 infoset-based description, the
|
|
<code>env:mustUnderstand</code> 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.</li>
|
|
<li>SOAP 1.2 provides a new fault code
|
|
<code>DataEncodingUnknown</code>.</li>
|
|
<li>The various namespaces defined by the two protocols are of course
|
|
different.</li>
|
|
<li>SOAP 1.2 replaces the attribute <code>env:actor</code> with
|
|
<code>env:role</code> but with essentially the same semantics.</li>
|
|
<li>SOAP 1.2 defines a new attribute, <code>env:relay</code>, for header
|
|
blocks to indicate if unprocessed header blocks should be forwarded.</li>
|
|
<li>SOAP 1.2 defines two new roles, "none" and "ultimateReceiver", together
|
|
with a more detailed processing model on how these behave.</li>
|
|
<li>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.</li>
|
|
<li>SOAP 1.2 replaces "client" and "server" fault codes with "Sender" and
|
|
"Receiver".</li>
|
|
<li>SOAP 1.2 uses the element names <code>env:Code</code> and
|
|
<code>env:Reason</code>, respectively, for what used to be called
|
|
<code>faultcode</code> and <code>faultstring</code> in SOAP 1.1. SOAP 1.2
|
|
also allows multiple <code>env:Text</code> child elements of
|
|
<code>env:Reason</code> qualified by <code>xml:lang</code> to allow
|
|
multiple language versions of the fault reason.</li>
|
|
<li>SOAP 1.2 provides a hierarchical structure for the mandatory SOAP
|
|
<code>env:Code</code> sub-element in the <code>env:Fault</code> element,
|
|
and introduces two new optional subelements, <code>env:Node</code> and
|
|
<code>env:Role</code>.</li>
|
|
<li>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
|
|
<code>env:Details</code> element in <code>env:Fault</code>. In SOAP 1.2,
|
|
the presence of the <code>env:Details</code> element has no significance
|
|
as to which part of the fault SOAP message was processed.</li>
|
|
<li>SOAP 1.2 uses XML Base <a href="#L2778">[XML Base]</a> for determining
|
|
a base URI for relative URI references whereas SOAP 1.1 is silent about
|
|
the matter.</li>
|
|
</ul>
|
|
|
|
<p><em>SOAP HTTP binding</em></p>
|
|
<ul>
|
|
<li>In the SOAP 1.2 HTTP binding, the <code>SOAPAction</code> 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 <code>SOAPAction</code> HTTP header are now
|
|
expressed as a value of an (optional) "<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#ietf-draft">action</a>"
|
|
parameter of the "application/soap+xml" media type that is signaled in
|
|
the HTTP binding.</li>
|
|
<li>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 [<a href="#r13">RFC 3902</a>].</li>
|
|
<li>SOAP 1.2 provides a finer grained description of use of the various
|
|
2xx, 3xx, 4xx HTTP status codes.</li>
|
|
<li>Support of the HTTP extensions framework has been removed from SOAP
|
|
1.2.</li>
|
|
<li>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.</li>
|
|
</ul>
|
|
|
|
<p><em>RPC</em></p>
|
|
<ul>
|
|
<li>SOAP 1.2 provides a <code>rpc:result</code> element accessor for
|
|
RPCs.</li>
|
|
<li>SOAP 1.2 provides several additional fault codes in the <a href="http://www.w3.org/2003/05/soap-rpc">RPC namespace</a>.</li>
|
|
<li>SOAP 1.2 offers guidance on a Web-friendly
|
|
approach to defining RPCs where the procedure's purpose is purely "safe"
|
|
informational retrieval.</li>
|
|
</ul>
|
|
|
|
<p><em>SOAP encodings</em></p>
|
|
<ul>
|
|
<li>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.</li>
|
|
<li>The syntax for the serialization of an array has been changed in SOAP
|
|
1.2 from that in SOAP 1.1.</li>
|
|
<li>The support provided in SOAP 1.1 for partially transmitted and sparse
|
|
arrays is not available in SOAP 1.2.</li>
|
|
<li>SOAP 1.2 allows the inline (embedded) serialization of multiref
|
|
values.</li>
|
|
<li>The <code>href</code> attribute in SOAP 1.1 (of type
|
|
<code>xs:anyURI</code>) is called <code>enc:ref</code> in SOAP 1.2 and is
|
|
of type <code>IDREF</code>.</li>
|
|
<li>In SOAP 1.2, omitted accessors of compound types are made equal to
|
|
NILs.</li>
|
|
<li>SOAP 1.2 provides several fault sub-codes for indicating encoding
|
|
errors.</li>
|
|
<li>Types on nodes are made optional in SOAP 1.2.</li>
|
|
<li>SOAP 1.2 has removed generic compound values from the SOAP Data
|
|
Model.</li>
|
|
<li>SOAP 1.2 has added an optional attribute <code>enc:nodeType</code> to
|
|
elements encoded using SOAP encoding that identifies its structure (i.e.,
|
|
a simple value, a struct or an array).</li>
|
|
</ul>
|
|
|
|
<p><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#version">SOAP Part
|
|
1 Appendix A</a> provides version management rules for a SOAP node that can
|
|
support the version transition from [<a href="#R11">SOAP 1.1</a>] to SOAP
|
|
Version 1.2. In particular, in defines an <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#vmfault">env:Upgrade</a></code>
|
|
header block which can be used by a SOAP 1.2 node on receipt of a [<a href="#R11">SOAP 1.1</a>] message to send a SOAP fault message to the
|
|
originator to signal which version of SOAP it supports.</p>
|
|
|
|
</div>
|
|
|
|
<div class="div1">
|
|
|
|
<h2><a name="L810"></a>7. References</h2>
|
|
|
|
<dl>
|
|
<dt class="label"><a name="L1092"></a>[SOAP Part 1] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427"><cite>SOAP Version 1.2 Part 1: Messaging Framework (Second Edition)</cite></a>,
|
|
Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau,
|
|
Henrik Frystyk Nielsen, Anish Karmarkar, Yves Lafon, Editors.
|
|
World Wide Web Consortium, 27 April 2007.
|
|
This version is http://www.w3.org/TR/2007/REC-soap12-part1-20070427.
|
|
The <a href="http://www.w3.org/TR/soap12-part1/">latest version</a> is
|
|
available at http://www.w3.org/TR/soap12-part1/.</dd>
|
|
|
|
<dt class="label"><a name="L1098"></a>[SOAP Part 2] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427"><cite>SOAP Version 1.2 Part 2: Adjuncts (Second Edition)</cite></a>,
|
|
Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau,
|
|
Henrik Frystyk Nielsen, Anish Karmarkar, Yves Lafon, Editors.
|
|
World Wide Web Consortium, 27 April 2007.
|
|
This version is http://www.w3.org/TR/2007/REC-soap12-part2-20070427.
|
|
The <a href="http://www.w3.org/TR/soap12-part2/">latest version</a> is
|
|
available at http://www.w3.org/TR/soap12-part2/.</dd>
|
|
|
|
<dt class="label"><a name="L9527"></a>[MTOM] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/"><cite>SOAP Message
|
|
Transmission Optimization Mechanism</cite></a>, Hervé Ruellan,
|
|
Noah Mendelsohn, Martin Gudgin, and Mark Nottingham, Editors.
|
|
World Wide Web Consortium,
|
|
25 January 2005.
|
|
This version is http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/.
|
|
The <a href="http://www.w3.org/TR/soap12-mtom/">latest version</a> is
|
|
available at http://www.w3.org/TR/soap12-mtom/.</dd>
|
|
|
|
<dt class="label"><a name="RFC3986"></a>[RFC 3986] </dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc3986.txt"><cite>Uniform Resource
|
|
Identifiers (URI): Generic Syntax</cite></a>, T. Berners-Lee,
|
|
R. Fielding and L. Masinter, Editors.
|
|
IETF, January 2005.
|
|
<em>Obsoletes: <span id="L1105">RFC 2396</span>,
|
|
<span id="RFC2732">RFC 2732</span></em>.
|
|
This RFC is available at http://www.ietf.org/rfc/rfc3986.txt.</dd>
|
|
|
|
<dt class="label"><a name="RFC3987"></a>[RFC 3987] </dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc3987.txt"><cite>
|
|
Internationalized Resource Identifiers (IRIs)
|
|
</cite></a>,
|
|
M. Duerst, Editors.
|
|
IETF, January 2005.
|
|
This RFC is available at http://www.ietf.org/rfc/rfc3987.txt.</dd>
|
|
|
|
<dt class="label"><a name="L3133"></a>[RFC 2616] </dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc2616.txt"><cite>Hypertext
|
|
Transfer Protocol -- HTTP/1.1</cite></a>, R. Fielding,
|
|
J. Gettys, J. C. Mogul, H. Frystyk Nielsen, P. Leach,
|
|
L. Masinter and T. Berners-Lee,
|
|
Editors.
|
|
IETF, June 1999.
|
|
This RFC is available at http://www.ietf.org/rfc/rfc2616.txt.</dd>
|
|
|
|
<dt class="label"><a name="L3532"></a>[XML 1.0] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2006/REC-xml-20060816"><cite>Extensible
|
|
Markup Language (XML) 1.0 (Fourth Edition)</cite></a>, Jean Paoli,
|
|
Eve Maler, Tim Bray, <em>et. al.</em>, Editors.
|
|
World Wide Web Consortium, 16 August 2006.
|
|
This version is http://www.w3.org/TR/2006/REC-xml-20060816.
|
|
The <a href="http://www.w3.org/TR/REC-xml">latest version</a> is
|
|
available at http://www.w3.org/TR/REC-xml.</dd>
|
|
|
|
<dt class="label"><a name="XMLNS"></a>[Namespaces in XML] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2006/REC-xml-names-20060816"><cite>
|
|
Namespaces in
|
|
XML (Second Edition)</cite></a>, Tim Bray, Dave Hollander,
|
|
Andrew Layman, and Richard Tobin, Editors.
|
|
World Wide Web Consortium, 16 August 2006.
|
|
This version is http://www.w3.org/TR/2006/REC-xml-names-20060816.
|
|
The <a href="http://www.w3.org/TR/REC-xml-names">latest version</a> is
|
|
available at http://www.w3.org/TR/REC-xml-names.</dd>
|
|
|
|
<dt class="label"><a name="R7"></a>[XML Schema Part 1] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/"><cite>
|
|
XML Schema Part 1:
|
|
Structures Second Edition</cite></a>, David Beech, Murray Maloney,
|
|
Henry S. Thompson, and Noah Mendelsohn, Editors.
|
|
World Wide Web Consortium, 28 October 2004.
|
|
This version is http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/
|
|
The <a href="http://www.w3.org/TR/xmlschema-1/">latest version</a> is
|
|
available at http://www.w3.org/TR/xmlschema-1/.</dd>
|
|
|
|
<dt class="label"><a name="R8"></a>[XML Schema Part 2] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/"><cite>
|
|
XML Schema Part 2:
|
|
Datatypes Second Edition</cite></a>,
|
|
Ashok Malhotra and Paul V. Biron, Editors.
|
|
World Wide Web Consortium, 28 October 2004.
|
|
This version is http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.
|
|
The <a href="http://www.w3.org/TR/xmlschema-2/">latest version</a> is
|
|
available at http://www.w3.org/TR/xmlschema-2/.</dd>
|
|
|
|
<dt class="label"><a name="xml11"></a>[XML 1.1] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2006/REC-xml11-20060816"><cite>
|
|
Extensible Markup Language (XML) 1.1 (Second Edition)</cite></a>,
|
|
Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler,
|
|
François Yergeau, John Cowan, Editors.
|
|
World Wide Web Consortium, 16 August 2006, edited in place 29 September 2006.
|
|
This version is http://www.w3.org/TR/2006/REC-xml11-20060816.
|
|
The <a href="http://www.w3.org/TR/xml11/">latest version</a> is
|
|
available at http://www.w3.org/TR/xml11/.</dd>
|
|
|
|
<dt class="label"><a name="R9"></a>[SMTP] </dt><dd>
|
|
SMTP is defined in a series of RFCs:
|
|
<dl>
|
|
<dt class="label"><a name="RFC2822"></a>[RFC 2822] </dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc2822.txt"><cite>
|
|
Internet Message Format</cite></a>
|
|
P. Resnick, Editor.
|
|
IETF, April 2001.
|
|
This RFC is available at http://www.ietf.org/rfc/rfc2822.txt.</dd>
|
|
|
|
<dt class="label"><a name="L3410"></a>[RFC 2045] </dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc2045.txt"><cite>
|
|
Multipurpose Internet Mail Extensions (MIME) Part One:
|
|
Format of Internet Message Bodies
|
|
</cite></a>, N. Freed, N. Borenstein, Editors.
|
|
IETF, November 1996.
|
|
This RFC is available at http://www.ietf.org/rfc/rfc2045.txt.</dd>
|
|
|
|
<dt class="label"><a name="RFC2046"></a>[RFC 2046] </dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc2046.txt"><cite>
|
|
Multipurpose Internet Mail Extensions (MIME) Part Two:
|
|
Media Types
|
|
</cite></a>, N. Freed, N. Borenstein, Editors.
|
|
IETF, November 1996.
|
|
This RFC is available at http://www.ietf.org/rfc/rfc2046.txt.</dd>
|
|
|
|
<dt class="label"><a name="RFC1894"></a>[RFC 1894] </dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc1894.txt"><cite>
|
|
An Extensible Message Format for Delivery Status Notifications
|
|
</cite></a>, K. Moore, G. Vaudreuil, Editors.
|
|
IETF, January 1996.
|
|
This RFC is available at http://www.ietf.org/rfc/rfc1894.txt.</dd>
|
|
|
|
<dt class="label"><a name="RFC2852"></a>[RFC 2852] </dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc2852.txt"><cite>
|
|
Deliver By SMTP Service Extension
|
|
</cite></a>, D. Newman, Editor.
|
|
IETF, June 2000.
|
|
This RFC is available at http://www.ietf.org/rfc/rfc2852.txt.</dd>
|
|
|
|
<dt class="label"><a name="RFC2298"></a>[RFC 2298] </dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc2298.txt"><cite>
|
|
An Extensible Message Format for Message Disposition Notifications
|
|
</cite></a>, R. Fajman, Editor.
|
|
IETF, March 1998.
|
|
This RFC is available at http://www.ietf.org/rfc/rfc2298.txt.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt class="label"><a name="L4867"></a>[RDF Primer] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2004/REC-rdf-primer-20040210/"><cite>RDF
|
|
Primer</cite></a>, Frank Manola and Eric Miller, Editors.
|
|
World Wide Web Consortium, 10 February 2004.
|
|
This version is http://www.w3.org/TR/2004/REC-rdf-primer-20040210/.
|
|
The <a href="http://www.w3.org/TR/rdf-primer/">latest version</a> is
|
|
available at http://www.w3.org/TR/rdf-primer/.</dd>
|
|
|
|
<dt class="label"><a name="R11"></a>[SOAP 1.1] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/"><cite>Simple
|
|
Object Access Protocol (SOAP) 1.1</cite></a>,
|
|
Don Box , David Ehnebuske, Gopal Kakivaya, Andrew Layman,
|
|
Noah Mendelsohn, Henrik Nielsen, Satish Thatte, Dave Winer.
|
|
DevelopMentor, Microsoft, IBM, UserLand Software, Inc.,
|
|
Lotus Development Corp.,
|
|
8 May 2000.
|
|
This Note is available at
|
|
http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.</dd>
|
|
|
|
<dt class="label"><a name="R12"></a>[XML InfoSet] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2004/REC-xml-infoset-20040204"><cite>XML
|
|
Information Set (Second Edition)</cite></a>, Richard Tobin and
|
|
John Cowan, Editors.
|
|
World Wide Web Consortium, 04 February 2004.
|
|
This version is http://www.w3.org/TR/2004/REC-xml-infoset-20040204.
|
|
The <a href="http://www.w3.org/TR/xml-infoset">latest version</a> is
|
|
available at http://www.w3.org/TR/xml-infoset.</dd>
|
|
|
|
<dt class="label"><a name="r13"></a>[RFC 3902] </dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc3902.txt"><cite>
|
|
The "application/soap+xml" media type</cite></a>, M. Baker,
|
|
M. Nottingham, Editors.
|
|
IETF, September 2004.
|
|
This RFC is available at http://www.ietf.org/rfc/rfc3902.txt.</dd>
|
|
|
|
|
|
<dt class="label"><a name="L3215"></a>[SOAP Email Binding] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2002/NOTE-soap12-email-20020703"><cite>
|
|
SOAP Version 1.2 Email Binding</cite></a>,
|
|
Highland Mary Mountain, Jacek Kopecky, Stuart Williams,
|
|
<em>et. al.</em>, Editors.
|
|
World Wide Web Consortium, 03 July 2002.
|
|
This version is http://www.w3.org/TR/2002/NOTE-soap12-email-20020703.
|
|
The <a href="http://www.w3.org/TR/soap12-email">latest version</a>
|
|
is available at http://www.w3.org/TR/soap12-email.</dd>
|
|
|
|
<dt class="label"><a name="L2778"></a>[XML Base] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2001/REC-xmlbase-20010627/"><cite>XML
|
|
Base</cite></a>,
|
|
Jonathan Marsh, Editor.
|
|
World Wide Web Consortium, 27 June 2001.
|
|
This version is http://www.w3.org/TR/2001/REC-xmlbase-20010627/.
|
|
The <a href="http://www.w3.org/TR/xmlbase/">latest version</a> is
|
|
available at http://www.w3.org/TR/xmlbase/.</dd>
|
|
|
|
<dt class="label"><a name="L15789"></a>[RFC 2119] </dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key words for
|
|
use in RFCs to Indicate Requirement Levels</cite></a>, S. Bradner,
|
|
Editor.
|
|
IETF, March 1997.
|
|
This RFC is available at http://www.ietf.org/rfc/rfc2119.txt.</dd>
|
|
|
|
<dt class="label"><a name="L3362"></a>[RFC 2387] </dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc2387.txt"><cite>The MIME
|
|
Multipart/Related Content-type</cite></a>, E. Levinson,
|
|
Editor.
|
|
IETF, August 1998.
|
|
This RFC is available at http://www.ietf.org/rfc/rfc2387.txt.</dd>
|
|
|
|
|
|
<dt class="label"><a name="L3777"></a>[XOP] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2005/REC-xop10-20050125/"><cite>XML-binary Optimized
|
|
Packaging</cite></a>, Mark Nottingham, Noah Mendelsohn, Martin Gudgin,
|
|
and Hervé Ruellan, Editors.
|
|
World Wide Web Consortium,
|
|
25 January 2005.
|
|
This version is http://www.w3.org/TR/2005/REC-xop10-20050125/.
|
|
The <a href="http://www.w3.org/TR/xop10/">latest version</a> is
|
|
available at http://www.w3.org/TR/xop10/.</dd>
|
|
|
|
<dt class="label"><a name="L4299"></a>[ResRep] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/"><cite>Resource
|
|
Representation SOAP Header Block</cite></a>, Martin Gudgin,
|
|
Yves Lafon, and Anish Karmarkar, Editors.
|
|
World Wide Web Consortium,
|
|
25 January 2005.
|
|
This version is http://www.w3.org/TR/2005/REC-soap12-rep-20050125/.
|
|
The <a href="http://www.w3.org/TR/soap12-rep/">latest version</a> is
|
|
available at http://www.w3.org/TR/soap12-rep/.</dd>
|
|
|
|
<dt class="label"><a name="L3991"></a>[MediaTypes] </dt><dd>
|
|
<a href="http://www.w3.org/TR/2005/NOTE-xml-media-types-20050504/"><cite>Assigning Media Types to
|
|
Binary Data in XML</cite></a>, Anish Karmarkar,
|
|
Ümit Yalçinalp, Editors.
|
|
World Wide Web Consortium, 04 May 2005.
|
|
This version is http://www.w3.org/TR/2005/NOTE-xml-media-types-20050504/.
|
|
The <a href="http://www.w3.org/TR/xml-media-types">latest version</a>
|
|
is available at http://www.w3.org/TR/xml-media-types.</dd>
|
|
|
|
</dl>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="back">
|
|
|
|
<div class="div1">
|
|
|
|
<h2><a name="L10313"></a>A. Acknowledgements (Non-Normative)</h2>
|
|
|
|
<p>Highland Mary Mountain provided the initial material for the section on
|
|
the SMTP binding. Paul Denning provided material for a usage scenario, which
|
|
has since been moved to the SOAP Version 1.2 Usage Scenarios Working Draft.
|
|
Stuart Williams, Oisin Hurley, Chris Ferris, Lynne Thompson, John Ibbotson,
|
|
Marc Hadley, Yin-Leng Husband and Jean-Jacques Moreau provided detailed
|
|
comments on earlier versions of this document, as did many others during the
|
|
Last Call Working Draft review. Jacek Kopecky provided a list of RPC and SOAP
|
|
encoding changes.</p>
|
|
|
|
<p>Martin Gudgin reviewed the additional material in the second edition and
|
|
provided many helpful comments.</p>
|
|
|
|
<p>This document is the work of the W3C XML Protocol Working Group.</p>
|
|
|
|
<p>Participants in the Working Group are (at the time of writing, and by
|
|
alphabetical order): Glen Daniels (Sonic Software, formerly of Macromedia),
|
|
Vikas Deolaliker (Sonoa Systems, Inc.),
|
|
Chris Ferris (IBM, formerly of Sun Microsystems),
|
|
Marc Hadley (Sun Microsystems),
|
|
David Hull (TIBCO Software, Inc.),
|
|
Anish Karmarkar (Oracle),
|
|
Yves Lafon (W3C),
|
|
Jonathan Marsh (WSO2),
|
|
Jeff Mischkinsky (Oracle),
|
|
Eric Newcomer (IONA Technologies),
|
|
David Orchard (BEA Systems, formerly of Jamcracker),
|
|
Seumas Soltysik (IONA Technologies),
|
|
Davanum Srinivas (WSO2),
|
|
Pete Wenzel (Sun Microsystems, formerly of SeeBeyond).
|
|
</p>
|
|
|
|
<p>Previous participants were: Yasser alSafadi (Philips Research),
|
|
Bill Anderson (Xerox),
|
|
Vidur Apparao (Netscape),
|
|
Camilo Arbelaez (webMethods),
|
|
Mark Baker (Idokorro Mobile, Inc., formerly of Sun Microsystems),
|
|
Philippe Bedu (EDF (Electricite De France)),
|
|
Olivier Boudeville (EDF (Electricite De France)),
|
|
Carine Bournez (W3C),
|
|
Don Box (Microsoft Corporation, formerly of DevelopMentor),
|
|
Tom Breuel (Xerox),
|
|
Dick Brooks (Group 8760),
|
|
Winston Bumpus (Novell, Inc.),
|
|
David Burdett (Commerce One),
|
|
Charles Campbell (Informix Software),
|
|
Alex Ceponkus (Bowstreet),
|
|
Michael Champion (Software AG),
|
|
David Chappell (Sonic Software),
|
|
Miles Chaston (Epicentric),
|
|
David Clay (Oracle),
|
|
David Cleary (Progress Software),
|
|
Dave Cleary (webMethods),
|
|
Ugo Corda (Xerox),
|
|
Paul Cotton (Microsoft Corporation),
|
|
Fransisco Cubera (IBM),
|
|
Jim d'Augustine (Excelon Corporation),
|
|
Ron Daniel (Interwoven),
|
|
Doug Davis (IBM),
|
|
Ray Denenberg (Library of Congress),
|
|
Paul Denning (MITRE Corporation),
|
|
Frank DeRose (TIBCO Software, Inc.),
|
|
Mike Dierken (DataChannel),
|
|
Andrew Eisenberg (Progress Software),
|
|
Brian Eisenberg (DataChannel),
|
|
Colleen Evans (Sonic Software),
|
|
John Evdemon (XMLSolutions),
|
|
David Ezell (Hewlett Packard),
|
|
James Falek (TIBCO Software, Inc.),
|
|
David Fallside (IBM),
|
|
Eric Fedok (Active Data Exchange),
|
|
Daniela Florescu (Propel),
|
|
Dan Frantz (BEA Systems),
|
|
Michael Freeman (Engenia Software),
|
|
Dietmar Gaertner (Software AG),
|
|
Scott Golubock (Epicentric),
|
|
Tony Graham (Sun Microsystems),
|
|
Mike Greenberg (IONA Technologies),
|
|
Rich Greenfield (Library of Congress),
|
|
Martin Gudgin (Microsoft Corporation, formerly of DevelopMentor),
|
|
Hugo Haas (W3C),
|
|
Mark Hale (Interwoven),
|
|
Randy Hall (Intel),
|
|
Bjoern Heckel (Epicentric),
|
|
Frederick Hirsch (Zolera Systems),
|
|
Gerd Hoelzing (SAP AG),
|
|
Erin Hoffmann (Tradia Inc.),
|
|
Steve Hole (MessagingDirect Ltd.),
|
|
Mary Holstege (Calico Commerce),
|
|
Jim Hughes (Fujitsu Limited),
|
|
Oisin Hurley (IONA Technologies),
|
|
Yin-Leng Husband (Hewlett Packard, formerly of Compaq),
|
|
John Ibbotson (IBM),
|
|
Ryuji Inoue (Matsushita Electric Industrial Co., Ltd.),
|
|
Scott Isaacson (Novell, Inc.),
|
|
Kazunori Iwasa (Fujitsu Limited),
|
|
Murali Janakiraman (Rogue Wave),
|
|
Mario Jeckle (DaimlerChrysler Research and Technology),
|
|
Eric Jenkins (Engenia Software),
|
|
Mark Jones (AT&T),
|
|
Jay Kasi (Commerce One),
|
|
Jeffrey Kay (Engenia Software),
|
|
Suresh Kodichath (IONA Technologies),
|
|
Richard Koo (Vitria Technology Inc.),
|
|
Jacek Kopecky (Systinet),
|
|
Alan Kropp (Epicentric),
|
|
Julian Kumar (Epicentric),
|
|
Peter Lecuyer (Progress Software),
|
|
Tony Lee (Vitria Technology Inc.),
|
|
Michah Lerner (AT&T),
|
|
Bob Lojek (Intalio Inc.),
|
|
Henry Lowe (OMG),
|
|
Brad Lund (Intel),
|
|
Matthew MacKenzie (XMLGlobal Technologies),
|
|
Michael Mahan (Nokia),
|
|
Murray Maloney (Commerce One),
|
|
Richard Martin (Active Data Exchange),
|
|
Noah Mendelsohn (IBM, formerly of Lotus Development),
|
|
Alex Milowski (Lexica),
|
|
Kevin Mitchell (XMLSolutions),
|
|
Nilo Mitra (Ericsson),
|
|
Ed Mooney (Sun Microsystems),
|
|
Jean-Jacques Moreau (Canon),
|
|
Dean Moses (Epicentric),
|
|
Highland Mary Mountain (Intel),
|
|
Don Mullen (TIBCO Software, Inc.),
|
|
Rekha Nagarajan (Calico Commerce),
|
|
Raj Nair (Cisco Systems),
|
|
Masahiko Narita (Fujitsu Limited),
|
|
Mark Needleman (Data Research Associates),
|
|
Art Nevarez (Novell, Inc.),
|
|
Henrik Nielsen (Microsoft Corporation),
|
|
Mark Nottingham (BEA Systems, formerly of Akamai Technologies),
|
|
Conleth O'Connell (Vignette),
|
|
Kevin Perkins (Compaq),
|
|
Doug Purdy (Microsoft Corporation),
|
|
Jags Ramnaryan (BEA Systems),
|
|
Andreas Riegg (DaimlerChrysler Research and Technology),
|
|
Vilhelm Rosenqvist (NCR),
|
|
Herve Ruellan (Canon),
|
|
Marwan Sabbouh (MITRE Corporation),
|
|
Waqar Sadiq (Vitria Technology Inc.),
|
|
Rich Salz (Zolera Systems),
|
|
Krishna Sankar (Cisco Systems),
|
|
Jeff Schlimmer (Microsoft Corporation),
|
|
George Scott (Tradia Inc.),
|
|
Shane Sesta (Active Data Exchange),
|
|
Lew Shannon (NCR),
|
|
John-Paul Sicotte (MessagingDirect Ltd.),
|
|
Miroslav Simek (Systinet),
|
|
Simeon Simeonov (Macromedia),
|
|
Aaron Skonnard (DevelopMentor),
|
|
Nick Smilonich (Unisys),
|
|
Soumitro Tagore (Informix Software),
|
|
James Tauber (Bowstreet),
|
|
Anne Thomas Manes (Sun Microsystems),
|
|
Lynne Thompson (Unisys),
|
|
Patrick Thompson (Rogue Wave),
|
|
Jim Trezzo (Oracle),
|
|
Asir Vedamuthu (webMethods),
|
|
Mike Vernal (Microsoft Corporation),
|
|
Randy Waldrop (WebMethods),
|
|
Fred Waskiewicz (OMG),
|
|
David Webber (XMLGlobal Technologies),
|
|
Ray Whitmer (Netscape),
|
|
Volker Wiechers (SAP AG),
|
|
Stuart Williams (Hewlett Packard),
|
|
Yan Xu (DataChannel),
|
|
Amr Yassin (Philips Research),
|
|
Susan Yee (Active Data Exchange),
|
|
Jin Yu (MartSoft Corp.).
|
|
</p>
|
|
|
|
<p>We also wish to thank all the people who have contributed to discussions
|
|
on <a href="mailto:xml-dist-app@w3.org">xml-dist-app@w3.org</a>.</p>
|
|
|
|
</div>
|
|
|
|
</div>
|
|
</body></html>
|