W3C home > Mailing lists > Public > public-ws-resource-access-notifications@w3.org > August 2009

WWW/2002/ws/ra/edcopies wsfrag.html,NONE,1.1 wsfrag.xml,NONE,1.1

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
Message-Id: <E1MXQ9U-0006r8-TM@lionel-hutz.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> &copy; 2009 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>&reg;</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" 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/>
&nbsp;&nbsp;&nbsp;1.1 <a href="#reqs">Requirements</a><br/>
2 <a href="#Notations_and_Terminology">Terminology and Notation</a><br/>
&nbsp;&nbsp;&nbsp;2.1 <a href="#terminology">Terminology</a><br/>
&nbsp;&nbsp;&nbsp;2.2 <a href="#namespaces">XML Namespaces</a><br/>
&nbsp;&nbsp;&nbsp;2.3 <a href="#conven">Notational Conventions</a><br/>
&nbsp;&nbsp;&nbsp;2.4 <a href="#extensions">Considerations on the Use of Extensibility Points</a><br/>
&nbsp;&nbsp;&nbsp;2.5 <a href="#compliance">Compliance</a><br/>
3 <a href="#fragments">Fragment WS-Transfer Dialect</a><br/>
&nbsp;&nbsp;&nbsp;3.1 <a href="#Get">Get</a><br/>
&nbsp;&nbsp;&nbsp;3.2 <a href="#Put">Put</a><br/>
&nbsp;&nbsp;&nbsp;3.3 <a href="#Delete">Delete</a><br/>
&nbsp;&nbsp;&nbsp;3.4 <a href="#Create">Create</a><br/>
4 <a href="#iddiv1_1_802">Examples</a><br/>
&nbsp;&nbsp;&nbsp;4.1 <a href="#iddiv2_1_805">Examples</a><br/>
5 <a href="#QName">QName Expressions</a><br/>
&nbsp;&nbsp;&nbsp;5.1 <a href="#QName_Get">Get</a><br/>
&nbsp;&nbsp;&nbsp;5.2 <a href="#QName_Put">Put</a><br/>
&nbsp;&nbsp;&nbsp;5.3 <a href="#QName_Delete">Delete</a><br/>
&nbsp;&nbsp;&nbsp;5.4 <a href="#QName_Create">Create</a><br/>
6 <a href="#XPath">XPath Expressions</a><br/>
7 <a href="#Faults">Faults</a><br/>
&nbsp;&nbsp;&nbsp;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>&lt;s:Envelope&gt;
  &lt;s:Header&gt;
    <b>[Headers]</b>
    &lt;wsa:Action&gt;<b>[Action]</b>&lt;/wsa:Action&gt;
    ...
  &lt;/s:Header&gt;
  &lt;s:Body&gt;<b>[Body]</b>&lt;/s:Body&gt;
&lt;/s:Envelope&gt;</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>
  &lt;wst:Get Dialect="http://www.w3.org/2009/02/ws-frag" ...&gt;
    &lt;wsf:Expression Language="<em>xs:anyURI</em>" ...&gt;
      <em>xs:any</em> *
    &lt;/wsf:Expression&gt;
    <em>xs:any</em> *
  &lt;/wst:Get&gt;</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>
  &lt;wst:GetResponse ...&gt;
    &lt;wsf:Value&gt; <em>xs:any</em> * &lt;/wsf:Value&gt;
    <em>xs:any</em> *
  &lt;/wst:GetResponse&gt;</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>
  &lt;wst:Put Dialect="http://www.w3.org/2009/02/ws-frag" ...&gt;
    &lt;wsf:Expression Language="<em>xs:anyURI</em>" ...&gt;
      <em>xs:any</em> *
    &lt;/wsf:Expression&gt; 
    &lt;wsf:Value ...&gt;
      <em>xs:any</em> *
    &lt;/wsf:Value&gt; 
    <em>xs:any</em> *
  &lt;/wst:Put&gt;</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>
  &lt;wst:PutResponse ...&gt;
    <em>xs:any</em> *
  &lt;/wst:PutResponse&gt;</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>
  &lt;wst:Delete Dialect="http://www.w3.org/2009/02/ws-frag" ...&gt;
    &lt;wsf:Expression Language="<em>xs:anyURI</em>" ...&gt;
      <em>xs:any</em> *
    &lt;/wsf:Expression&gt;
    <em>xs:any</em> *
  &lt;/wst:Delete&gt;</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>
  &lt;wst:DeleteResponse ...&gt;
    <em>xs:any</em> *
  &lt;/wst:DeleteResponse&gt;</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>
  &lt;wst:Create Dialect="http://www.w3.org/2009/02/ws-frag" ...&gt;
    &lt;wsf:Expression Language="<em>xs:anyURI</em>" ...&gt;
      <em>xs:any</em> *
    &lt;/wsf:Expression&gt; 
    &lt;wsf:Value ...&gt;
      <em>xs:any</em> *
    &lt;/wsf:Value&gt; 
    <em>xs:any</em> *
  &lt;/wst:Create&gt;</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>
  &lt;wst:CreateResponse ...&gt;
    &lt;wst:ResourceCreated&gt; <em>endpoint-reference</em> &lt;/wst:ResourceCreated&gt;
    <em>xs:any</em> *
  &lt;/wst:CreateResponse&gt;</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>&lt;ab:AddressBook xmlns:ab="http://example.com/address"&gt;
  &lt;ab:owner&gt;Me&lt;/owner&gt;
  &lt;ab:size&gt;2&lt;/size&gt;
  &lt;ab:contact&gt;
    &lt;ab:name&gt;Joe Brown&lt;/name&gt;
    &lt;ab:address&gt;123 Main Street&lt;/address&gt;
    &lt;ab:city&gt;AnyTown&lt;/city&gt;
    &lt;ab:state&gt;CA&lt;/state&gt;
    &lt;ab:zip&gt;90210&lt;/zip&gt;
    &lt;ab:email&gt;joe@example.com&lt;/email&gt;
  &lt;/ab:contact&gt;
  &lt;ab:contact&gt;
    &lt;ab:name&gt;Mary Smith&lt;/name&gt;
    &lt;ab:address&gt;345 South Pine&lt;/address&gt;
    &lt;ab:city&gt;AnyTown&lt;/city&gt;
    &lt;ab:state&gt;CA&lt;/state&gt;
    &lt;ab:zip&gt;90210&lt;/zip&gt;
    &lt;ab:email&gt;mary@example.com&lt;/email&gt;
  &lt;/ab:contact&gt;
&lt;/ab:AddressBook&gt;</pre></div></div><p>
     The following shows a sample SOAP envelope containing a Get 
     request:
    </p><div class="exampleOuter"><div class="exampleInner"><pre>&lt;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/" &gt;
  &lt;s:Header&gt;
    &lt;wsa:To&gt;http://www.example.org/resourceABC&lt;/wsa:To&gt;
    &lt;wsa:Action&gt;
      http://www.w3.org/2009/02/ws-tra/Get
    &lt;/wsa:Action&gt;
    &lt;wsa:MessageID&gt;
      uuid:00000000-0000-0000-C000-000000000046
    &lt;/wsa:MessageID&gt;
  &lt;/s:Header&gt;
  &lt;s:Body&gt;
    &lt;wst:Get&gt;
      &lt;wsf:Expression Language=".../ws-frag/QName"&gt;
        ab:contact
      &lt;/wsf:Expression&gt;
    &lt;/wst:Get&gt;
  &lt;/s:Body&gt;
&lt;/s:Envelope&gt;</pre></div></div><p>
     The following shows the corresponding response message:</p><div class="exampleOuter"><div class="exampleInner"><pre>&lt;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/" &gt;
  &lt;s:Header&gt;
    &lt;wsa:Action&gt;
      http://www.w3.org/2009/02/ws-tra/GetResponse
    &lt;/wsa:Action&gt;
    &lt;wsa:MessageID&gt;
      uuid:0000010e-0000-0000-C000-000000000047
    &lt;/wsa:MessageID&gt;
    &lt;wsa:RelatesTo&gt;
      uuid:00000000-0000-0000-C000-000000000046
    &lt;/wsa:RelatesTo&gt;
  &lt;/s:Header&gt;
  &lt;s:Body&gt;
    &lt;wst:GetResponse&gt;
      &lt;wsf:Value&gt;
        &lt;ab:contact&gt;
          &lt;ab:name&gt;Joe Brown&lt;/name&gt;
          &lt;ab:address&gt;123 Main Street&lt;/address&gt;
          &lt;ab:city&gt;AnyTown&lt;/city&gt;
          &lt;ab:state&gt;CA&lt;/state&gt;
          &lt;ab:zip&gt;90210&lt;/zip&gt;
          &lt;ab:email&gt;joe@example.com&lt;/email&gt;
        &lt;/ab:contact&gt;
        &lt;ab:contact&gt;
          &lt;ab:name&gt;Mary Smith&lt;/name&gt;
          &lt;ab:address&gt;345 South Pine&lt;/address&gt;
          &lt;ab:city&gt;AnyTown&lt;/city&gt;
          &lt;ab:state&gt;CA&lt;/state&gt;
          &lt;ab:zip&gt;90210&lt;/zip&gt;
          &lt;ab:email&gt;mary@example.com&lt;/email&gt;
        &lt;/ab:contact&gt;
      &lt;/wsf:Value&gt;
    &lt;/wst:GetResponse&gt;
  &lt;/s:Body&gt;
&lt;/s:Envelope&gt;</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>&lt;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" &gt;
 
&lt;/xs:schema&gt;  </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>&lt;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"&gt;
 
&lt;/wsdl:definitions&gt;</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 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Sunday, 2 August 2009 01:46:31 GMT