- From: Doug Davis via cvs-syncmail <cvsmail@w3.org>
- Date: Sun, 02 Aug 2009 01:46:20 +0000
- To: public-ws-resource-access-notifications@w3.org
Update of /w3ccvs/WWW/2002/ws/ra/edcopies
In directory hutz:/tmp/cvs-serv26263
Added Files:
wsfrag.html wsfrag.xml
Log Message:
for safe keeping
--- NEW FILE: wsfrag.html ---
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Web Services Fragment (WS-Fragment)</title><style type="text/css">
code { font-family: monospace; }
div.constraint,
div.issue,
div.note,
div.notice { margin-left: 2em; }
ol.enumar { list-style-type: decimal; }
ol.enumla { list-style-type: lower-alpha; }
ol.enumlr { list-style-type: lower-roman; }
ol.enumua { list-style-type: upper-alpha; }
ol.enumur { list-style-type: upper-roman; }
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/base.css"/></head><body><div class="head">
<h1><a name="title" id="title"/>Web Services Fragment (WS-Fragment)</h1>
<h2><a name="w3c-doctype" id="w3c-doctype"/>Editor's Draft $Date: 2009/08/02 01:46:18 $</h2><dl><dt>Latest version:</dt><dd><a href="http://www.w3.org/TR/ws-fragment">http://www.w3.org/TR/ws-fragment
</a></dd><dt>Previous version:</dt><dd><a href="http://www.w3.org/TR/2009/WD-ws-fragment-20090317">http://www.w3.org/TR/2009/WD-ws-fragment-20090317</a></dd><dt>Editors:</dt><dd>Doug Davis, IBM</dd><dd>Ashok Malhotra, Oracle</dd><dd>Katy Warr, IBM</dd><dd>Wu Chou, Avaya</dd></dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2009 <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/Consotium/Legal/copyright-documents">document use</a> rules apply.</p></div><hr/><div>
<h2><a name="abstract" id="abstract"/>Abstract</h2><p>
This specification extends the <a href="#WsTransfer">[WS-Transfer]</a>
specification to enable clients to retrieve and manipulate subsets
of a WS-Transfer enabled resource without needing to include the entire
XML representation in a message exchange.
</p></div><div>
<h2><a name="status" id="status"/>Status of this Document</h2><p><strong>This document is an editors' copy that has
no official standing.</strong></p></div><div class="toc">
<h2><a name="contents" id="contents"/>Table of Contents</h2><p class="toc">1 <a href="#intro">Introduction</a><br/>
1.1 <a href="#reqs">Requirements</a><br/>
2 <a href="#Notations_and_Terminology">Terminology and Notation</a><br/>
2.1 <a href="#terminology">Terminology</a><br/>
2.2 <a href="#namespaces">XML Namespaces</a><br/>
2.3 <a href="#conven">Notational Conventions</a><br/>
2.4 <a href="#extensions">Considerations on the Use of Extensibility Points</a><br/>
2.5 <a href="#compliance">Compliance</a><br/>
3 <a href="#fragments">Fragment WS-Transfer Dialect</a><br/>
3.1 <a href="#Get">Get</a><br/>
3.2 <a href="#Put">Put</a><br/>
3.3 <a href="#Delete">Delete</a><br/>
3.4 <a href="#Create">Create</a><br/>
4 <a href="#iddiv1_1_802">Examples</a><br/>
4.1 <a href="#iddiv2_1_805">Examples</a><br/>
5 <a href="#QName">QName Expressions</a><br/>
5.1 <a href="#QName_Get">Get</a><br/>
5.2 <a href="#QName_Put">Put</a><br/>
5.3 <a href="#QName_Delete">Delete</a><br/>
5.4 <a href="#QName_Create">Create</a><br/>
6 <a href="#XPath">XPath Expressions</a><br/>
7 <a href="#Faults">Faults</a><br/>
7.1 <a href="#UnsupportedLanguage">UnsupportedLanguage</a><br/>
8 <a href="#acks">Acknowledgements</a><br/>
9 <a href="#refs">References</a><br/>
</p>
<h3><a name="appendices" id="appendices"/>Appendices</h3><p class="toc">A <a href="#Appendix_I__E2_80_93_XSD">XML Schema</a><br/>
B <a href="#Appendix_II__E2_80_93_WSDL">WSDL</a><br/>
C <a href="#ChangeLog">Change Log</a><br/>
D <a href="#Questions">Open Questions and Actions</a><br/>
</p></div><hr/><div class="body"><div class="div1">
<h2><a name="intro" id="intro"/>1 Introduction</h2><p>
This specification extends the WS-Transfer specification and defines
a mechanism that allows clients to retrieve and manipulate subsets
of a WS-Transfer enabled resource without needing to include the entire
XML representation in a message exchange.
</p><p>
This specification defines a fragment transfer mechanism, an
extension framework for defining expression languages, and a set of
expression languages.
</p><p>
The fragment transfer mechanism is defined as an extension to
WS-Transfer. This
involves defining a WS-Transfer Dialect and corresponding XML elements
that go into the SOAP Body of the Get, Put, Delete and Create
WS-Transfer operations.
This fragment transfer mechanism is designed so that it can be used
with any number of
expression languages to indentify a subset of the resource the
operation is to operate over.
</p><p>
While other specifications can define other expression languages,
it is RECOMMENDED that those languages
reuse the fragment transfer framework that this specification defines.
</p><div class="div2">
<h3><a name="reqs" id="reqs"/>1.1 Requirements</h3><p>This specification intends to meet the following requirement:</p><ul><li><p>
Provide an extension mechanism to WS-Transfer that allows for
subsets of a resource to be retrieved and modified.
</p></li><li><p>
Provide a set of expression languages that implementations
can leverage.
</p></li></ul></div></div><div class="div1">
<h2><a name="Notations_and_Terminology" id="Notations_and_Terminology"/>2 Terminology and Notation</h2><div class="div2">
<h3><a name="terminology" id="terminology"/>2.1 Terminology</h3><dl><dt class="label">Expression</dt><dd><p>
A Language specific set of tokens that are used refer to a location
in a resource.
</p></dd><dt class="label">Fragment</dt><dd><p>
A subset of a resource.
</p></dd></dl></div><div class="div2">
<h3><a name="namespaces" id="namespaces"/>2.2 XML Namespaces</h3><p>
The XML Namespace URI that MUST be used by implementations of this
specification is:
</p><div class="exampleOuter"><div class="exampleInner"><pre><a href="http://www.w3.org/2009/02/ws-fra">http://www.w3.org/2009/02/ws-fra</a></pre></div></div><p><a href="#xmlnamespaces">Table 2-1</a> lists XML namespaces that are
used in this specification. The
choice of any namespace prefix is arbitrary and not semantically
significant.
</p><a name="xmlnamespaces" id="xmlnamespaces"/><table border="1" cellpadding="5"><caption>Table 2-1:
Prefixes and XML Namespaces used in this specification.
</caption><tbody><tr><th align="left"> Prefix </th><th align="left"> XML Namespace </th><th align="left"> Specification(s) </th></tr><tr><td> wsf </td><td><a href="http://www.w3.org/2009/02/ws-fra">http://www.w3.org/2009/02/ws-fra</a></td><td>
This specification
</td></tr><tr><td> s </td><td> Either SOAP 1.1 or 1.2 </td><td> SOAP </td></tr><tr><td> s11 </td><td><a href="http://schemas.xmlsoap.org/soap/envelope/">http://schemas.xmlsoap.org/soap/envelope/</a></td><td><a href="#Soap11">[SOAP 1.1]</a></td></tr><tr><td> s12 </td><td><a href="http://www.w3.org/2003/05/soap-envelope">http://www.w3.org/2003/05/soap-envelope</a></td><td><a href="#Soap12">[SOAP 1.2]</a></td></tr><tr><td> wsa </td><td><a href="http://www.w3.org/2005/08/addressing">http://www.w3.org/2005/08/addressing</a></td><td><a href="#AddrCore">[WS-Addressing]</a></td></tr><tr><td> wsdl </td><td><a href="http://schemas.xmlsoap.org/wsdl/">http://schemas.xmlsoap.org/wsdl/</a></td><td><a href="#Wsdl11">[WSDL 1.1]</a></td></tr><tr><td> xs </td><td><a href="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</a></td><td>
XML Schema <a href="#XmlSchemaPart1">[XML Schema, Part 1]</a>, <a href="#XmlSchemaPart2">[XML Schema, Part 2]</a></td></tr><tr><td> wst </td><td><a href="http://www.w3.org/2009/02/ws-tra">http://www.w3.org/2009/02/ws-tra</a></td><td><a href="#WsTransfer">[WS-Transfer]</a></td></tr></tbody></table><p>
The working group intends to update the value of the Web Services
Fragment namespace URI each time a new version of this document is
published until such time that the document reaches Candidate
Recommendation status. Once it has reached Candidate Recommendation
status, the working group intends to maintain the value of the
Web Services Fragment namespace URI that was assigned in the
Candidate Recommendation unless significant changes are made that
impact the implementation or break post-CR implementations of the
specification. Also see
<a href="http://www.w3.org/2001/tag/doc/namespaceState.html">
http://www.w3.org/2001/tag/doc/namespaceState.html
</a> and
<a href="http://www.w3.org/2005/07/13-nsuri">
http://www.w3.org/2005/07/13-nsuri
</a>.
</p></div><div class="div2">
<h3><a name="conven" id="conven"/>2.3 Notational Conventions</h3><p>
The keywords "MUST", "MUST NOT",
"REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be
interpreted as described in RFC 2119
<a href="#Rfc2119">[RFC 2119]</a>.
</p><p>
This specification uses the following syntax to define outlines for
messages:
</p><ul><li><p>
The syntax appears as an XML instance, but values in italics
indicate data types instead of literal values.
</p></li><li><p>
Characters are appended to elements and attributes to indicate
cardinality:
</p><ul><li><p> "?" (0 or 1) </p></li><li><p> "*" (0 or more) </p></li><li><p> "+" (1 or more) </p></li></ul></li><li><p>
The character "|" is used to indicate a choice between
alternatives.
</p></li><li><p>
The characters "(" and ")" are used to
indicate that contained items are to be treated as a group with
respect to cardinality or choice.
</p></li><li><p>
The characters "[" and "]" are used to call
out references and property names.
</p></li><li><p>
Ellipsis (i.e. "...") indicate points of extensibility.
</p></li><li><p>
XML namespace prefixes (see <a href="#xmlnamespaces">Table 2-1</a>) are used
to indicate the namespace of the element being defined.
</p></li></ul><p>
In addition to Message Information Header properties
<a href="#AddrCore">[WS-Addressing]</a>,
this specification uses the following properties to define messages:
</p><dl><dt class="label"><b>[Headers]</b></dt><dd><p> Unordered message headers. </p></dd><dt class="label"><b>[Action]</b></dt><dd><p> The value to be used for the wsa:Action URI. </p></dd><dt class="label"><b>[Body]</b></dt><dd><p> A message body. </p></dd></dl><p>
These properties bind to a SOAP Envelope as follows:
</p><div class="exampleOuter"><div class="exampleInner"><pre><s:Envelope>
<s:Header>
<b>[Headers]</b>
<wsa:Action><b>[Action]</b></wsa:Action>
...
</s:Header>
<s:Body><b>[Body]</b></s:Body>
</s:Envelope></pre></div></div></div><div class="div2">
<h3><a name="extensions" id="extensions"/>2.4 Considerations on the Use of Extensibility Points</h3><p>
The elements defined in this specification MAY be extended at the
points indicated by their outlines and schema. Implementations MAY
add child elements and/or attributes at the indicated extension
points but MUST NOT contradict the semantics of the parent and/or
owner, respectively. If a receiver does not recognize an extension,
the receiver SHOULD ignore that extension. Senders MAY indicate
the presence of an extension that has to be understood through the use
of a corresponding SOAP Header with a soap:mustUnderstand attribute
with the value "1".
</p><p>
Extension elements and attributes MUST NOT use the Web Services
Fragment namespace URI.
</p></div><div class="div2">
<h3><a name="compliance" id="compliance"/>2.5 Compliance</h3><p>
An implementation is not compliant with this specification if it fails to
satisfy one or more of the MUST or REQUIRED level requirements defined
herein. A SOAP Node MUST NOT use the XML namespace identifier for this
specification (listed in <a href="#namespaces"><b>2.2 XML Namespaces</b></a>) within SOAP
Envelopes unless it is compliant with this specification.
</p><p>
Normative text within this specification takes precedence over the XML
Schema and WSDL descriptions, which in turn take precedence over
outlines, which in turn take precedence over examples.
</p><p>
All messages defined by this specification MUST be sent to a Web service
that is addressable by an EPR (see <a href="#AddrCore">[WS-Addressing]</a>).
</p></div></div><div class="div1">
<h2><a name="fragments" id="fragments"/>3 Fragment WS-Transfer Dialect</h2><p>
This section defines the fragment transfer mechanism that the expression
languages defined in subsequent sections will use.
The following sections define the expected behavior when the WS-Fragment
Dialect is used in each of the WS-Transfer operations.
</p><p>
Each Expression language that uses this transfer fragment mechanism
MUST fully define how it behaves for each operation and for the
language specific expression constructs it supports. For example,
an XPath language will need to explain how a new XML element is
inserted into an existing resource.
</p><p>
WS-Transfer defines what the expected behavior of a resource is
with respect to modifications of the resource that might result in
an invalid state or if the client does not have the authority to
perform such operations. This specification only extends but does
not modify the base WS-Transfer behavior.
</p><div class="div2">
<h3><a name="Get" id="Get"/>3.1 Get</h3><p>
To retrieve a subset of a resource
a client MUST specify the WS-Fragment URI in the wst:Get request.
</p><p>
The Get request message MUST be of the following form:
</p><div class="exampleOuter"><div class="exampleInner"><pre><b>[Action]</b>
http://www.w3.org/2009/02/ws-tra/Get
<b>[Body]</b>
<wst:Get Dialect="http://www.w3.org/2009/02/ws-frag" ...>
<wsf:Expression Language="<em>xs:anyURI</em>" ...>
<em>xs:any</em> *
</wsf:Expression>
<em>xs:any</em> *
</wst:Get></pre></div></div><p>
The following describes additional, normative constraints on the outline
listed above:
</p><dl><dt class="label"><b>[Body]</b>/wst:Get@Dialect </dt><dd><p>
This attribute MUST be set to http://www.w3.org/2009/02/ws-frag.
</p></dd><dt class="label"><b>[Body]</b>/wst:Get/wsf:Expression </dt><dd><p>
This element identifies which fragment in the resource this
operation applies to.
The value of this element MUST conform to the syntax of the language
specified in Language attribute, otherwise a
wsf:InvalidExpression fault MUST be generated.
</p></dd><dt class="label"><b>[Body]</b>/wst:Get/wsf:Expression@Language </dt><dd><p>
This URI indicates which expression language will be
used to identify the subset of the resource this operation applies
to. A resource MUST generate a wsf:UnsupportedLanguage Fault if it
does not support the specified Language.
</p></dd></dl><p>
If the resource accepts a Get request, it MUST reply with a response of
the following form:
</p><div class="exampleOuter"><div class="exampleInner"><pre><b>[Action]</b>
http://www.w3.org/2009/02/ws-tra/GetResponse
<b>[Body]</b>
<wst:GetResponse ...>
<wsf:Value> <em>xs:any</em> * </wsf:Value>
<em>xs:any</em> *
</wst:GetResponse></pre></div></div><p>
The following describes additional, normative constraints on the
outline listed above:
</p><dl><dt class="label"><b>[Body]</b>/wst:GetResponse/wsf:Value </dt><dd><p>
This element encompasses the fragment response corresponding to the
wsf:Expression in the request and MUST contain the subset of the
resource identified by the wsf:Expression element in the
corresponding Get request. If the
Expression identifies non-existent data, or
it corresponds to a fragment with no value, then this
element MAY be empty.
</p></dd></dl><p>
Other components of the outline above are not further constrained
by this specification.
</p></div><div class="div2">
<h3><a name="Put" id="Put"/>3.2 Put</h3><p>
To update a subset of a resource a client MUST specify the WS-Fragment
URI in the wst:Put request.
</p><p>
The Put request message MUST be of the following form:
</p><div class="exampleOuter"><div class="exampleInner"><pre><b>[Action]</b>
http://www.w3.org/2009/02/ws-tra/Put
<b>[Body]</b>
<wst:Put Dialect="http://www.w3.org/2009/02/ws-frag" ...>
<wsf:Expression Language="<em>xs:anyURI</em>" ...>
<em>xs:any</em> *
</wsf:Expression>
<wsf:Value ...>
<em>xs:any</em> *
</wsf:Value>
<em>xs:any</em> *
</wst:Put></pre></div></div><p>
The following describes additional, normative constraints on the outline
listed above:
</p><dl><dt class="label"><b>[Body]</b>/wst:Put@Dialect </dt><dd><p>
This attribute MUST be set to http://www.w3.org/2009/02/ws-frag.
</p></dd><dt class="label"><b>[Body]</b>/wst:Put/wsf:Expression </dt><dd><p>
This element identifies which fragment in the resource this
operation applies to.
The value of this element MUST conform to the syntax of the language
specified in Language attribute, otherwise a
wsf:InvalidExpression fault MUST be generated.
</p></dd><dt class="label"><b>[Body]</b>/wst:Put/wsf:Expression@Language </dt><dd><p>
This URI indicates which expression language will be
used to identify the subset of the resource this operation applies
to. A resource MUST generate a wsf:UnsupportedLanguage Fault if it
does not support the specified Language.
</p></dd><dt class="label"><b>[Body]</b>/wst:Put/wsf:Value </dt><dd><p>
This element contains the fragment resource representation
corresponding to the
subset of the resource identified by the wsf:Expression element.
</p></dd></dl><p>
This operation MUST be performed by removing any data that corresponds
to the Expression element of the request and inserting the specified
Fragment data in its place.
If the Expression identifies non-existent data
then this operation will not have any impact on the resource.
In other words, to insert new information into a resource the
wst:Create operation is to be used.
</p><p>
Note: do we really want this? Should the client really be forced
to know whether or not there's data there just to add something?
What if, instead, we just allowed it to replace the existing
data (if any)?
</p><p>
If the resource accepts a Put request, it MUST reply with a response of
the following form:
</p><div class="exampleOuter"><div class="exampleInner"><pre><b>[Action]</b>
http://www.w3.org/2009/02/ws-tra/PutResponse
<b>[Body]</b>
<wst:PutResponse ...>
<em>xs:any</em> *
</wst:PutResponse></pre></div></div><p>
There are no additional constraints beyond what WS-Transfer defines.
</p></div><div class="div2">
<h3><a name="Delete" id="Delete"/>3.3 Delete</h3><p>
To delete a subset of a resource a client MUST specify the WS-Fragment
URI in the wst:Delete request.
</p><p>
The Delete request message MUST be of the following form:
</p><div class="exampleOuter"><div class="exampleInner"><pre><b>[Action]</b>
http://www.w3.org/2009/02/ws-tra/Delete
<b>[Body]</b>
<wst:Delete Dialect="http://www.w3.org/2009/02/ws-frag" ...>
<wsf:Expression Language="<em>xs:anyURI</em>" ...>
<em>xs:any</em> *
</wsf:Expression>
<em>xs:any</em> *
</wst:Delete></pre></div></div><p>
The following describes additional, normative constraints on the outline
listed above:
</p><dl><dt class="label"><b>[Body]</b>/wst:Delete@Dialect </dt><dd><p>
This attribute MUST be set to http://www.w3.org/2009/02/ws-frag.
</p></dd><dt class="label"><b>[Body]</b>/wst:Delete/wsf:Expression </dt><dd><p>
This element identifies which fragment in the resource this
operation applies to.
The value of this element MUST conform to the syntax of the language
specified in Language attribute, otherwise a
wsf:InvalidExpression fault MUST be generated.
</p></dd><dt class="label"><b>[Body]</b>/wst:Delete/wsf:Expression@Language </dt><dd><p>
This URI indicates which expression language will be
used to identify the subset of the resource this operation applies
to. A resource MUST generate a wsf:UnsupportedLanguage Fault if it
does not support the specified Language.
</p></dd></dl><p>
This operation MUST be performed by removing any data that corresponds
to the Expression element of the request.
If the Expression identifies non-existent data
then this operation will not have any impact on the resource and
no fault is generated.
</p><p>
If the resource accepts a Delete request, it MUST reply with a response of
the following form:
</p><div class="exampleOuter"><div class="exampleInner"><pre><b>[Action]</b>
http://www.w3.org/2009/02/ws-tra/DeleteResponse
<b>[Body]</b>
<wst:DeleteResponse ...>
<em>xs:any</em> *
</wst:DeleteResponse></pre></div></div><p>
There are no additional constraints beyond what WS-Transfer defines.
</p></div><div class="div2">
<h3><a name="Create" id="Create"/>3.4 Create</h3><p>
To insert data into an existing resource a client MUST specify the
WS-Fragment URI in the wst:Delete request.
</p><p>
The Create request message MUST be of the following form:
</p><div class="exampleOuter"><div class="exampleInner"><pre><b>[Action]</b>
http://www.w3.org/2009/02/ws-tra/Create
<b>[Body]</b>
<wst:Create Dialect="http://www.w3.org/2009/02/ws-frag" ...>
<wsf:Expression Language="<em>xs:anyURI</em>" ...>
<em>xs:any</em> *
</wsf:Expression>
<wsf:Value ...>
<em>xs:any</em> *
</wsf:Value>
<em>xs:any</em> *
</wst:Create></pre></div></div><p>
The following describes additional, normative constraints on the outline
listed above:
</p><dl><dt class="label"><b>[Body]</b>/wst:Create@Dialect </dt><dd><p>
This attribute MUST be set to http://www.w3.org/2009/02/ws-frag.
</p></dd><dt class="label"><b>[Body]</b>/wst:Create/wsf:Expression </dt><dd><p>
This element identifies which fragment in the resource this
operation applies to.
The value of this element MUST conform to the syntax of the language
specified in Language attribute, otherwise a
wsf:InvalidExpression fault MUST be generated.
</p><p>
This element identifies the fragment in the resource as it
appears after successful processing of the current fragment.
</p></dd><dt class="label"><b>[Body]</b>/wst:Create/wsf:Expression@Language </dt><dd><p>
This URI indicates which expression language will be
used to identify the subset of the resource this operation applies
to. A resource MUST generate a wsf:UnsupportedLanguage Fault if it
does not support the specified Language.
</p></dd><dt class="label"><b>[Body]</b>/wst:Create/wsf:Value </dt><dd><p>
This element encompasses the fragment corresponding to the
subset of the resource indentified by the wsf:Expression element.
</p></dd></dl><p>
This operation MUST be performed by inserting new data within the
Fragment element into the resource as specified by the Expression
element. If data is already present and would result in the resource
being left in an invalid state then a wst:InvalidRepresentation
fault MUST be generated.
</p><p>
If the resource accepts a Create request, it MUST reply with a response of
the following form:
</p><div class="exampleOuter"><div class="exampleInner"><pre><b>[Action]</b>
http://www.w3.org/2009/02/ws-tra/CreateResponse
<b>[Body]</b>
<wst:CreateResponse ...>
<wst:ResourceCreated> <em>endpoint-reference</em> </wst:ResourceCreated>
<em>xs:any</em> *
</wst:CreateResponse></pre></div></div><p>
There are no additional constraints beyond what WS-Transfer defines.
</p></div></div><div class="div1">
<h2><a name="iddiv1_1_802" id="iddiv1_1_802"/>4 Examples</h2><div class="div2">
<h3><a name="iddiv2_1_805" id="iddiv2_1_805"/>4.1 Examples</h3><p>
In the following examples, and Expression Language definitions,
the following representation of a resource is used for
informational purposes:
</p><div class="exampleOuter"><div class="exampleInner"><pre><ab:AddressBook xmlns:ab="http://example.com/address">
<ab:owner>Me</owner>
<ab:size>2</size>
<ab:contact>
<ab:name>Joe Brown</name>
<ab:address>123 Main Street</address>
<ab:city>AnyTown</city>
<ab:state>CA</state>
<ab:zip>90210</zip>
<ab:email>joe@example.com</email>
</ab:contact>
<ab:contact>
<ab:name>Mary Smith</name>
<ab:address>345 South Pine</address>
<ab:city>AnyTown</city>
<ab:state>CA</state>
<ab:zip>90210</zip>
<ab:email>mary@example.com</email>
</ab:contact>
</ab:AddressBook></pre></div></div><p>
The following shows a sample SOAP envelope containing a Get
request:
</p><div class="exampleOuter"><div class="exampleInner"><pre><s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:ex="http://www.example.com/" >
<s:Header>
<wsa:To>http://www.example.org/resourceABC</wsa:To>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Get
</wsa:Action>
<wsa:MessageID>
uuid:00000000-0000-0000-C000-000000000046
</wsa:MessageID>
</s:Header>
<s:Body>
<wst:Get>
<wsf:Expression Language=".../ws-frag/QName">
ab:contact
</wsf:Expression>
</wst:Get>
</s:Body>
</s:Envelope></pre></div></div><p>
The following shows the corresponding response message:</p><div class="exampleOuter"><div class="exampleInner"><pre><s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:ex="http://www.example.com/" >
<s:Header>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/GetResponse
</wsa:Action>
<wsa:MessageID>
uuid:0000010e-0000-0000-C000-000000000047
</wsa:MessageID>
<wsa:RelatesTo>
uuid:00000000-0000-0000-C000-000000000046
</wsa:RelatesTo>
</s:Header>
<s:Body>
<wst:GetResponse>
<wsf:Value>
<ab:contact>
<ab:name>Joe Brown</name>
<ab:address>123 Main Street</address>
<ab:city>AnyTown</city>
<ab:state>CA</state>
<ab:zip>90210</zip>
<ab:email>joe@example.com</email>
</ab:contact>
<ab:contact>
<ab:name>Mary Smith</name>
<ab:address>345 South Pine</address>
<ab:city>AnyTown</city>
<ab:state>CA</state>
<ab:zip>90210</zip>
<ab:email>mary@example.com</email>
</ab:contact>
</wsf:Value>
</wst:GetResponse>
</s:Body>
</s:Envelope></pre></div></div></div></div><div class="div1">
<h2><a name="QName" id="QName"/>5 QName Expressions</h2><p>
The QName expression language is a syntax for expressions that
uses a single QName to reference the immediate children of the root
element of
the resource representation. The expression MUST evaluate to zero or
more elements, each including the element name, any attributes
and its entire content.
This language can be implemented as a precise subset of the XPath language.
</p><p>
The QName language MUST be indicated by using the URI:
</p><div class="exampleOuter"><div class="exampleInner"><pre><a href="http://www.w3.org/2009/02/ws-fra/QName">http://www.w3.org/2009/02/ws-fra/QName</a></pre></div></div><div class="div2">
<h3><a name="QName_Get" id="QName_Get"/>5.1 Get</h3><p>
When used in a Get request message, the expression identifies
which immediate children of the root element to return. If the
QName matches more than one element then all of those elements
are returned. If the QName doesn't match any element then
an empty Fragment element is returned.
</p></div><div class="div2">
<h3><a name="QName_Put" id="QName_Put"/>5.2 Put</h3><p>
When used in a Put request message. the expression identifies
which immediate children of the root element to replace. If the
QName matches more than one element then all of those elements
are deleted and the children Fragment elements are inserted in their
place.
</p></div><div class="div2">
<h3><a name="QName_Delete" id="QName_Delete"/>5.3 Delete</h3><p>
When used in a Delete request message. the expression identifies
which immediate children of the root element to remove. If the
QName matches more than one element then all of those elements
are deleted. If the QName doesn't match any element then this
operation will have no impact on the resource.
</p></div><div class="div2">
<h3><a name="QName_Create" id="QName_Create"/>5.4 Create</h3><p>
When used in a Create request message. the children Fragment elements
are inserted as children of the root element. If the expression
identifies an existing element then the new elements are inserted
after them.
</p></div></div><div class="div1">
<h2><a name="XPath" id="XPath"/>6 XPath Expressions</h2><p>
...
</p><div class="exampleOuter"><div class="exampleInner"><pre><a href="http://www.w3.org/2009/02/ws-fra/XPath">http://www.w3.org/2009/02/ws-fra/XPath</a></pre></div></div></div><div class="div1">
<h2><a name="Faults" id="Faults"/>7 Faults</h2><p>
All fault messages defined in this specification MUST be sent according to
the rules and usage described in
<a href="http://www.w3.org/TR/2006/REC-ws-addr-soap-20060509/">WS-Addressing 1.0 SOAP Binding</a>
Section 6 for encoding SOAP 1.1 and SOAP 1.2 faults.
The <b>[action]</b> property below SHOULD be used for faults
defined in this specification:
</p><div class="exampleOuter"><div class="exampleInner"><pre><a href="http://www.w3.org/2009/02/ws-fra/fault">http://www.w3.org/2009/02/ws-fra/fault</a></pre></div></div><div class="div2">
<h3><a name="UnsupportedLanguage" id="UnsupportedLanguage"/>7.1 UnsupportedLanguage</h3><p>
This fault is generated when a service detects an unknown Language
URI in a request message.
</p><a name="Table3" id="Table3"/><table border="1" cellpadding="5"><tbody><tr><th align="left"><b>[Code]</b></th><td>s:Sender</td></tr><tr><th align="left"><b>[Subcode]</b></th><td>wst:UnknownLanguage</td></tr><tr><th align="left"><b>[Reason]</b></th><td>
The specified Language URI is not known.
</td></tr><tr><th align="left"><b>[Detail]</b></th><td><em>The unknown URI if specified</em></td></tr></tbody></table></div></div><div class="div1">
<h2><a name="acks" id="acks"/>8 Acknowledgements</h2><p>
This specification has been developed as a result of joint
work with many individuals and teams, including:
Ashok Malhotra (Oracle Corp.),
Asir Vedamuthu (Microsoft Corp.),
Bob Freund (Hitachi, Ltd.),
Doug Davis (IBM),
Fred Maciel (Hitachi, Ltd.),
Geoff Bullen (Microsoft Corp.),
Gilbert Pilz (Oracle Corp.),
Greg Carpenter (Microsoft Corp.),
Jeff Mischkinsky (Oracle Corp.),
Katy Warr (IBM),
Li Li (Avaya Communications),
Mark Little (Red Hat),
Prasad Yendluri (Software AG),
Sreedhara Narayanaswamy (CA),
Sumeet Vij (Software AG),
Vikas Varma (Software AG),
Wu Chou (Avaya Communications),
Yves Lafon (W3C)
</p></div><div class="div1">
<h2><a name="refs" id="refs"/>9 References</h2><dl><dt class="label"><a name="Rfc2119" id="Rfc2119"/>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, Harvard University, March 1997.
(See http://www.ietf.org/rfc/rfc2119.txt.)</dd><dt class="label"><a name="Soap11" id="Soap11"/>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>
, D. Box, et al, May 2000.
(See http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.)</dd><dt class="label"><a name="Soap12" id="Soap12"/>SOAP 1.2</dt><dd><a href="http://www.w3.org/TR/soap12-part1/"><cite>
SOAP Version 1.2 Part 1: Messaging Framework
</cite></a>
, M. Gudgin, et al, June 2003.
(See http://www.w3.org/TR/soap12-part1/.)</dd><dt class="label"><a name="AddrCore" id="AddrCore"/>WS-Addressing</dt><dd><a href="http://www.w3.org/2005/08/addressing/"><cite>
W3C Recommendation, "Web Services Addressing 1.0 (WS-Addressing)"
</cite></a>
, May 2006.
(See http://www.w3.org/2005/08/addressing/.)</dd><dt class="label"><a name="WsPolicy" id="WsPolicy"/>WS-Policy</dt><dd><a href="http://www.w3.org/TR/ws-policy/"><cite>
W3C Recommendation, "Web Services Policy 1.5 - Framework"
</cite></a>
, September 2007.
(See http://www.w3.org/TR/ws-policy/.)</dd><dt class="label"><a name="WsTransfer" id="WsTransfer"/>WS-Transfer</dt><dd><a href="http://www.w3.org/2009/02/ws-tra"><cite>
W3C Working Group Draft, "Web Services Transfer"
</cite></a>
, July 2009.
(See http://www.w3.org/2009/02/ws-tra.)</dd><dt class="label"><a name="Wsdl11" id="Wsdl11"/>WSDL 1.1</dt><dd><a href="http://www.w3.org/TR/2001/NOTE-wsdl-20010315"><cite>
Web Services Description Language (WSDL) 1.1
</cite></a>
, E. Christensen, et al, March 2001.
(See http://www.w3.org/TR/2001/NOTE-wsdl-20010315.)</dd><dt class="label"><a name="XMLInfoSet" id="XMLInfoSet"/>XML Infoset</dt><dd><a href="http://www.w3.org/TR/2004/REC-xml-infoset-20040204/"><cite>
J. Cowan, et al, "XML Information Set"
</cite></a>
, February 2004.
(See http://www.w3.org/TR/2004/REC-xml-infoset-20040204/.)</dd><dt class="label"><a name="XmlSchemaPart1" id="XmlSchemaPart1"/>XML Schema, Part 1</dt><dd><a href="http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/"><cite>
XML Schema Part 1: Structures
</cite></a>
, H. Thompson, et al, October 2004.
(See http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/.)</dd><dt class="label"><a name="XmlSchemaPart2" id="XmlSchemaPart2"/>XML Schema, Part 2</dt><dd><a href="http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/"><cite>
XML Schema Part 2: Datatypes
</cite></a>
, James Clark, et al, November 1999.
(See http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.)</dd></dl></div></div><div class="back"><div class="div1">
<h2><a name="Appendix_I__E2_80_93_XSD" id="Appendix_I__E2_80_93_XSD"/>A XML Schema</h2><p>
A normative copy of the XML Schema <a href="#XmlSchemaPart1">[XML Schema, Part 1]</a>,
<a href="#XmlSchemaPart2">[XML Schema, Part 2]</a> description for this specification may be
retrieved from the following address:
</p><div class="exampleOuter"><div class="exampleInner"><pre><a href="http://www.w3.org/2009/02/ws-fra/fragment.xsd">http://www.w3.org/2009/02/ws-fra/fragment.xsd</a></pre></div></div><p>
A non-normative copy of the XML schema is listed below for convenience.
</p><div class="exampleOuter"><div class="exampleInner"><pre><xs:schema
targetNamespace="http://www.w3.org/2009/02/ws-fra"
xmlns:tns="http://www.w3.org/2009/02/ws-fra"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
elementFormDefault="qualified"
blockDefault="#all" >
</xs:schema> </pre></div></div></div><div class="div1">
<h2><a name="Appendix_II__E2_80_93_WSDL" id="Appendix_II__E2_80_93_WSDL"/>B WSDL</h2><p>
A normative copy of the WSDL <a href="#Wsdl11">[WSDL 1.1]</a> description
for this specification may be retrieved from the following address:
</p><div class="exampleOuter"><div class="exampleInner"><pre><a href="http://www.w3.org/2009/02/ws-fra/fragment.wsdl">http://www.w3.org/2009/02/ws-fra/fragment.wsdl</a></pre></div></div><p>
A non-normative copy of the WSDL description is listed below for
convenience.
</p><div class="exampleOuter"><div class="exampleInner"><pre><wsdl:definitions
targetNamespace="http://www.w3.org/2009/02/ws-fra"
xmlns:tns="http://www.w3.org/2009/02/ws-fra"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
</wsdl:definitions></pre></div></div></div><div class="div1">
<h2><a name="ChangeLog" id="ChangeLog"/>C Change Log</h2><table border="1"><tbody><tr><th> Data </th><th> Author </th><th> Description </th></tr><tr><td> 2009/03/04 </td><td> DD </td><td> Added resolution of issue
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=xxxx">xxxx</a></td></tr></tbody></table></div><div class="div1">
<h2><a name="Questions" id="Questions"/>D Open Questions and Actions</h2><p>
Ram - If the expression resolves to a non-existent noe should it fault
or do nothing?
</p><p>
Ram - should we allow for the creation with default value? This is,
allow 0 or 1 value elements on the Create.
</p><p>
Ram - add an invalidExpression, NonExistentNode fault.
</p><p>
Add the 2 xpath expressions languages defined by RT
</p><p>
Ram - add a general fault to indicate that a fragment message is invalid.
</p><p>
Dug - on put - Should the client really be forced to know whether or not
there's data there just to add something? What if, instead, we just
allowed it to replace the existing data (if any)?
</p></div></div></body></html>
--- NEW FILE: wsfrag.xml ---
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type='text/xsl' href='xmlspec.xsl'?>
<!DOCTYPE spec PUBLIC "-//W3C//DTD Specification V2.1//EN" "xmlspec.dtd" [
<!ENTITY % entities SYSTEM "entitieswd.dtd" >
%entities;
<!ENTITY status "&wsfra.status;" >
<!ENTITY short-status "&wsfra.short-status;" >
]>
<spec w3c-doctype="&wsfra.w3c-doctype;" role="&wsfra.role;">
<header>
<title>&wsfra.name;</title>
<w3c-designation>&wsfra.w3c-designation;</w3c-designation>
<w3c-doctype>"&wsfra.w3c-doctype;</w3c-doctype>
<pubdate>
<day>&wsfra.day;</day>
<month>&wsfra.month;</month>
<year>&wsfra.year;</year>
</pubdate>
[...1298 lines suppressed...]
Ram - add an invalidExpression, NonExistentNode fault.
</p>
<p>
Add the 2 xpath expressions languages defined by RT
</p>
<p>
Ram - add a general fault to indicate that a fragment message is invalid.
</p>
<p>
Dug - on put - Should the client really be forced to know whether or not
there's data there just to add something? What if, instead, we just
allowed it to replace the existing data (if any)?
</p>
</div1>
</back>
</spec>
Received on Sunday, 2 August 2009 01:46:30 UTC