Tech-invite3GPPspaceIETFspace
96959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 2518

HTTP Extensions for Distributed Authoring -- WEBDAV

Pages: 94
Obsoleted by:  4918
Part 2 of 4 – Pages 23 to 52
First   Prev   Next

ToP   noToC   RFC2518 - Page 23   prevText

8 HTTP Methods for Distributed Authoring

The following new HTTP methods use XML as a request and response format. All DAV compliant clients and resources MUST use XML parsers that are compliant with [REC-XML]. All XML used in either requests or responses MUST be, at minimum, well formed. If a server receives
ToP   noToC   RFC2518 - Page 24
   ill-formed XML in a request it MUST reject the entire request with a
   400 (Bad Request).  If a client receives ill-formed XML in a response
   then it MUST NOT assume anything about the outcome of the executed
   method and SHOULD treat the server as malfunctioning.

8.1 PROPFIND

The PROPFIND method retrieves properties defined on the resource identified by the Request-URI, if the resource does not have any internal members, or on the resource identified by the Request-URI and potentially its member resources, if the resource is a collection that has internal member URIs. All DAV compliant resources MUST support the PROPFIND method and the propfind XML element (section 12.14) along with all XML elements defined for use with that element. A client may submit a Depth header with a value of "0", "1", or "infinity" with a PROPFIND on a collection resource with internal member URIs. DAV compliant servers MUST support the "0", "1" and "infinity" behaviors. By default, the PROPFIND method without a Depth header MUST act as if a "Depth: infinity" header was included. A client may submit a propfind XML element in the body of the request method describing what information is being requested. It is possible to request particular property values, all property values, or a list of the names of the resource's properties. A client may choose not to submit a request body. An empty PROPFIND request body MUST be treated as a request for the names and values of all properties. All servers MUST support returning a response of content type text/xml or application/xml that contains a multistatus XML element that describes the results of the attempts to retrieve the various properties. If there is an error retrieving a property then a proper error result MUST be included in the response. A request to retrieve the value of a property which does not exist is an error and MUST be noted, if the response uses a multistatus XML element, with a response XML element which contains a 404 (Not Found) status value. Consequently, the multistatus XML element for a collection resource with member URIs MUST include a response XML element for each member URI of the collection, to whatever depth was requested. Each response XML element MUST contain an href XML element that gives the URI of the resource on which the properties in the prop XML element are defined. Results for a PROPFIND on a collection resource with internal member URIs are returned as a flat list whose order of entries is not significant.
ToP   noToC   RFC2518 - Page 25
   In the case of allprop and propname, if a principal does not have the
   right to know whether a particular property exists then the property
   should be silently excluded from the response.

   The results of this method SHOULD NOT be cached.

8.1.1 Example - Retrieving Named Properties

>>Request PROPFIND /file HTTP/1.1 Host: www.foo.bar Content-type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:propfind xmlns:D="DAV:"> <D:prop xmlns:R="http://www.foo.bar/boxschema/"> <R:bigbox/> <R:author/> <R:DingALing/> <R:Random/> </D:prop> </D:propfind> >>Response HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:"> <D:response> <D:href>http://www.foo.bar/file</D:href> <D:propstat> <D:prop xmlns:R="http://www.foo.bar/boxschema/"> <R:bigbox> <R:BoxType>Box type A</R:BoxType> </R:bigbox> <R:author> <R:Name>J.J. Johnson</R:Name> </R:author> </D:prop> <D:status>HTTP/1.1 200 OK</D:status> </D:propstat> <D:propstat> <D:prop><R:DingALing/><R:Random/></D:prop>
ToP   noToC   RFC2518 - Page 26
               <D:status>HTTP/1.1 403 Forbidden</D:status>
               <D:responsedescription> The user does not have access to
   the DingALing property.
               </D:responsedescription>
          </D:propstat>
     </D:response>
     <D:responsedescription> There has been an access violation error.
     </D:responsedescription>
   </D:multistatus>

   In this example, PROPFIND is executed on a non-collection resource
   http://www.foo.bar/file.  The propfind XML element specifies the name
   of four properties whose values are being requested. In this case
   only two properties were returned, since the principal issuing the
   request did not have sufficient access rights to see the third and
   fourth properties.

8.1.2 Example - Using allprop to Retrieve All Properties

>>Request PROPFIND /container/ HTTP/1.1 Host: www.foo.bar Depth: 1 Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:propfind xmlns:D="DAV:"> <D:allprop/> </D:propfind> >>Response HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:"> <D:response> <D:href>http://www.foo.bar/container/</D:href> <D:propstat> <D:prop xmlns:R="http://www.foo.bar/boxschema/"> <R:bigbox> <R:BoxType>Box type A</R:BoxType> </R:bigbox> <R:author>
ToP   noToC   RFC2518 - Page 27
                         <R:Name>Hadrian</R:Name>
                    </R:author>
                    <D:creationdate>
                         1997-12-01T17:42:21-08:00
                    </D:creationdate>
                    <D:displayname>
                         Example collection
                    </D:displayname>
                    <D:resourcetype><D:collection/></D:resourcetype>
                    <D:supportedlock>
                         <D:lockentry>
                              <D:lockscope><D:exclusive/></D:lockscope>
                              <D:locktype><D:write/></D:locktype>
                         </D:lockentry>
                         <D:lockentry>
                              <D:lockscope><D:shared/></D:lockscope>
                              <D:locktype><D:write/></D:locktype>
                         </D:lockentry>
                    </D:supportedlock>
               </D:prop>
               <D:status>HTTP/1.1 200 OK</D:status>
          </D:propstat>
     </D:response>
     <D:response>
          <D:href>http://www.foo.bar/container/front.html</D:href>
          <D:propstat>
               <D:prop xmlns:R="http://www.foo.bar/boxschema/">
                    <R:bigbox>
                         <R:BoxType>Box type B</R:BoxType>
                    </R:bigbox>
                    <D:creationdate>
                         1997-12-01T18:27:21-08:00
                    </D:creationdate>
                    <D:displayname>
                         Example HTML resource
                    </D:displayname>
                    <D:getcontentlength>
                         4525
                    </D:getcontentlength>
                    <D:getcontenttype>
                         text/html
                    </D:getcontenttype>
                    <D:getetag>
                         zzyzx
                    </D:getetag>
                    <D:getlastmodified>
                         Monday, 12-Jan-98 09:25:56 GMT
                    </D:getlastmodified>
ToP   noToC   RFC2518 - Page 28
                    <D:resourcetype/>
                    <D:supportedlock>
                         <D:lockentry>
                              <D:lockscope><D:exclusive/></D:lockscope>
                              <D:locktype><D:write/></D:locktype>
                         </D:lockentry>
                         <D:lockentry>
                              <D:lockscope><D:shared/></D:lockscope>
                              <D:locktype><D:write/></D:locktype>
                         </D:lockentry>
                    </D:supportedlock>
               </D:prop>
               <D:status>HTTP/1.1 200 OK</D:status>
          </D:propstat>
     </D:response>
   </D:multistatus>

   In this example, PROPFIND was invoked on the resource
   http://www.foo.bar/container/ with a Depth header of 1, meaning the
   request applies to the resource and its children, and a propfind XML
   element containing the allprop XML element, meaning the request
   should return the name and value of all properties defined on each
   resource.

   The resource http://www.foo.bar/container/ has six properties defined
   on it:

   http://www.foo.bar/boxschema/bigbox,
   http://www.foo.bar/boxschema/author, DAV:creationdate,
   DAV:displayname, DAV:resourcetype, and DAV:supportedlock.

   The last four properties are WebDAV-specific, defined in section 13.
   Since GET is not supported on this resource, the get* properties
   (e.g., getcontentlength) are not defined on this resource. The DAV-
   specific properties assert that "container" was created on December
   1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT
   (creationdate), has a name of "Example collection" (displayname), a
   collection resource type (resourcetype), and supports exclusive write
   and shared write locks (supportedlock).

   The resource http://www.foo.bar/container/front.html has nine
   properties defined on it:

   http://www.foo.bar/boxschema/bigbox (another instance of the "bigbox"
   property type), DAV:creationdate, DAV:displayname,
   DAV:getcontentlength, DAV:getcontenttype, DAV:getetag,
   DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock.
ToP   noToC   RFC2518 - Page 29
   The DAV-specific properties assert that "front.html" was created on
   December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT
   (creationdate), has a name of "Example HTML resource" (displayname),
   a content length of 4525 bytes (getcontentlength), a MIME type of
   "text/html" (getcontenttype), an entity tag of "zzyzx" (getetag), was
   last modified on Monday, January 12, 1998, at 09:25:56 GMT
   (getlastmodified), has an empty resource type, meaning that it is not
   a collection (resourcetype), and supports both exclusive write and
   shared write locks (supportedlock).

8.1.3 Example - Using propname to Retrieve all Property Names

>>Request PROPFIND /container/ HTTP/1.1 Host: www.foo.bar Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <propfind xmlns="DAV:"> <propname/> </propfind> >>Response HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <multistatus xmlns="DAV:"> <response> <href>http://www.foo.bar/container/</href> <propstat> <prop xmlns:R="http://www.foo.bar/boxschema/"> <R:bigbox/> <R:author/> <creationdate/> <displayname/> <resourcetype/> <supportedlock/> </prop> <status>HTTP/1.1 200 OK</status> </propstat> </response> <response> <href>http://www.foo.bar/container/front.html</href>
ToP   noToC   RFC2518 - Page 30
          <propstat>
               <prop xmlns:R="http://www.foo.bar/boxschema/">
                    <R:bigbox/>
                    <creationdate/>
                    <displayname/>
                    <getcontentlength/>
                    <getcontenttype/>
                    <getetag/>
                    <getlastmodified/>
                    <resourcetype/>
                    <supportedlock/>
               </prop>
               <status>HTTP/1.1 200 OK</status>
          </propstat>
     </response>
   </multistatus>


   In this example, PROPFIND is invoked on the collection resource
   http://www.foo.bar/container/, with a propfind XML element containing
   the propname XML element, meaning the name of all properties should
   be returned.  Since no Depth header is present, it assumes its
   default value of "infinity", meaning the name of the properties on
   the collection and all its progeny should be returned.

   Consistent with the previous example, resource
   http://www.foo.bar/container/ has six properties defined on it,
   http://www.foo.bar/boxschema/bigbox,
   http://www.foo.bar/boxschema/author, DAV:creationdate,
   DAV:displayname, DAV:resourcetype, and DAV:supportedlock.

   The resource http://www.foo.bar/container/index.html, a member of the
   "container" collection, has nine properties defined on it,
   http://www.foo.bar/boxschema/bigbox, DAV:creationdate,
   DAV:displayname, DAV:getcontentlength, DAV:getcontenttype,
   DAV:getetag, DAV:getlastmodified, DAV:resourcetype, and
   DAV:supportedlock.

   This example also demonstrates the use of XML namespace scoping, and
   the default namespace.  Since the "xmlns" attribute does not contain
   an explicit "shorthand name" (prefix) letter, the namespace applies
   by default to all enclosed elements.  Hence, all elements which do
   not explicitly state the namespace to which they belong are members
   of the "DAV:" namespace schema.
ToP   noToC   RFC2518 - Page 31

8.2 PROPPATCH

The PROPPATCH method processes instructions specified in the request body to set and/or remove properties defined on the resource identified by the Request-URI. All DAV compliant resources MUST support the PROPPATCH method and MUST process instructions that are specified using the propertyupdate, set, and remove XML elements of the DAV schema. Execution of the directives in this method is, of course, subject to access control constraints. DAV compliant resources SHOULD support the setting of arbitrary dead properties. The request message body of a PROPPATCH method MUST contain the propertyupdate XML element. Instruction processing MUST occur in the order instructions are received (i.e., from top to bottom). Instructions MUST either all be executed or none executed. Thus if any error occurs during processing all executed instructions MUST be undone and a proper error result returned. Instruction processing details can be found in the definition of the set and remove instructions in section 12.13.

8.2.1 Status Codes for use with 207 (Multi-Status)

The following are examples of response codes one would expect to be used in a 207 (Multi-Status) response for this method. Note, however, that unless explicitly prohibited any 2/3/4/5xx series response code may be used in a 207 (Multi-Status) response. 200 (OK) - The command succeeded. As there can be a mixture of sets and removes in a body, a 201 (Created) seems inappropriate. 403 (Forbidden) - The client, for reasons the server chooses not to specify, cannot alter one of the properties. 409 (Conflict) - The client has provided a value whose semantics are not appropriate for the property. This includes trying to set read- only properties. 423 (Locked) - The specified resource is locked and the client either is not a lock owner or the lock type requires a lock token to be submitted and the client did not submit it. 507 (Insufficient Storage) - The server did not have sufficient space to record the property.
ToP   noToC   RFC2518 - Page 32

8.2.2 Example - PROPPATCH

>>Request PROPPATCH /bar.html HTTP/1.1 Host: www.foo.com Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:propertyupdate xmlns:D="DAV:" xmlns:Z="http://www.w3.com/standards/z39.50/"> <D:set> <D:prop> <Z:authors> <Z:Author>Jim Whitehead</Z:Author> <Z:Author>Roy Fielding</Z:Author> </Z:authors> </D:prop> </D:set> <D:remove> <D:prop><Z:Copyright-Owner/></D:prop> </D:remove> </D:propertyupdate> >>Response HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:" xmlns:Z="http://www.w3.com/standards/z39.50"> <D:response> <D:href>http://www.foo.com/bar.html</D:href> <D:propstat> <D:prop><Z:Authors/></D:prop> <D:status>HTTP/1.1 424 Failed Dependency</D:status> </D:propstat> <D:propstat> <D:prop><Z:Copyright-Owner/></D:prop> <D:status>HTTP/1.1 409 Conflict</D:status> </D:propstat> <D:responsedescription> Copyright Owner can not be deleted or altered.</D:responsedescription> </D:response> </D:multistatus>
ToP   noToC   RFC2518 - Page 33
   In this example, the client requests the server to set the value of
   the http://www.w3.com/standards/z39.50/Authors property, and to
   remove the property http://www.w3.com/standards/z39.50/Copyright-
   Owner.  Since the Copyright-Owner property could not be removed, no
   property modifications occur.  The 424 (Failed Dependency) status
   code for the Authors property indicates this action would have
   succeeded if it were not for the conflict with removing the
   Copyright-Owner property.

8.3 MKCOL Method

The MKCOL method is used to create a new collection. All DAV compliant resources MUST support the MKCOL method.

8.3.1 Request

MKCOL creates a new collection resource at the location specified by the Request-URI. If the resource identified by the Request-URI is non-null then the MKCOL MUST fail. During MKCOL processing, a server MUST make the Request-URI a member of its parent collection, unless the Request-URI is "/". If no such ancestor exists, the method MUST fail. When the MKCOL operation creates a new collection resource, all ancestors MUST already exist, or the method MUST fail with a 409 (Conflict) status code. For example, if a request to create collection /a/b/c/d/ is made, and neither /a/b/ nor /a/b/c/ exists, the request must fail. When MKCOL is invoked without a request body, the newly created collection SHOULD have no members. A MKCOL request message may contain a message body. The behavior of a MKCOL request when the body is present is limited to creating collections, members of a collection, bodies of members and properties on the collections or members. If the server receives a MKCOL request entity type it does not support or understand it MUST respond with a 415 (Unsupported Media Type) status code. The exact behavior of MKCOL for various request media types is undefined in this document, and will be specified in separate documents.

8.3.2 Status Codes

Responses from a MKCOL request MUST NOT be cached as MKCOL has non- idempotent semantics. 201 (Created) - The collection or structured resource was created in its entirety.
ToP   noToC   RFC2518 - Page 34
   403 (Forbidden) - This indicates at least one of two conditions: 1)
   the server does not allow the creation of collections at the given
   location in its namespace, or 2) the parent collection of the
   Request-URI exists but cannot accept members.

   405 (Method Not Allowed) - MKCOL can only be executed on a
   deleted/non-existent resource.

   409 (Conflict) - A collection cannot be made at the Request-URI until
   one or more intermediate collections have been created.

   415 (Unsupported Media Type)- The server does not support the request
   type of the body.

   507 (Insufficient Storage) - The resource does not have sufficient
   space to record the state of the resource after the execution of this
   method.

8.3.3 Example - MKCOL

This example creates a collection called /webdisc/xfiles/ on the server www.server.org. >>Request MKCOL /webdisc/xfiles/ HTTP/1.1 Host: www.server.org >>Response HTTP/1.1 201 Created

8.4 GET, HEAD for Collections

The semantics of GET are unchanged when applied to a collection, since GET is defined as, "retrieve whatever information (in the form of an entity) is identified by the Request-URI" [RFC2068]. GET when applied to a collection may return the contents of an "index.html" resource, a human-readable view of the contents of the collection, or something else altogether. Hence it is possible that the result of a GET on a collection will bear no correlation to the membership of the collection. Similarly, since the definition of HEAD is a GET without a response message body, the semantics of HEAD are unmodified when applied to collection resources.
ToP   noToC   RFC2518 - Page 35

8.5 POST for Collections

Since by definition the actual function performed by POST is determined by the server and often depends on the particular resource, the behavior of POST when applied to collections cannot be meaningfully modified because it is largely undefined. Thus the semantics of POST are unmodified when applied to a collection.

8.6 DELETE

8.6.1 DELETE for Non-Collection Resources

If the DELETE method is issued to a non-collection resource whose URIs are an internal member of one or more collections, then during DELETE processing a server MUST remove any URI for the resource identified by the Request-URI from collections which contain it as a member.

8.6.2 DELETE for Collections

The DELETE method on a collection MUST act as if a "Depth: infinity" header was used on it. A client MUST NOT submit a Depth header with a DELETE on a collection with any value but infinity. DELETE instructs that the collection specified in the Request-URI and all resources identified by its internal member URIs are to be deleted. If any resource identified by a member URI cannot be deleted then all of the member's ancestors MUST NOT be deleted, so as to maintain namespace consistency. Any headers included with DELETE MUST be applied in processing every resource to be deleted. When the DELETE method has completed processing it MUST result in a consistent namespace. If an error occurs with a resource other than the resource identified in the Request-URI then the response MUST be a 207 (Multi-Status). 424 (Failed Dependency) errors SHOULD NOT be in the 207 (Multi- Status). They can be safely left out because the client will know that the ancestors of a resource could not be deleted when the client receives an error for the ancestor's progeny. Additionally 204 (No Content) errors SHOULD NOT be returned in the 207 (Multi-Status). The reason for this prohibition is that 204 (No Content) is the default success code.
ToP   noToC   RFC2518 - Page 36
8.6.2.1 Example - DELETE
>>Request DELETE /container/ HTTP/1.1 Host: www.foo.bar >>Response HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <d:multistatus xmlns:d="DAV:"> <d:response> <d:href>http://www.foo.bar/container/resource3</d:href> <d:status>HTTP/1.1 423 Locked</d:status> </d:response> </d:multistatus> In this example the attempt to delete http://www.foo.bar/container/resource3 failed because it is locked, and no lock token was submitted with the request. Consequently, the attempt to delete http://www.foo.bar/container/ also failed. Thus the client knows that the attempt to delete http://www.foo.bar/container/ must have also failed since the parent can not be deleted unless its child has also been deleted. Even though a Depth header has not been included, a depth of infinity is assumed because the method is on a collection.

8.7 PUT

8.7.1 PUT for Non-Collection Resources

A PUT performed on an existing resource replaces the GET response entity of the resource. Properties defined on the resource may be recomputed during PUT processing but are not otherwise affected. For example, if a server recognizes the content type of the request body, it may be able to automatically extract information that could be profitably exposed as properties. A PUT that would result in the creation of a resource without an appropriately scoped parent collection MUST fail with a 409 (Conflict).
ToP   noToC   RFC2518 - Page 37

8.7.2 PUT for Collections

As defined in the HTTP/1.1 specification [RFC2068], the "PUT method requests that the enclosed entity be stored under the supplied Request-URI." Since submission of an entity representing a collection would implicitly encode creation and deletion of resources, this specification intentionally does not define a transmission format for creating a collection using PUT. Instead, the MKCOL method is defined to create collections. When the PUT operation creates a new non-collection resource all ancestors MUST already exist. If all ancestors do not exist, the method MUST fail with a 409 (Conflict) status code. For example, if resource /a/b/c/d.html is to be created and /a/b/c/ does not exist, then the request must fail.

8.8 COPY Method

The COPY method creates a duplicate of the source resource, identified by the Request-URI, in the destination resource, identified by the URI in the Destination header. The Destination header MUST be present. The exact behavior of the COPY method depends on the type of the source resource. All WebDAV compliant resources MUST support the COPY method. However, support for the COPY method does not guarantee the ability to copy a resource. For example, separate programs may control resources on the same server. As a result, it may not be possible to copy a resource to a location that appears to be on the same server.

8.8.1 COPY for HTTP/1.1 resources

When the source resource is not a collection the result of the COPY method is the creation of a new resource at the destination whose state and behavior match that of the source resource as closely as possible. After a successful COPY invocation, all properties on the source resource MUST be duplicated on the destination resource, subject to modifying headers and XML elements, following the definition for copying properties. Since the environment at the destination may be different than at the source due to factors outside the scope of control of the server, such as the absence of resources required for correct operation, it may not be possible to completely duplicate the behavior of the resource at the destination. Subsequent alterations to the destination resource will not modify the source resource. Subsequent alterations to the source resource will not modify the destination resource.
ToP   noToC   RFC2518 - Page 38

8.8.2. COPY for Properties

The following section defines how properties on a resource are handled during a COPY operation. Live properties SHOULD be duplicated as identically behaving live properties at the destination resource. If a property cannot be copied live, then its value MUST be duplicated, octet-for-octet, in an identically named, dead property on the destination resource subject to the effects of the propertybehavior XML element. The propertybehavior XML element can specify that properties are copied on best effort, that all live properties must be successfully copied or the method must fail, or that a specified list of live properties must be successfully copied or the method must fail. The propertybehavior XML element is defined in section 12.12.

8.8.3 COPY for Collections

The COPY method on a collection without a Depth header MUST act as if a Depth header with value "infinity" was included. A client may submit a Depth header on a COPY on a collection with a value of "0" or "infinity". DAV compliant servers MUST support the "0" and "infinity" Depth header behaviors. A COPY of depth infinity instructs that the collection resource identified by the Request-URI is to be copied to the location identified by the URI in the Destination header, and all its internal member resources are to be copied to a location relative to it, recursively through all levels of the collection hierarchy. A COPY of "Depth: 0" only instructs that the collection and its properties but not resources identified by its internal member URIs, are to be copied. Any headers included with a COPY MUST be applied in processing every resource to be copied with the exception of the Destination header. The Destination header only specifies the destination URI for the Request-URI. When applied to members of the collection identified by the Request-URI the value of Destination is to be modified to reflect the current location in the hierarchy. So, if the Request- URI is /a/ with Host header value http://fun.com/ and the Destination is http://fun.com/b/ then when http://fun.com/a/c/d is processed it must use a Destination of http://fun.com/b/c/d.
ToP   noToC   RFC2518 - Page 39
   When the COPY method has completed processing it MUST have created a
   consistent namespace at the destination (see section 5.1 for the
   definition of namespace consistency).  However, if an error occurs
   while copying an internal collection, the server MUST NOT copy any
   resources identified by members of this collection (i.e., the server
   must skip this subtree), as this would create an inconsistent
   namespace. After detecting an error, the COPY operation SHOULD try to
   finish as much of the original copy operation as possible (i.e., the
   server should still attempt to copy other subtrees and their members,
   that are not descendents of an error-causing collection).  So, for
   example, if an infinite depth copy operation is performed on
   collection /a/, which contains collections /a/b/ and /a/c/, and an
   error occurs copying /a/b/, an attempt should still be made to copy
   /a/c/. Similarly, after encountering an error copying a non-
   collection resource as part of an infinite depth copy, the server
   SHOULD try to finish as much of the original copy operation as
   possible.

   If an error in executing the COPY method occurs with a resource other
   than the resource identified in the Request-URI then the response
   MUST be a 207 (Multi-Status).

   The 424 (Failed Dependency) status code SHOULD NOT be returned in the
   207 (Multi-Status) response from a COPY method.  These responses can
   be safely omitted because the client will know that the progeny of a
   resource could not be copied when the client receives an error for
   the parent.  Additionally 201 (Created)/204 (No Content) status codes
   SHOULD NOT be returned as values in 207 (Multi-Status) responses from
   COPY methods.  They, too, can be safely omitted because they are the
   default success codes.

8.8.4 COPY and the Overwrite Header

If a resource exists at the destination and the Overwrite header is "T" then prior to performing the copy the server MUST perform a DELETE with "Depth: infinity" on the destination resource. If the Overwrite header is set to "F" then the operation will fail.

8.8.5 Status Codes

201 (Created) - The source resource was successfully copied. The copy operation resulted in the creation of a new resource. 204 (No Content) - The source resource was successfully copied to a pre-existing destination resource. 403 (Forbidden) _ The source and destination URIs are the same.
ToP   noToC   RFC2518 - Page 40
   409 (Conflict) _ A resource cannot be created at the destination
   until one or more intermediate collections have been created.

   412 (Precondition Failed) - The server was unable to maintain the
   liveness of the properties listed in the propertybehavior XML element
   or the Overwrite header is "F" and the state of the destination
   resource is non-null.

   423 (Locked) - The destination resource was locked.

   502 (Bad Gateway) - This may occur when the destination is on another
   server and the destination server refuses to accept the resource.

   507 (Insufficient Storage) - The destination resource does not have
   sufficient space to record the state of the resource after the
   execution of this method.

8.8.6 Example - COPY with Overwrite

This example shows resource http://www.ics.uci.edu/~fielding/index.html being copied to the location http://www.ics.uci.edu/users/f/fielding/index.html. The 204 (No Content) status code indicates the existing resource at the destination was overwritten. >>Request COPY /~fielding/index.html HTTP/1.1 Host: www.ics.uci.edu Destination: http://www.ics.uci.edu/users/f/fielding/index.html >>Response HTTP/1.1 204 No Content

8.8.7 Example - COPY with No Overwrite

The following example shows the same copy operation being performed, but with the Overwrite header set to "F." A response of 412 (Precondition Failed) is returned because the destination resource has a non-null state. >>Request COPY /~fielding/index.html HTTP/1.1 Host: www.ics.uci.edu Destination: http://www.ics.uci.edu/users/f/fielding/index.html Overwrite: F
ToP   noToC   RFC2518 - Page 41
   >>Response

   HTTP/1.1 412 Precondition Failed

8.8.8 Example - COPY of a Collection

>>Request COPY /container/ HTTP/1.1 Host: www.foo.bar Destination: http://www.foo.bar/othercontainer/ Depth: infinity Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <d:propertybehavior xmlns:d="DAV:"> <d:keepalive>*</d:keepalive> </d:propertybehavior> >>Response HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <d:multistatus xmlns:d="DAV:"> <d:response> <d:href>http://www.foo.bar/othercontainer/R2/</d:href> <d:status>HTTP/1.1 412 Precondition Failed</d:status> </d:response> </d:multistatus> The Depth header is unnecessary as the default behavior of COPY on a collection is to act as if a "Depth: infinity" header had been submitted. In this example most of the resources, along with the collection, were copied successfully. However the collection R2 failed, most likely due to a problem with maintaining the liveness of properties (this is specified by the propertybehavior XML element). Because there was an error copying R2, none of R2's members were copied. However no errors were listed for those members due to the error minimization rules given in section 8.8.3.
ToP   noToC   RFC2518 - Page 42

8.9 MOVE Method

The MOVE operation on a non-collection resource is the logical equivalent of a copy (COPY), followed by consistency maintenance processing, followed by a delete of the source, where all three actions are performed atomically. The consistency maintenance step allows the server to perform updates caused by the move, such as updating all URIs other than the Request-URI which identify the source resource, to point to the new destination resource. Consequently, the Destination header MUST be present on all MOVE methods and MUST follow all COPY requirements for the COPY part of the MOVE method. All DAV compliant resources MUST support the MOVE method. However, support for the MOVE method does not guarantee the ability to move a resource to a particular destination. For example, separate programs may actually control different sets of resources on the same server. Therefore, it may not be possible to move a resource within a namespace that appears to belong to the same server. If a resource exists at the destination, the destination resource will be DELETEd as a side-effect of the MOVE operation, subject to the restrictions of the Overwrite header.

8.9.1 MOVE for Properties

The behavior of properties on a MOVE, including the effects of the propertybehavior XML element, MUST be the same as specified in section 8.8.2.

8.9.2 MOVE for Collections

A MOVE with "Depth: infinity" instructs that the collection identified by the Request-URI be moved to the URI specified in the Destination header, and all resources identified by its internal member URIs are to be moved to locations relative to it, recursively through all levels of the collection hierarchy. The MOVE method on a collection MUST act as if a "Depth: infinity" header was used on it. A client MUST NOT submit a Depth header on a MOVE on a collection with any value but "infinity". Any headers included with MOVE MUST be applied in processing every resource to be moved with the exception of the Destination header. The behavior of the Destination header is the same as given for COPY on collections.
ToP   noToC   RFC2518 - Page 43
   When the MOVE method has completed processing it MUST have created a
   consistent namespace at both the source and destination (see section
   5.1 for the definition of namespace consistency). However, if an
   error occurs while moving an internal collection, the server MUST NOT
   move any resources identified by members of the failed collection
   (i.e., the server must skip the error-causing subtree), as this would
   create an inconsistent namespace. In this case, after detecting the
   error, the move operation SHOULD try to finish as much of the
   original move as possible (i.e., the server should still attempt to
   move other subtrees and the resources identified by their members,
   that are not descendents of an error-causing collection).  So, for
   example, if an infinite depth move is performed on collection /a/,
   which contains collections /a/b/ and /a/c/, and an error occurs
   moving /a/b/, an attempt should still be made to try moving /a/c/.
   Similarly, after encountering an error moving a non-collection
   resource as part of an infinite depth move, the server SHOULD try to
   finish as much of the original move operation as possible.

   If an error occurs with a resource other than the resource identified
   in the Request-URI then the response MUST be a 207 (Multi-Status).

   The 424 (Failed Dependency) status code SHOULD NOT be returned in the
   207 (Multi-Status) response from a MOVE method.  These errors can be
   safely omitted because the client will know that the progeny of a
   resource could not be moved when the client receives an error for the
   parent.  Additionally 201 (Created)/204 (No Content) responses SHOULD
   NOT be returned as values in 207 (Multi-Status) responses from a
   MOVE.  These responses can be safely omitted because they are the
   default success codes.

8.9.3 MOVE and the Overwrite Header

If a resource exists at the destination and the Overwrite header is "T" then prior to performing the move the server MUST perform a DELETE with "Depth: infinity" on the destination resource. If the Overwrite header is set to "F" then the operation will fail.

8.9.4 Status Codes

201 (Created) - The source resource was successfully moved, and a new resource was created at the destination. 204 (No Content) - The source resource was successfully moved to a pre-existing destination resource. 403 (Forbidden) _ The source and destination URIs are the same.
ToP   noToC   RFC2518 - Page 44
   409 (Conflict) _ A resource cannot be created at the destination
   until one or more intermediate collections have been created.

   412 (Precondition Failed) - The server was unable to maintain the
   liveness of the properties listed in the propertybehavior XML element
   or the Overwrite header is "F" and the state of the destination
   resource is non-null.

   423 (Locked) - The source or the destination resource was locked.

   502 (Bad Gateway) - This may occur when the destination is on another
   server and the destination server refuses to accept the resource.

8.9.5 Example - MOVE of a Non-Collection

This example shows resource http://www.ics.uci.edu/~fielding/index.html being moved to the location http://www.ics.uci.edu/users/f/fielding/index.html. The contents of the destination resource would have been overwritten if the destination resource had been non-null. In this case, since there was nothing at the destination resource, the response code is 201 (Created). >>Request MOVE /~fielding/index.html HTTP/1.1 Host: www.ics.uci.edu Destination: http://www.ics.uci.edu/users/f/fielding/index.html >>Response HTTP/1.1 201 Created Location: http://www.ics.uci.edu/users/f/fielding/index.html

8.9.6 Example - MOVE of a Collection

>>Request MOVE /container/ HTTP/1.1 Host: www.foo.bar Destination: http://www.foo.bar/othercontainer/ Overwrite: F If: (<opaquelocktoken:fe184f2e-6eec-41d0-c765-01adc56e6bb4>) (<opaquelocktoken:e454f3f3-acdc-452a-56c7-00a5c91e4b77>) Content-Type: text/xml; charset="utf-8" Content-Length: xxxx
ToP   noToC   RFC2518 - Page 45
   <?xml version="1.0" encoding="utf-8" ?>
   <d:propertybehavior xmlns:d='DAV:'>
     <d:keepalive>*</d:keepalive>
   </d:propertybehavior>

   >>Response

   HTTP/1.1 207 Multi-Status
   Content-Type: text/xml; charset="utf-8"
   Content-Length: xxxx

   <?xml version="1.0" encoding="utf-8" ?>
   <d:multistatus xmlns:d='DAV:'>
     <d:response>
          <d:href>http://www.foo.bar/othercontainer/C2/</d:href>
          <d:status>HTTP/1.1 423 Locked</d:status>
     </d:response>
   </d:multistatus>

   In this example the client has submitted a number of lock tokens with
   the request.  A lock token will need to be submitted for every
   resource, both source and destination, anywhere in the scope of the
   method, that is locked.  In this case the proper lock token was not
   submitted for the destination http://www.foo.bar/othercontainer/C2/.
   This means that the resource /container/C2/ could not be moved.
   Because there was an error copying /container/C2/, none of
   /container/C2's members were copied.  However no errors were listed
   for those members due to the error minimization rules given in
   section 8.8.3.  User agent authentication has previously occurred via
   a mechanism outside the scope of the HTTP protocol, in an underlying
   transport layer.

8.10 LOCK Method

The following sections describe the LOCK method, which is used to take out a lock of any access type. These sections on the LOCK method describe only those semantics that are specific to the LOCK method and are independent of the access type of the lock being requested. Any resource which supports the LOCK method MUST, at minimum, support the XML request and response formats defined herein.
ToP   noToC   RFC2518 - Page 46

8.10.1 Operation

A LOCK method invocation creates the lock specified by the lockinfo XML element on the Request-URI. Lock method requests SHOULD have a XML request body which contains an owner XML element for this lock request, unless this is a refresh request. The LOCK request may have a Timeout header. Clients MUST assume that locks may arbitrarily disappear at any time, regardless of the value given in the Timeout header. The Timeout header only indicates the behavior of the server if "extraordinary" circumstances do not occur. For example, an administrator may remove a lock at any time or the system may crash in such a way that it loses the record of the lock's existence. The response MUST contain the value of the lockdiscovery property in a prop XML element. In order to indicate the lock token associated with a newly created lock, a Lock-Token response header MUST be included in the response for every successful LOCK request for a new lock. Note that the Lock-Token header would not be returned in the response for a successful refresh LOCK request because a new lock was not created.

8.10.2 The Effect of Locks on Properties and Collections

The scope of a lock is the entire state of the resource, including its body and associated properties. As a result, a lock on a resource MUST also lock the resource's properties. For collections, a lock also affects the ability to add or remove members. The nature of the effect depends upon the type of access control involved.

8.10.3 Locking Replicated Resources

A resource may be made available through more than one URI. However locks apply to resources, not URIs. Therefore a LOCK request on a resource MUST NOT succeed if can not be honored by all the URIs through which the resource is addressable.

8.10.4 Depth and Locking

The Depth header may be used with the LOCK method. Values other than 0 or infinity MUST NOT be used with the Depth header on a LOCK method. All resources that support the LOCK method MUST support the Depth header. A Depth header of value 0 means to just lock the resource specified by the Request-URI.
ToP   noToC   RFC2518 - Page 47
   If the Depth header is set to infinity then the resource specified in
   the Request-URI along with all its internal members, all the way down
   the hierarchy, are to be locked.  A successful result MUST return a
   single lock token which represents all the resources that have been
   locked.  If an UNLOCK is successfully executed on this token, all
   associated resources are unlocked.  If the lock cannot be granted to
   all resources, a 409 (Conflict) status code MUST be returned with a
   response entity body containing a multistatus XML element describing
   which resource(s) prevented the lock from being granted.  Hence,
   partial success is not an option.  Either the entire hierarchy is
   locked or no resources are locked.

   If no Depth header is submitted on a LOCK request then the request
   MUST act as if a "Depth:infinity" had been submitted.

8.10.5 Interaction with other Methods

The interaction of a LOCK with various methods is dependent upon the lock type. However, independent of lock type, a successful DELETE of a resource MUST cause all of its locks to be removed.

8.10.6 Lock Compatibility Table

The table below describes the behavior that occurs when a lock request is made on a resource. Current lock state/ | Shared Lock | Exclusive Lock request | | Lock =====================+=================+============== None | True | True ---------------------+-----------------+-------------- Shared Lock | True | False ---------------------+-----------------+-------------- Exclusive Lock | False | False* ------------------------------------------------------ Legend: True = lock may be granted. False = lock MUST NOT be granted. *=It is illegal for a principal to request the same lock twice. The current lock state of a resource is given in the leftmost column, and lock requests are listed in the first row. The intersection of a row and column gives the result of a lock request. For example, if a shared lock is held on a resource, and an exclusive lock is requested, the table entry is "false", indicating the lock must not be granted.
ToP   noToC   RFC2518 - Page 48

8.10.7 Status Codes

200 (OK) - The lock request succeeded and the value of the lockdiscovery property is included in the body. 412 (Precondition Failed) - The included lock token was not enforceable on this resource or the server could not satisfy the request in the lockinfo XML element. 423 (Locked) - The resource is locked, so the method has been rejected.

8.10.8 Example - Simple Lock Request

>>Request LOCK /workspace/webdav/proposal.doc HTTP/1.1 Host: webdav.sb.aol.com Timeout: Infinite, Second-4100000000 Content-Type: text/xml; charset="utf-8" Content-Length: xxxx Authorization: Digest username="ejw", realm="ejw@webdav.sb.aol.com", nonce="...", uri="/workspace/webdav/proposal.doc", response="...", opaque="..." <?xml version="1.0" encoding="utf-8" ?> <D:lockinfo xmlns:D='DAV:'> <D:lockscope><D:exclusive/></D:lockscope> <D:locktype><D:write/></D:locktype> <D:owner> <D:href>http://www.ics.uci.edu/~ejw/contact.html</D:href> </D:owner> </D:lockinfo> >>Response HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:prop xmlns:D="DAV:"> <D:lockdiscovery> <D:activelock> <D:locktype><D:write/></D:locktype> <D:lockscope><D:exclusive/></D:lockscope> <D:depth>Infinity</D:depth>
ToP   noToC   RFC2518 - Page 49
               <D:owner>
                    <D:href>
                         http://www.ics.uci.edu/~ejw/contact.html
                    </D:href>
               </D:owner>
               <D:timeout>Second-604800</D:timeout>
               <D:locktoken>
                    <D:href>
               opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4
                    </D:href>
               </D:locktoken>
          </D:activelock>
     </D:lockdiscovery>
   </D:prop>

   This example shows the successful creation of an exclusive write lock
   on resource http://webdav.sb.aol.com/workspace/webdav/proposal.doc.
   The resource http://www.ics.uci.edu/~ejw/contact.html contains
   contact information for the owner of the lock.  The server has an
   activity-based timeout policy in place on this resource, which causes
   the lock to automatically be removed after 1 week (604800 seconds).
   Note that the nonce, response, and opaque fields have not been
   calculated in the Authorization request header.

8.10.9 Example - Refreshing a Write Lock

>>Request LOCK /workspace/webdav/proposal.doc HTTP/1.1 Host: webdav.sb.aol.com Timeout: Infinite, Second-4100000000 If: (<opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>) Authorization: Digest username="ejw", realm="ejw@webdav.sb.aol.com", nonce="...", uri="/workspace/webdav/proposal.doc", response="...", opaque="..." >>Response HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:prop xmlns:D="DAV:"> <D:lockdiscovery> <D:activelock> <D:locktype><D:write/></D:locktype>
ToP   noToC   RFC2518 - Page 50
               <D:lockscope><D:exclusive/></D:lockscope>
               <D:depth>Infinity</D:depth>
               <D:owner>
                    <D:href>
                    http://www.ics.uci.edu/~ejw/contact.html
                    </D:href>
               </D:owner>
               <D:timeout>Second-604800</D:timeout>
               <D:locktoken>
                    <D:href>
               opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4
                    </D:href>
               </D:locktoken>
          </D:activelock>
     </D:lockdiscovery>
   </D:prop>

   This request would refresh the lock, resetting any time outs.  Notice
   that the client asked for an infinite time out but the server choose
   to ignore the request. In this example, the nonce, response, and
   opaque fields have not been calculated in the Authorization request
   header.

8.10.10 Example - Multi-Resource Lock Request

>>Request LOCK /webdav/ HTTP/1.1 Host: webdav.sb.aol.com Timeout: Infinite, Second-4100000000 Depth: infinity Content-Type: text/xml; charset="utf-8" Content-Length: xxxx Authorization: Digest username="ejw", realm="ejw@webdav.sb.aol.com", nonce="...", uri="/workspace/webdav/proposal.doc", response="...", opaque="..." <?xml version="1.0" encoding="utf-8" ?> <D:lockinfo xmlns:D="DAV:"> <D:locktype><D:write/></D:locktype> <D:lockscope><D:exclusive/></D:lockscope> <D:owner> <D:href>http://www.ics.uci.edu/~ejw/contact.html</D:href> </D:owner> </D:lockinfo> >>Response
ToP   noToC   RFC2518 - Page 51
   HTTP/1.1 207 Multi-Status
   Content-Type: text/xml; charset="utf-8"
   Content-Length: xxxx

   <?xml version="1.0" encoding="utf-8" ?>
   <D:multistatus xmlns:D="DAV:">
     <D:response>
          <D:href>http://webdav.sb.aol.com/webdav/secret</D:href>
          <D:status>HTTP/1.1 403 Forbidden</D:status>
     </D:response>
     <D:response>
          <D:href>http://webdav.sb.aol.com/webdav/</D:href>
          <D:propstat>
               <D:prop><D:lockdiscovery/></D:prop>
               <D:status>HTTP/1.1 424 Failed Dependency</D:status>
          </D:propstat>
     </D:response>
   </D:multistatus>

   This example shows a request for an exclusive write lock on a
   collection and all its children.  In this request, the client has
   specified that it desires an infinite length lock, if available,
   otherwise a timeout of 4.1 billion seconds, if available. The request
   entity body contains the contact information for the principal taking
   out the lock, in this case a web page URL.

   The error is a 403 (Forbidden) response on the resource
   http://webdav.sb.aol.com/webdav/secret.  Because this resource could
   not be locked, none of the resources were locked.  Note also that the
   lockdiscovery property for the Request-URI has been included as
   required.  In this example the lockdiscovery property is empty which
   means that there are no outstanding locks on the resource.

   In this example, the nonce, response, and opaque fields have not been
   calculated in the Authorization request header.

8.11 UNLOCK Method

The UNLOCK method removes the lock identified by the lock token in the Lock-Token request header from the Request-URI, and all other resources included in the lock. If all resources which have been locked under the submitted lock token can not be unlocked then the UNLOCK request MUST fail. Any DAV compliant resource which supports the LOCK method MUST support the UNLOCK method.
ToP   noToC   RFC2518 - Page 52

8.11.1 Example - UNLOCK

>>Request UNLOCK /workspace/webdav/info.doc HTTP/1.1 Host: webdav.sb.aol.com Lock-Token: <opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7> Authorization: Digest username="ejw", realm="ejw@webdav.sb.aol.com", nonce="...", uri="/workspace/webdav/proposal.doc", response="...", opaque="..." >>Response HTTP/1.1 204 No Content In this example, the lock identified by the lock token "opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is successfully removed from the resource http://webdav.sb.aol.com/workspace/webdav/info.doc. If this lock included more than just one resource, the lock is removed from all resources included in the lock. The 204 (No Content) status code is used instead of 200 (OK) because there is no response entity body. In this example, the nonce, response, and opaque fields have not been calculated in the Authorization request header.


(page 52 continued on part 3)

Next Section