Tech-invite3GPPspaceIETF RFCsSIP
929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 4918

HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)

Pages: 127
Proposed Standard
Errata
Obsoletes:  2518
Updated by:  5689
Part 3 of 5 – Pages 44 to 77
First   Prev   Next

Top   ToC   RFC4918 - Page 44   prevText

9.2. PROPPATCH Method

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. 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. Servers MUST process PROPPATCH instructions in document order (an exception to the normal rule that ordering is irrelevant). 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 Sections 14.23 and 14.26. If a server attempts to make any of the property changes in a PROPPATCH request (i.e., the request is not rejected for high-level errors before processing the body), the response MUST be a Multi- Status response as described in Section 9.2.1. This method is idempotent, but not safe (see Section 9.1 of [RFC2616]). Responses to this method MUST NOT be cached.

9.2.1. Status Codes for Use in 'propstat' Element

In PROPPATCH responses, information about individual properties is returned inside 'propstat' elements (see Section 14.22), each containing an individual 'status' element containing information about the properties appearing in it. The list below summarizes the most common status codes used inside 'propstat'; however, clients should be prepared to handle other 2/3/4/5xx series status codes as well.
Top   ToC   RFC4918 - Page 45
   200 (OK) - The property set or change succeeded.  Note that if this
   appears for one property, it appears for every property in the
   response, due to the atomicity of PROPPATCH.

   403 (Forbidden) - The client, for reasons the server chooses not to
   specify, cannot alter one of the properties.

   403 (Forbidden): The client has attempted to set a protected
   property, such as DAV:getetag.  If returning this error, the server
   SHOULD use the precondition code 'cannot-modify-protected-property'
   inside the response body.

   409 (Conflict) - The client has provided a value whose semantics are
   not appropriate for the property.

   424 (Failed Dependency) - The property change could not be made
   because of another property change that failed.

   507 (Insufficient Storage) - The server did not have sufficient space
   to record the property.

9.2.2. Example - PROPPATCH

>>Request PROPPATCH /bar.html HTTP/1.1 Host: www.example.com Content-Type: application/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:propertyupdate xmlns:D="DAV:" xmlns:Z="http://ns.example.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>
Top   ToC   RFC4918 - Page 46
   >>Response

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

     <?xml version="1.0" encoding="utf-8" ?>
     <D:multistatus xmlns:D="DAV:"
             xmlns:Z="http://ns.example.com/standards/z39.50/">
       <D:response>
         <D:href>http://www.example.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 cannot be deleted or
           altered.</D:responsedescription>
       </D:response>
     </D:multistatus>

   In this example, the client requests the server to set the value of
   the "Authors" property in the
   "http://ns.example.com/standards/z39.50/" namespace, and to remove
   the property "Copyright-Owner" in the same namespace.  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.

9.3. MKCOL Method

MKCOL creates a new collection resource at the location specified by the Request-URI. If the Request-URI is already mapped to a resource, then the MKCOL MUST fail. During MKCOL processing, a server MUST make the Request-URI an internal 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 /a/b/c/ does not exist, the request must fail. When MKCOL is invoked without a request body, the newly created collection SHOULD have no members.
Top   ToC   RFC4918 - Page 47
   A MKCOL request message may contain a message body.  The precise
   behavior of a MKCOL request when the body is present is undefined,
   but 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.  If the server decides to reject the request based on
   the presence of an entity or the type of an entity, it should use the
   415 (Unsupported Media Type) status code.

   This method is idempotent, but not safe (see Section 9.1 of
   [RFC2616]).  Responses to this method MUST NOT be cached.

9.3.1. MKCOL Status Codes

In addition to the general status codes possible, the following status codes have specific applicability to MKCOL: 201 (Created) - The collection was created. 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 URL 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 an unmapped URL. 409 (Conflict) - A collection cannot be made at the Request-URI until one or more intermediate collections have been created. The server MUST NOT create those intermediate collections automatically. 415 (Unsupported Media Type) - The server does not support the request body type (although bodies are legal on MKCOL requests, since this specification doesn't define any, the server is likely not to support any given body type). 507 (Insufficient Storage) - The resource does not have sufficient space to record the state of the resource after the execution of this method.

9.3.2. Example - MKCOL

This example creates a collection called /webdisc/xfiles/ on the server www.example.com.
Top   ToC   RFC4918 - Page 48
   >>Request

     MKCOL /webdisc/xfiles/ HTTP/1.1
     Host: www.example.com


   >>Response

     HTTP/1.1 201 Created

9.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" [RFC2616]. 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.

9.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.

9.6. DELETE Requirements

DELETE is defined in [RFC2616], Section 9.7, to "delete the resource identified by the Request-URI". However, WebDAV changes some DELETE handling requirements. A server processing a successful DELETE request: MUST destroy locks rooted on the deleted resource MUST remove the mapping from the Request-URI to any resource. Thus, after a successful DELETE operation (and in the absence of other actions), a subsequent GET/HEAD/PROPFIND request to the target Request-URI MUST return 404 (Not Found).
Top   ToC   RFC4918 - Page 49

9.6.1. 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 URLs are to be deleted. If any resource identified by a member URL cannot be deleted, then all of the member's ancestors MUST NOT be deleted, so as to maintain URL 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 URL namespace. If an error occurs deleting a member resource (a resource other than the resource identified in the Request-URI), then the response can be a 207 (Multi-Status). Multi-Status is used here to indicate which internal resources could NOT be deleted, including an error code, which should help the client understand which resources caused the failure. For example, the Multi-Status body could include a response with status 423 (Locked) if an internal resource was locked. The server MAY return a 4xx status response, rather than a 207, if the request failed completely. 424 (Failed Dependency) status codes SHOULD NOT be in the 207 (Multi- Status) response for DELETE. 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.

9.6.2. Example - DELETE

>>Request DELETE /container/ HTTP/1.1 Host: www.example.com
Top   ToC   RFC4918 - Page 50
   >>Response

     HTTP/1.1 207 Multi-Status
     Content-Type: application/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.example.com/container/resource3</d:href>
         <d:status>HTTP/1.1 423 Locked</d:status>
         <d:error><d:lock-token-submitted/></d:error>
       </d:response>
     </d:multistatus>

   In this example, the attempt to delete
   http://www.example.com/container/resource3 failed because it is
   locked, and no lock token was submitted with the request.
   Consequently, the attempt to delete http://www.example.com/container/
   also failed.  Thus, the client knows that the attempt to delete
   http://www.example.com/container/ must have also failed since the
   parent cannot 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.

9.7. PUT Requirements

9.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). A PUT request allows a client to indicate what media type an entity body has, and whether it should change if overwritten. Thus, a client SHOULD provide a Content-Type for a new resource if any is known. If the client does not provide a Content-Type for a new resource, the server MAY create a resource with no Content-Type assigned, or it MAY attempt to assign a Content-Type.
Top   ToC   RFC4918 - Page 51
   Note that although a recipient ought generally to treat metadata
   supplied with an HTTP request as authoritative, in practice there's
   no guarantee that a server will accept client-supplied metadata
   (e.g., any request header beginning with "Content-").  Many servers
   do not allow configuring the Content-Type on a per-resource basis in
   the first place.  Thus, clients can't always rely on the ability to
   directly influence the content type by including a Content-Type
   request header.

9.7.2. PUT for Collections

This specification does not define the behavior of the PUT method for existing collections. A PUT request to an existing collection MAY be treated as an error (405 Method Not Allowed). The MKCOL method is defined to create collections.

9.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. This method is idempotent, but not safe (see Section 9.1 of [RFC2616]). Responses to this method MUST NOT be cached.

9.8.1. COPY for Non-collection 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. 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   ToC   RFC4918 - Page 52

9.8.2. COPY for Properties

After a successful COPY invocation, all dead properties on the source resource SHOULD be duplicated on the destination resource. Live properties described in this document SHOULD be duplicated as identically behaving live properties at the destination resource, but not necessarily with the same values. Servers SHOULD NOT convert live properties into dead properties on the destination resource, because clients may then draw incorrect conclusions about the state or functionality of a resource. Note that some live properties are defined such that the absence of the property has a specific meaning (e.g., a flag with one meaning if present, and the opposite if absent), and in these cases, a successful COPY might result in the property being reported as "Not Found" in subsequent requests. When the destination is an unmapped URL, a COPY operation creates a new resource much like a PUT operation does. Live properties that are related to resource creation (such as DAV:creationdate) should have their values set accordingly.

9.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". Servers MUST support the "0" and "infinity" Depth header behaviors on WebDAV-compliant resources. An infinite-depth COPY 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. Note that an infinite-depth COPY of /A/ into /A/B/ could lead to infinite recursion if not handled correctly. A COPY of "Depth: 0" only instructs that the collection and its properties, but not resources identified by its internal member URLs, 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://example.com/ and the
Top   ToC   RFC4918 - Page 53
   Destination is http://example.com/b/, then when
   http://example.com/a/c/d is processed, it must use a Destination of
   http://example.com/b/c/d.

   When the COPY method has completed processing, it MUST have created a
   consistent URL 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 descendants 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), and the URL of the resource causing the
   failure MUST appear with the specific error.

   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.

9.8.4. COPY and Overwriting Destination Resources

If a COPY request has an Overwrite header with a value of "F", and a resource exists at the Destination URL, the server MUST fail the request. When a server executes a COPY request and overwrites a destination resource, the exact behavior MAY depend on many factors, including WebDAV extension capabilities (see particularly [RFC3253]). For
Top   ToC   RFC4918 - Page 54
   example, when an ordinary resource is overwritten, the server could
   delete the target resource before doing the copy, or could do an in-
   place overwrite to preserve live properties.

   When a collection is overwritten, the membership of the destination
   collection after the successful COPY request MUST be the same
   membership as the source collection immediately before the COPY.
   Thus, merging the membership of the source and destination
   collections together in the destination is not a compliant behavior.

   In general, if clients require the state of the destination URL to be
   wiped out prior to a COPY (e.g., to force live properties to be
   reset), then the client could send a DELETE to the destination before
   the COPY request to ensure this reset.

9.8.5. Status Codes

In addition to the general status codes possible, the following status codes have specific applicability to COPY: 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 preexisting destination resource. 207 (Multi-Status) - Multiple resources were to be affected by the COPY, but errors on some of them prevented the operation from taking place. Specific error messages, together with the most appropriate of the source and destination URLs, appear in the body of the multi- status response. For example, if a destination resource was locked and could not be overwritten, then the destination resource URL appears with the 423 (Locked) status. 403 (Forbidden) - The operation is forbidden. A special case for COPY could be that the source and destination resources are the same resource. 409 (Conflict) - A resource cannot be created at the destination until one or more intermediate collections have been created. The server MUST NOT create those intermediate collections automatically. 412 (Precondition Failed) - A precondition header check failed, e.g., the Overwrite header is "F" and the destination URL is already mapped to a resource.
Top   ToC   RFC4918 - Page 55
   423 (Locked) - The destination resource, or resource within the
   destination collection, was locked.  This response SHOULD contain the
   'lock-token-submitted' precondition element.

   502 (Bad Gateway) - This may occur when the destination is on another
   server, repository, or URL namespace.  Either the source namespace
   does not support copying to the destination namespace, or the
   destination namespace refuses to accept the resource.  The client may
   wish to try GET/PUT and PROPFIND/PROPPATCH instead.

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

9.8.6. Example - COPY with Overwrite

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

9.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 URL is already mapped to a resource. >>Request COPY /~fielding/index.html HTTP/1.1 Host: www.example.com Destination: http://www.example.com/users/f/fielding/index.html Overwrite: F
Top   ToC   RFC4918 - Page 56
   >>Response

     HTTP/1.1 412 Precondition Failed

9.8.8. Example - COPY of a Collection

>>Request COPY /container/ HTTP/1.1 Host: www.example.com Destination: http://www.example.com/othercontainer/ Depth: infinity >>Response HTTP/1.1 207 Multi-Status Content-Type: application/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.example.com/othercontainer/R2/</d:href> <d:status>HTTP/1.1 423 Locked</d:status> <d:error><d:lock-token-submitted/></d:error> </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 because the destination R2 is locked. 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.

9.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 in a single operation. The consistency maintenance step allows the server to perform updates caused by the move, such as updating all URLs, other than the Request-URI that identifies the source resource, to point to the new destination resource.
Top   ToC   RFC4918 - Page 57
   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 WebDAV-compliant resources MUST support the MOVE method.

   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.

   This method is idempotent, but not safe (see Section 9.1 of
   [RFC2616]).  Responses to this method MUST NOT be cached.

9.9.1. MOVE for Properties

Live properties described in this document SHOULD be moved along with the resource, such that the resource has identically behaving live properties at the destination resource, but not necessarily with the same values. Note that some live properties are defined such that the absence of the property has a specific meaning (e.g., a flag with one meaning if present, and the opposite if absent), and in these cases, a successful MOVE might result in the property being reported as "Not Found" in subsequent requests. If the live properties will not work the same way at the destination, the server MAY fail the request. MOVE is frequently used by clients to rename a file without changing its parent collection, so it's not appropriate to reset all live properties that are set at resource creation. For example, the DAV: creationdate property value SHOULD remain the same after a MOVE. Dead properties MUST be moved along with the resource.

9.9.2. MOVE for Collections

A MOVE with "Depth: infinity" instructs that the collection identified by the Request-URI be moved to the address specified in the Destination header, and all resources identified by its internal member URLs 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".
Top   ToC   RFC4918 - Page 58
   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.

   When the MOVE method has completed processing, it MUST have created a
   consistent URL 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 descendants 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),
   and the errored resource's URL MUST appear with the specific error.

   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.

9.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.
Top   ToC   RFC4918 - Page 59

9.9.4. Status Codes

In addition to the general status codes possible, the following status codes have specific applicability to MOVE: 201 (Created) - The source resource was successfully moved, and a new URL mapping was created at the destination. 204 (No Content) - The source resource was successfully moved to a URL that was already mapped. 207 (Multi-Status) - Multiple resources were to be affected by the MOVE, but errors on some of them prevented the operation from taking place. Specific error messages, together with the most appropriate of the source and destination URLs, appear in the body of the multi- status response. For example, if a source resource was locked and could not be moved, then the source resource URL appears with the 423 (Locked) status. 403 (Forbidden) - Among many possible reasons for forbidding a MOVE operation, this status code is recommended for use when the source and destination resources are the same. 409 (Conflict) - A resource cannot be created at the destination until one or more intermediate collections have been created. The server MUST NOT create those intermediate collections automatically. Or, the server was unable to preserve the behavior of the live properties and still move the resource to the destination (see 'preserved-live-properties' postcondition). 412 (Precondition Failed) - A condition header failed. Specific to MOVE, this could mean that the Overwrite header is "F" and the destination URL is already mapped to a resource. 423 (Locked) - The source or the destination resource, the source or destination resource parent, or some resource within the source or destination collection, was locked. This response SHOULD contain the 'lock-token-submitted' precondition element. 502 (Bad Gateway) - This may occur when the destination is on another server and the destination server refuses to accept the resource. This could also occur when the destination is on another sub-section of the same server namespace.
Top   ToC   RFC4918 - Page 60

9.9.5. Example - MOVE of a Non-Collection

This example shows resource http://www.example.com/~fielding/index.html being moved to the location http://www.example.com/users/f/fielding/index.html. The contents of the destination resource would have been overwritten if the destination URL was already mapped to a resource. 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.example.com Destination: http://www.example/users/f/fielding/index.html >>Response HTTP/1.1 201 Created Location: http://www.example.com/users/f/fielding/index.html

9.9.6. Example - MOVE of a Collection

>>Request MOVE /container/ HTTP/1.1 Host: www.example.com Destination: http://www.example.com/othercontainer/ Overwrite: F If: (<urn:uuid:fe184f2e-6eec-41d0-c765-01adc56e6bb4>) (<urn:uuid:e454f3f3-acdc-452a-56c7-00a5c91e4b77>) >>Response HTTP/1.1 207 Multi-Status Content-Type: application/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.example.com/othercontainer/C2/</d:href> <d:status>HTTP/1.1 423 Locked</d:status> <d:error><d:lock-token-submitted/></d:error> </d:response> </d:multistatus>
Top   ToC   RFC4918 - Page 61
   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.example.com/othercontainer/C2/.  This means that the
   resource /container/C2/ could not be moved.  Because there was an
   error moving /container/C2/, none of /container/C2's members were
   moved.  However, no errors were listed for those members due to the
   error minimization rules.  User agent authentication has previously
   occurred via a mechanism outside the scope of the HTTP protocol, in
   an underlying transport layer.

9.10. LOCK Method

The following sections describe the LOCK method, which is used to take out a lock of any access type and to refresh an existing lock. 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 that supports the LOCK method MUST, at minimum, support the XML request and response formats defined herein. This method is neither idempotent nor safe (see Section 9.1 of [RFC2616]). Responses to this method MUST NOT be cached.

9.10.1. Creating a Lock on an Existing Resource

A LOCK request to an existing resource will create a lock on the resource identified by the Request-URI, provided the resource is not already locked with a conflicting lock. The resource identified in the Request-URI becomes the root of the lock. LOCK method requests to create a new lock MUST have an XML request body. The server MUST preserve the information provided by the client in the 'owner' element in the LOCK request. The LOCK request MAY have a Timeout header. When a new lock is created, the LOCK response: o MUST contain a body with the value of the DAV:lockdiscovery property in a prop XML element. This MUST contain the full information about the lock just granted, while information about other (shared) locks is OPTIONAL. o MUST include the Lock-Token response header with the token associated with the new lock.
Top   ToC   RFC4918 - Page 62

9.10.2. Refreshing Locks

A lock is refreshed by sending a LOCK request to the URL of a resource within the scope of the lock. This request MUST NOT have a body and it MUST specify which lock to refresh by using the 'If' header with a single lock token (only one lock may be refreshed at a time). The request MAY contain a Timeout header, which a server MAY accept to change the duration remaining on the lock to the new value. A server MUST ignore the Depth header on a LOCK refresh. If the resource has other (shared) locks, those locks are unaffected by a lock refresh. Additionally, those locks do not prevent the named lock from being refreshed. The Lock-Token header is not returned in the response for a successful refresh LOCK request, but the LOCK response body MUST contain the new value for the DAV:lockdiscovery property.

9.10.3. 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. If the Depth header is set to infinity, then the resource specified in the Request-URI along with all its members, all the way down the hierarchy, are to be locked. A successful result MUST return a single lock token. Similarly, if an UNLOCK is successfully executed on this token, all associated resources are unlocked. Hence, partial success is not an option for LOCK or UNLOCK. Either the entire hierarchy is locked or no resources are locked. If the lock cannot be granted to all resources, the server MUST return a Multi-Status response with a 'response' element for at least one resource that prevented the lock from being granted, along with a suitable status code for that failure (e.g., 403 (Forbidden) or 423 (Locked)). Additionally, if the resource causing the failure was not the resource requested, then the server SHOULD include a 'response' element for the Request-URI as well, with a 'status' element containing 424 Failed Dependency. If no Depth header is submitted on a LOCK request, then the request MUST act as if a "Depth:infinity" had been submitted.
Top   ToC   RFC4918 - Page 63

9.10.4. Locking Unmapped URLs

A successful LOCK method MUST result in the creation of an empty resource that is locked (and that is not a collection) when a resource did not previously exist at that URL. Later on, the lock may go away but the empty resource remains. Empty resources MUST then appear in PROPFIND responses including that URL in the response scope. A server MUST respond successfully to a GET request to an empty resource, either by using a 204 No Content response, or by using 200 OK with a Content-Length header indicating zero length

9.10.5. Lock Compatibility Table

The table below describes the behavior that occurs when a lock request is made on a resource. +--------------------------+----------------+-------------------+ | Current State | Shared Lock OK | Exclusive Lock OK | +--------------------------+----------------+-------------------+ | 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 that the lock must not be granted.

9.10.6. LOCK Responses

In addition to the general status codes possible, the following status codes have specific applicability to LOCK: 200 (OK) - The LOCK request succeeded and the value of the DAV: lockdiscovery property is included in the response body. 201 (Created) - The LOCK request was to an unmapped URL, the request succeeded and resulted in the creation of a new resource, and the value of the DAV:lockdiscovery property is included in the response body.
Top   ToC   RFC4918 - Page 64
   409 (Conflict) - A resource cannot be created at the destination
   until one or more intermediate collections have been created.  The
   server MUST NOT create those intermediate collections automatically.

   423 (Locked), potentially with 'no-conflicting-lock' precondition
   code - There is already a lock on the resource that is not compatible
   with the requested lock (see lock compatibility table above).

   412 (Precondition Failed), with 'lock-token-matches-request-uri'
   precondition code - The LOCK request was made with an If header,
   indicating that the client wishes to refresh the given lock.
   However, the Request-URI did not fall within the scope of the lock
   identified by the token.  The lock may have a scope that does not
   include the Request-URI, or the lock could have disappeared, or the
   token may be invalid.

9.10.7. Example - Simple Lock Request

>>Request LOCK /workspace/webdav/proposal.doc HTTP/1.1 Host: example.com Timeout: Infinite, Second-4100000000 Content-Type: application/xml; charset="utf-8" Content-Length: xxxx Authorization: Digest username="ejw", realm="ejw@example.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://example.org/~ejw/contact.html</D:href> </D:owner> </D:lockinfo> >>Response HTTP/1.1 200 OK Lock-Token: <urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4> Content-Type: application/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:prop xmlns:D="DAV:">
Top   ToC   RFC4918 - Page 65
       <D:lockdiscovery>
         <D:activelock>
           <D:locktype><D:write/></D:locktype>
           <D:lockscope><D:exclusive/></D:lockscope>
           <D:depth>infinity</D:depth>
           <D:owner>
             <D:href>http://example.org/~ejw/contact.html</D:href>
           </D:owner>
           <D:timeout>Second-604800</D:timeout>
           <D:locktoken>
             <D:href
             >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href>
           </D:locktoken>
           <D:lockroot>
             <D:href
             >http://example.com/workspace/webdav/proposal.doc</D:href>
           </D:lockroot>
         </D:activelock>
       </D:lockdiscovery>
     </D:prop>


   This example shows the successful creation of an exclusive write lock
   on resource http://example.com/workspace/webdav/proposal.doc.  The
   resource http://example.org/~ejw/contact.html contains contact
   information for the creator 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.

9.10.8. Example - Refreshing a Write Lock

>>Request LOCK /workspace/webdav/proposal.doc HTTP/1.1 Host: example.com Timeout: Infinite, Second-4100000000 If: (<urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>) Authorization: Digest username="ejw", realm="ejw@example.com", nonce="...", uri="/workspace/webdav/proposal.doc", response="...", opaque="..."
Top   ToC   RFC4918 - Page 66
   >>Response

     HTTP/1.1 200 OK
     Content-Type: application/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>
           <D:owner>
             <D:href>http://example.org/~ejw/contact.html</D:href>
           </D:owner>
           <D:timeout>Second-604800</D:timeout>
           <D:locktoken>
             <D:href
             >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href>
           </D:locktoken>
           <D:lockroot>
             <D:href
             >http://example.com/workspace/webdav/proposal.doc</D:href>
           </D:lockroot>
         </D:activelock>
       </D:lockdiscovery>
     </D:prop>


   This request would refresh the lock, attempting to reset the timeout
   to the new value specified in the timeout header.  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.

9.10.9. Example - Multi-Resource Lock Request

>>Request LOCK /webdav/ HTTP/1.1 Host: example.com Timeout: Infinite, Second-4100000000 Depth: infinity Content-Type: application/xml; charset="utf-8" Content-Length: xxxx Authorization: Digest username="ejw", realm="ejw@example.com", nonce="...",
Top   ToC   RFC4918 - Page 67
       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://example.org/~ejw/contact.html</D:href>
       </D:owner>
     </D:lockinfo>

   >>Response

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

     <?xml version="1.0" encoding="utf-8" ?>
     <D:multistatus xmlns:D="DAV:">
       <D:response>
         <D:href>http://example.com/webdav/secret</D:href>
         <D:status>HTTP/1.1 403 Forbidden</D:status>
       </D:response>
       <D:response>
         <D:href>http://example.com/webdav/</D:href>
         <D:status>HTTP/1.1 424 Failed Dependency</D:status>
       </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://example.com/webdav/secret.  Because this resource could not be
   locked, none of the resources were locked.  Note also that the a
   'response' element for the Request-URI itself has been included as
   required.

   In this example, the nonce, response, and opaque fields have not been
   calculated in the Authorization request header.
Top   ToC   RFC4918 - Page 68

9.11. UNLOCK Method

The UNLOCK method removes the lock identified by the lock token in the Lock-Token request header. The Request-URI MUST identify a resource within the scope of the lock. Note that use of the Lock-Token header to provide the lock token is not consistent with other state-changing methods, which all require an If header with the lock token. Thus, the If header is not needed to provide the lock token. Naturally, when the If header is present, it has its normal meaning as a conditional header. For a successful response to this method, the server MUST delete the lock entirely. If all resources that have been locked under the submitted lock token cannot be unlocked, then the UNLOCK request MUST fail. A successful response to an UNLOCK method does not mean that the resource is necessarily unlocked. It means that the specific lock corresponding to the specified token no longer exists. Any DAV-compliant resource that supports the LOCK method MUST support the UNLOCK method. This method is idempotent, but not safe (see Section 9.1 of [RFC2616]). Responses to this method MUST NOT be cached.

9.11.1. Status Codes

In addition to the general status codes possible, the following status codes have specific applicability to UNLOCK: 204 (No Content) - Normal success response (rather than 200 OK, since 200 OK would imply a response body, and an UNLOCK success response does not normally contain a body). 400 (Bad Request) - No lock token was provided. 403 (Forbidden) - The currently authenticated principal does not have permission to remove the lock. 409 (Conflict), with 'lock-token-matches-request-uri' precondition - The resource was not locked, or the request was made to a Request-URI that was not within the scope of the lock.
Top   ToC   RFC4918 - Page 69

9.11.2. Example - UNLOCK

>>Request UNLOCK /workspace/webdav/info.doc HTTP/1.1 Host: example.com Lock-Token: <urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7> Authorization: Digest username="ejw" realm="ejw@example.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 "urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is successfully removed from the resource http://example.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. In this example, the nonce, response, and opaque fields have not been calculated in the Authorization request header.

10. HTTP Headers for Distributed Authoring

All DAV headers follow the same basic formatting rules as HTTP headers. This includes rules like line continuation and how to combine (or separate) multiple instances of the same header using commas. WebDAV adds two new conditional headers to the set defined in HTTP: the If and Overwrite headers.

10.1. DAV Header

DAV = "DAV" ":" #( compliance-class ) compliance-class = ( "1" | "2" | "3" | extend ) extend = Coded-URL | token ; token is defined in RFC 2616, Section 2.2 Coded-URL = "<" absolute-URI ">" ; No linear whitespace (LWS) allowed in Coded-URL ; absolute-URI defined in RFC 3986, Section 4.3
Top   ToC   RFC4918 - Page 70
   This general-header appearing in the response indicates that the
   resource supports the DAV schema and protocol as specified.  All DAV-
   compliant resources MUST return the DAV header with compliance-class
   "1" on all OPTIONS responses.  In cases where WebDAV is only
   supported in part of the server namespace, an OPTIONS request to non-
   WebDAV resources (including "/") SHOULD NOT advertise WebDAV support.

   The value is a comma-separated list of all compliance class
   identifiers that the resource supports.  Class identifiers may be
   Coded-URLs or tokens (as defined by [RFC2616]).  Identifiers can
   appear in any order.  Identifiers that are standardized through the
   IETF RFC process are tokens, but other identifiers SHOULD be Coded-
   URLs to encourage uniqueness.

   A resource must show class 1 compliance if it shows class 2 or 3
   compliance.  In general, support for one compliance class does not
   entail support for any other, and in particular, support for
   compliance class 3 does not require support for compliance class 2.
   Please refer to Section 18 for more details on compliance classes
   defined in this specification.

   Note that many WebDAV servers do not advertise WebDAV support in
   response to "OPTIONS *".

   As a request header, this header allows the client to advertise
   compliance with named features when the server needs that
   information.  Clients SHOULD NOT send this header unless a standards
   track specification requires it.  Any extension that makes use of
   this as a request header will need to carefully consider caching
   implications.

10.2. Depth Header

Depth = "Depth" ":" ("0" | "1" | "infinity") The Depth request header is used with methods executed on resources that could potentially have internal members to indicate whether the method is to be applied only to the resource ("Depth: 0"), to the resource and its internal members only ("Depth: 1"), or the resource and all its members ("Depth: infinity"). The Depth header is only supported if a method's definition explicitly provides for such support. The following rules are the default behavior for any method that supports the Depth header. A method may override these defaults by defining different behavior in its definition.
Top   ToC   RFC4918 - Page 71
   Methods that support the Depth header may choose not to support all
   of the header's values and may define, on a case-by-case basis, the
   behavior of the method if a Depth header is not present.  For
   example, the MOVE method only supports "Depth: infinity", and if a
   Depth header is not present, it will act as if a "Depth: infinity"
   header had been applied.

   Clients MUST NOT rely upon methods executing on members of their
   hierarchies in any particular order or on the execution being atomic
   unless the particular method explicitly provides such guarantees.

   Upon execution, a method with a Depth header will perform as much of
   its assigned task as possible and then return a response specifying
   what it was able to accomplish and what it failed to do.

   So, for example, an attempt to COPY a hierarchy may result in some of
   the members being copied and some not.

   By default, the Depth header does not interact with other headers.
   That is, each header on a request with a Depth header MUST be applied
   only to the Request-URI if it applies to any resource, unless
   specific Depth behavior is defined for that header.

   If a source or destination resource within the scope of the Depth
   header is locked in such a way as to prevent the successful execution
   of the method, then the lock token for that resource MUST be
   submitted with the request in the If request header.

   The Depth header only specifies the behavior of the method with
   regards to internal members.  If a resource does not have internal
   members, then the Depth header MUST be ignored.

10.3. Destination Header

The Destination request header specifies the URI that identifies a destination resource for methods such as COPY and MOVE, which take two URIs as parameters. Destination = "Destination" ":" Simple-ref If the Destination value is an absolute-URI (Section 4.3 of [RFC3986]), it may name a different server (or different port or scheme). If the source server cannot attempt a copy to the remote server, it MUST fail the request. Note that copying and moving resources to remote servers is not fully defined in this specification (e.g., specific error conditions).
Top   ToC   RFC4918 - Page 72
   If the Destination value is too long or otherwise unacceptable, the
   server SHOULD return 400 (Bad Request), ideally with helpful
   information in an error body.

10.4. If Header

The If request header is intended to have similar functionality to the If-Match header defined in Section 14.24 of [RFC2616]. However, the If header handles any state token as well as ETags. A typical example of a state token is a lock token, and lock tokens are the only state tokens defined in this specification.

10.4.1. Purpose

The If header has two distinct purposes: o The first purpose is to make a request conditional by supplying a series of state lists with conditions that match tokens and ETags to a specific resource. If this header is evaluated and all state lists fail, then the request MUST fail with a 412 (Precondition Failed) status. On the other hand, the request can succeed only if one of the described state lists succeeds. The success criteria for state lists and matching functions are defined in Sections 10.4.3 and 10.4.4. o Additionally, the mere fact that a state token appears in an If header means that it has been "submitted" with the request. In general, this is used to indicate that the client has knowledge of that state token. The semantics for submitting a state token depend on its type (for lock tokens, please refer to Section 6). Note that these two purposes need to be treated distinctly: a state token counts as being submitted independently of whether the server actually has evaluated the state list it appears in, and also independently of whether or not the condition it expressed was found to be true.

10.4.2. Syntax

If = "If" ":" ( 1*No-tag-list | 1*Tagged-list ) No-tag-list = List Tagged-list = Resource-Tag 1*List List = "(" 1*Condition ")" Condition = ["Not"] (State-token | "[" entity-tag "]") ; entity-tag: see Section 3.11 of [RFC2616] ; No LWS allowed between "[", entity-tag and "]"
Top   ToC   RFC4918 - Page 73
     State-token = Coded-URL

     Resource-Tag = "<" Simple-ref ">"
     ; Simple-ref: see Section 8.3
     ; No LWS allowed in Resource-Tag

   The syntax distinguishes between untagged lists ("No-tag-list") and
   tagged lists ("Tagged-list").  Untagged lists apply to the resource
   identified by the Request-URI, while tagged lists apply to the
   resource identified by the preceding Resource-Tag.

   A Resource-Tag applies to all subsequent Lists, up to the next
   Resource-Tag.

   Note that the two list types cannot be mixed within an If header.
   This is not a functional restriction because the No-tag-list syntax
   is just a shorthand notation for a Tagged-list production with a
   Resource-Tag referring to the Request-URI.

   Each List consists of one or more Conditions.  Each Condition is
   defined in terms of an entity-tag or state-token, potentially negated
   by the prefix "Not".

   Note that the If header syntax does not allow multiple instances of
   If headers in a single request.  However, the HTTP header syntax
   allows extending single header values across multiple lines, by
   inserting a line break followed by whitespace (see [RFC2616], Section
   4.2).

10.4.3. List Evaluation

A Condition that consists of a single entity-tag or state-token evaluates to true if the resource matches the described state (where the individual matching functions are defined below in Section 10.4.4). Prefixing it with "Not" reverses the result of the evaluation (thus, the "Not" applies only to the subsequent entity-tag or state-token). Each List production describes a series of conditions. The whole list evaluates to true if and only if each condition evaluates to true (that is, the list represents a logical conjunction of Conditions). Each No-tag-list and Tagged-list production may contain one or more Lists. They evaluate to true if and only if any of the contained lists evaluates to true (that is, if there's more than one List, that List sequence represents a logical disjunction of the Lists).
Top   ToC   RFC4918 - Page 74
   Finally, the whole If header evaluates to true if and only if at
   least one of the No-tag-list or Tagged-list productions evaluates to
   true.  If the header evaluates to false, the server MUST reject the
   request with a 412 (Precondition Failed) status.  Otherwise,
   execution of the request can proceed as if the header wasn't present.

10.4.4. Matching State Tokens and ETags

When performing If header processing, the definition of a matching state token or entity tag is as follows: Identifying a resource: The resource is identified by the URI along with the token, in tagged list production, or by the Request-URI in untagged list production. Matching entity tag: Where the entity tag matches an entity tag associated with the identified resource. Servers MUST use either the weak or the strong comparison function defined in Section 13.3.3 of [RFC2616]. Matching state token: Where there is an exact match between the state token in the If header and any state token on the identified resource. A lock state token is considered to match if the resource is anywhere in the scope of the lock. Handling unmapped URLs: For both ETags and state tokens, treat as if the URL identified a resource that exists but does not have the specified state.

10.4.5. If Header and Non-DAV-Aware Proxies

Non-DAV-aware proxies will not honor the If header, since they will not understand the If header, and HTTP requires non-understood headers to be ignored. When communicating with HTTP/1.1 proxies, the client MUST use the "Cache-Control: no-cache" request header so as to prevent the proxy from improperly trying to service the request from its cache. When dealing with HTTP/1.0 proxies, the "Pragma: no- cache" request header MUST be used for the same reason. Because in general clients may not be able to reliably detect non- DAV-aware intermediates, they are advised to always prevent caching using the request directives mentioned above.
Top   ToC   RFC4918 - Page 75

10.4.6. Example - No-tag Production

If: (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2> ["I am an ETag"]) (["I am another ETag"]) The previous header would require that the resource identified in the Request-URI be locked with the specified lock token and be in the state identified by the "I am an ETag" ETag or in the state identified by the second ETag "I am another ETag". To put the matter more plainly one can think of the previous If header as expressing the condition below: ( is-locked-with(urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2) AND matches-etag("I am an ETag") ) OR ( matches-etag("I am another ETag") )

10.4.7. Example - Using "Not" with No-tag Production

If: (Not <urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2> <urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092>) This If header requires that the resource must not be locked with a lock having the lock token urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 and must be locked by a lock with the lock token urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092.

10.4.8. Example - Causing a Condition to Always Evaluate to True

There may be cases where a client wishes to submit state tokens, but doesn't want the request to fail just because the state token isn't current anymore. One simple way to do this is to include a Condition that is known to always evaluate to true, such as in: If: (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>) (Not <DAV:no-lock>) "DAV:no-lock" is known to never represent a current lock token. Lock tokens are assigned by the server, following the uniqueness requirements described in Section 6.5, therefore cannot use the "DAV:" scheme. Thus, by applying "Not" to a state token that is
Top   ToC   RFC4918 - Page 76
   known not to be current, the Condition always evaluates to true.
   Consequently, the whole If header will always evaluate to true, and
   the lock token urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 will be
   submitted in any case.

10.4.9. Example - Tagged List If Header in COPY

>>Request COPY /resource1 HTTP/1.1 Host: www.example.com Destination: /resource2 If: </resource1> (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2> [W/"A weak ETag"]) (["strong ETag"]) In this example, http://www.example.com/resource1 is being copied to http://www.example.com/resource2. When the method is first applied to http://www.example.com/resource1, resource1 must be in the state specified by "(<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2> [W/"A weak ETag"]) (["strong ETag"])". That is, either it must be locked with a lock token of "urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2" and have a weak entity tag W/"A weak ETag" or it must have a strong entity tag "strong ETag".

10.4.10. Example - Matching Lock Tokens with Collection Locks

DELETE /specs/rfc2518.txt HTTP/1.1 Host: www.example.com If: <http://www.example.com/specs/> (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>) For this example, the lock token must be compared to the identified resource, which is the 'specs' collection identified by the URL in the tagged list production. If the 'specs' collection is not locked by a lock with the specified lock token, the request MUST fail. Otherwise, this request could succeed, because the If header evaluates to true, and because the lock token for the lock affecting the affected resource has been submitted.

10.4.11. Example - Matching ETags on Unmapped URLs

Consider a collection "/specs" that does not contain the member "/specs/rfc2518.doc". In this case, the If header If: </specs/rfc2518.doc> (["4217"])
Top   ToC   RFC4918 - Page 77
   will evaluate to false (the URI isn't mapped, thus the resource
   identified by the URI doesn't have an entity matching the ETag
   "4217").

   On the other hand, an If header of

     If: </specs/rfc2518.doc> (Not ["4217"])

   will consequently evaluate to true.

   Note that, as defined above in Section 10.4.4, the same
   considerations apply to matching state tokens.



(page 77 continued on part 4)

Next Section