Section 6.2) conflicts with any other kind of lock on the same resource, whether either lock is direct or indirect. A server MUST NOT create conflicting locks on a resource. 4. For a collection that is locked with a depth-infinity lock L, all member resources are indirectly locked. Changes in membership of such a collection affect the set of indirectly locked resources: * If a member resource is added to the collection, the new member resource MUST NOT already have a conflicting lock, because the new resource MUST become indirectly locked by L. * If a member resource stops being a member of the collection, then the resource MUST no longer be indirectly locked by L. 5. Each lock is identified by a single globally unique lock token (Section 6.5). 6. An UNLOCK request deletes the lock with the specified lock token. After a lock is deleted, no resource is locked by that lock. 7. A lock token is "submitted" in a request when it appears in an "If" header (Section 7, "Write Lock", discusses when token submission is required for write locks). 8. If a request causes the lock-root of any lock to become an unmapped URL, then the lock MUST also be deleted by that request.
unlocking a resource. While both timeouts (Section 6.6) and administrative action can be used to remove an offending lock, neither mechanism may be available when needed; the timeout may be long or the administrator may not be available. A successful request for a new shared lock MUST result in the generation of a unique lock associated with the requesting principal. Thus, if five principals have taken out shared write locks on the same resource, there will be five locks and five lock tokens, one for each principal. RFC3744] was defined to provide that permission. There is no requirement for servers to accept LOCK requests from all users or from anonymous users. Note that having a lock does not confer full privilege to modify the locked resource. Write access and other privileges MUST be enforced through normal privilege or authentication mechanisms, not based on the possible obscurity of lock token values.
Section 10.5, and also in the body of the response. Servers MAY make lock tokens publicly readable (e.g., in the DAV: lockdiscovery property). One use case for making lock tokens readable is so that a long-lived lock can be removed by the resource owner (the client that obtained the lock might have crashed or disconnected before cleaning up the lock). Except for the case of using UNLOCK under user guidance, a client SHOULD NOT use a lock token created by another client instance. This specification encourages servers to create Universally Unique Identifiers (UUIDs) for lock tokens, and to use the URI form defined by "A Universally Unique Identifier (UUID) URN Namespace" ([RFC4122]). However, servers are free to use any URI (e.g., from another scheme) so long as it meets the uniqueness requirements. For example, a valid lock token might be constructed using the "opaquelocktoken" scheme defined in Appendix C. Example: "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6" Section 9.10.2). The timeout counter SHOULD NOT be restarted at any other time. If the timeout expires, then the lock SHOULD be removed. In this case the server SHOULD act as if an UNLOCK method was executed by the
server on the resource using the lock token of the timed-out lock, performed with its override authority. Servers are advised to pay close attention to the values submitted by clients, as they will be indicative of the type of activity the client intends to perform. For example, an applet running in a browser may need to lock a resource, but because of the instability of the environment within which the applet is running, the applet may be turned off without warning. As a result, the applet is likely to ask for a relatively small timeout value so that if the applet dies, the lock can be quickly harvested. However, a document management system is likely to ask for an extremely long timeout because its user may be planning on going offline. A client MUST NOT assume that just because the timeout has expired, the lock has immediately been removed. Likewise, a client MUST NOT assume that just because the timeout has not expired, the lock still exists. Clients MUST assume that locks can 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, a sufficiently privileged user 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.
Section 7.4. 3. A modification of the mapping of the root of the write lock, either to another resource or to no resource (e.g., DELETE). Of the methods defined in HTTP and WebDAV, PUT, POST, PROPPATCH, LOCK, UNLOCK, MOVE, COPY (for the destination resource), DELETE, and MKCOL are affected by write locks. All other HTTP/WebDAV methods defined so far -- GET in particular -- function independently of a write lock. The next few sections describe in more specific terms how write locks interact with various operations.
HTTP 1.1 clients can be good citizens, avoiding overwriting other clients' changes, by using entity tags in If-Match headers with any requests that would modify resources. Information managers may attempt to prevent overwrites by implementing client-side procedures requiring locking before modifying WebDAV resources. Section 14.26 of [RFC2616]). It has the side benefit of locking the new resource immediately for use of the creator. Note that the lost-update problem is not an issue for collections because MKCOL can only be used to create a collection, not to overwrite an existing collection. When trying to lock a collection upon creation, clients can attempt to increase the likelihood of getting the lock by pipelining the MKCOL and LOCK requests together (but because this doesn't convert two separate operations into one atomic operation, there's no guarantee this will work). A successful lock request to an unmapped URL MUST result in the creation of a locked (non-collection) resource with empty content. Subsequently, a successful PUT request (with the correct lock token) provides the content for the resource. Note that the LOCK request has no mechanism for the client to provide Content-Type or Content- Language, thus the server will use defaults or empty values and rely on the subsequent PUT request for correct values. A resource created with a LOCK is empty but otherwise behaves in every way as a normal resource. It behaves the same way as a resource created by a PUT request with an empty body (and where a Content-Type and Content-Language was not specified), followed by a LOCK request to the same resource. Following from this model, a locked empty resource: o Can be read, deleted, moved, and copied, and in all ways behaves as a regular non-collection resource. o Appears as a member of its parent collection. o SHOULD NOT disappear when its lock goes away (clients must therefore be responsible for cleaning up their own mess, as with any other operation or any non-empty resource).
o MAY NOT have values for properties like DAV:getcontentlanguage that haven't been specified yet by the client. o Can be updated (have content added) with a PUT request. o MUST NOT be converted into a collection. The server MUST fail a MKCOL request (as it would with a MKCOL request to any existing non-collection resource). o MUST have defined values for DAV:lockdiscovery and DAV: supportedlock properties. o The response MUST indicate that a resource was created, by use of the "201 Created" response code (a LOCK request to an existing resource instead will result in 200 OK). The body must still include the DAV:lockdiscovery property, as with a LOCK request to an existing resource. The client is expected to update the locked empty resource shortly after locking it, using PUT and possibly PROPPATCH. Alternatively and for backwards compatibility to [RFC2518], servers MAY implement Lock-Null Resources (LNRs) instead (see definition in Appendix D). Clients can easily interoperate both with servers that support the old model LNRs and the recommended model of "locked empty resources" by only attempting PUT after a LOCK to an unmapped URL, not MKCOL or GET, and by not relying on specific properties of LNRs.
o MOVE an internal member out of the collection, o MOVE an internal member into the collection, o MOVE to rename an internal member within a collection, o COPY an internal member into a collection, and o PUT or MKCOL request that would create a new internal member. The collection's lock token is required in addition to the lock token on the internal member itself, if it is locked separately. In addition, a depth-infinity lock affects all write operations to all members of the locked collection. With a depth-infinity lock, the resource identified by the root of the lock is directly locked, and all its members are indirectly locked. o Any new resource added as a descendant of a depth-infinity locked collection becomes indirectly locked. o Any indirectly locked resource moved out of the locked collection into an unlocked collection is thereafter unlocked. o Any indirectly locked resource moved out of a locked source collection into a depth-infinity locked target collection remains indirectly locked but is now protected by the lock on the target collection (the target collection's lock token will thereafter be required to make further changes). If a depth-infinity write LOCK request is issued to a collection containing member URLs identifying resources that are currently locked in a manner that conflicts with the new lock (see Section 6.1, point 3), the request MUST fail with a 423 (Locked) status code, and the response SHOULD contain the 'no-conflicting-lock' precondition. If a lock request causes the URL of a resource to be added as an internal member URL of a depth-infinity locked collection, then the new resource MUST be automatically protected by the lock. For example, if the collection /a/b/ is write locked and the resource /c is moved to /a/b/c, then resource /a/b/c will be added to the write lock.
Section 10.4) could be used. "No-Tag-List" format: If: (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>) "Tagged-List" format, for "http://example.com/locked/": If: <http://example.com/locked/> (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>) "Tagged-List" format, for "http://example.com/locked/member": If: <http://example.com/locked/member> (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>) Note that, for the purpose of submitting the lock token, the actual form doesn't matter; what's relevant is that the lock token appears in the If header, and that the If header itself evaluates to true.
Section 7.5, an If header must be submitted containing a lock token for both the source and destination.
REC-XML]) request entity body, or in an HTTP header. The use of XML to encode method parameters was motivated by the ability to add extra XML elements to existing structures, providing extensibility; and by XML's ability to encode information in ISO 10646 character sets, providing internationalization support. In addition to encoding method parameters, XML is used in WebDAV to encode the responses from methods, providing the extensibility and internationalization advantages of XML for method output, as well as input. When XML is used for a request or response body, the Content-Type type SHOULD be application/xml. Implementations MUST accept both text/xml and application/xml in request and response bodies. Use of text/xml is deprecated. All DAV-compliant clients and resources MUST use XML parsers that are compliant with [REC-XML] and [REC-XML-NAMES]. All XML used in either requests or responses MUST be, at minimum, well formed and use namespaces correctly. If a server receives XML that is not well- formed, then the server MUST reject the entire request with a 400 (Bad Request). If a client receives XML that is not well-formed in a response, then the client MUST NOT assume anything about the outcome of the executed method and SHOULD treat the server as malfunctioning. Note that processing XML submitted by an untrusted source may cause risks connected to privacy, security, and service quality (see Section 20). Servers MAY reject questionable requests (even though they consist of well-formed XML), for instance, with a 400 (Bad Request) status code and an optional response body explaining the problem.
RFC2518] showed that many clients parsing Multi-Status responses did not fully implement the full Reference Resolution defined in Section 5 of [RFC3986]. Thus, servers in particular need to be careful in handling URLs in responses, to ensure that clients have enough context to be able to interpret all the URLs. The rules in this section apply not only to resource URLs in the 'href' element in Multi-Status responses, but also to the Destination and If header resource URLs. The sender has a choice between two approaches: using a relative reference, which is resolved against the Request-URI, or a full URI. A server MUST ensure that every 'href' value within a Multi-Status response uses the same format. WebDAV only uses one form of relative reference in its extensions, the absolute path. Simple-ref = absolute-URI | ( path-absolute [ "?" query ] ) The absolute-URI, path-absolute and query productions are defined in Sections 4.3, 3.3, and 3.4 of [RFC3986]. Within Simple-ref productions, senders MUST NOT: o use dot-segments ("." or ".."), or o have prefixes that do not match the Request-URI (using the comparison rules defined in Section 3.2.3 of [RFC2616]). Identifiers for collections SHOULD end in a '/' character.
In this case, the server should return two 'href' elements containing either o 'http://example.com/sample/' and 'http://example.com/sample/a%20test', or o '/sample/' and '/sample/a%20test' Note that even though the server may be storing the member resource internally as 'a test', it has to be percent-encoded when used inside a URI reference (see Section 2.1 of [RFC3986]). Also note that a legal URI may still contain characters that need to be escaped within XML character data, such as the ampersand character. Section 14.18, [RFC2616]). The server MUST do authorization checks before checking any HTTP conditional header.
client is forced to ask the user whether to overwrite the resource on the server without even being able to tell the user if it has changed. Timestamps do not solve this problem nearly as well as ETags. Strong ETags are much more useful for authoring use cases than weak ETags (see Section 13.3.3 of [RFC2616]). Semantic equivalence can be a useful concept but that depends on the document type and the application type, and interoperability might require some agreement or standard outside the scope of this specification and HTTP. Note also that weak ETags have certain restrictions in HTTP, e.g., these cannot be used in If-Match headers. Note that the meaning of an ETag in a PUT response is not clearly defined either in this document or in RFC 2616 (i.e., whether the ETag means that the resource is octet-for-octet equivalent to the body of the PUT request, or whether the server could have made minor changes in the formatting or content of the document upon storage). This is an HTTP issue, not purely a WebDAV issue. Because clients may be forced to prompt users or throw away changed content if the ETag changes, a WebDAV server SHOULD NOT change the ETag (or the Last-Modified time) for a resource that has an unchanged body and location. The ETag represents the state of the body or contents of the resource. There is no similar way to tell if properties have changed. Section 1.6 of [RFC3253]). The error body mechanism is appropriate to use with any error response that may take a body but does not already have a body defined. The mechanism is particularly appropriate when a status code can mean many things (for example, 400 Bad Request can mean required headers are missing, headers are incorrectly formatted, or much more). This error body mechanism is covered in Section 16. RFC2616], Sections 14.19 and 14.29) are defined per URL (not per resource), and are used by clients for caching. Therefore servers must ensure that executing any operation that affects the URL namespace (such as COPY, MOVE, DELETE, PUT, or MKCOL) does preserve their semantics, in particular:
o For any given URL, the "Last-Modified" value MUST increment every time the representation returned upon GET changes (within the limits of timestamp resolution). o For any given URL, an "ETag" value MUST NOT be reused for different representations returned by GET. In practice this means that servers o might have to increment "Last-Modified" timestamps for every resource inside the destination namespace of a namespace operation unless it can do so more selectively, and o similarly, might have to re-assign "ETag" values for these resources (unless the server allocates entity tags in a way so that they are unique across the whole URL namespace managed by the server). Note that these considerations also apply to specific use cases, such as using PUT to create a new resource at a URL that has been mapped before, but has been deleted since then. Finally, WebDAV properties (such as DAV:getetag and DAV: getlastmodified) that inherit their semantics from HTTP headers must behave accordingly. Section 14.20) along with all XML elements defined for use with that element. A client MUST submit a Depth header with a value of "0", "1", or "infinity" with a PROPFIND request. Servers MUST support "0" and "1" depth requests on WebDAV-compliant resources and SHOULD support "infinity" requests. In practice, support for infinite-depth requests MAY be disabled, due to the performance and security concerns associated with this behavior. Servers SHOULD treat a request without a Depth header 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: o Request particular property values, by naming the properties desired within the 'prop' element (the ordering of properties in here MAY be ignored by the server), o Request property values for those properties defined in this specification (at a minimum) plus dead properties, by using the 'allprop' element (the 'include' element can be used with 'allprop' to instruct the server to also include additional live properties that may not have been returned otherwise), o Request a list of names of all the properties defined on the resource, by using the 'propname' element. A client may choose not to submit a request body. An empty PROPFIND request body MUST be treated as if it were an 'allprop' request. Note that 'allprop' does not return values for all live properties. WebDAV servers increasingly have expensively-calculated or lengthy properties (see [RFC3253] and [RFC3744]) and do not return all properties already. Instead, WebDAV clients can use propname requests to discover what live properties exist, and request named properties when retrieving values. For a live property defined elsewhere, that definition can specify whether or not that live property would be returned in 'allprop' requests. 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 that does not exist is an error and MUST be noted with a 'response' XML element that contains a 404 (Not Found) status value. Consequently, the 'multistatus' XML element for a collection resource MUST include a 'response' XML element for each member URL of the collection, to whatever depth was requested. It SHOULD NOT include any 'response' elements for resources that are not WebDAV-compliant. Each 'response' element MUST contain an 'href' element that contains the URL of the resource on which the properties in the prop XML element are defined. Results for a PROPFIND on a collection resource are returned as a flat list whose order of entries is not
significant. Note that a resource may have only one value for a property of a given name, so the property may only show up once in PROPFIND responses. Properties may be subject to access control. In the case of 'allprop' and 'propname' requests, if a principal does not have the right to know whether a particular property exists, then the property MAY be silently excluded from the response. Some PROPFIND results MAY be cached, with care, as there is no cache validation mechanism for most properties. This method is both safe and idempotent (see Section 9.1 of [RFC2616]). Section 16) that might be particularly useful with PROPFIND. 403 Forbidden - A server MAY reject PROPFIND requests on collections with depth header of "Infinity", in which case it SHOULD use this error with the precondition code 'propfind-finite-depth' inside the error body. 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. 200 OK - A property exists and/or its value is successfully returned. 401 Unauthorized - The property cannot be viewed without appropriate authorization. 403 Forbidden - The property cannot be viewed regardless of authentication. 404 Not Found - The property does not exist.
</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.example.com/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.
</propstat> </response> <response> <href>http://www.example.com/container/front.html</href> <propstat> <prop xmlns:R="http://ns.example.com/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.example.com/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 descendants should be returned. Consistent with the previous example, resource http://www.example.com/container/ has six properties defined on it: bigbox and author in the "http://ns.example.com/boxschema/" namespace, and creationdate, displayname, resourcetype, and supportedlock in the "DAV:" namespace. The resource http://www.example.com/container/index.html, a member of the "container" collection, has nine properties defined on it, bigbox in the "http://ns.example.com/boxschema/" namespace and creationdate, displayname, getcontentlength, getcontenttype, getetag, getlastmodified, resourcetype, and supportedlock in the "DAV:" namespace. This example also demonstrates the use of XML namespace scoping and the default namespace. Since the "xmlns" attribute does not contain a prefix, the namespace applies by default to all enclosed elements. Hence, all elements that do not explicitly state the namespace to which they belong are members of the "DAV:" namespace.
<D:status>HTTP/1.1 200 OK</D:status> </D:propstat> </D:response> <D:response> <D:href>/container/front.html</D:href> <D:propstat> <D:prop xmlns:R="http://ns.example.com/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 >Mon, 12 Jan 1998 09:25:56 GMT</D:getlastmodified> <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.example.com/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 the dead properties defined on the resources, plus the name and value of all the properties defined in this specification. This example illustrates the use of relative references in the 'href' elements of the response. The resource http://www.example.com/container/ has six properties defined on it: 'bigbox' and 'author in the "http://ns.example.com/boxschema/" namespace, DAV:creationdate, DAV: displayname, DAV:resourcetype, and DAV:supportedlock.
The last four properties are WebDAV-specific, defined in Section 15. Since GET is not supported on this resource, the get* properties (e.g., DAV:getcontentlength) are not defined on this resource. The WebDAV-specific properties assert that "container" was created on December 1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT (DAV:creationdate), has a name of "Example collection" (DAV: displayname), a collection resource type (DAV:resourcetype), and supports exclusive write and shared write locks (DAV:supportedlock). The resource http://www.example.com/container/front.html has nine properties defined on it: 'bigbox' in the "http://ns.example.com/boxschema/" namespace (another instance of the "bigbox" property type), DAV:creationdate, DAV: displayname, DAV:getcontentlength, DAV:getcontenttype, DAV:getetag, DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock. 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 (DAV:creationdate), has a name of "Example HTML resource" (DAV: displayname), a content length of 4525 bytes (DAV:getcontentlength), a MIME type of "text/html" (DAV:getcontenttype), an entity tag of "zzyzx" (DAV:getetag), was last modified on Monday, January 12, 1998, at 09:25:56 GMT (DAV:getlastmodified), has an empty resource type, meaning that it is not a collection (DAV:resourcetype), and supports both exclusive write and shared write locks (DAV:supportedlock).
In this example, PROPFIND is executed on the resource http://www.example.com/mycol/ and its internal member resources. The client requests the values of all live properties defined in this specification, plus all dead properties, plus two more live properties defined in [RFC3253]. The response is not shown.