rfc2518.txt | draft-ietf-webdav-rfc2518bis-latest.txt | |||
---|---|---|---|---|
Network Working Group Y. Goland | WebDAV Working Group L. Dusseault, Ed. | |||
Request for Comments: 2518 Microsoft | Internet-Draft CommerceNet | |||
Category: Standards Track E. Whitehead | Obsoletes: 2518 (if approved) February 15, 2007 | |||
UC Irvine | Intended status: Standards Track | |||
A. Faizi | Expires: August 19, 2007 | |||
Netscape | ||||
S. Carter | ||||
D. Jensen | ||||
Novell | ||||
February 1999 | ||||
HTTP Extensions for Distributed Authoring -- WEBDAV | HTTP Extensions for Distributed Authoring - WebDAV | |||
draft-ietf-webdav-rfc2518bis-18 | ||||
Status of this Memo | Status of this Memo | |||
This document specifies an Internet standards track protocol for the | By submitting this Internet-Draft, each author represents that any | |||
Internet community, and requests discussion and suggestions for | applicable patent or other IPR claims of which he or she is aware | |||
improvements. Please refer to the current edition of the "Internet | have been or will be disclosed, and any of which he or she becomes | |||
Official Protocol Standards" (STD 1) for the standardization state | aware will be disclosed, in accordance with Section 6 of BCP 79. | |||
and status of this protocol. Distribution of this memo is unlimited. | ||||
Copyright Notice | Internet-Drafts are working documents of the Internet Engineering | |||
Task Force (IETF), its areas, and its working groups. Note that | ||||
other groups may also distribute working documents as Internet- | ||||
Drafts. | ||||
Copyright (C) The Internet Society (1999). All Rights Reserved. | Internet-Drafts are draft documents valid for a maximum of six months | |||
and may be updated, replaced, or obsoleted by other documents at any | ||||
time. It is inappropriate to use Internet-Drafts as reference | ||||
material or to cite them other than as "work in progress." | ||||
The list of current Internet-Drafts can be accessed at | ||||
http://www.ietf.org/ietf/1id-abstracts.txt. | ||||
The list of Internet-Draft Shadow Directories can be accessed at | ||||
http://www.ietf.org/shadow.html. | ||||
This Internet-Draft will expire on August 19, 2007. | ||||
Abstract | Abstract | |||
This document specifies a set of methods, headers, and content-types | WebDAV consists of a set of methods, headers, and content-types | |||
ancillary to HTTP/1.1 for the management of resource properties, | ancillary to HTTP/1.1 for the management of resource properties, | |||
creation and management of resource collections, namespace | creation and management of resource collections, URL namespace | |||
manipulation, and resource locking (collision avoidance). | manipulation, and resource locking (collision avoidance). | |||
Table of Contents | RFC2518 was published in February 1999, and this specification makes | |||
minor revisions mostly due to interoperability experience. | ||||
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 | Table of Contents | |||
2. Notational Conventions . . . . . . . . . . . . . . . . . . . 7 | ||||
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 7 | ||||
4. Data Model for Resource Properties . . . . . . . . . . . . . 8 | ||||
4.1. The Resource Property Model . . . . . . . . . . . . . . 8 | ||||
4.2. Existing Metadata Proposals . . . . . . . . . . . . . . 9 | ||||
4.3. Properties and HTTP Headers . . . . . . . . . . . . . . 9 | ||||
4.4. Property Values . . . . . . . . . . . . . . . . . . . . 10 | ||||
4.5. Property Names . . . . . . . . . . . . . . . . . . . . . 10 | ||||
4.6. Media Independent Links . . . . . . . . . . . . . . . . 11 | ||||
5. Collections of Web Resources . . . . . . . . . . . . . . . . 11 | ||||
5.1. HTTP URL Namespace Model . . . . . . . . . . . . . . . . 11 | ||||
5.2. Collection Resources . . . . . . . . . . . . . . . . . . 11 | ||||
5.3. Creation and Retrieval of Collection Resources . . . . . 13 | ||||
5.4. Source Resources and Output Resources . . . . . . . . . 13 | ||||
6. Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 | ||||
6.1. Exclusive Vs. Shared Locks . . . . . . . . . . . . . . . 15 | ||||
6.2. Required Support . . . . . . . . . . . . . . . . . . . . 16 | ||||
6.3. Lock Tokens . . . . . . . . . . . . . . . . . . . . . . 16 | ||||
6.4. opaquelocktoken Lock Token URI Scheme . . . . . . . . . 16 | ||||
6.4.1. Node Field Generation Without the IEEE 802 Address . 17 | ||||
6.5. Lock Capability Discovery . . . . . . . . . . . . . . . 19 | ||||
6.6. Active Lock Discovery . . . . . . . . . . . . . . . . . 19 | ||||
6.7. Usage Considerations . . . . . . . . . . . . . . . . . . 20 | ||||
7. Write Lock . . . . . . . . . . . . . . . . . . . . . . . . . 21 | ||||
7.1. Methods Restricted by Write Locks . . . . . . . . . . . 21 | ||||
7.2. Write Locks and Lock Tokens . . . . . . . . . . . . . . 21 | ||||
7.3. Write Locks and Properties . . . . . . . . . . . . . . . 21 | ||||
7.4. Write Locks and Null Resources . . . . . . . . . . . . . 21 | ||||
7.5. Write Locks and Collections . . . . . . . . . . . . . . 22 | ||||
7.6. Write Locks and the If Request Header . . . . . . . . . 22 | ||||
7.6.1. Example - Write Lock . . . . . . . . . . . . . . . . 23 | ||||
7.7. Write Locks and COPY/MOVE . . . . . . . . . . . . . . . 23 | ||||
7.8. Refreshing Write Locks . . . . . . . . . . . . . . . . . 24 | ||||
8. HTTP Methods for Distributed Authoring . . . . . . . . . . . 24 | ||||
8.1. PROPFIND . . . . . . . . . . . . . . . . . . . . . . . . 24 | ||||
8.1.1. Example - Retrieving Named Properties . . . . . . . 26 | ||||
8.1.2. Example - Using allprop to Retrieve All Properties . 28 | ||||
8.1.3. Example - Using propname to Retrieve all Property | ||||
Names . . . . . . . . . . . . . . . . . . . . . . . 31 | ||||
8.2. PROPPATCH . . . . . . . . . . . . . . . . . . . . . . . 33 | ||||
8.2.1. Status Codes for use with 207 (Multi-Status) . . . . 33 | ||||
8.2.2. Example - PROPPATCH . . . . . . . . . . . . . . . . 34 | ||||
8.3. MKCOL Method . . . . . . . . . . . . . . . . . . . . . . 35 | ||||
8.3.1. Request . . . . . . . . . . . . . . . . . . . . . . 35 | ||||
8.3.2. Status Codes . . . . . . . . . . . . . . . . . . . . 36 | ||||
8.3.3. Example - MKCOL . . . . . . . . . . . . . . . . . . 36 | ||||
8.4. GET, HEAD for Collections . . . . . . . . . . . . . . . 37 | ||||
8.5. POST for Collections . . . . . . . . . . . . . . . . . . 37 | ||||
8.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 37 | ||||
8.6.1. DELETE for Non-Collection Resources . . . . . . . . 37 | ||||
8.6.2. DELETE for Collections . . . . . . . . . . . . . . . 37 | ||||
8.7. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . 39 | ||||
8.7.1. PUT for Non-Collection Resources . . . . . . . . . . 39 | ||||
8.7.2. PUT for Collections . . . . . . . . . . . . . . . . 39 | ||||
8.8. COPY Method . . . . . . . . . . . . . . . . . . . . . . 39 | ||||
8.8.1. COPY for HTTP/1.1 resources . . . . . . . . . . . . 40 | ||||
8.8.2. COPY for Properties . . . . . . . . . . . . . . . . 40 | ||||
8.8.3. COPY for Collections . . . . . . . . . . . . . . . . 40 | ||||
8.8.4. COPY and the Overwrite Header . . . . . . . . . . . 42 | ||||
8.8.5. Status Codes . . . . . . . . . . . . . . . . . . . . 42 | ||||
8.8.6. Example - COPY with Overwrite . . . . . . . . . . . 42 | ||||
8.8.7. Example - COPY with No Overwrite . . . . . . . . . . 43 | ||||
8.8.8. Example - COPY of a Collection . . . . . . . . . . . 43 | ||||
8.9. MOVE Method . . . . . . . . . . . . . . . . . . . . . . 44 | ||||
8.9.1. MOVE for Properties . . . . . . . . . . . . . . . . 45 | ||||
8.9.2. MOVE for Collections . . . . . . . . . . . . . . . . 45 | ||||
8.9.3. MOVE and the Overwrite Header . . . . . . . . . . . 46 | ||||
8.9.4. Status Codes . . . . . . . . . . . . . . . . . . . . 46 | ||||
8.9.5. Example - MOVE of a Non-Collection . . . . . . . . . 46 | ||||
8.9.6. Example - MOVE of a Collection . . . . . . . . . . . 47 | ||||
8.10. LOCK Method . . . . . . . . . . . . . . . . . . . . . . 48 | ||||
8.10.1. Operation . . . . . . . . . . . . . . . . . . . . . 48 | ||||
8.10.2. The Effect of Locks on Properties and Collections . 48 | ||||
8.10.3. Locking Replicated Resources . . . . . . . . . . . . 49 | ||||
8.10.4. Depth and Locking . . . . . . . . . . . . . . . . . 49 | ||||
8.10.5. Interaction with other Methods . . . . . . . . . . . 49 | ||||
8.10.6. Lock Compatibility Table . . . . . . . . . . . . . . 50 | ||||
8.10.7. Status Codes . . . . . . . . . . . . . . . . . . . . 50 | ||||
8.10.8. Example - Simple Lock Request . . . . . . . . . . . 51 | ||||
8.10.9. Example - Refreshing a Write Lock . . . . . . . . . 53 | ||||
8.10.10. Example - Multi-Resource Lock Request . . . . . . . 54 | ||||
8.11. UNLOCK Method . . . . . . . . . . . . . . . . . . . . . 55 | ||||
8.11.1. Example - UNLOCK . . . . . . . . . . . . . . . . . . 55 | ||||
9. HTTP Headers for Distributed Authoring . . . . . . . . . . . 56 | ||||
9.1. DAV Header . . . . . . . . . . . . . . . . . . . . . . . 56 | ||||
9.2. Depth Header . . . . . . . . . . . . . . . . . . . . . . 56 | ||||
9.3. Destination Header . . . . . . . . . . . . . . . . . . . 57 | ||||
9.4. If Header . . . . . . . . . . . . . . . . . . . . . . . 57 | ||||
9.4.1. No-tag-list Production . . . . . . . . . . . . . . . 58 | ||||
9.4.2. Tagged-list Production . . . . . . . . . . . . . . . 58 | ||||
9.4.3. not Production . . . . . . . . . . . . . . . . . . . 59 | ||||
9.4.4. Matching Function . . . . . . . . . . . . . . . . . 60 | ||||
9.4.5. If Header and Non-DAV Compliant Proxies . . . . . . 60 | ||||
9.5. Lock-Token Header . . . . . . . . . . . . . . . . . . . 60 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 | |||
9.6. Overwrite Header . . . . . . . . . . . . . . . . . . . . 60 | 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 10 | |||
9.7. Status-URI Response Header . . . . . . . . . . . . . . . 61 | 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 11 | |||
9.8. Timeout Request Header . . . . . . . . . . . . . . . . . 61 | 4. Data Model for Resource Properties . . . . . . . . . . . . . 13 | |||
10. Status Code Extensions to HTTP/1.1 . . . . . . . . . . . . . 62 | 4.1. The Resource Property Model . . . . . . . . . . . . . . 13 | |||
10.1. 102 Processing . . . . . . . . . . . . . . . . . . . . . 62 | 4.2. Properties and HTTP Headers . . . . . . . . . . . . . . 13 | |||
10.2. 207 Multi-Status . . . . . . . . . . . . . . . . . . . . 63 | 4.3. Property Values . . . . . . . . . . . . . . . . . . . . 13 | |||
10.3. 422 Unprocessable Entity . . . . . . . . . . . . . . . . 63 | 4.3.1. Example - Property with Mixed Content . . . . . . . 15 | |||
10.4. 423 Locked . . . . . . . . . . . . . . . . . . . . . . . 63 | 4.4. Property Names . . . . . . . . . . . . . . . . . . . . . 17 | |||
10.5. 424 Failed Dependency . . . . . . . . . . . . . . . . . 63 | 4.5. Source Resources and Output Resources . . . . . . . . . 17 | |||
10.6. 507 Insufficient Storage . . . . . . . . . . . . . . . . 63 | 5. Collections of Web Resources . . . . . . . . . . . . . . . . 18 | |||
11. Multi-Status Response . . . . . . . . . . . . . . . . . . . . 64 | 5.1. HTTP URL Namespace Model . . . . . . . . . . . . . . . . 18 | |||
12. XML Element Definitions . . . . . . . . . . . . . . . . . . . 64 | 5.2. Collection Resources . . . . . . . . . . . . . . . . . . 18 | |||
12.1. activelock XML Element . . . . . . . . . . . . . . . . . 64 | 6. Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 | |||
12.1.1. depth XML Element . . . . . . . . . . . . . . . . . 64 | 6.1. Lock Model . . . . . . . . . . . . . . . . . . . . . . . 21 | |||
12.1.2. locktoken XML Element . . . . . . . . . . . . . . . 65 | 6.2. Exclusive Vs. Shared Locks . . . . . . . . . . . . . . . 22 | |||
12.1.3. timeout XML Element . . . . . . . . . . . . . . . . 65 | 6.3. Required Support . . . . . . . . . . . . . . . . . . . . 23 | |||
12.2. collection XML Element . . . . . . . . . . . . . . . . . 65 | 6.4. Lock Creator and Privileges . . . . . . . . . . . . . . 23 | |||
12.3. href XML Element . . . . . . . . . . . . . . . . . . . . 65 | 6.5. Lock Tokens . . . . . . . . . . . . . . . . . . . . . . 24 | |||
12.4. link XML Element . . . . . . . . . . . . . . . . . . . . 66 | 6.6. Lock Timeout . . . . . . . . . . . . . . . . . . . . . . 25 | |||
12.4.1. dst XML Element . . . . . . . . . . . . . . . . . . 66 | 6.7. Lock Capability Discovery . . . . . . . . . . . . . . . 25 | |||
12.4.2. src XML Element . . . . . . . . . . . . . . . . . . 66 | 6.8. Active Lock Discovery . . . . . . . . . . . . . . . . . 26 | |||
12.5. lockentry XML Element . . . . . . . . . . . . . . . . . 67 | 7. Write Lock . . . . . . . . . . . . . . . . . . . . . . . . . 27 | |||
12.6. lockinfo XML Element . . . . . . . . . . . . . . . . . . 67 | 7.1. Write Locks and Properties . . . . . . . . . . . . . . . 27 | |||
12.7. lockscope XML Element . . . . . . . . . . . . . . . . . 67 | 7.2. Avoiding Lost Updates . . . . . . . . . . . . . . . . . 28 | |||
12.7.1. exclusive XML Element . . . . . . . . . . . . . . . 68 | 7.3. Write Locks and Unmapped URLs . . . . . . . . . . . . . 29 | |||
12.7.2. shared XML Element . . . . . . . . . . . . . . . . . 68 | 7.4. Write Locks and Collections . . . . . . . . . . . . . . 30 | |||
12.8. locktype XML Element . . . . . . . . . . . . . . . . . . 68 | 7.5. Write Locks and the If Request Header . . . . . . . . . 31 | |||
12.8.1. write XML Element . . . . . . . . . . . . . . . . . 68 | 7.5.1. Example - Write Lock and COPY . . . . . . . . . . . 32 | |||
12.9. multistatus XML Element . . . . . . . . . . . . . . . . 69 | 7.5.2. Example - Deleting a Member of a Locked Collection . 32 | |||
12.9.1. response XML Element . . . . . . . . . . . . . . . . 69 | 7.6. Write Locks and COPY/MOVE . . . . . . . . . . . . . . . 33 | |||
12.9.2. responsedescription XML Element . . . . . . . . . . 70 | 7.7. Refreshing Write Locks . . . . . . . . . . . . . . . . . 34 | |||
12.10. owner XML Element . . . . . . . . . . . . . . . . . . . 70 | 8. General Request and Response Handling . . . . . . . . . . . . 35 | |||
12.11. prop XML element . . . . . . . . . . . . . . . . . . . . 71 | 8.1. Precedence in Error Handling . . . . . . . . . . . . . . 35 | |||
12.12. propertybehavior XML element . . . . . . . . . . . . . . 71 | 8.2. Use of XML . . . . . . . . . . . . . . . . . . . . . . . 35 | |||
12.12.1. keepalive XML element . . . . . . . . . . . . . . . 71 | 8.3. URL Handling . . . . . . . . . . . . . . . . . . . . . . 36 | |||
12.12.2. omit XML element . . . . . . . . . . . . . . . . . . 72 | 8.3.1. Example - Correct URL Handling . . . . . . . . . . . 36 | |||
12.13. propertyupdate XML element . . . . . . . . . . . . . . . 72 | 8.4. Required Bodies in Requests . . . . . . . . . . . . . . 37 | |||
12.13.1. remove XML element . . . . . . . . . . . . . . . . . 73 | 8.5. HTTP Headers for use in WebDAV . . . . . . . . . . . . . 37 | |||
12.13.2. set XML element . . . . . . . . . . . . . . . . . . 73 | 8.6. ETag . . . . . . . . . . . . . . . . . . . . . . . . . . 37 | |||
12.14. propfind XML Element . . . . . . . . . . . . . . . . . . 74 | 8.7. Including Error Response Bodies . . . . . . . . . . . . 38 | |||
12.14.1. allprop XML Element . . . . . . . . . . . . . . . . 74 | 8.8. Impact of Namespace Operations on Cache Validators . . . 38 | |||
12.14.2. propname XML Element . . . . . . . . . . . . . . . . 74 | 9. HTTP Methods for Distributed Authoring . . . . . . . . . . . 40 | |||
13. DAV Properties . . . . . . . . . . . . . . . . . . . . . . . 74 | 9.1. PROPFIND Method . . . . . . . . . . . . . . . . . . . . 40 | |||
13.1. creationdate Property . . . . . . . . . . . . . . . . . 75 | 9.1.1. PROPFIND Status Codes . . . . . . . . . . . . . . . 41 | |||
13.2. displayname Property . . . . . . . . . . . . . . . . . . 75 | 9.1.2. Status Codes for Use in 'propstat' Element . . . . . 42 | |||
13.3. getcontentlanguage Property . . . . . . . . . . . . . . 75 | 9.1.3. Example - Retrieving Named Properties . . . . . . . 42 | |||
13.4. getcontentlength Property . . . . . . . . . . . . . . . 76 | 9.1.4. Example - Using 'propname' to Retrieve All | |||
13.5. getcontenttype Property . . . . . . . . . . . . . . . . 76 | Property Names . . . . . . . . . . . . . . . . . . . 44 | |||
13.6. getetag Property . . . . . . . . . . . . . . . . . . . . 76 | 9.1.5. Example - Using So-called 'allprop' . . . . . . . . 46 | |||
13.7. getlastmodified Property . . . . . . . . . . . . . . . . 77 | 9.1.6. Example - Using 'allprop' with 'include' . . . . . . 49 | |||
13.8. lockdiscovery Property . . . . . . . . . . . . . . . . . 77 | 9.2. PROPPATCH Method . . . . . . . . . . . . . . . . . . . . 49 | |||
13.8.1. Example - Retrieving the lockdiscovery Property . . 78 | 9.2.1. Status Codes for Use in 'propstat' Element . . . . . 50 | |||
13.9. resourcetype Property . . . . . . . . . . . . . . . . . 79 | 9.2.2. Example - PROPPATCH . . . . . . . . . . . . . . . . 51 | |||
13.10. source Property . . . . . . . . . . . . . . . . . . . . 80 | 9.3. MKCOL Method . . . . . . . . . . . . . . . . . . . . . . 52 | |||
13.10.1. Example - A source Property . . . . . . . . . . . . 80 | 9.3.1. MKCOL Status Codes . . . . . . . . . . . . . . . . . 53 | |||
13.11. supportedlock Property . . . . . . . . . . . . . . . . . 81 | 9.3.2. Example - MKCOL . . . . . . . . . . . . . . . . . . 53 | |||
13.11.1. Example - Retrieving the supportedlock Property . . 81 | 9.4. GET, HEAD for Collections . . . . . . . . . . . . . . . 54 | |||
14. Instructions for Processing XML in DAV . . . . . . . . . . . 82 | 9.5. POST for Collections . . . . . . . . . . . . . . . . . . 54 | |||
15. DAV Compliance Classes . . . . . . . . . . . . . . . . . . . 83 | 9.6. DELETE Requirements . . . . . . . . . . . . . . . . . . 54 | |||
15.1. Class 1 . . . . . . . . . . . . . . . . . . . . . . . . 83 | 9.6.1. DELETE for Collections . . . . . . . . . . . . . . . 55 | |||
15.2. Class 2 . . . . . . . . . . . . . . . . . . . . . . . . 83 | 9.6.2. Example - DELETE . . . . . . . . . . . . . . . . . . 55 | |||
16. Internationalization Considerations . . . . . . . . . . . . . 83 | 9.7. PUT Requirements . . . . . . . . . . . . . . . . . . . . 56 | |||
17. Security Considerations . . . . . . . . . . . . . . . . . . . 85 | 9.7.1. PUT for Non-Collection Resources . . . . . . . . . . 56 | |||
17.1. Authentication of Clients . . . . . . . . . . . . . . . 85 | 9.7.2. PUT for Collections . . . . . . . . . . . . . . . . 57 | |||
17.2. Denial of Service . . . . . . . . . . . . . . . . . . . 86 | 9.8. COPY Method . . . . . . . . . . . . . . . . . . . . . . 57 | |||
17.3. Security through Obscurity . . . . . . . . . . . . . . . 86 | 9.8.1. COPY for Non-collection Resources . . . . . . . . . 57 | |||
17.4. Privacy Issues Connected to Locks . . . . . . . . . . . 86 | 9.8.2. COPY for Properties . . . . . . . . . . . . . . . . 58 | |||
17.5. Privacy Issues Connected to Properties . . . . . . . . . 86 | 9.8.3. COPY for Collections . . . . . . . . . . . . . . . . 58 | |||
17.6. Reduction of Security due to Source Link . . . . . . . . 87 | 9.8.4. COPY and Overwriting Destination Resources . . . . . 59 | |||
17.7. Implications of XML External Entities . . . . . . . . . 87 | 9.8.5. Status Codes . . . . . . . . . . . . . . . . . . . . 60 | |||
17.8. Risks Connected with Lock Tokens . . . . . . . . . . . . 88 | 9.8.6. Example - COPY with Overwrite . . . . . . . . . . . 61 | |||
18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 88 | 9.8.7. Example - COPY with No Overwrite . . . . . . . . . . 61 | |||
19. Intellectual Property . . . . . . . . . . . . . . . . . . . . 89 | 9.8.8. Example - COPY of a Collection . . . . . . . . . . . 62 | |||
20. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 89 | 9.9. MOVE Method . . . . . . . . . . . . . . . . . . . . . . 62 | |||
21. References . . . . . . . . . . . . . . . . . . . . . . . . . 90 | 9.9.1. MOVE for Properties . . . . . . . . . . . . . . . . 63 | |||
21.1. Normative References . . . . . . . . . . . . . . . . . . 90 | 9.9.2. MOVE for Collections . . . . . . . . . . . . . . . . 63 | |||
21.2. Informational References . . . . . . . . . . . . . . . . 91 | 9.9.3. MOVE and the Overwrite Header . . . . . . . . . . . 64 | |||
Appendix A. Appendices . . . . . . . . . . . . . . . . . . . . . 92 | 9.9.4. Status Codes . . . . . . . . . . . . . . . . . . . . 64 | |||
A.1. Appendix 1 - WebDAV Document Type Definition . . . . . . 92 | 9.9.5. Example - MOVE of a Non-Collection . . . . . . . . . 65 | |||
A.2. Appendix 2 - ISO 8601 Date and Time Profile . . . . . . 94 | 9.9.6. Example - MOVE of a Collection . . . . . . . . . . . 66 | |||
A.3. Appendix 3 - Notes on Processing XML Elements . . . . . 94 | 9.10. LOCK Method . . . . . . . . . . . . . . . . . . . . . . 67 | |||
A.3.1. Notes on Empty XML Elements . . . . . . . . . . . . 94 | 9.10.1. Creating a Lock on an Existing Resource . . . . . . 67 | |||
A.3.2. Notes on Illegal XML Processing . . . . . . . . . . 95 | 9.10.2. Refreshing Locks . . . . . . . . . . . . . . . . . . 67 | |||
A.4. Appendix 4 -- XML Namespaces for WebDAV . . . . . . . . 97 | 9.10.3. Depth and Locking . . . . . . . . . . . . . . . . . 68 | |||
A.4.1. Introduction . . . . . . . . . . . . . . . . . . . . 97 | 9.10.4. Locking Unmapped URLs . . . . . . . . . . . . . . . 68 | |||
A.4.2. Meaning of Qualified Names . . . . . . . . . . . . . 97 | 9.10.5. Lock Compatibility Table . . . . . . . . . . . . . . 69 | |||
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 | 9.10.6. LOCK Responses . . . . . . . . . . . . . . . . . . . 69 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 102 | 9.10.7. Example - Simple Lock Request . . . . . . . . . . . 70 | |||
Intellectual Property and Copyright Statements . . . . . . . . . 104 | 9.10.8. Example - Refreshing a Write Lock . . . . . . . . . 72 | |||
9.10.9. Example - Multi-Resource Lock Request . . . . . . . 73 | ||||
9.11. UNLOCK Method . . . . . . . . . . . . . . . . . . . . . 74 | ||||
9.11.1. Status Codes . . . . . . . . . . . . . . . . . . . . 74 | ||||
9.11.2. Example - UNLOCK . . . . . . . . . . . . . . . . . . 75 | ||||
10. HTTP Headers for Distributed Authoring . . . . . . . . . . . 76 | ||||
10.1. DAV Header . . . . . . . . . . . . . . . . . . . . . . . 76 | ||||
10.2. Depth Header . . . . . . . . . . . . . . . . . . . . . . 77 | ||||
10.3. Destination Header . . . . . . . . . . . . . . . . . . . 78 | ||||
10.4. If Header . . . . . . . . . . . . . . . . . . . . . . . 78 | ||||
10.4.1. Purpose . . . . . . . . . . . . . . . . . . . . . . 78 | ||||
10.4.2. Syntax . . . . . . . . . . . . . . . . . . . . . . . 79 | ||||
10.4.3. List Evaluation . . . . . . . . . . . . . . . . . . 80 | ||||
10.4.4. Matching State Tokens and ETags . . . . . . . . . . 80 | ||||
10.4.5. If Header and Non-DAV Aware Proxies . . . . . . . . 81 | ||||
10.4.6. Example - No-tag Production . . . . . . . . . . . . 81 | ||||
10.4.7. Example - using "Not" with No-tag Production . . . . 81 | ||||
10.4.8. Example - causing a Condition to always evaluate | ||||
to True . . . . . . . . . . . . . . . . . . . . . . 82 | ||||
10.4.9. Example - Tagged List If header in COPY . . . . . . 82 | ||||
10.4.10. Example - Matching lock tokens with collection | ||||
locks . . . . . . . . . . . . . . . . . . . . . . . 82 | ||||
10.4.11. Example - Matching ETags on unmapped URLs . . . . . 83 | ||||
10.5. Lock-Token Header . . . . . . . . . . . . . . . . . . . 83 | ||||
10.6. Overwrite Header . . . . . . . . . . . . . . . . . . . . 83 | ||||
10.7. Timeout Request Header . . . . . . . . . . . . . . . . . 84 | ||||
11. Status Code Extensions to HTTP/1.1 . . . . . . . . . . . . . 85 | ||||
11.1. 207 Multi-Status . . . . . . . . . . . . . . . . . . . . 85 | ||||
11.2. 422 Unprocessable Entity . . . . . . . . . . . . . . . . 85 | ||||
11.3. 423 Locked . . . . . . . . . . . . . . . . . . . . . . . 85 | ||||
11.4. 424 Failed Dependency . . . . . . . . . . . . . . . . . 85 | ||||
11.5. 507 Insufficient Storage . . . . . . . . . . . . . . . . 85 | ||||
12. Use of HTTP Status Codes . . . . . . . . . . . . . . . . . . 86 | ||||
12.1. 412 Precondition Failed . . . . . . . . . . . . . . . . 86 | ||||
12.2. 414 Request-URI Too Long . . . . . . . . . . . . . . . . 86 | ||||
13. Multi-Status Response . . . . . . . . . . . . . . . . . . . . 87 | ||||
13.1. Response Headers . . . . . . . . . . . . . . . . . . . . 87 | ||||
13.2. Handling Redirected Child Resources . . . . . . . . . . 88 | ||||
13.3. Internal Status Codes . . . . . . . . . . . . . . . . . 88 | ||||
14. XML Element Definitions . . . . . . . . . . . . . . . . . . . 89 | ||||
14.1. activelock XML Element . . . . . . . . . . . . . . . . . 89 | ||||
14.2. allprop XML Element . . . . . . . . . . . . . . . . . . 89 | ||||
14.3. collection XML Element . . . . . . . . . . . . . . . . . 89 | ||||
14.4. depth XML Element . . . . . . . . . . . . . . . . . . . 89 | ||||
14.5. error XML Element . . . . . . . . . . . . . . . . . . . 90 | ||||
14.6. exclusive XML Element . . . . . . . . . . . . . . . . . 90 | ||||
14.7. href XML Element . . . . . . . . . . . . . . . . . . . . 90 | ||||
14.8. include XML Element . . . . . . . . . . . . . . . . . . 91 | ||||
14.9. location XML Element . . . . . . . . . . . . . . . . . . 91 | ||||
14.10. lockentry XML Element . . . . . . . . . . . . . . . . . 91 | ||||
14.11. lockinfo XML Element . . . . . . . . . . . . . . . . . . 91 | ||||
14.12. lockroot XML Element . . . . . . . . . . . . . . . . . . 92 | ||||
14.13. lockscope XML Element . . . . . . . . . . . . . . . . . 92 | ||||
14.14. locktoken XML Element . . . . . . . . . . . . . . . . . 92 | ||||
14.15. locktype XML Element . . . . . . . . . . . . . . . . . . 92 | ||||
14.16. multistatus XML Element . . . . . . . . . . . . . . . . 93 | ||||
14.17. owner XML Element . . . . . . . . . . . . . . . . . . . 93 | ||||
14.18. prop XML Element . . . . . . . . . . . . . . . . . . . . 93 | ||||
14.19. propertyupdate XML Element . . . . . . . . . . . . . . . 94 | ||||
14.20. propfind XML Element . . . . . . . . . . . . . . . . . . 94 | ||||
14.21. propname XML Element . . . . . . . . . . . . . . . . . . 94 | ||||
14.22. propstat XML Element . . . . . . . . . . . . . . . . . . 94 | ||||
14.23. remove XML Element . . . . . . . . . . . . . . . . . . . 95 | ||||
14.24. response XML Element . . . . . . . . . . . . . . . . . . 95 | ||||
14.25. responsedescription XML Element . . . . . . . . . . . . 96 | ||||
14.26. set XML Element . . . . . . . . . . . . . . . . . . . . 96 | ||||
14.27. shared XML Element . . . . . . . . . . . . . . . . . . . 96 | ||||
14.28. status XML Element . . . . . . . . . . . . . . . . . . . 96 | ||||
14.29. timeout XML Element . . . . . . . . . . . . . . . . . . 97 | ||||
14.30. write XML Element . . . . . . . . . . . . . . . . . . . 97 | ||||
15. DAV Properties . . . . . . . . . . . . . . . . . . . . . . . 98 | ||||
15.1. creationdate Property . . . . . . . . . . . . . . . . . 98 | ||||
15.2. displayname Property . . . . . . . . . . . . . . . . . . 99 | ||||
15.3. getcontentlanguage Property . . . . . . . . . . . . . . 99 | ||||
15.4. getcontentlength Property . . . . . . . . . . . . . . . 100 | ||||
15.5. getcontenttype Property . . . . . . . . . . . . . . . . 100 | ||||
15.6. getetag Property . . . . . . . . . . . . . . . . . . . . 101 | ||||
15.7. getlastmodified Property . . . . . . . . . . . . . . . . 101 | ||||
15.8. lockdiscovery Property . . . . . . . . . . . . . . . . . 102 | ||||
15.8.1. Example - Retrieving DAV:lockdiscovery . . . . . . . 103 | ||||
15.9. resourcetype Property . . . . . . . . . . . . . . . . . 104 | ||||
15.10. supportedlock Property . . . . . . . . . . . . . . . . . 105 | ||||
15.10.1. Example - Retrieving DAV:supportedlock . . . . . . . 106 | ||||
16. Precondition/Postcondition XML Elements . . . . . . . . . . . 107 | ||||
17. XML Extensibility in DAV . . . . . . . . . . . . . . . . . . 111 | ||||
18. DAV Compliance Classes . . . . . . . . . . . . . . . . . . . 113 | ||||
18.1. Class 1 . . . . . . . . . . . . . . . . . . . . . . . . 113 | ||||
18.2. Class 2 . . . . . . . . . . . . . . . . . . . . . . . . 113 | ||||
18.3. Class 3 . . . . . . . . . . . . . . . . . . . . . . . . 113 | ||||
19. Internationalization Considerations . . . . . . . . . . . . . 115 | ||||
20. Security Considerations . . . . . . . . . . . . . . . . . . . 117 | ||||
20.1. Authentication of Clients . . . . . . . . . . . . . . . 117 | ||||
20.2. Denial of Service . . . . . . . . . . . . . . . . . . . 117 | ||||
20.3. Security through Obscurity . . . . . . . . . . . . . . . 118 | ||||
20.4. Privacy Issues Connected to Locks . . . . . . . . . . . 118 | ||||
20.5. Privacy Issues Connected to Properties . . . . . . . . . 118 | ||||
20.6. Implications of XML Entities . . . . . . . . . . . . . . 119 | ||||
20.7. Risks Connected with Lock Tokens . . . . . . . . . . . . 119 | ||||
20.8. Hosting Malicious Content . . . . . . . . . . . . . . . 120 | ||||
21. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 121 | ||||
21.1. New URI Schemes . . . . . . . . . . . . . . . . . . . . 121 | ||||
21.2. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 121 | ||||
21.3. Message Header Fields . . . . . . . . . . . . . . . . . 121 | ||||
21.3.1. DAV . . . . . . . . . . . . . . . . . . . . . . . . 121 | ||||
21.3.2. Depth . . . . . . . . . . . . . . . . . . . . . . . 121 | ||||
21.3.3. Destination . . . . . . . . . . . . . . . . . . . . 122 | ||||
21.3.4. If . . . . . . . . . . . . . . . . . . . . . . . . . 122 | ||||
21.3.5. Lock-Token . . . . . . . . . . . . . . . . . . . . . 122 | ||||
21.3.6. Overwrite . . . . . . . . . . . . . . . . . . . . . 122 | ||||
21.3.7. Timeout . . . . . . . . . . . . . . . . . . . . . . 123 | ||||
22. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 124 | ||||
23. Contributors to This Specification . . . . . . . . . . . . . 126 | ||||
24. Authors of RFC2518 . . . . . . . . . . . . . . . . . . . . . 127 | ||||
25. References . . . . . . . . . . . . . . . . . . . . . . . . . 128 | ||||
25.1. Normative References . . . . . . . . . . . . . . . . . . 128 | ||||
25.2. Informational References . . . . . . . . . . . . . . . . 129 | ||||
Appendix A. Notes on Processing XML Elements . . . . . . . . . . 130 | ||||
A.1. Notes on Empty XML Elements . . . . . . . . . . . . . . 130 | ||||
A.2. Notes on Illegal XML Processing . . . . . . . . . . . . 130 | ||||
A.3. Example - XML Syntax Error . . . . . . . . . . . . . . . 130 | ||||
A.4. Example - Unexpected XML Element . . . . . . . . . . . . 131 | ||||
Appendix B. Notes on HTTP Client Compatibility . . . . . . . . . 132 | ||||
Appendix C. The 'opaquelocktoken' Scheme and URIs . . . . . . . 133 | ||||
Appendix D. Lock-null Resources . . . . . . . . . . . . . . . . 134 | ||||
D.1. Guidance for Clients Using LOCK to Create Resources . . 134 | ||||
Appendix E. Guidance for Clients Desiring to Authenticate . . . 136 | ||||
Appendix F. Summary of changes from RFC2518 . . . . . . . . . . 138 | ||||
F.1. Changes for both Client and Server Implementations . . . 138 | ||||
F.2. Changes for Server Implementations . . . . . . . . . . . 139 | ||||
F.3. Other Changes . . . . . . . . . . . . . . . . . . . . . 140 | ||||
Appendix G. Change Log (to be removed by RFC Editor before | ||||
publication) . . . . . . . . . . . . . . . . . . . . 142 | ||||
G.1. Changes from -05 to -06 . . . . . . . . . . . . . . . . 142 | ||||
G.2. Changes in -07 . . . . . . . . . . . . . . . . . . . . . 142 | ||||
G.3. Changes in -08 . . . . . . . . . . . . . . . . . . . . . 143 | ||||
G.4. Changes in -09 . . . . . . . . . . . . . . . . . . . . . 144 | ||||
G.5. Changes in -10 . . . . . . . . . . . . . . . . . . . . . 145 | ||||
G.6. Changes in -11 . . . . . . . . . . . . . . . . . . . . . 145 | ||||
G.7. Changes in -12 . . . . . . . . . . . . . . . . . . . . . 145 | ||||
G.8. Changes in -13 . . . . . . . . . . . . . . . . . . . . . 146 | ||||
G.9. Changes in -14 . . . . . . . . . . . . . . . . . . . . . 146 | ||||
G.10. Changes in -15 . . . . . . . . . . . . . . . . . . . . . 146 | ||||
G.11. Changes in -16 . . . . . . . . . . . . . . . . . . . . . 146 | ||||
G.12. Changes in -17 . . . . . . . . . . . . . . . . . . . . . 147 | ||||
G.13. Changes in -18 . . . . . . . . . . . . . . . . . . . . . 147 | ||||
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 148 | ||||
Intellectual Property and Copyright Statements . . . . . . . . . 149 | ||||
1. Introduction | 1. Introduction | |||
This document describes an extension to the HTTP/1.1 protocol that | This document describes an extension to the HTTP/1.1 protocol that | |||
allows clients to perform remote web content authoring operations. | allows clients to perform remote web content authoring operations. | |||
This extension provides a coherent set of methods, headers, request | This extension provides a coherent set of methods, headers, request | |||
entity body formats, and response entity body formats that provide | entity body formats, and response entity body formats that provide | |||
operations for: | operations for: | |||
Properties: The ability to create, remove, and query information | Properties: The ability to create, remove, and query information | |||
about Web pages, such as their authors, creation dates, etc. Also, | about Web pages, such as their authors, creation dates, etc. | |||
the ability to link pages of any media type to related pages. | ||||
Collections: The ability to create sets of documents and to retrieve | Collections: The ability to create sets of documents and to retrieve | |||
a hierarchical membership listing (like a directory listing in a file | a hierarchical membership listing (like a directory listing in a file | |||
system). | system). | |||
Locking: The ability to keep more than one person from working on a | Locking: The ability to keep more than one person from working on a | |||
document at the same time. This prevents the "lost update problem," | document at the same time. This prevents the "lost update problem", | |||
in which modifications are lost as first one author then another | in which modifications are lost as first one author then another | |||
writes changes without merging the other author's changes. | writes changes without merging the other author's changes. | |||
Namespace Operations: The ability to instruct the server to copy and | Namespace Operations: The ability to instruct the server to copy and | |||
move Web resources. | move Web resources, operations which change the mapping from URLs to | |||
resources. | ||||
Requirements and rationale for these operations are described in a | Requirements and rationale for these operations are described in a | |||
companion document, "Requirements for a Distributed Authoring and | companion document, "Requirements for a Distributed Authoring and | |||
Versioning Protocol for the World Wide Web" [RFC2291]. | Versioning Protocol for the World Wide Web" [RFC2291]. | |||
The sections below provide a detailed introduction to resource | This document does not specify the versioning operations suggested by | |||
properties (Section 4), collections of resources (Section 5), and | [RFC2291]. That work was done in a separate document, "Versioning | |||
locking operations (Section 6). These sections introduce the | Extensions to WebDAV" [RFC3253]. | |||
abstractions manipulated by the WebDAV-specific HTTP methods | ||||
described in Section 8, "HTTP Methods for Distributed Authoring". | ||||
In HTTP/1.1, method parameter information was exclusively encoded in | ||||
HTTP headers. Unlike HTTP/1.1, WebDAV encodes method parameter | ||||
information either in an Extensible Markup Language (XML) [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. As a rule of thumb, | ||||
parameters are encoded in XML entity bodies when they have unbounded | ||||
length, or when they may be shown to a human user and hence require | ||||
encoding in an ISO 10646 character set. Otherwise, parameters are | ||||
encoded within HTTP headers. Section 9 describes the new HTTP | ||||
headers used with WebDAV methods. | ||||
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. | ||||
XML elements used in this specification are defined in Section 12. | The sections below provide a detailed introduction to various WebDAV | |||
abstractions: resource properties (Section 4), collections of | ||||
resources (Section 5), locks (Section 6) in general and write locks | ||||
(Section 7) specifically. | ||||
The XML namespace extension (Appendix A.4) is also used in this | These abstractions are manipulated by the WebDAV-specific HTTP | |||
specification in order to allow for new XML elements to be added | methods (Section 9) and the extra HTTP headers (Section 10) used with | |||
without fear of colliding with other element names. | WebDAV methods. General considerations for handling HTTP requests | |||
and responses in WebDAV are found in Section 8. | ||||
While the status codes provided by HTTP/1.1 are sufficient to | While the status codes provided by HTTP/1.1 are sufficient to | |||
describe most error conditions encountered by WebDAV methods, there | describe most error conditions encountered by WebDAV methods, there | |||
are some errors that do not fall neatly into the existing categories. | are some errors that do not fall neatly into the existing categories. | |||
New status codes developed for the WebDAV methods are defined in | This specification defines extra status codes developed for WebDAV | |||
Section 10. Since some WebDAV methods may operate over many | methods (Section 11) and describes existing HTTP status codes | |||
resources, the Multi-Status response has been introduced to return | (Section 12) as used in WebDAV. Since some WebDAV methods may | |||
status information for multiple resources. The Multi-Status response | operate over many resources, the Multi-Status response (Section 13) | |||
is described in Section 11. | has been introduced to return status information for multiple | |||
resources. Finally, this version of WebDAV introduces precondition | ||||
and postcondition (Section 16) XML elements in error response bodies. | ||||
WebDAV employs the property mechanism to store information about the | WebDAV uses XML ([REC-XML]) for property names and some values, and | |||
current state of the resource. For example, when a lock is taken out | also uses XML to marshal complicated requests and responses. This | |||
on a resource, a lock information property describes the current | specification contains DTD and text definitions of all all properties | |||
state of the lock. Section 13 defines the properties used within the | (Section 15) and all other XML elements (Section 14) used in | |||
WebDAV specification. | marshalling. WebDAV includes a few special rules on extending | |||
WebDAV XML marshalling in backwards-compatible ways (Section 17). | ||||
Finishing off the specification are sections on what it means to be | Finishing off the specification are sections on what it means for a | |||
compliant with this specification (Section 15), on | resource to be compliant with this specification (Section 18), on | |||
internationalization support (Section 16), and on security | internationalization support (Section 19), and on security | |||
(Section 17). | (Section 20). | |||
2. Notational Conventions | 2. Notational Conventions | |||
Since this document describes a set of extensions to the HTTP/1.1 | Since this document describes a set of extensions to the HTTP/1.1 | |||
protocol, the augmented BNF used herein to describe protocol elements | protocol, the augmented BNF used herein to describe protocol elements | |||
is exactly the same as described in section 2.1 of [RFC2068]. Since | is exactly the same as described in Section 2.1 of [RFC2616], | |||
this augmented BNF uses the basic production rules provided in | including the rules about implied linear white-space. Since this | |||
section 2.2 of [RFC2068], these rules apply to this document as well. | augmented BNF uses the basic production rules provided in Section 2.2 | |||
of [RFC2616], these rules apply to this document as well. | ||||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |||
"SHOULD", SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | |||
document are to be interpreted as described in RFC 2119 [RFC2119]. | document are to be interpreted as described in [RFC2119]. | |||
Note that in natural language, a property like the "creationdate" | ||||
property in the "DAV:" XML namespace is sometimes referred to as | ||||
"DAV:creationdate" for brevity. | ||||
3. Terminology | 3. Terminology | |||
"URI"/"URL" - A Uniform Resource Identifier and Uniform Resource | URI/URL - A Uniform Resource Identifier and Uniform Resource Locator, | |||
Locator, respectively. These terms (and the distinction between | respectively. These terms (and the distinction between them) are | |||
them) are defined in [RFC2396]. | defined in [RFC3986]. | |||
"Collection" - A resource that contains a set of URIs, termed member | URI/URL Mapping - A relation between an absolute URI and a resource. | |||
URIs, which identify member resources and meets the requirements in | Since a resource can represent items that are not network | |||
Section 5 of this specification. | retrievable, as well as those that are, it is possible for a resource | |||
to have zero, one, or many URI mappings. Mapping a resource to an | ||||
"http" scheme URI makes it possible to submit HTTP protocol requests | ||||
to the resource using the URI. | ||||
"Member URI" - A URI which is a member of the set of URIs contained | Path Segment - Informally, the characters found between slashes ("/") | |||
by a collection. | in a URI. Formally, as defined in Section 3.3 of [RFC3986]. | |||
"Internal Member URI" - A Member URI that is immediately relative to | Collection - Informally, a resource that also acts as a container of | |||
the URI of the collection (the definition of immediately relative is | references to child resources. Formally, a resource that contains a | |||
given in Section 5.2). | set of mappings between path segments and resources and meets the | |||
requirements defined in Section 5. | ||||
"Property" - A name/value pair that contains descriptive information | Internal Member (of a Collection) - Informally, a child resource of a | |||
collection. Formally, a resource referenced by a path segment | ||||
mapping contained in the collection. | ||||
Internal Member URL (of a Collection) - A URL of an internal member, | ||||
consisting of the URL of the collection (including trailing slash) | ||||
plus the path segment identifying the internal member. | ||||
Member (of a Collection) - Informally, a "descendant" of a | ||||
collection. Formally, an internal member of the collection, or, | ||||
recursively, a member of an internal member. | ||||
Member URL (of a Collection) - A URL that is either an internal | ||||
member URL of the collection itself, or is an internal member URL of | ||||
a member of that collection. | ||||
Property - A name/value pair that contains descriptive information | ||||
about a resource. | about a resource. | |||
"Live Property" - A property whose semantics and syntax are enforced | Live Property - A property whose semantics and syntax are enforced by | |||
by the server. For example, the live "getcontentlength" property has | the server. For example, the live property DAV:getcontentlength has | |||
its value, the length of the entity returned by a GET request, | its value, the length of the entity returned by a GET request, | |||
automatically calculated by the server. | automatically calculated by the server. | |||
"Dead Property" - A property whose semantics and syntax are not | Dead Property - A property whose semantics and syntax are not | |||
enforced by the server. The server only records the value of a dead | enforced by the server. The server only records the value of a dead | |||
property; the client is responsible for maintaining the consistency | property; the client is responsible for maintaining the consistency | |||
of the syntax and semantics of a dead property. | of the syntax and semantics of a dead property. | |||
"Null Resource" - A resource which responds with a 404 (Not Found) to | Principal - A "principal" is a distinct human or computational actor | |||
any HTTP/1.1 or DAV method except for PUT, MKCOL, OPTIONS and LOCK. | that initiates access to network resources. | |||
A NULL resource MUST NOT appear as a member of its parent collection. | ||||
State Token - A URI which represents a state of a resource. Lock | ||||
tokens are the only state tokens defined in this specification. | ||||
4. Data Model for Resource Properties | 4. Data Model for Resource Properties | |||
4.1. The Resource Property Model | 4.1. The Resource Property Model | |||
Properties are pieces of data that describe the state of a resource. | Properties are pieces of data that describe the state of a resource. | |||
Properties are data about data. | Properties are data about data. | |||
Properties are used in distributed authoring environments to provide | Properties are used in distributed authoring environments to provide | |||
for efficient discovery and management of resources. For example, a | for efficient discovery and management of resources. For example, a | |||
'subject' property might allow for the indexing of all resources by | 'subject' property might allow for the indexing of all resources by | |||
their subject, and an 'author' property might allow for the discovery | their subject, and an 'author' property might allow for the discovery | |||
of what authors have written which documents. | of what authors have written which documents. | |||
The DAV property model consists of name/value pairs. The name of a | The DAV property model consists of name/value pairs. The name of a | |||
property identifies the property's syntax and semantics, and provides | property identifies the property's syntax and semantics, and provides | |||
an address by which to refer to its syntax and semantics. | an address by which to refer to its syntax and semantics. | |||
There are two categories of properties: "live" and "dead". A live | There are two categories of properties: "live" and "dead". A live | |||
property has its syntax and semantics enforced by the server. Live | property has its syntax and semantics enforced by the server. Live | |||
properties include cases where a) the value of a property is read- | properties include cases where a) the value of a property is | |||
only, maintained by the server, and b) the value of the property is | protected, maintained by the server, and b) the value of the property | |||
maintained by the client, but the server performs syntax checking on | is maintained by the client, but the server performs syntax checking | |||
submitted values. All instances of a given live property MUST comply | on submitted values. All instances of a given live property MUST | |||
with the definition associated with that property name. A dead | comply with the definition associated with that property name. A | |||
property has its syntax and semantics enforced by the client; the | dead property has its syntax and semantics enforced by the client; | |||
server merely records the value of the property verbatim. | the server merely records the value of the property verbatim. | |||
4.2. Existing Metadata Proposals | ||||
Properties have long played an essential role in the maintenance of | ||||
large document repositories, and many current proposals contain some | ||||
notion of a property, or discuss web metadata more generally. These | ||||
include PICS [REC-PICS], PICS-NG, XML, Web Collections, and several | ||||
proposals on representing relationships within HTML. Work on PICS-NG | ||||
and Web Collections has been subsumed by the Resource Description | ||||
Framework (RDF) metadata activity of the World Wide Web Consortium. | ||||
RDF consists of a network-based data model and an XML representation | ||||
of that model. | ||||
Some proposals come from a digital library perspective. These | ||||
include the Dublin Core [RFC2413] metadata set and the Warwick | ||||
Framework [WF], a container architecture for different metadata | ||||
schemas. The literature includes many examples of metadata, | ||||
including MARC [USMARC], a bibliographic metadata format, and a | ||||
technical report bibliographic format employed by the Dienst system | ||||
[RFC1807]. Additionally, the proceedings from the first IEEE | ||||
Metadata conference describe many community-specific metadata sets. | ||||
Participants of the 1996 Metadata II Workshop in Warwick, UK [WF], | ||||
noted that "new metadata sets will develop as the networked | ||||
infrastructure matures" and "different communities will propose, | ||||
design, and be responsible for different types of metadata." These | ||||
observations can be corroborated by noting that many community- | ||||
specific sets of metadata already exist, and there is significant | ||||
motivation for the development of new forms of metadata as many | ||||
communities increasingly make their data available in digital form, | ||||
requiring a metadata format to assist data location and cataloging. | ||||
4.3. Properties and HTTP Headers | 4.2. Properties and HTTP Headers | |||
Properties already exist, in a limited sense, in HTTP message | Properties already exist, in a limited sense, in HTTP message | |||
headers. However, in distributed authoring environments a relatively | headers. However, in distributed authoring environments a relatively | |||
large number of properties are needed to describe the state of a | large number of properties are needed to describe the state of a | |||
resource, and setting/returning them all through HTTP headers is | resource, and setting/returning them all through HTTP headers is | |||
inefficient. Thus a mechanism is needed which allows a principal to | inefficient. Thus a mechanism is needed which allows a principal to | |||
identify a set of properties in which the principal is interested and | identify a set of properties in which the principal is interested and | |||
to set or retrieve just those properties. | to set or retrieve just those properties. | |||
4.4. Property Values | 4.3. Property Values | |||
The value of a property when expressed in XML MUST be well formed. | The value of a property is always a (well-formed) XML fragment. | |||
XML has been chosen because it is a flexible, self-describing, | XML has been chosen because it is a flexible, self-describing, | |||
structured data format that supports rich schema definitions, and | structured data format that supports rich schema definitions, and | |||
because of its support for multiple character sets. XML's self- | because of its support for multiple character sets. XML's self- | |||
describing nature allows any property's value to be extended by | describing nature allows any property's value to be extended by | |||
adding new elements. Older clients will not break when they | adding elements. Clients will not break when they encounter | |||
encounter extensions because they will still have the data specified | extensions because they will still have the data specified in the | |||
in the original schema and will ignore elements they do not | original schema and MUST ignore elements they do not understand. | |||
understand. XML's support for multiple character sets allows any | ||||
human-readable property to be encoded and read in a character set | ||||
familiar to the user. XML's support for multiple human languages, | ||||
using the "xml:lang" attribute, handles cases where the same | ||||
character set is employed by multiple human languages. | ||||
4.5. Property Names | XML's support for multiple character sets allows any human-readable | |||
property to be encoded and read in a character set familiar to the | ||||
user. XML's support for multiple human languages, using the "xml: | ||||
lang" attribute, handles cases where the same character set is | ||||
employed by multiple human languages. Note that xml:lang scope is | ||||
recursive, so an xml:lang attribute on any element containing a | ||||
property name element applies to the property value unless it has | ||||
been overridden by a more locally scoped attribute. Note that a | ||||
property only has one value, in one language (or language MAY be left | ||||
undefined), not multiple values in different languages or a single | ||||
value in multiple languages. | ||||
A property is always represented with an XML element consisting of | ||||
the property name, called the "property name element". The simplest | ||||
example is an empty property, which is different from a property that | ||||
does not exist: | ||||
<R:title xmlns:R="http://www.example.com/ns/"></R:title> | ||||
The value of the property appears inside the property name element. | ||||
The value may be any kind of well-formed XML content, including both | ||||
text-only and mixed content. Servers MUST preserve the following XML | ||||
Information Items (using the terminology from [REC-XML-INFOSET]) in | ||||
storage and transmission of dead properties: | ||||
For the property name Element Information Item itself: | ||||
[namespace name] | ||||
[local name] | ||||
[attributes] named "xml:lang" or any such attribute in scope | ||||
[children] of type element or character | ||||
On all Element Information Items in the property value: | ||||
[namespace name] | ||||
[local name] | ||||
[attributes] | ||||
[children] of type element or character | ||||
On Attribute Information Items in the property value: | ||||
[namespace name] | ||||
[local name] | ||||
[normalized value] | ||||
On Character Information Items in the property value: | ||||
[character code] | ||||
Since prefixes are used in some XML vocabularies (XPath and XML | ||||
Schema, for example), servers SHOULD preserve, for any Information | ||||
Item in the value: | ||||
[prefix] | ||||
XML Infoset attributes not listed above MAY be preserved by the | ||||
server, but clients MUST NOT rely on them being preserved. The above | ||||
rules would also apply by default to live properties, unless defined | ||||
otherwise. | ||||
Servers MUST ignore the XML attribute xml:space if present and never | ||||
use it to change white space handling. White space in property | ||||
values is significant. | ||||
4.3.1. Example - Property with Mixed Content | ||||
Consider a dead property 'author' created by the client as follows: | ||||
<D:prop xml:lang="en" xmlns:D="DAV:"> | ||||
<x:author xmlns:x='http://example.com/ns'> | ||||
<x:name>Jane Doe</x:name> | ||||
<!-- Jane's contact info --> | ||||
<x:uri type='email' | ||||
added='2005-11-26'>mailto:jane.doe@example.com</x:uri> | ||||
<x:uri type='web' | ||||
added='2005-11-27'>http://www.example.com</x:uri> | ||||
<x:notes xmlns:h='http://www.w3.org/1999/xhtml'> | ||||
Jane has been working way <h:em>too</h:em> long on the | ||||
long-awaited revision of <![CDATA[<RFC2518>]]>. | ||||
</x:notes> | ||||
</x:author> | ||||
</D:prop> | ||||
When this property is requested, a server might return: | ||||
<D:prop xmlns:D='DAV:'><author | ||||
xml:lang='en' | ||||
xmlns:x='http://example.com/ns' | ||||
xmlns='http://example.com/ns' | ||||
xmlns:h='http://www.w3.org/1999/xhtml'> | ||||
<x:name>Jane Doe</x:name> | ||||
<x:uri added="2005-11-26" type="email" | ||||
>mailto:jane.doe@example.com</x:uri> | ||||
<x:uri added="2005-11-27" type="web" | ||||
>http://www.example.com</x:uri> | ||||
<x:notes> | ||||
Jane has been working way <h:em>too</h:em> long on the | ||||
long-awaited revision of <RFC2518>. | ||||
</x:notes> | ||||
</author> | ||||
</D:prop> | ||||
Note in this example: | ||||
o The [prefix] for the property name itself was not preserved, being | ||||
non-significant, all other [prefix] values have been preserved, | ||||
o attribute values have been rewritten with double quotes instead of | ||||
single quotes (quoting style is not significant), and attribute | ||||
order has not been preserved, | ||||
o the xml:lang attribute has been returned on the property name | ||||
element itself (it was in scope when the property was set, but the | ||||
exact position in the response is not considered significant as | ||||
long as it is in scope), | ||||
o whitespace between tags has been preserved everywhere (whitespace | ||||
between attributes not so), | ||||
o CDATA encapsulation was replaced with character escaping (the | ||||
reverse would also be legal), | ||||
o the comment item was stripped (as would have been a processing | ||||
instruction item). | ||||
Implementation note: there are cases such as editing scenarios where | ||||
clients may require that XML content is preserved character-by- | ||||
character (such as attribute ordering or quoting style). In this | ||||
case, clients should consider using a text-only property value by | ||||
escaping all characters that have a special meaning in XML parsing. | ||||
4.4. Property Names | ||||
A property name is a universally unique identifier that is associated | A property name is a universally unique identifier that is associated | |||
with a schema that provides information about the syntax and | with a schema that provides information about the syntax and | |||
semantics of the property. | semantics of the property. | |||
Because a property's name is universally unique, clients can depend | Because a property's name is universally unique, clients can depend | |||
upon consistent behavior for a particular property across multiple | upon consistent behavior for a particular property across multiple | |||
resources, on the same and across different servers, so long as that | resources, on the same and across different servers, so long as that | |||
property is "live" on the resources in question, and the | property is "live" on the resources in question, and the | |||
implementation of the live property is faithful to its definition. | implementation of the live property is faithful to its definition. | |||
The XML namespace mechanism, which is based on URIs [RFC2396], is | The XML namespace mechanism, which is based on URIs ([RFC3986]), is | |||
used to name properties because it prevents namespace collisions and | used to name properties because it prevents namespace collisions and | |||
provides for varying degrees of administrative control. | provides for varying degrees of administrative control. | |||
The property namespace is flat; that is, no hierarchy of properties | The property namespace is flat; that is, no hierarchy of properties | |||
is explicitly recognized. Thus, if a property A and a property A/B | is explicitly recognized. Thus, if a property A and a property A/B | |||
exist on a resource, there is no recognition of any relationship | exist on a resource, there is no recognition of any relationship | |||
between the two properties. It is expected that a separate | between the two properties. It is expected that a separate | |||
specification will eventually be produced which will address issues | specification will eventually be produced which will address issues | |||
relating to hierarchical properties. | relating to hierarchical properties. | |||
Finally, it is not possible to define the same property twice on a | Finally, it is not possible to define the same property twice on a | |||
single resource, as this would cause a collision in the resource's | single resource, as this would cause a collision in the resource's | |||
property namespace. | property namespace. | |||
4.6. Media Independent Links | 4.5. Source Resources and Output Resources | |||
Although HTML resources support links to other resources, the Web | Some HTTP resources are dynamically generated by the server. For | |||
needs more general support for links between resources of any media | these resources, there presumably exists source code somewhere | |||
type (media types are also known as MIME types, or content types). | governing how that resource is generated. The relationship of source | |||
WebDAV provides such links. A WebDAV link is a special type of | files to output HTTP resources may be one to one, one to many, many | |||
property value, formally defined in Section 12.4, that allows typed | to one or many to many. There is no mechanism in HTTP to determine | |||
connections to be established between resources of any media type. | whether a resource is even dynamic, let alone where its source files | |||
The property value consists of source and destination Uniform | exist or how to author them. Although this problem would usefully be | |||
Resource Identifiers (URIs); the property name identifies the link | solved, interoperable WebDAV implementations have been widely | |||
type. | deployed without actually solving this problem, by dealing only with | |||
static resources. Thus, the source vs. output problem is not solved | ||||
in this specification and has been deferred to a separate document. | ||||
5. Collections of Web Resources | 5. Collections of Web Resources | |||
This section provides a description of a new type of Web resource, | This section provides a description of a type of Web resource, the | |||
the collection, and discusses its interactions with the HTTP URL | collection, and discusses its interactions with the HTTP URL | |||
namespace. The purpose of a collection resource is to model | namespace and with HTTP methods. The purpose of a collection | |||
collection-like objects (e.g., file system directories) within a | resource is to model collection-like objects (e.g., file system | |||
server's namespace. | directories) within a server's namespace. | |||
All DAV compliant resources MUST support the HTTP URL namespace model | All DAV compliant resources MUST support the HTTP URL namespace model | |||
specified herein. | specified herein. | |||
5.1. HTTP URL Namespace Model | 5.1. HTTP URL Namespace Model | |||
The HTTP URL namespace is a hierarchical namespace where the | The HTTP URL namespace is a hierarchical namespace where the | |||
hierarchy is delimited with the "/" character. | hierarchy is delimited with the "/" character. | |||
An HTTP URL namespace is said to be consistent if it meets the | An HTTP URL namespace is said to be consistent if it meets the | |||
following conditions: for every URL in the HTTP hierarchy there | following conditions: for every URL in the HTTP hierarchy there | |||
exists a collection that contains that URL as an internal member. | exists a collection that contains that URL as an internal member URL. | |||
The root, or top-level collection of the namespace under | The root, or top-level collection of the namespace under | |||
consideration is exempt from the previous rule. | consideration, is exempt from the previous rule. The top-level | |||
collection of the namespace under consideration is not necessarily | ||||
the collection identified by the absolute path '/', it may be | ||||
identified by one or more path segments (e.g. /servlets/webdav/...) | ||||
Neither HTTP/1.1 nor WebDAV require that the entire HTTP URL | Neither HTTP/1.1 nor WebDAV require that the entire HTTP URL | |||
namespace be consistent. However, certain WebDAV methods are | namespace be consistent -- a WebDAV-compatible resource may not have | |||
prohibited from producing results that cause namespace | a parent collection. However, certain WebDAV methods are prohibited | |||
inconsistencies. | from producing results that cause namespace inconsistencies. | |||
Although implicit in [RFC2068] and [RFC2396], any resource, including | As is implicit in [RFC2616] and [RFC3986], any resource, including | |||
collection resources, MAY be identified by more than one URI. For | collection resources, MAY be identified by more than one URI. For | |||
example, a resource could be identified by multiple HTTP URLs. | example, a resource could be identified by multiple HTTP URLs. | |||
5.2. Collection Resources | 5.2. Collection Resources | |||
A collection is a resource whose state consists of at least a list of | Collection resources differ from other resources in that they also | |||
internal member URIs and a set of properties, but which may have | act as containers. Some HTTP methods apply only to a collection, but | |||
additional state such as entity bodies returned by GET. An internal | some apply to some or all of the resources inside the container | |||
member URI MUST be immediately relative to a base URI of the | defined by the collection. When the scope of a method is not clear, | |||
collection. That is, the internal member URI is equal to a | the client can specify what depth to apply. Depth can be either zero | |||
containing collection's URI plus an additional segment for non- | levels in (only the collection), one level (the collection and | |||
collection resources, or additional segment plus trailing slash "/" | directly contained resources) or infinite levels (the collection and | |||
for collection resources, where segment is defined in section 3.3 of | all contained resources recursively). | |||
[RFC2396]. | ||||
Any given internal member URI MUST only belong to the collection | ||||
once, i.e., it is illegal to have multiple instances of the same URI | ||||
in a collection. Properties defined on collections behave exactly as | ||||
do properties on non-collection resources. | ||||
For all WebDAV compliant resources A and B, identified by URIs U and | ||||
V, for which U is immediately relative to V, B MUST be a collection | ||||
that has U as an internal member URI. So, if the resource with URL | ||||
http://foo.com/bar/blah is WebDAV compliant and if the resource with | ||||
URL http://foo.com/bar/ is WebDAV compliant then the resource with | ||||
URL http://foo.com/bar/ must be a collection and must contain URL | ||||
http://foo.com/bar/blah as an internal member. | ||||
Collection resources MAY list the URLs of non-WebDAV compliant | ||||
children in the HTTP URL namespace hierarchy as internal members but | ||||
are not required to do so. For example, if the resource with URL | ||||
http://foo.com/bar/blah is not WebDAV compliant and the URL | ||||
http://foo.com/bar/ identifies a collection then URL | ||||
http://foo.com/bar/blah may or may not be an internal member of the | ||||
collection with URL http://foo.com/bar/. | ||||
If a WebDAV compliant resource has no WebDAV compliant children in | ||||
the HTTP URL namespace hierarchy then the WebDAV compliant resource | ||||
is not required to be a collection. | ||||
There is a standing convention that when a collection is referred to | ||||
by its name without a trailing slash, the trailing slash is | ||||
automatically appended. Due to this, a resource may accept a URI | ||||
without a trailing "/" to point to a collection. In this case it | ||||
SHOULD return a content-location header in the response pointing to | ||||
the URI ending with the "/". For example, if a client invokes a | ||||
method on http://foo.bar/blah (no trailing slash), the resource | ||||
http://foo.bar/blah/ (trailing slash) may respond as if the operation | ||||
were invoked on it, and should return a content-location header with | ||||
http://foo.bar/blah/ in it. In general clients SHOULD use the "/" | ||||
form of collection names. | ||||
A resource MAY be a collection but not be WebDAV compliant. That is, | ||||
the resource may comply with all the rules set out in this | ||||
specification regarding how a collection is to behave without | ||||
necessarily supporting all methods that a WebDAV compliant resource | ||||
is required to support. In such a case the resource may return the | ||||
DAV:resourcetype property with the value DAV:collection but MUST NOT | ||||
return a DAV header containing the value "1" on an OPTIONS response. | ||||
5.3. Creation and Retrieval of Collection Resources | ||||
This document specifies the MKCOL method to create new collection | A collection's state consists of at least a set of mappings between | |||
resources, rather than using the existing HTTP/1.1 PUT or POST | path segments and resources, and a set of properties on the | |||
method, for the following reasons: | collection itself. In this document, a resource B will be said to be | |||
contained in the collection resource A if there is a path segment | ||||
mapping which maps to B and which is contained in A. A collection | ||||
MUST contain at most one mapping for a given path segment, i.e., it | ||||
is illegal to have the same path segment mapped to more than one | ||||
resource. | ||||
In HTTP/1.1, the PUT method is defined to store the request body at | Properties defined on collections behave exactly as do properties on | |||
the location specified by the Request-URI. While a description | non-collection resources. A collection MAY have additional state | |||
format for a collection can readily be constructed for use with PUT, | such as entity bodies returned by GET. | |||
the implications of sending such a description to the server are | ||||
undesirable. For example, if a description of a collection that | ||||
omitted some existing resources were PUT to a server, this might be | ||||
interpreted as a command to remove those members. This would extend | ||||
PUT to perform DELETE functionality, which is undesirable since it | ||||
changes the semantics of PUT, and makes it difficult to control | ||||
DELETE functionality with an access control scheme based on methods. | ||||
While the POST method is sufficiently open-ended that a "create a | For all WebDAV compliant resources A and B, identified by URLs "U" | |||
collection" POST command could be constructed, this is undesirable | and "V" respectively, such that "V" is equal to "U/SEGMENT", A MUST | |||
because it would be difficult to separate access control for | be a collection that contains a mapping from "SEGMENT" to B. So, if | |||
collection creation from other uses of POST. | resource B with URL "http://example.com/bar/blah" is WebDAV compliant | |||
and if resource A with URL "http://example.com/bar/" is WebDAV | ||||
compliant, then resource A must be a collection and must contain | ||||
exactly one mapping from "blah" to B. | ||||
The exact definition of the behavior of GET and PUT on collections is | Although commonly a mapping consists of a single segment and a | |||
defined later in this document. | resource, in general, a mapping consists of a set of segments and a | |||
resource. This allows a server to treat a set of segments as | ||||
equivalent (i.e. either all of the segments are mapped to the same | ||||
resource, or none of the segments are mapped to a resource). For | ||||
example, a server that performs case-folding on segments will treat | ||||
the segments "ab", "Ab", "aB", and "AB" as equivalent. A client can | ||||
then use any of these segments to identify the resource. Note that a | ||||
PROPFIND result will select one of these equivalent segments to | ||||
identify the mapping, so there will be one PROPFIND response element | ||||
per mapping, not one per segment in the mapping. | ||||
5.4. Source Resources and Output Resources | Collection resources MAY have mappings to non-WebDAV compliant | |||
resources in the HTTP URL namespace hierarchy but are not required to | ||||
do so. For example, if resource X with URL | ||||
"http://example.com/bar/blah" is not WebDAV compliant and resource A | ||||
with "URL http://example.com/bar/" identifies a WebDAV collection, | ||||
then A may or may not have a mapping from "blah" to X. | ||||
For many resources, the entity returned by a GET method exactly | If a WebDAV compliant resource has no WebDAV compliant internal | |||
matches the persistent state of the resource, for example, a GIF file | members in the HTTP URL namespace hierarchy then the WebDAV compliant | |||
stored on a disk. For this simple case, the URI at which a resource | resource is not required to be a collection. | |||
is accessed is identical to the URI at which the source (the | ||||
persistent state) of the resource is accessed. This is also the case | ||||
for HTML source files that are not processed by the server prior to | ||||
transmission. | ||||
However, the server can sometimes process HTML resources before they | There is a standing convention that when a collection is referred to | |||
are transmitted as a return entity body. For example, a server-side- | by its name without a trailing slash, the server MAY handle the | |||
include directive within an HTML file might instruct a server to | request as if the trailing slash were present. In this case it | |||
replace the directive with another value, such as the current date. | SHOULD return a Content-Location header in the response, pointing to | |||
In this case, what is returned by GET (HTML plus date) differs from | the URL ending with the "/". For example, if a client invokes a | |||
the persistent state of the resource (HTML plus directive). | method on http://example.com/blah (no trailing slash), the server may | |||
Typically there is no way to access the HTML resource containing the | respond as if the operation were invoked on http://example.com/blah/ | |||
unprocessed directive. | (trailing slash), and should return a Content-Location header with | |||
the value http://example.com/blah/. Wherever a server produces a URL | ||||
referring to a collection, the server SHOULD include the trailing | ||||
slash. In general clients SHOULD use the trailing slash form of | ||||
collection names. If clients do not use the trailing slash form the | ||||
client needs to be prepared to see a redirect response. Clients will | ||||
find the DAV:resourcetype property more reliable than the URL to find | ||||
out if a resource is a collection. | ||||
Sometimes the entity returned by GET is the output of a data- | Clients MUST be able to support the case where WebDAV resources are | |||
producing process that is described by one or more source resources | contained inside non-WebDAV resources. For example, if a OPTIONS | |||
(that may not even have a location in the URI namespace). A single | response from "http://example.com/servlet/dav/collection" indicates | |||
data-producing process may dynamically generate the state of a | WebDAV support, the client cannot assume that | |||
potentially large number of output resources. An example of this is | "http://example.com/servlet/dav/" or its parent necessarily are | |||
a CGI script that describes a "finger" gateway process that maps part | WebDAV collections. | |||
of the namespace of a server into finger requests, such as | ||||
http://www.foo.bar.org/finger_gateway/user@host. | ||||
In the absence of distributed authoring capabilities, it is | A typical scenario in which mapped URLs do not appear as members of | |||
acceptable to have no mapping of source resource(s) to the URI | their parent collection is the case where a server allows links or | |||
namespace. In fact, preventing access to the source resource(s) has | redirects to non-WebDAV resources. For instance, "/col/link" might | |||
desirable security benefits. However, if remote editing of the | not appear as a member of "/col/", although the server would respond | |||
source resource(s) is desired, the source resource(s) should be given | with a 302 status to a GET request to "/col/link", thus the URL | |||
a location in the URI namespace. This source location should not be | "/col/link" would indeed be mapped. Similarly, a dynamically- | |||
one of the locations at which the generated output is retrievable, | generated page might have a URL mapping from "/col/index.html", thus | |||
since in general it is impossible for the server to differentiate | this resource might respond with a 200 OK to a GET request yet not | |||
requests for source resources from requests for process output | appear as a member of "/col/". | |||
resources. There is often a many-to-many relationship between source | ||||
resources and output resources. | ||||
On WebDAV compliant servers the URI of the source resource(s) may be | Some mappings to even WebDAV-compliant resources might not appear in | |||
stored in a link on the output resource with type DAV:source (see | the parent collection. An example for this case are servers that | |||
Section 13.10 for a description of the source link property). | support multiple alias URLs for each WebDAV compliant resource. A | |||
Storing the source URIs in links on the output resources places the | server may implement case-insensitive URLs, thus "/col/a" and | |||
burden of discovering the source on the authoring client. Note that | "/col/A" identify the same resource, yet only either "a" or "A" are | |||
the value of a source link is not guaranteed to point to the correct | reported upon listing the members of "/col". In cases where a server | |||
source. Source links may break or incorrect values may be entered. | treats a set of segments as equivalent, the server MUST expose only | |||
Also note that not all servers will allow the client to set the | one preferred segment per mapping, consistently chosen, in PROPFIND | |||
source link value. For example a server which generates source links | responses. | |||
on the fly for its CGI files will most likely not allow a client to | ||||
set the source link value. | ||||
6. Locking | 6. Locking | |||
The ability to lock a resource provides a mechanism for serializing | The ability to lock a resource provides a mechanism for serializing | |||
access to that resource. Using a lock, an authoring client can | access to that resource. Using a lock, an authoring client can | |||
provide a reasonable guarantee that another principal will not modify | provide a reasonable guarantee that another principal will not modify | |||
a resource while it is being edited. In this way, a client can | a resource while it is being edited. In this way, a client can | |||
prevent the "lost update" problem. | prevent the "lost update" problem. | |||
This specification allows locks to vary over two client-specified | This specification allows locks to vary over two client-specified | |||
parameters, the number of principals involved (exclusive vs. shared) | parameters, the number of principals involved (exclusive vs. shared) | |||
and the type of access to be granted. This document defines locking | and the type of access to be granted. This document defines locking | |||
for only one access type, write. However, the syntax is extensible, | for only one access type, write. However, the syntax is extensible, | |||
and permits the eventual specification of locking for other access | and permits the eventual specification of locking for other access | |||
types. | types. | |||
6.1. Exclusive Vs. Shared Locks | 6.1. Lock Model | |||
The most basic form of lock is an exclusive lock. This is a lock | This section provides a concise model for how locking behaves. Later | |||
where the access right in question is only granted to a single | sections will provide more detail on some of the concepts and refer | |||
principal. The need for this arbitration results from a desire to | back to these model statements. Normative statements related to LOCK | |||
avoid having to merge results. | and UNLOCK method handling can be found in the sections on those | |||
methods, whereas normative statements that cover any method are | ||||
gathered here. | ||||
1. A lock either directly or indirectly locks a resource. | ||||
2. A resource becomes directly locked when a LOCK request to a URL | ||||
of that resource creates a new lock. The "lock-root" of the new | ||||
lock is that URL. If at the time of the request, the URL is not | ||||
mapped to a resource, a new empty resource is created and | ||||
directly locked. | ||||
3. An exclusive lock (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 | ||||
a 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 (the Write Lock (Section 7) section 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. | ||||
6.2. Exclusive Vs. Shared Locks | ||||
The most basic form of lock is an exclusive lock. Exclusive locks | ||||
avoid having to deal with content change conflicts, without requiring | ||||
any coordination other than the methods described in this | ||||
specification. | ||||
However, there are times when the goal of a lock is not to exclude | However, there are times when the goal of a lock is not to exclude | |||
others from exercising an access right but rather to provide a | others from exercising an access right but rather to provide a | |||
mechanism for principals to indicate that they intend to exercise | mechanism for principals to indicate that they intend to exercise | |||
their access rights. Shared locks are provided for this case. A | their access rights. Shared locks are provided for this case. A | |||
shared lock allows multiple principals to receive a lock. Hence any | shared lock allows multiple principals to receive a lock. Hence any | |||
principal with appropriate access can get the lock. | principal that has both access privileges and a valid lock can use | |||
the locked resource. | ||||
With shared locks there are two trust sets that affect a resource. | With shared locks there are two trust sets that affect a resource. | |||
The first trust set is created by access permissions. Principals who | The first trust set is created by access permissions. Principals who | |||
are trusted, for example, may have permission to write to the | are trusted, for example, may have permission to write to the | |||
resource. Among those who have access permission to write to the | resource. Among those who have access permission to write to the | |||
resource, the set of principals who have taken out a shared lock also | resource, the set of principals who have taken out a shared lock also | |||
must trust each other, creating a (typically) smaller trust set | must trust each other, creating a (typically) smaller trust set | |||
within the access permission write set. | within the access permission write set. | |||
Starting with every possible principal on the Internet, in most | Starting with every possible principal on the Internet, in most | |||
skipping to change at page 15, line 42 ¶ | skipping to change at page 23, line 7 ¶ | |||
decide they trust their collaborators will not overwrite their work | decide they trust their collaborators will not overwrite their work | |||
(the potential set of collaborators being the set of principals who | (the potential set of collaborators being the set of principals who | |||
have write permission) and use a shared lock, which informs their | have write permission) and use a shared lock, which informs their | |||
collaborators that a principal may be working on the resource. | collaborators that a principal may be working on the resource. | |||
The WebDAV extensions to HTTP do not need to provide all of the | The WebDAV extensions to HTTP do not need to provide all of the | |||
communications paths necessary for principals to coordinate their | communications paths necessary for principals to coordinate their | |||
activities. When using shared locks, principals may use any out of | activities. When using shared locks, principals may use any out of | |||
band communication channel to coordinate their work (e.g., face-to- | band communication channel to coordinate their work (e.g., face-to- | |||
face interaction, written notes, post-it notes on the screen, | face interaction, written notes, post-it notes on the screen, | |||
telephone conversation, Email, etc.) The intent of a shared lock is | telephone conversation, email, etc.) The intent of a shared lock is | |||
to let collaborators know who else may be working on a resource. | to let collaborators know who else may be working on a resource. | |||
Shared locks are included because experience from web distributed | Shared locks are included because experience from web distributed | |||
authoring systems has indicated that exclusive locks are often too | authoring systems has indicated that exclusive locks are often too | |||
rigid. An exclusive lock is used to enforce a particular editing | rigid. An exclusive lock is used to enforce a particular editing | |||
process: take out an exclusive lock, read the resource, perform | process: take out an exclusive lock, read the resource, perform | |||
edits, write the resource, release the lock. This editing process | edits, write the resource, release the lock. This editing process | |||
has the problem that locks are not always properly released, for | has the problem that locks are not always properly released, for | |||
example when a program crashes, or when a lock owner leaves without | example when a program crashes, or when a lock creator leaves without | |||
unlocking a resource. While both timeouts and administrative action | unlocking a resource. While both timeouts (Section 6.6) and | |||
can be used to remove an offending lock, neither mechanism may be | administrative action can be used to remove an offending lock, | |||
available when needed; the timeout may be long or the administrator | neither mechanism may be available when needed; the timeout may be | |||
may not be available. | long or the administrator may not be available. | |||
6.2. Required Support | 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. | ||||
A WebDAV compliant server is not required to support locking in any | 6.3. Required Support | |||
form. If the server does support locking it may choose to support | ||||
A WebDAV compliant resource is not required to support locking in any | ||||
form. If the resource does support locking it may choose to support | ||||
any combination of exclusive and shared locks for any access types. | any combination of exclusive and shared locks for any access types. | |||
The reason for this flexibility is that locking policy strikes to the | The reason for this flexibility is that locking policy strikes to the | |||
very heart of the resource management and versioning systems employed | very heart of the resource management and versioning systems employed | |||
by various storage repositories. These repositories require control | by various storage repositories. These repositories require control | |||
over what sort of locking will be made available. For example, some | over what sort of locking will be made available. For example, some | |||
repositories only support shared write locks while others only | repositories only support shared write locks while others only | |||
provide support for exclusive write locks while yet others use no | provide support for exclusive write locks while yet others use no | |||
locking at all. As each system is sufficiently different to merit | locking at all. As each system is sufficiently different to merit | |||
exclusion of certain locking features, this specification leaves | exclusion of certain locking features, this specification leaves | |||
locking as the sole axis of negotiation within WebDAV. | locking as the sole axis of negotiation within WebDAV. | |||
6.3. Lock Tokens | 6.4. Lock Creator and Privileges | |||
A lock token is a type of state token, represented as a URI, which | ||||
identifies a particular lock. A lock token is returned by every | ||||
successful LOCK operation in the lockdiscovery property in the | ||||
response body, and can also be found through lock discovery on a | ||||
resource. | ||||
Lock token URIs MUST be unique across all resources for all time. | ||||
This uniqueness constraint allows lock tokens to be submitted across | ||||
resources and servers without fear of confusion. | ||||
This specification provides a lock token URI scheme called | ||||
opaquelocktoken that meets the uniqueness requirements. However | ||||
resources are free to return any URI scheme so long as it meets the | ||||
uniqueness requirements. | ||||
Having a lock token provides no special access rights. Anyone can | ||||
find out anyone else's lock token by performing lock discovery. | ||||
Locks MUST be enforced based upon whatever authentication mechanism | ||||
is used by the server, not based on the secrecy of the token values. | ||||
6.4. opaquelocktoken Lock Token URI Scheme | ||||
The opaquelocktoken URI scheme is designed to be unique across all | ||||
resources for all time. Due to this uniqueness quality, a client may | ||||
submit an opaque lock token in an If header on a resource other than | ||||
the one that returned it. | ||||
All resources MUST recognize the opaquelocktoken scheme and, at | ||||
minimum, recognize that the lock token does not refer to an | ||||
outstanding lock on the resource. | ||||
In order to guarantee uniqueness across all resources for all time | The creator of a lock has special privileges to use the lock to | |||
the opaquelocktoken requires the use of the Universal Unique | modify the resource. When a locked resource is modified, a server | |||
Identifier (UUID) mechanism, as described in [ISO-11578]. | MUST check that the authenticated principal matches the lock creator | |||
(in addition to checking for valid lock token submission). | ||||
Opaquelocktoken generators, however, have a choice of how they create | The server MAY allow privileged users other than the lock creator to | |||
these tokens. They can either generate a new UUID for every lock | destroy a lock (for example, the resource owner or an administrator). | |||
token they create or they can create a single UUID and then add | The 'unlock' privilege in [RFC3744] was defined to provide that | |||
extension characters. If the second method is selected then the | permission. | |||
program generating the extensions MUST guarantee that the same | ||||
extension will never be used twice with the associated UUID. | ||||
OpaqueLockToken-URI = "opaquelocktoken:" UUID [Extension] ; The UUID | There is no requirement for servers to accept LOCK requests from all | |||
production is the string representation of a UUID, as defined in | users or from anonymous users. | |||
[ISO-11578]. Note that white space (LWS) is not allowed between | ||||
elements of this production. | ||||
Extension = path ; path is defined in section 3.2.1 of RFC 2068 | Note that having a lock does not confer full privilege to modify the | |||
[RFC2068] | 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. | ||||
6.4.1. Node Field Generation Without the IEEE 802 Address | 6.5. Lock Tokens | |||
UUIDs, as defined in [ISO-11578], contain a "node" field that | A lock token is a type of state token which identifies a particular | |||
contains one of the IEEE 802 addresses for the server machine. As | lock. Each lock has exactly one unique lock token generated by the | |||
noted in Section 17.8, there are several security risks associated | server. Clients MUST NOT attempt to interpret lock tokens in any | |||
with exposing a machine's IEEE 802 address. This section provides an | way. | |||
alternate mechanism for generating the "node" field of a UUID which | ||||
does not employ an IEEE 802 address. WebDAV servers MAY use this | ||||
algorithm for creating the node field when generating UUIDs. The | ||||
text in this section is originally from an Internet-Draft by Paul | ||||
Leach and Rich Salz, who are noted here to properly attribute their | ||||
work. | ||||
The ideal solution is to obtain a 47 bit cryptographic quality random | Lock token URIs MUST be unique across all resources for all time. | |||
number, and use it as the low 47 bits of the node ID, with the most | This uniqueness constraint allows lock tokens to be submitted across | |||
significant bit of the first octet of the node ID set to 1. This bit | resources and servers without fear of confusion. Since lock tokens | |||
is the unicast/multicast bit, which will never be set in IEEE 802 | are unique, a client MAY submit a lock token in an If header on a | |||
addresses obtained from network cards; hence, there can never be a | resource other than the one that returned it. | |||
conflict between UUIDs generated by machines with and without network | ||||
cards. | ||||
If a system does not have a primitive to generate cryptographic | When a LOCK operation creates a new lock, the new lock token is | |||
quality random numbers, then in most systems there are usually a | returned in the Lock-Token response header defined in Section 10.5, | |||
fairly large number of sources of randomness available from which one | and also in the body of the response. | |||
can be generated. Such sources are system specific, but often | ||||
include: | ||||
o the percent of memory in use | 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. | ||||
o the size of main memory in bytes | This specification encourages servers to create 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. | ||||
o the amount of free main memory in bytes | Example: "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6" | |||
o the size of the paging or swap file in bytes | 6.6. Lock Timeout | |||
o free bytes of paging or swap file | A lock MAY have a limited lifetime. The lifetime is suggested by the | |||
client when creating or refreshing the lock, but the server | ||||
ultimately chooses the timeout value. Timeout is measured in seconds | ||||
remaining until lock expiration. | ||||
o the total size of user virtual address space in bytes | The timeout counter MUST be restarted if a refresh lock request is | |||
successful (see Section 9.10.2). The timeout counter SHOULD NOT be | ||||
restarted at any other time. | ||||
o the total available user address space bytes | 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. | ||||
o the size of boot disk drive in bytes | 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 off-line. | ||||
o the free disk space on boot drive in bytes | A client MUST NOT assume that just because the time-out has expired | |||
the lock has immediately been removed. | ||||
o the current time | Likewise, a client MUST NOT assume that just because the time-out 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. | ||||
o the amount of time since the system booted | 6.7. Lock Capability Discovery | |||
o the individual sizes of files in various system directories | Since server lock support is optional, a client trying to lock a | |||
resource on a server can either try the lock and hope for the best, | ||||
or perform some form of discovery to determine what lock capabilities | ||||
the server supports. This is known as lock capability discovery. A | ||||
client can determine what lock types the server supports by | ||||
retrieving the DAV:supportedlock property. | ||||
o the creation, last read, and modification times of files in | Any DAV compliant resource that supports the LOCK method MUST support | |||
various system directories | the DAV:supportedlock property. | |||
o the utilization factors of various system resources (heap, etc.) | 6.8. Active Lock Discovery | |||
o current mouse cursor position | If another principal locks a resource that a principal wishes to | |||
access, it is useful for the second principal to be able to find out | ||||
who the first principal is. For this purpose the DAV:lockdiscovery | ||||
property is provided. This property lists all outstanding locks, | ||||
describes their type, and MAY even provide the lock tokens. | ||||
o current caret position | Any DAV compliant resource that supports the LOCK method MUST support | |||
the DAV:lockdiscovery property. | ||||
o current number of running processes, threads | 7. Write Lock | |||
o handles or IDs of the desktop window and the active window | This section describes the semantics specific to the write lock type. | |||
The write lock is a specific instance of a lock type, and is the only | ||||
lock type described in this specification. | ||||
o the value of stack pointer of the caller | An exclusive write lock protects a resource: it prevents changes by | |||
any principal other than the lock creator and in any case where the | ||||
lock token is not submitted (e.g. by a client process other than the | ||||
one holding the lock). | ||||
o the process and thread ID of caller | Clients MUST submit a lock-token they are authorized to use in any | |||
request which modifies a write-locked resource. The list of | ||||
modifications covered by a write-lock include: | ||||
o various processor architecture specific performance counters | 1. A change to any of the following aspects of any write-locked | |||
(instructions executed, cache misses, TLB misses) | resource: | |||
(Note that it is precisely the above kinds of sources of randomness | * any variant, | |||
that are used to seed cryptographic quality random number generators | ||||
on systems without special hardware for their construction.) | ||||
In addition, items such as the computer's name and the name of the | * any dead property, | |||
operating system, while not strictly speaking random, will help | ||||
differentiate the results from those obtained by other systems. | ||||
The exact algorithm to generate a node ID using these data is system | * any live property which is lockable (a live property is | |||
specific, because both the data available and the functions to obtain | lockable unless otherwise defined.) | |||
them are often very system specific. However, assuming that one can | ||||
concatenate all the values from the randomness sources into a buffer, | ||||
and that a cryptographic hash function such as MD5 is available, then | ||||
any 6 bytes of the MD5 hash of the buffer, with the multicast bit | ||||
(the high bit of the first byte) set will be an appropriately random | ||||
node ID. | ||||
Other hash functions, such as SHA-1, can also be used. The only | 2. For collections, any modification of an internal member URI. An | |||
requirement is that the result be suitably random _ in the sense that | internal member URI of a collection is considered to be modified | |||
the outputs from a set uniformly distributed inputs are themselves | if it is added, removed, or identifies a different resource. | |||
uniformly distributed, and that a single bit change in the input can | More discussion on write locks and collections is found in | |||
be expected to cause half of the output bits to change. | Section 7.4. | |||
6.5. Lock Capability Discovery | 3. A modification of the mapping of the root of the write lock, | |||
either to another resource or to no resource (e.g. DELETE). | ||||
Since server lock support is optional, a client trying to lock a | Of the methods defined in HTTP and WebDAV, PUT, POST, PROPPATCH, | |||
resource on a server can either try the lock and hope for the best, | LOCK, UNLOCK, MOVE, COPY (for the destination resource), DELETE, and | |||
or perform some form of discovery to determine what lock capabilities | MKCOL are affected by write locks. All other HTTP/WebDAV methods | |||
the server supports. This is known as lock capability discovery. | defined so far, GET in particular, function independently of a write | |||
Lock capability discovery differs from discovery of supported access | lock. | |||
control types, since there may be access control types without | ||||
corresponding lock types. A client can determine what lock types the | ||||
server supports by retrieving the supportedlock property. | ||||
Any DAV compliant resource that supports the LOCK method MUST support | The next few sections describe in more specific terms how write locks | |||
the supportedlock property. | interact with various operations. | |||
6.6. Active Lock Discovery | 7.1. Write Locks and Properties | |||
If another principal locks a resource that a principal wishes to | While those without a write lock may not alter a property on a | |||
access, it is useful for the second principal to be able to find out | resource it is still possible for the values of live properties to | |||
who the first principal is. For this purpose the lockdiscovery | change, even while locked, due to the requirements of their schemas. | |||
property is provided. This property lists all outstanding locks, | ||||
describes their type, and where available, provides their lock token. | ||||
Any DAV compliant resource that supports the LOCK method MUST support | Only dead properties and live properties defined as lockable are | |||
the lockdiscovery property. | guaranteed not to change while write locked. | |||
6.7. Usage Considerations | 7.2. Avoiding Lost Updates | |||
Although the locking mechanisms specified here provide some help in | Although the write locks provide some help in preventing lost | |||
preventing lost updates, they cannot guarantee that updates will | updates, they cannot guarantee that updates will never be lost. | |||
never be lost. Consider the following scenario: | Consider the following scenario: | |||
Two clients A and B are interested in editing the resource ' | Two clients A and B are interested in editing the resource | |||
index.html'. Client A is an HTTP client rather than a WebDAV client, | 'index.html'. Client A is an HTTP client rather than a WebDAV | |||
and so does not know how to perform locking. | client, and so does not know how to perform locking. | |||
Client A doesn't lock the document, but does a GET and begins | Client A doesn't lock the document, but does a GET and begins | |||
editing. | editing. | |||
Client B does LOCK, performs a GET and begins editing. | Client B does LOCK, performs a GET and begins editing. | |||
Client B finishes editing, performs a PUT, then an UNLOCK. | Client B finishes editing, performs a PUT, then an UNLOCK. | |||
Client A performs a PUT, overwriting and losing all of B's changes. | Client A performs a PUT, overwriting and losing all of B's changes. | |||
skipping to change at page 21, line 5 ¶ | skipping to change at page 29, line 5 ¶ | |||
they interact with a WebDAV server that supports locking. | they interact with a WebDAV server that supports locking. | |||
HTTP 1.1 clients can be good citizens, avoiding overwriting other | HTTP 1.1 clients can be good citizens, avoiding overwriting other | |||
clients' changes, by using entity tags in If-Match headers with any | clients' changes, by using entity tags in If-Match headers with any | |||
requests that would modify resources. | requests that would modify resources. | |||
Information managers may attempt to prevent overwrites by | Information managers may attempt to prevent overwrites by | |||
implementing client-side procedures requiring locking before | implementing client-side procedures requiring locking before | |||
modifying WebDAV resources. | modifying WebDAV resources. | |||
7. Write Lock | 7.3. Write Locks and Unmapped URLs | |||
This section describes the semantics specific to the write lock type. | WebDAV provides the ability to send a LOCK request to an unmapped URL | |||
The write lock is a specific instance of a lock type, and is the only | in order to reserve the name for use. This is a simple way to avoid | |||
lock type described in this specification. | the lost-update problem on the creation of a new resource (another | |||
way is to use If-None-Match header specified in Section 14.26 of | ||||
[RFC2616]). It has the side benefit of locking the new resource | ||||
immediately for use of the creator. | ||||
7.1. Methods Restricted by Write Locks | 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 write lock MUST prevent a principal without the lock from | A successful lock request to an unmapped URL MUST result in the | |||
successfully executing a PUT, POST, PROPPATCH, LOCK, UNLOCK, MOVE, | creation of a locked (non-collection) resource with empty content. | |||
DELETE, or MKCOL on the locked resource. All other current methods, | Subsequently, a successful PUT request (with the correct lock token) | |||
GET in particular, function independently of the lock. | 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. | ||||
Note, however, that as new methods are created it will be necessary | A resource created with a LOCK is empty but otherwise behaves in | |||
to specify how they interact with a write lock. | 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: | ||||
7.2. Write Locks and Lock Tokens | o Can be read, deleted, moved, copied, and in all ways behave as a | |||
regular non-collection resource. | ||||
A successful request for an exclusive or shared write lock MUST | o Appears as a member of its parent collection. | |||
result in the generation of a unique lock token associated with the | ||||
requesting principal. Thus if five principals have a shared write | ||||
lock on the same resource there will be five lock tokens, one for | ||||
each principal. | ||||
7.3. Write Locks and Properties | 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) | ||||
While those without a write lock may not alter a property on a | o MAY NOT have values for properties like DAV:getcontentlanguage | |||
resource it is still possible for the values of live properties to | which haven't been specified yet by the client. | |||
change, even while locked, due to the requirements of their schemas. | ||||
Only dead properties and live properties defined to respect locks are | ||||
guaranteed not to change while write locked. | ||||
7.4. Write Locks and Null Resources | o Can be updated (have content added) with a PUT request. | |||
It is possible to assert a write lock on a null resource in order to | o MUST NOT be converted into a collection. The server MUST fail a | |||
lock the name. | MKCOL request (as it would with a MKCOL request to any existing | |||
non-collection resource). | ||||
A write locked null resource, referred to as a lock-null resource, | o MUST have defined values for DAV:lockdiscovery and DAV: | |||
MUST respond with a 404 (Not Found) or 405 (Method Not Allowed) to | supportedlock properties. | |||
any HTTP/1.1 or DAV methods except for PUT, MKCOL, OPTIONS, PROPFIND, | ||||
LOCK, and UNLOCK. A lock-null resource MUST appear as a member of | ||||
its parent collection. Additionally the lock-null resource MUST have | ||||
defined on it all mandatory DAV properties. Most of these | ||||
properties, such as all the get* properties, will have no value as a | ||||
lock-null resource does not support the GET method. Lock-Null | ||||
resources MUST have defined values for lockdiscovery and | ||||
supportedlock properties. | ||||
Until a method such as PUT or MKCOL is successfully executed on the | o The response MUST indicate that a resource was created, by use of | |||
lock-null resource the resource MUST stay in the lock-null state. | the "201 Created" response code (a LOCK request to an existing | |||
However, once a PUT or MKCOL is successfully executed on a lock-null | resource instead will result in 200 OK). The body must still | |||
resource the resource ceases to be in the lock-null state. | include the DAV:lockdiscovery property, as with a LOCK request to | |||
an existing resource. | ||||
If the resource is unlocked, for any reason, without a PUT, MKCOL, or | The client is expected to update the locked empty resource shortly | |||
similar method having been successfully executed upon it then the | after locking it, using PUT and possibly PROPPATCH. | |||
resource MUST return to the null state. | ||||
7.5. Write Locks and Collections | 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. | ||||
A write lock on a collection, whether created by a "Depth: 0" or | 7.4. Write Locks and Collections | |||
"Depth: infinity" lock request, prevents the addition or removal of | ||||
member URIs of the collection by non-lock owners. As a consequence, | ||||
when a principal issues a PUT or POST request to create a new | ||||
resource under a URI which needs to be an internal member of a write | ||||
locked collection to maintain HTTP namespace consistency, or issues a | ||||
DELETE to remove a resource which has a URI which is an existing | ||||
internal member URI of a write locked collection, this request MUST | ||||
fail if the principal does not have a write lock on the collection. | ||||
However, if a write lock request is issued to a collection containing | There are two kinds of collection write locks. A depth-0 write lock | |||
member URIs identifying resources that are currently locked in a | on a collection protects the collection properties plus the internal | |||
manner which conflicts with the write lock, the request MUST fail | member URLs of that one collection, while not protecting the content | |||
with a 423 (Locked) status code. | or properties of member resources (if the collection itself has any | |||
entity bodies, those are also protected). A depth-infinity write | ||||
lock on a collection provides the same protection on that collection | ||||
and also provides write lock protection on every member resource. | ||||
If a lock owner causes the URI of a resource to be added as an | Expressed otherwise, a write lock protects any request that would | |||
internal member URI of a locked collection then the new resource MUST | create a new resource in a write locked collection, any request that | |||
be automatically added to the lock. This is the only mechanism that | would remove an internal member URL of a write locked collection, and | |||
allows a resource to be added to a write lock. Thus, for example, if | any request that would change the segment name of any internal | |||
the collection /a/b/ is write locked and the resource /c is moved to | member. | |||
/a/b/c then resource /a/b/c will be added to the write lock. | ||||
7.6. Write Locks and the If Request Header | Thus, a collection write lock protects all the following actions: | |||
If a user agent is not required to have knowledge about a lock when | o DELETE a collection's direct internal member, | |||
requesting an operation on a locked resource, the following scenario | ||||
might occur. Program A, run by User A, takes out a write lock on a | o MOVE an internal member out of the collection, | |||
resource. Program B, also run by User A, has no knowledge of the | ||||
lock taken out by Program A, yet performs a PUT to the locked | o MOVE an internal member into the collection, | |||
resource. In this scenario, the PUT succeeds because locks are | ||||
associated with a principal, not a program, and thus program B, | o MOVE to rename an internal member within a collection, | |||
because it is acting with principal A's credential, is allowed to | o COPY an internal member into a collection, and | |||
perform the PUT. However, had program B known about the lock, it | ||||
would not have overwritten the resource, preferring instead to | o PUT or MKCOL request which would create a new internal member. | |||
present a dialog box describing the conflict to the user. Due to | ||||
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 descendent 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 which 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. | ||||
7.5. Write Locks and the If Request Header | ||||
A user agent has to demonstrate knowledge of a lock when requesting | ||||
an operation on a locked resource. Otherwise, the following scenario | ||||
might occur. In the scenario, program A, run by User A, takes out a | ||||
write lock on a resource. Program B, also run by User A, has no | ||||
knowledge of the lock taken out by program A, yet performs a PUT to | ||||
the locked resource. In this scenario, the PUT succeeds because | ||||
locks are associated with a principal, not a program, and thus | ||||
program B, because it is acting with principal A's credential, is | ||||
allowed to perform the PUT. However, had program B known about the | ||||
lock, it would not have overwritten the resource, preferring instead | ||||
to present a dialog box describing the conflict to the user. Due to | ||||
this scenario, a mechanism is needed to prevent different programs | this scenario, a mechanism is needed to prevent different programs | |||
from accidentally ignoring locks taken out by other programs with the | from accidentally ignoring locks taken out by other programs with the | |||
same authorization. | same authorization. | |||
In order to prevent these collisions a lock token MUST be submitted | In order to prevent these collisions a lock token MUST be submitted | |||
by an authorized principal in the If header for all locked resources | by an authorized principal for all locked resources that a method may | |||
that a method may interact with or the method MUST fail. For | change or the method MUST fail. A lock token is submitted when it | |||
example, if a resource is to be moved and both the source and | appears in an If header. For example, if a resource is to be moved | |||
destination are locked then two lock tokens must be submitted, one | and both the source and destination are locked then two lock tokens | |||
for the source and the other for the destination. | must be submitted in the If header, one for the source and the other | |||
for the destination. | ||||
7.6.1. Example - Write Lock | 7.5.1. Example - Write Lock and COPY | |||
>>Request | >>Request | |||
COPY /~fielding/index.html HTTP/1.1 | COPY /~fielding/index.html HTTP/1.1 | |||
Host: www.ics.uci.edu | Host: www.example.com | |||
Destination: http://www.ics.uci.edu/users/f/fielding/index.html | Destination: http://www.example.com/users/f/fielding/index.html | |||
If: <http://www.ics.uci.edu/users/f/fielding/index.html> | If: <http://www.example.com/users/f/fielding/index.html> | |||
(<opaquelocktoken:f81d4fae-7dec-11d0-a765-00a0c91e6bf6>) | (<urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6>) | |||
␉ | ||||
>>Response | >>Response | |||
HTTP/1.1 204 No Content | HTTP/1.1 204 No Content | |||
In this example, even though both the source and destination are | In this example, even though both the source and destination are | |||
locked, only one lock token must be submitted, for the lock on the | locked, only one lock token must be submitted, for the lock on the | |||
destination. This is because the source resource is not modified by | destination. This is because the source resource is not modified by | |||
a COPY, and hence unaffected by the write lock. In this example, | a COPY, and hence unaffected by the write lock. In this example, | |||
user agent authentication has previously occurred via a mechanism | user agent authentication has previously occurred via a mechanism | |||
outside the scope of the HTTP protocol, in the underlying transport | outside the scope of the HTTP protocol, in the underlying transport | |||
layer. | layer. | |||
7.7. Write Locks and COPY/MOVE | 7.5.2. Example - Deleting a Member of a Locked Collection | |||
Consider a collection "/locked" with an exclusive, depth-infinity | ||||
write lock, and an attempt to delete an internal member "/locked/ | ||||
member": | ||||
>>Request | ||||
DELETE /locked/member HTTP/1.1 | ||||
Host: example.com | ||||
>>Response | ||||
HTTP/1.1 423 Locked | ||||
Content-Type: application/xml; charset="utf-8" | ||||
Content-Length: xxxx | ||||
<?xml version="1.0" encoding="utf-8" ?> | ||||
<D:error xmlns:D="DAV:"> | ||||
<D:lock-token-submitted> | ||||
<D:href>/locked/</D:href> | ||||
</D:lock-token-submitted> | ||||
</D:error> | ||||
Thus the client would need to submit the lock token with the request | ||||
to make it succeed. To do that, various forms of the If header (see | ||||
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. | ||||
7.6. Write Locks and COPY/MOVE | ||||
A COPY method invocation MUST NOT duplicate any write locks active on | A COPY method invocation MUST NOT duplicate any write locks active on | |||
the source. However, as previously noted, if the COPY copies the | the source. However, as previously noted, if the COPY copies the | |||
resource into a collection that is locked with "Depth: infinity", | resource into a collection that is locked with a depth-infinity lock, | |||
then the resource will be added to the lock. | then the resource will be added to the lock. | |||
A successful MOVE request on a write locked resource MUST NOT move | A successful MOVE request on a write locked resource MUST NOT move | |||
the write lock with the resource. However, the resource is subject | the write lock with the resource. However, if there is an existing | |||
to being added to an existing lock at the destination, as specified | lock at the destination, the server MUST add the moved resource to | |||
in Section 7.5. For example, if the MOVE makes the resource a child | the destination lock scope. For example, if the MOVE makes the | |||
of a collection that is locked with "Depth: infinity", then the | resource a child of a collection that has a depth-infinity lock, then | |||
resource will be added to that collection's lock. Additionally, if a | the resource will be added to that collection's lock. Additionally, | |||
resource locked with "Depth: infinity" is moved to a destination that | if a resource with a depth-infinity lock is moved to a destination | |||
is within the scope of the same lock (e.g., within the namespace tree | that is within the scope of the same lock (e.g., within the URL | |||
covered by the lock), the moved resource will again be a added to the | namespace tree covered by the lock), the moved resource will again be | |||
lock. In both these examples, as specified in Section 7.6, an If | a added to the lock. In both these examples, as specified in | |||
header must be submitted containing a lock token for both the source | Section 7.5, an If header must be submitted containing a lock token | |||
and destination. | for both the source and destination. | |||
7.8. Refreshing Write Locks | 7.7. Refreshing Write Locks | |||
A client MUST NOT submit the same write lock request twice. Note | A client MUST NOT submit the same write lock request twice. Note | |||
that a client is always aware it is resubmitting the same lock | that a client is always aware it is resubmitting the same lock | |||
request because it must include the lock token in the If header in | request because it must include the lock token in the If header in | |||
order to make the request for a resource that is already locked. | order to make the request for a resource that is already locked. | |||
However, a client may submit a LOCK method with an If header but | However, a client may submit a LOCK request with an If header but | |||
without a body. This form of LOCK MUST only be used to "refresh" a | without a body. A server receiving a LOCK request with no body MUST | |||
lock. Meaning, at minimum, that any timers associated with the lock | NOT create a new lock -- this form of the LOCK request is only to be | |||
MUST be re-set. | used to "refresh" an existing lock (meaning, at minimum, that any | |||
timers associated with the lock MUST be re-set). | ||||
A server may return a Timeout header with a lock refresh that is | Clients may submit Timeout headers of arbitrary value with their lock | |||
different than the Timeout header returned when the lock was | refresh requests. Servers, as always, may ignore Timeout headers | |||
originally requested. Additionally clients may submit Timeout | submitted by the client, and a server MAY refresh a lock with a | |||
headers of arbitrary value with their lock refresh requests. | timeout period that is different than the previous timeout period | |||
Servers, as always, may ignore Timeout headers submitted by the | used for the lock, provided it advertises the new value in the LOCK | |||
client. | refresh response. | |||
If an error is received in response to a refresh LOCK request the | If an error is received in response to a refresh LOCK request the | |||
client SHOULD assume that the lock was not refreshed. | client MUST NOT assume that the lock was refreshed. | |||
8. HTTP Methods for Distributed Authoring | 8. General Request and Response Handling | |||
The following new HTTP methods use XML as a request and response | 8.1. Precedence in Error Handling | |||
format. All DAV compliant clients and resources MUST use XML parsers | ||||
that are compliant with [REC-XML]. All XML used in either requests | ||||
or responses MUST be, at minimum, well formed. If a server receives | ||||
ill-formed XML in a request it MUST reject the entire request with a | ||||
400 (Bad Request). If a client receives ill-formed XML in a response | ||||
then it MUST NOT assume anything about the outcome of the executed | ||||
method and SHOULD treat the server as malfunctioning. | ||||
8.1. PROPFIND | Servers MUST return authorization errors in preference to other | |||
errors. This avoids leaking information about protected resources | ||||
(e.g. a client that finds that a hidden resource exists by seeing a | ||||
423 Locked response to an anonymous request to the resource). | ||||
8.2. Use of XML | ||||
In HTTP/1.1, method parameter information was exclusively encoded in | ||||
HTTP headers. Unlike HTTP/1.1, WebDAV encodes method parameter | ||||
information either in an XML ([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. | ||||
8.3. URL Handling | ||||
URLs appear in many places in requests and responses. | ||||
Interoperability experience with [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 | ||||
Section 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. | ||||
8.3.1. Example - Correct URL Handling | ||||
Consider the collection http://example.com/sample/ with the internal | ||||
member URL http://example.com/sample/a%20test and the PROPFIND | ||||
request below: | ||||
>>Request: | ||||
PROPFIND /sample/ HTTP/1.1 | ||||
Host: example.com | ||||
Depth: 1 | ||||
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. | ||||
8.4. Required Bodies in Requests | ||||
Some of these new methods do not define bodies. Servers MUST examine | ||||
all requests for a body, even when a body was not expected. In cases | ||||
where a request body is present but would be ignored by a server, the | ||||
server MUST reject the request with 415 (Unsupported Media Type). | ||||
This informs the client (which may have been attempting to use an | ||||
extension) that the body could not be processed as the client | ||||
intended. | ||||
8.5. HTTP Headers for use in WebDAV | ||||
HTTP defines many headers that can be used in WebDAV requests and | ||||
responses. Not all of these are appropriate in all situations and | ||||
some interactions may be undefined. Note that HTTP 1.1 requires the | ||||
Date header in all responses if possible (see Section 14.18, | ||||
[RFC2616]). | ||||
The server MUST do authorization checks before checking any HTTP | ||||
conditional header. | ||||
8.6. ETag | ||||
HTTP 1.1 recommends the use of ETags rather than modification dates, | ||||
for cache-control, and there are even stronger reasons to prefer | ||||
ETags for authoring. Correct use of ETags is even more important in | ||||
a distributed authoring environment, because ETags are necessary | ||||
along with locks to avoid the lost-update problem. A client might | ||||
fail to renew a lock, for example when the lock times out and the | ||||
client is accidentally offline or in the middle of a long upload. | ||||
When a client fails to renew the lock, it's quite possible the | ||||
resource can still be relocked and the user can go on editing, as | ||||
long as no changes were made in the meantime. ETags are required for | ||||
the client to be able to distinguish this case. Otherwise, the | ||||
client is forced to ask the user whether to overwrite the resource on | ||||
the server without even being able to tell the user whether 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 RFC2616 (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. | ||||
8.7. Including Error Response Bodies | ||||
HTTP and WebDAV did not use the bodies of most error responses for | ||||
machine-parsable information until the specification for Versioning | ||||
Extensions to WebDAV introduced a mechanism to include more specific | ||||
information in the body of an error response (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. | ||||
8.8. Impact of Namespace Operations on Cache Validators | ||||
Note that the HTTP response headers "Etag" and "Last-Modified" (see | ||||
[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 re-used 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 similarily, 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. | ||||
9. HTTP Methods for Distributed Authoring | ||||
9.1. PROPFIND Method | ||||
The PROPFIND method retrieves properties defined on the resource | The PROPFIND method retrieves properties defined on the resource | |||
identified by the Request-URI, if the resource does not have any | identified by the Request-URI, if the resource does not have any | |||
internal members, or on the resource identified by the Request-URI | internal members, or on the resource identified by the Request-URI | |||
and potentially its member resources, if the resource is a collection | and potentially its member resources, if the resource is a collection | |||
that has internal member URIs. All DAV compliant resources MUST | that has internal member URLs. All DAV compliant resources MUST | |||
support the PROPFIND method and the propfind XML element (section | support the PROPFIND method and the propfind XML element | |||
12.14) along with all XML elements defined for use with that element. | (Section 14.20) along with all XML elements defined for use with that | |||
element. | ||||
A client may submit a Depth header with a value of "0", "1", or | A client MUST submit a Depth header with a value of "0", "1", or | |||
"infinity" with a PROPFIND on a collection resource with internal | "infinity" with a PROPFIND request. Servers MUST support "0" and "1" | |||
member URIs. DAV compliant servers MUST support the "0", "1" and | depth requests on WebDAV-compliant resources and SHOULD support | |||
"infinity" behaviors. By default, the PROPFIND method without a | "infinity" requests. In practice, support for infinite depth | |||
Depth header MUST act as if a "Depth: infinity" header was included. | requests MAY be disabled, due to the performance and security | |||
concerns associated with this behavior. Since clients weren't | ||||
required to include the Depth header in [RFC2518], servers SHOULD | ||||
treat such a request as if a "Depth: infinity" header was included. | ||||
A client may submit a propfind XML element in the body of the request | A client may submit a 'propfind' XML element in the body of the | |||
method describing what information is being requested. It is | request method describing what information is being requested. It is | |||
possible to request particular property values, all property values, | possible to: | |||
or a list of the names of the resource's properties. A client may | ||||
choose not to submit a request body. An empty PROPFIND request body | o Request particular property values, by naming the properties | |||
MUST be treated as a request for the names and values of all | desired within the 'prop' element (the ordering of properties in | |||
properties. | here MAY be ignored by 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 that live property | ||||
would be returned in 'allprop' requests or not. | ||||
All servers MUST support returning a response of content type text/ | All servers MUST support returning a response of content type text/ | |||
xml or application/xml that contains a multistatus XML element that | xml or application/xml that contains a multistatus XML element that | |||
describes the results of the attempts to retrieve the various | describes the results of the attempts to retrieve the various | |||
properties. | properties. | |||
If there is an error retrieving a property then a proper error result | 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 | MUST be included in the response. A request to retrieve the value of | |||
a property which does not exist is an error and MUST be noted, if the | a property which does not exist is an error and MUST be noted with a | |||
response uses a multistatus XML element, with a response XML element | 'response' XML element which contains a 404 (Not Found) status value. | |||
which contains a 404 (Not Found) status value. | ||||
Consequently, the multistatus XML element for a collection resource | Consequently, the 'multistatus' XML element for a collection resource | |||
with member URIs MUST include a response XML element for each member | MUST include a 'response' XML element for each member URL of the | |||
URI of the collection, to whatever depth was requested. Each | collection, to whatever depth was requested. It SHOULD NOT include | |||
response XML element MUST contain an href XML element that gives the | any 'response' elements for resources that are not WebDAV-compliant. | |||
URI of the resource on which the properties in the prop XML element | Each 'response' element MUST contain an 'href' element that contains | |||
are defined. Results for a PROPFIND on a collection resource with | the URL of the resource on which the properties in the prop XML | |||
internal member URIs are returned as a flat list whose order of | element are defined. Results for a PROPFIND on a collection resource | |||
entries is not significant. | 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. | ||||
In the case of allprop and propname, if a principal does not have the | 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 | right to know whether a particular property exists then the property | |||
should be silently excluded from the response. | MAY be silently excluded from the response. | |||
The results of this method SHOULD NOT be cached. | 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]). | ||||
8.1.1. Example - Retrieving Named Properties | 9.1.1. PROPFIND Status Codes | |||
>>Request | This section, as with similar sections for other methods, provides | |||
some guidance on error codes and preconditions or postconditions | ||||
(defined in Section 16) that might be particularly useful with | ||||
PROPFIND. | ||||
PROPFIND /file HTTP/1.1 | 403 Forbidden - A server MAY reject PROPFIND requests on collections | |||
Host: www.foo.bar | with depth header of "Infinity", in which case it SHOULD use this | |||
Content-type: text/xml; charset="utf-8" | error with the precondition code 'propfind-finite-depth' inside the | |||
Content-Length: xxxx | error body. | |||
<?xml version="1.0" encoding="utf-8" ?> | 9.1.2. Status Codes for Use in 'propstat' Element | |||
<D:propfind xmlns:D="DAV:"> | ||||
<D:prop xmlns:R="http://www.foo.bar/boxschema/"> | ||||
<R:bigbox/> | ||||
<R:author/> | ||||
<R:DingALing/> | ||||
<R:Random/> | ||||
</D:prop> | ||||
</D:propfind> | ||||
>>Response | In PROPFIND 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. | ||||
HTTP/1.1 207 Multi-Status | 200 OK - A property exists and/or its value is successfully returned. | |||
Content-Type: text/xml; charset="utf-8" | ||||
Content-Length: xxxx | ||||
<?xml version="1.0" encoding="utf-8" ?> | 401 Unauthorized - The property cannot be viewed without appropriate | |||
<D:multistatus xmlns:D="DAV:"> | authorization. | |||
<D:response> | ||||
<D:href>http://www.foo.bar/file</D:href> | ||||
<D:propstat> | ||||
<D:prop xmlns:R="http://www.foo.bar/boxschema/"> | ||||
<R:bigbox> | ||||
<R:BoxType>Box type A</R:BoxType> | ||||
</R:bigbox> | ||||
<R:author> | ||||
<R:Name>J.J. Johnson</R:Name> | ||||
</R:author> | ||||
</D:prop> | ||||
<D:status>HTTP/1.1 200 OK</D:status> | ||||
</D:propstat> | ||||
<D:propstat> | ||||
<D:prop><R:DingALing/><R:Random/></D:prop> | ||||
<D:status>HTTP/1.1 403 Forbidden</D:status> | ||||
<D:responsedescription> The user does not have access to | ||||
the DingALing property. | ||||
</D:responsedescription> | ||||
</D:propstat> | ||||
</D:response> | ||||
<D:responsedescription> There has been an access violation error. | ||||
</D:responsedescription> | ||||
</D:multistatus> | ||||
In this example, PROPFIND is executed on a non-collection resource | 403 Forbidden - The property cannot be viewed regardless of | |||
http://www.foo.bar/file. The propfind XML element specifies the name | authentication. | |||
of four properties whose values are being requested. In this case | ||||
only two properties were returned, since the principal issuing the | ||||
request did not have sufficient access rights to see the third and | ||||
fourth properties. | ||||
8.1.2. Example - Using allprop to Retrieve All Properties | 404 Not Found - The property does not exist. | |||
9.1.3. Example - Retrieving Named Properties | ||||
>>Request | >>Request | |||
PROPFIND /container/ HTTP/1.1 | PROPFIND /file HTTP/1.1 | |||
Host: www.foo.bar | Host: www.example.com | |||
Depth: 1 | Content-type: application/xml; charset="utf-8" | |||
Content-Type: text/xml; charset="utf-8" | Content-Length: xxxx | |||
Content-Length: xxxx | ||||
<?xml version="1.0" encoding="utf-8" ?> | <?xml version="1.0" encoding="utf-8" ?> | |||
<D:propfind xmlns:D="DAV:"> | <D:propfind xmlns:D="DAV:"> | |||
<D:allprop/> | <D:prop xmlns:R="http://ns.example.com/boxschema/"> | |||
</D:propfind> | <R:bigbox/> | |||
<R:author/> | ||||
<R:DingALing/> | ||||
<R:Random/> | ||||
</D:prop> | ||||
</D:propfind> | ||||
>>Response | >>Response | |||
HTTP/1.1 207 Multi-Status | HTTP/1.1 207 Multi-Status | |||
Content-Type: text/xml; charset="utf-8" | Content-Type: application/xml; charset="utf-8" | |||
Content-Length: xxxx | Content-Length: xxxx | |||
<?xml version="1.0" encoding="utf-8" ?> | <?xml version="1.0" encoding="utf-8" ?> | |||
<D:multistatus xmlns:D="DAV:"> | <D:multistatus xmlns:D="DAV:"> | |||
<D:response> | <D:response xmlns:R="http://ns.example.com/boxschema/"> | |||
<D:href>http://www.foo.bar/container/</D:href> | <D:href>http://www.example.com/file</D:href> | |||
<D:propstat> | <D:propstat> | |||
<D:prop xmlns:R="http://www.foo.bar/boxschema/"> | <D:prop> | |||
<R:bigbox> | <R:bigbox> | |||
<R:BoxType>Box type A</R:BoxType> | <R:BoxType>Box type A</R:BoxType> | |||
</R:bigbox> | </R:bigbox> | |||
<R:author> | <R:author> | |||
<R:Name>Hadrian</R:Name> | <R:Name>J.J. Johnson</R:Name> | |||
</R:author> | </R:author> | |||
<D:creationdate> | </D:prop> | |||
1997-12-01T17:42:21-08:00 | <D:status>HTTP/1.1 200 OK</D:status> | |||
</D:creationdate> | </D:propstat> | |||
<D:displayname> | <D:propstat> | |||
Example collection | <D:prop><R:DingALing/><R:Random/></D:prop> | |||
</D:displayname> | <D:status>HTTP/1.1 403 Forbidden</D:status> | |||
<D:resourcetype><D:collection/></D:resourcetype> | <D:responsedescription> The user does not have access to the | |||
<D:supportedlock> | DingALing property. | |||
<D:lockentry> | </D:responsedescription> | |||
<D:lockscope><D:exclusive/></D:lockscope> | </D:propstat> | |||
<D:locktype><D:write/></D:locktype> | </D:response> | |||
</D:lockentry> | <D:responsedescription> There has been an access violation error. | |||
<D:lockentry> | </D:responsedescription> | |||
<D:lockscope><D:shared/></D:lockscope> | </D:multistatus> | |||
<D:locktype><D:write/></D:locktype> | ||||
</D:lockentry> | In this example, PROPFIND is executed on a non-collection resource | |||
</D:supportedlock> | http://www.example.com/file. The propfind XML element specifies the | |||
</D:prop> | name of four properties whose values are being requested. In this | |||
<D:status>HTTP/1.1 200 OK</D:status> | case only two properties were returned, since the principal issuing | |||
</D:propstat> | the request did not have sufficient access rights to see the third | |||
</D:response> | and fourth properties. | |||
<D:response> | ||||
<D:href>http://www.foo.bar/container/front.html</D:href> | ||||
<D:propstat> | ||||
<D:prop xmlns:R="http://www.foo.bar/boxschema/"> | ||||
<R:bigbox> | ||||
<R:BoxType>Box type B</R:BoxType> | ||||
</R:bigbox> | ||||
<D:creationdate> | ||||
1997-12-01T18:27:21-08:00 | ||||
</D:creationdate> | ||||
<D:displayname> | ||||
Example HTML resource | ||||
</D:displayname> | ||||
<D:getcontentlength> | ||||
4525 | ||||
</D:getcontentlength> | ||||
<D:getcontenttype> | ||||
text/html | ||||
</D:getcontenttype> | ||||
<D:getetag> | ||||
zzyzx | ||||
</D:getetag> | ||||
<D:getlastmodified> | ||||
Monday, 12-Jan-98 09:25:56 GMT | ||||
</D:getlastmodified> | ||||
<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 | 9.1.4. Example - Using 'propname' to Retrieve All Property Names | |||
http://www.foo.bar/container/ with a Depth header of 1, meaning the | ||||
request applies to the resource and its children, and a propfind XML | ||||
element containing the allprop XML element, meaning the request | ||||
should return the name and value of all properties defined on each | ||||
resource. | ||||
The resource http://www.foo.bar/container/ has six properties defined | >>Request | |||
on it: | ||||
http://www.foo.bar/boxschema/bigbox, | PROPFIND /container/ HTTP/1.1 | |||
http://www.foo.bar/boxschema/author, DAV:creationdate, DAV: | Host: www.example.com | |||
displayname, DAV:resourcetype, and DAV:supportedlock. | Content-Type: application/xml; charset="utf-8" | |||
Content-Length: xxxx | ||||
The last four properties are WebDAV-specific, defined in Section 13. | <?xml version="1.0" encoding="utf-8" ?> | |||
Since GET is not supported on this resource, the get* properties | <propfind xmlns="DAV:"> | |||
(e.g., getcontentlength) are not defined on this resource. The DAV- | <propname/> | |||
specific properties assert that "container" was created on December | </propfind> | |||
1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT | ||||
(creationdate), has a name of "Example collection" (displayname), a | ||||
collection resource type (resourcetype), and supports exclusive write | ||||
and shared write locks (supportedlock). | ||||
The resource http://www.foo.bar/container/front.html has nine | >>Response | |||
properties defined on it: | ||||
http://www.foo.bar/boxschema/bigbox (another instance of the "bigbox" | HTTP/1.1 207 Multi-Status | |||
property type), DAV:creationdate, DAV:displayname, DAV: | Content-Type: application/xml; charset="utf-8" | |||
getcontentlength, DAV:getcontenttype, DAV:getetag, DAV: | Content-Length: xxxx | |||
getlastmodified, DAV:resourcetype, and DAV:supportedlock. | ||||
The DAV-specific properties assert that "front.html" was created on | <?xml version="1.0" encoding="utf-8" ?> | |||
December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT | <multistatus xmlns="DAV:"> | |||
(creationdate), has a name of "Example HTML resource" (displayname), | <response> | |||
a content length of 4525 bytes (getcontentlength), a MIME type of | <href>http://www.example.com/container/</href> | |||
"text/html" (getcontenttype), an entity tag of "zzyzx" (getetag), was | <propstat> | |||
last modified on Monday, January 12, 1998, at 09:25:56 GMT | <prop xmlns:R="http://ns.example.com/boxschema/"> | |||
(getlastmodified), has an empty resource type, meaning that it is not | <R:bigbox/> | |||
a collection (resourcetype), and supports both exclusive write and | <R:author/> | |||
shared write locks (supportedlock). | <creationdate/> | |||
<displayname/> | ||||
<resourcetype/> | ||||
<supportedlock/> | ||||
</prop> | ||||
<status>HTTP/1.1 200 OK</status> | ||||
</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> | ||||
8.1.3. Example - Using propname to Retrieve all Property Names | 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 descendents 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 which do not explicitly state the namespace to | ||||
which they belong are members of the "DAV:" namespace. | ||||
9.1.5. Example - Using So-called 'allprop' | ||||
Note that 'allprop', despite its name which remains for backward- | ||||
compatibility, does not return every property, but only dead | ||||
properties and the live properties defined in this specification. | ||||
>>Request | >>Request | |||
PROPFIND /container/ HTTP/1.1 | PROPFIND /container/ HTTP/1.1 | |||
Host: www.foo.bar | Host: www.example.com | |||
Content-Type: text/xml; charset="utf-8" | Depth: 1 | |||
Content-Length: xxxx | Content-Type: application/xml; charset="utf-8" | |||
Content-Length: xxxx | ||||
<?xml version="1.0" encoding="utf-8" ?> | <?xml version="1.0" encoding="utf-8" ?> | |||
<propfind xmlns="DAV:"> | <D:propfind xmlns:D="DAV:"> | |||
<propname/> | <D:allprop/> | |||
</propfind> | </D:propfind> | |||
>>Response | >>Response | |||
HTTP/1.1 207 Multi-Status | HTTP/1.1 207 Multi-Status | |||
Content-Type: text/xml; charset="utf-8" | Content-Type: application/xml; charset="utf-8" | |||
Content-Length: xxxx | Content-Length: xxxx | |||
<?xml version="1.0" encoding="utf-8" ?> | <?xml version="1.0" encoding="utf-8" ?> | |||
<multistatus xmlns="DAV:"> | <D:multistatus xmlns:D="DAV:"> | |||
<response> | <D:response> | |||
<href>http://www.foo.bar/container/</href> | <D:href>/container/</D:href> | |||
<propstat> | <D:propstat> | |||
<prop xmlns:R="http://www.foo.bar/boxschema/"> | <D:prop xmlns:R="http://ns.example.com/boxschema/"> | |||
<R:bigbox/> | <R:bigbox><R:BoxType>Box type A</R:BoxType></R:bigbox> | |||
<R:author/> | <R:author><R:Name>Hadrian</R:Name></R:author> | |||
<creationdate/> | <D:creationdate>1997-12-01T17:42:21-08:00</D:creationdate> | |||
<displayname/> | <D:displayname>Example collection</D:displayname> | |||
<resourcetype/> | <D:resourcetype><D:collection/></D:resourcetype> | |||
<supportedlock/> | <D:supportedlock> | |||
</prop> | <D:lockentry> | |||
<status>HTTP/1.1 200 OK</status> | <D:lockscope><D:exclusive/></D:lockscope> | |||
</propstat> | <D:locktype><D:write/></D:locktype> | |||
</response> | </D:lockentry> | |||
<response> | <D:lockentry> | |||
<href>http://www.foo.bar/container/front.html</href> | <D:lockscope><D:shared/></D:lockscope> | |||
<propstat> | <D:locktype><D:write/></D:locktype> | |||
<prop xmlns:R="http://www.foo.bar/boxschema/"> | </D:lockentry> | |||
<R:bigbox/> | </D:supportedlock> | |||
<creationdate/> | </D:prop> | |||
<displayname/> | <D:status>HTTP/1.1 200 OK</D:status> | |||
<getcontentlength/> | </D:propstat> | |||
<getcontenttype/> | </D:response> | |||
<getetag/> | <D:response> | |||
<getlastmodified/> | <D:href>/container/front.html</D:href> | |||
<resourcetype/> | <D:propstat> | |||
<supportedlock/> | <D:prop xmlns:R="http://ns.example.com/boxschema/"> | |||
</prop> | <R:bigbox><R:BoxType>Box type B</R:BoxType> | |||
<status>HTTP/1.1 200 OK</status> | </R:bigbox> | |||
</propstat> | <D:creationdate>1997-12-01T18:27:21-08:00</D:creationdate> | |||
</response> | <D:displayname>Example HTML resource</D:displayname> | |||
</multistatus> | <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> | ||||
In this example, PROPFIND is invoked on the collection resource | </D:propstat> | |||
http://www.foo.bar/container/, with a propfind XML element containing | </D:response> | |||
the propname XML element, meaning the name of all properties should | </D:multistatus> | |||
be returned. Since no Depth header is present, it assumes its | ||||
default value of "infinity", meaning the name of the properties on | ||||
the collection and all its progeny should be returned. | ||||
Consistent with the previous example, resource | In this example, PROPFIND was invoked on the resource | |||
http://www.foo.bar/container/ has six properties defined on it, | http://www.example.com/container/ with a Depth header of 1, meaning | |||
http://www.foo.bar/boxschema/bigbox, | the request applies to the resource and its children, and a propfind | |||
http://www.foo.bar/boxschema/author, DAV:creationdate, DAV: | 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. | displayname, DAV:resourcetype, and DAV:supportedlock. | |||
The resource http://www.foo.bar/container/index.html, a member of the | The last four properties are WebDAV-specific, defined in Section 15. | |||
"container" collection, has nine properties defined on it, | Since GET is not supported on this resource, the get* properties | |||
http://www.foo.bar/boxschema/bigbox, DAV:creationdate, DAV: | (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, | displayname, DAV:getcontentlength, DAV:getcontenttype, DAV:getetag, | |||
DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock. | DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock. | |||
This example also demonstrates the use of XML namespace scoping, and | The DAV-specific properties assert that "front.html" was created on | |||
the default namespace. Since the "xmlns" attribute does not contain | December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT | |||
an explicit "shorthand name" (prefix) letter, the namespace applies | (DAV:creationdate), has a name of "Example HTML resource" (DAV: | |||
by default to all enclosed elements. Hence, all elements which do | displayname), a content length of 4525 bytes (DAV:getcontentlength), | |||
not explicitly state the namespace to which they belong are members | a MIME type of "text/html" (DAV:getcontenttype), an entity tag of | |||
of the "DAV:" namespace schema. | "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). | ||||
8.2. PROPPATCH | 9.1.6. Example - Using 'allprop' with 'include' | |||
>>Request | ||||
PROPFIND /mycol/ HTTP/1.1 | ||||
Host: www.example.com | ||||
Depth: 1 | ||||
Content-Type: application/xml; charset="utf-8" | ||||
Content-Length: xxxx | ||||
<?xml version="1.0" encoding="utf-8" ?> | ||||
<D:propfind xmlns:D="DAV:"> | ||||
<D:allprop/> | ||||
<D:include> | ||||
<D:supported-live-property-set/> | ||||
<D:supported-report-set/> | ||||
</D:include> | ||||
</D:propfind> | ||||
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. | ||||
9.2. PROPPATCH Method | ||||
The PROPPATCH method processes instructions specified in the request | The PROPPATCH method processes instructions specified in the request | |||
body to set and/or remove properties defined on the resource | body to set and/or remove properties defined on the resource | |||
identified by the Request-URI. | identified by the Request-URI. | |||
All DAV compliant resources MUST support the PROPPATCH method and | All DAV compliant resources MUST support the PROPPATCH method and | |||
MUST process instructions that are specified using the | MUST process instructions that are specified using the | |||
propertyupdate, set, and remove XML elements of the DAV schema. | propertyupdate, set, and remove XML elements. Execution of the | |||
Execution of the directives in this method is, of course, subject to | directives in this method is, of course, subject to access control | |||
access control constraints. DAV compliant resources SHOULD support | constraints. DAV compliant resources SHOULD support the setting of | |||
the setting of arbitrary dead properties. | arbitrary dead properties. | |||
The request message body of a PROPPATCH method MUST contain the | The request message body of a PROPPATCH method MUST contain the | |||
propertyupdate XML element. Instruction processing MUST occur in the | propertyupdate XML element. | |||
order instructions are received (i.e., from top to bottom). | ||||
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 | Instructions MUST either all be executed or none executed. Thus if | |||
any error occurs during processing all executed instructions MUST be | any error occurs during processing all executed instructions MUST be | |||
undone and a proper error result returned. Instruction processing | undone and a proper error result returned. Instruction processing | |||
details can be found in the definition of the set and remove | details can be found in the definition of the set and remove | |||
instructions in Section 12.13. | instructions in Section 14.23 and Section 14.26. | |||
8.2.1. Status Codes for use with 207 (Multi-Status) | 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. | ||||
The following are examples of response codes one would expect to be | This method is idempotent, but not safe (see Section 9.1 of | |||
used in a 207 (Multi-Status) response for this method. Note, | [RFC2616]). Responses to this method MUST NOT be cached. | |||
however, that unless explicitly prohibited any 2/3/4/5xx series | ||||
response code may be used in a 207 (Multi-Status) response. | ||||
200 (OK) - The command succeeded. As there can be a mixture of sets | 9.2.1. Status Codes for Use in 'propstat' Element | |||
and removes in a body, a 201 (Created) seems inappropriate. | ||||
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. | ||||
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 | 403 (Forbidden) - The client, for reasons the server chooses not to | |||
specify, cannot alter one of the properties. | 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 | 409 (Conflict) - The client has provided a value whose semantics are | |||
not appropriate for the property. This includes trying to set read- | not appropriate for the property. | |||
only properties. | ||||
423 (Locked) - The specified resource is locked and the client either | 424 (Failed Dependency) - The property change could not be made | |||
is not a lock owner or the lock type requires a lock token to be | because of another property change that failed. | |||
submitted and the client did not submit it. | ||||
507 (Insufficient Storage) - The server did not have sufficient space | 507 (Insufficient Storage) - The server did not have sufficient space | |||
to record the property. | to record the property. | |||
8.2.2. Example - PROPPATCH | 9.2.2. Example - PROPPATCH | |||
>>Request | >>Request | |||
PROPPATCH /bar.html HTTP/1.1 | PROPPATCH /bar.html HTTP/1.1 | |||
Host: www.foo.com | Host: www.example.com | |||
Content-Type: text/xml; charset="utf-8" | Content-Type: application/xml; charset="utf-8" | |||
Content-Length: xxxx | Content-Length: xxxx | |||
<?xml version="1.0" encoding="utf-8" ?> | <?xml version="1.0" encoding="utf-8" ?> | |||
<D:propertyupdate xmlns:D="DAV:" | <D:propertyupdate xmlns:D="DAV:" | |||
xmlns:Z="http://www.w3.com/standards/z39.50/"> | xmlns:Z="http://ns.example.com/standards/z39.50/"> | |||
<D:set> | <D:set> | |||
<D:prop> | <D:prop> | |||
<Z:authors> | <Z:Authors> | |||
<Z:Author>Jim Whitehead</Z:Author> | <Z:Author>Jim Whitehead</Z:Author> | |||
<Z:Author>Roy Fielding</Z:Author> | <Z:Author>Roy Fielding</Z:Author> | |||
</Z:authors> | </Z:Authors> | |||
</D:prop> | </D:prop> | |||
</D:set> | </D:set> | |||
<D:remove> | <D:remove> | |||
<D:prop><Z:Copyright-Owner/></D:prop> | <D:prop><Z:Copyright-Owner/></D:prop> | |||
</D:remove> | </D:remove> | |||
</D:propertyupdate> | </D:propertyupdate> | |||
>>Response | >>Response | |||
HTTP/1.1 207 Multi-Status | HTTP/1.1 207 Multi-Status | |||
Content-Type: text/xml; charset="utf-8" | Content-Type: application/xml; charset="utf-8" | |||
Content-Length: xxxx | Content-Length: xxxx | |||
<?xml version="1.0" encoding="utf-8" ?> | <?xml version="1.0" encoding="utf-8" ?> | |||
<D:multistatus xmlns:D="DAV:" | <D:multistatus xmlns:D="DAV:" | |||
xmlns:Z="http://www.w3.com/standards/z39.50"> | xmlns:Z="http://ns.example.com/standards/z39.50/"> | |||
<D:response> | <D:response> | |||
<D:href>http://www.foo.com/bar.html</D:href> | <D:href>http://www.example.com/bar.html</D:href> | |||
<D:propstat> | <D:propstat> | |||
<D:prop><Z:Authors/></D:prop> | <D:prop><Z:Authors/></D:prop> | |||
<D:status>HTTP/1.1 424 Failed Dependency</D:status> | <D:status>HTTP/1.1 424 Failed Dependency</D:status> | |||
</D:propstat> | </D:propstat> | |||
<D:propstat> | <D:propstat> | |||
<D:prop><Z:Copyright-Owner/></D:prop> | <D:prop><Z:Copyright-Owner/></D:prop> | |||
<D:status>HTTP/1.1 409 Conflict</D:status> | <D:status>HTTP/1.1 409 Conflict</D:status> | |||
</D:propstat> | </D:propstat> | |||
<D:responsedescription> Copyright Owner can not be deleted or | <D:responsedescription> Copyright Owner can not be deleted or | |||
altered.</D:responsedescription> | altered.</D:responsedescription> | |||
</D:response> | </D:response> | |||
</D:multistatus> | </D:multistatus> | |||
In this example, the client requests the server to set the value of | In this example, the client requests the server to set the value of | |||
the http://www.w3.com/standards/z39.50/Authors property, and to | the "Authors" property in the | |||
remove the property | "http://ns.example.com/standards/z39.50/" namespace, and to remove | |||
http://www.w3.com/standards/z39.50/Copyright-Owner. Since the | the property "Copyright-Owner" in the same namespace. Since the | |||
Copyright-Owner property could not be removed, no property | Copyright-Owner property could not be removed, no property | |||
modifications occur. The 424 (Failed Dependency) status code for the | modifications occur. The 424 (Failed Dependency) status code for the | |||
Authors property indicates this action would have succeeded if it | Authors property indicates this action would have succeeded if it | |||
were not for the conflict with removing the Copyright-Owner property. | were not for the conflict with removing the Copyright-Owner property. | |||
8.3. MKCOL Method | 9.3. MKCOL Method | |||
The MKCOL method is used to create a new collection. All DAV | ||||
compliant resources MUST support the MKCOL method. | ||||
8.3.1. Request | ||||
MKCOL creates a new collection resource at the location specified by | MKCOL creates a new collection resource at the location specified by | |||
the Request-URI. If the resource identified by the Request-URI is | the Request-URI. If the Request-URI is already mapped to a resource | |||
non-null then the MKCOL MUST fail. During MKCOL processing, a server | then the MKCOL MUST fail. During MKCOL processing, a server MUST | |||
MUST make the Request-URI a member of its parent collection, unless | make the Request-URI an internal member of its parent collection, | |||
the Request-URI is "/". If no such ancestor exists, the method MUST | unless the Request-URI is "/". If no such ancestor exists, the | |||
fail. When the MKCOL operation creates a new collection resource, | method MUST fail. When the MKCOL operation creates a new collection | |||
all ancestors MUST already exist, or the method MUST fail with a 409 | resource, all ancestors MUST already exist, or the method MUST fail | |||
(Conflict) status code. For example, if a request to create | with a 409 (Conflict) status code. For example, if a request to | |||
collection /a/b/c/d/ is made, and neither /a/b/ nor /a/b/c/ exists, | create collection /a/b/c/d/ is made, and /a/b/c/ does not exist, the | |||
the request must fail. | request must fail. | |||
When MKCOL is invoked without a request body, the newly created | When MKCOL is invoked without a request body, the newly created | |||
collection SHOULD have no members. | collection SHOULD have no members. | |||
A MKCOL request message may contain a message body. The behavior of | A MKCOL request message may contain a message body. The precise | |||
a MKCOL request when the body is present is limited to creating | behavior of a MKCOL request when the body is present is undefined, | |||
collections, members of a collection, bodies of members and | but limited to creating collections, members of a collection, bodies | |||
properties on the collections or members. If the server receives a | of members and properties on the collections or members. If the | |||
MKCOL request entity type it does not support or understand it MUST | server receives a MKCOL request entity type it does not support or | |||
respond with a 415 (Unsupported Media Type) status code. The exact | understand it MUST respond with a 415 (Unsupported Media Type) status | |||
behavior of MKCOL for various request media types is undefined in | code. If the server decides to reject the request based on the | |||
this document, and will be specified in separate documents. | presence of an entity or the type of an entity, it should use the 415 | |||
(Unsupported Media Type) status code. | ||||
8.3.2. Status Codes | This method is idempotent, but not safe (see Section 9.1 of | |||
[RFC2616]). Responses to this method MUST NOT be cached. | ||||
Responses from a MKCOL request MUST NOT be cached as MKCOL has non- | 9.3.1. MKCOL Status Codes | |||
idempotent semantics. | ||||
201 (Created) - The collection or structured resource was created in | In addition to the general status codes possible, the following | |||
its entirety. | status codes have specific applicability to MKCOL: | |||
201 (Created) - The collection was created. | ||||
403 (Forbidden) - This indicates at least one of two conditions: 1) | 403 (Forbidden) - This indicates at least one of two conditions: 1) | |||
the server does not allow the creation of collections at the given | the server does not allow the creation of collections at the given | |||
location in its namespace, or 2) the parent collection of the | location in its URL namespace, or 2) the parent collection of the | |||
Request-URI exists but cannot accept members. | Request-URI exists but cannot accept members. | |||
405 (Method Not Allowed) - MKCOL can only be executed on a deleted/ | 405 (Method Not Allowed) - MKCOL can only be executed on an unmapped | |||
non-existent resource. | URL. | |||
409 (Conflict) - A collection cannot be made at the Request-URI until | 409 (Conflict) - A collection cannot be made at the Request-URI until | |||
one or more intermediate collections have been created. | 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 | 415 (Unsupported Media Type) - The server does not support the | |||
type of the body. | 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 | 507 (Insufficient Storage) - The resource does not have sufficient | |||
space to record the state of the resource after the execution of this | space to record the state of the resource after the execution of this | |||
method. | method. | |||
8.3.3. Example - MKCOL | 9.3.2. Example - MKCOL | |||
This example creates a collection called /webdisc/xfiles/ on the | This example creates a collection called /webdisc/xfiles/ on the | |||
server www.server.org. | server www.example.com. | |||
>>Request | >>Request | |||
MKCOL /webdisc/xfiles/ HTTP/1.1 | MKCOL /webdisc/xfiles/ HTTP/1.1 | |||
Host: www.server.org | Host: www.example.com | |||
>>Response | >>Response | |||
HTTP/1.1 201 Created | HTTP/1.1 201 Created | |||
8.4. GET, HEAD for Collections | 9.4. GET, HEAD for Collections | |||
The semantics of GET are unchanged when applied to a collection, | The semantics of GET are unchanged when applied to a collection, | |||
since GET is defined as, "retrieve whatever information (in the form | since GET is defined as, "retrieve whatever information (in the form | |||
of an entity) is identified by the Request-URI" [RFC2068]. GET when | of an entity) is identified by the Request-URI" [RFC2616]. GET when | |||
applied to a collection may return the contents of an "index.html" | applied to a collection may return the contents of an "index.html" | |||
resource, a human-readable view of the contents of the collection, or | resource, a human-readable view of the contents of the collection, or | |||
something else altogether. Hence it is possible that the result of a | 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 | GET on a collection will bear no correlation to the membership of the | |||
collection. | collection. | |||
Similarly, since the definition of HEAD is a GET without a response | Similarly, since the definition of HEAD is a GET without a response | |||
message body, the semantics of HEAD are unmodified when applied to | message body, the semantics of HEAD are unmodified when applied to | |||
collection resources. | collection resources. | |||
8.5. POST for Collections | 9.5. POST for Collections | |||
Since by definition the actual function performed by POST is | Since by definition the actual function performed by POST is | |||
determined by the server and often depends on the particular | determined by the server and often depends on the particular | |||
resource, the behavior of POST when applied to collections cannot be | resource, the behavior of POST when applied to collections cannot be | |||
meaningfully modified because it is largely undefined. Thus the | meaningfully modified because it is largely undefined. Thus the | |||
semantics of POST are unmodified when applied to a collection. | semantics of POST are unmodified when applied to a collection. | |||
8.6. DELETE | 9.6. DELETE Requirements | |||
8.6.1. DELETE for Non-Collection Resources | DELETE is defined in [RFC2616], Section 9.7, to "delete the resource | |||
identified by the Request-URI". However, WebDAV changes some DELETE | ||||
handling requirements. | ||||
If the DELETE method is issued to a non-collection resource whose | A server processing a successful DELETE request: | |||
URIs are an internal member of one or more collections, then during | ||||
DELETE processing a server MUST remove any URI for the resource | ||||
identified by the Request-URI from collections which contain it as a | ||||
member. | ||||
8.6.2. DELETE for Collections | 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). | ||||
9.6.1. DELETE for Collections | ||||
The DELETE method on a collection MUST act as if a "Depth: infinity" | 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 | header was used on it. A client MUST NOT submit a Depth header with | |||
a DELETE on a collection with any value but infinity. | a DELETE on a collection with any value but infinity. | |||
DELETE instructs that the collection specified in the Request-URI and | DELETE instructs that the collection specified in the Request-URI and | |||
all resources identified by its internal member URIs are to be | all resources identified by its internal member URLs are to be | |||
deleted. | deleted. | |||
If any resource identified by a member URI cannot be deleted then all | 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 | of the member's ancestors MUST NOT be deleted, so as to maintain URL | |||
namespace consistency. | namespace consistency. | |||
Any headers included with DELETE MUST be applied in processing every | Any headers included with DELETE MUST be applied in processing every | |||
resource to be deleted. | resource to be deleted. | |||
When the DELETE method has completed processing it MUST result in a | When the DELETE method has completed processing it MUST result in a | |||
consistent namespace. | consistent URL namespace. | |||
If an error occurs with a resource other than the resource identified | If an error occurs deleting a member resource (a resource other than | |||
in the Request-URI then the response MUST be a 207 (Multi-Status). | the resource identified in the Request-URI) then the response can be | |||
424 (Failed Dependency) errors SHOULD NOT be in the 207 (Multi- | a 207 (Multi-Status). Multi-Status is used here to indicate which | |||
Status). They can be safely left out because the client will know | internal resources could NOT be deleted, including an error code | |||
that the ancestors of a resource could not be deleted when the client | which should help the client understand which resources caused the | |||
receives an error for the ancestor's progeny. Additionally 204 (No | failure. For example, the Multi-Status body could include a response | |||
Content) errors SHOULD NOT be returned in the 207 (Multi-Status). | with status 423 (Locked) if an internal resource was locked. | |||
The reason for this prohibition is that 204 (No Content) is the | ||||
default success code. | ||||
8.6.2.1. Example - DELETE | 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 | >>Request | |||
DELETE /container/ HTTP/1.1 | DELETE /container/ HTTP/1.1 | |||
Host: www.foo.bar | Host: www.example.com | |||
>>Response | >>Response | |||
HTTP/1.1 207 Multi-Status | HTTP/1.1 207 Multi-Status | |||
Content-Type: text/xml; charset="utf-8" | Content-Type: application/xml; charset="utf-8" | |||
Content-Length: xxxx | Content-Length: xxxx | |||
<?xml version="1.0" encoding="utf-8" ?> | <?xml version="1.0" encoding="utf-8" ?> | |||
<d:multistatus xmlns:d="DAV:"> | <d:multistatus xmlns:d="DAV:"> | |||
<d:response> | <d:response> | |||
<d:href>http://www.foo.bar/container/resource3</d:href> | <d:href>http://www.example.com/container/resource3</d:href> | |||
<d:status>HTTP/1.1 423 Locked</d:status> | <d:status>HTTP/1.1 423 Locked</d:status> | |||
</d:response> | <d:error><d:lock-token-submitted/></d:error> | |||
</d:multistatus> | </d:response> | |||
</d:multistatus> | ||||
In this example the attempt to delete | In this example the attempt to delete | |||
http://www.foo.bar/container/resource3 failed because it is locked, | http://www.example.com/container/resource3 failed because it is | |||
and no lock token was submitted with the request. Consequently, the | locked, and no lock token was submitted with the request. | |||
attempt to delete http://www.foo.bar/container/ also failed. Thus | Consequently, the attempt to delete http://www.example.com/container/ | |||
the client knows that the attempt to delete | also failed. Thus the client knows that the attempt to delete | |||
http://www.foo.bar/container/ must have also failed since the parent | http://www.example.com/container/ must have also failed since the | |||
can not be deleted unless its child has also been deleted. Even | parent can not be deleted unless its child has also been deleted. | |||
though a Depth header has not been included, a depth of infinity is | Even though a Depth header has not been included, a depth of infinity | |||
assumed because the method is on a collection. | is assumed because the method is on a collection. | |||
8.7. PUT | 9.7. PUT Requirements | |||
8.7.1. PUT for Non-Collection Resources | 9.7.1. PUT for Non-Collection Resources | |||
A PUT performed on an existing resource replaces the GET response | A PUT performed on an existing resource replaces the GET response | |||
entity of the resource. Properties defined on the resource may be | entity of the resource. Properties defined on the resource may be | |||
recomputed during PUT processing but are not otherwise affected. For | recomputed during PUT processing but are not otherwise affected. For | |||
example, if a server recognizes the content type of the request body, | example, if a server recognizes the content type of the request body, | |||
it may be able to automatically extract information that could be | it may be able to automatically extract information that could be | |||
profitably exposed as properties. | profitably exposed as properties. | |||
A PUT that would result in the creation of a resource without an | A PUT that would result in the creation of a resource without an | |||
appropriately scoped parent collection MUST fail with a 409 | appropriately scoped parent collection MUST fail with a 409 | |||
(Conflict). | (Conflict). | |||
8.7.2. PUT for Collections | 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. | ||||
As defined in the HTTP/1.1 specification [RFC2068], the "PUT method | Note that although a recipient ought generally to treat metadata | |||
requests that the enclosed entity be stored under the supplied | supplied with an HTTP request as authoritative, in practice there's | |||
Request-URI." Since submission of an entity representing a | no guarantee that a server will accept client-supplied metadata (e.g. | |||
collection would implicitly encode creation and deletion of | any request header beginning with "Content-"). Many servers do not | |||
resources, this specification intentionally does not define a | allow configuring the Content-Type on a per-resource basis in the | |||
transmission format for creating a collection using PUT. Instead, | first place. Thus, clients can't always rely on the ability to | |||
the MKCOL method is defined to create collections. | directly influence the content type by including a Content-Type | |||
request header. | ||||
When the PUT operation creates a new non-collection resource all | 9.7.2. PUT for Collections | |||
ancestors MUST already exist. If all ancestors do not exist, the | ||||
method MUST fail with a 409 (Conflict) status code. For example, if | ||||
resource /a/b/c/d.html is to be created and /a/b/c/ does not exist, | ||||
then the request must fail. | ||||
8.8. COPY Method | 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 COPY method creates a duplicate of the source resource, | The MKCOL method is defined to create collections. | |||
identified by the Request-URI, in the destination resource, | ||||
identified by the URI in the Destination header. The Destination | 9.8. COPY Method | |||
header MUST be present. The exact behavior of the COPY method | ||||
depends on the type of the source resource. | 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. | All WebDAV compliant resources MUST support the COPY method. | |||
However, support for the COPY method does not guarantee the ability | However, support for the COPY method does not guarantee the ability | |||
to copy a resource. For example, separate programs may control | to copy a resource. For example, separate programs may control | |||
resources on the same server. As a result, it may not be possible to | 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. | copy a resource to a location that appears to be on the same server. | |||
8.8.1. COPY for HTTP/1.1 resources | 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 | 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 | method is the creation of a new resource at the destination whose | |||
state and behavior match that of the source resource as closely as | state and behavior match that of the source resource as closely as | |||
possible. After a successful COPY invocation, all properties on the | possible. Since the environment at the destination may be different | |||
source resource MUST be duplicated on the destination resource, | than at the source due to factors outside the scope of control of the | |||
subject to modifying headers and XML elements, following the | server, such as the absence of resources required for correct | |||
definition for copying properties. Since the environment at the | operation, it may not be possible to completely duplicate the | |||
destination may be different than at the source due to factors | behavior of the resource at the destination. Subsequent alterations | |||
outside the scope of control of the server, such as the absence of | to the destination resource will not modify the source resource. | |||
resources required for correct operation, it may not be possible to | Subsequent alterations to the source resource will not modify the | |||
completely duplicate the behavior of the resource at the destination. | destination resource. | |||
Subsequent alterations to the destination resource will not modify | ||||
the source resource. Subsequent alterations to the source resource | ||||
will not modify the destination resource. | ||||
8.8.2. COPY for Properties | ||||
The following section defines how properties on a resource are | 9.8.2. COPY for Properties | |||
handled during a COPY operation. | ||||
Live properties SHOULD be duplicated as identically behaving live | After a successful COPY invocation, all dead properties on the source | |||
properties at the destination resource. If a property cannot be | resource SHOULD be duplicated on the destination resource. Live | |||
copied live, then its value MUST be duplicated, octet-for-octet, in | properties described in this document SHOULD be duplicated as | |||
an identically named, dead property on the destination resource | identically behaving live properties at the destination resource, but | |||
subject to the effects of the propertybehavior XML element. | 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. | ||||
The propertybehavior XML element can specify that properties are | When the destination is an unmapped URL, a COPY operation creates a | |||
copied on best effort, that all live properties must be successfully | new resource much like a PUT operation does. Live properties which | |||
copied or the method must fail, or that a specified list of live | are related to resource creation (such as DAV:creationdate) should | |||
properties must be successfully copied or the method must fail. The | have their values set accordingly. | |||
propertybehavior XML element is defined in Section 12.12. | ||||
8.8.3. COPY for Collections | 9.8.3. COPY for Collections | |||
The COPY method on a collection without a Depth header MUST act as if | 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 | 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" | submit a Depth header on a COPY on a collection with a value of "0" | |||
or "infinity". DAV compliant servers MUST support the "0" and | or "infinity". Servers MUST support the "0" and "infinity" Depth | |||
"infinity" Depth header behaviors. | header behaviors on WebDAV-compliant resources. | |||
A COPY of depth infinity instructs that the collection resource | An infinite depth COPY instructs that the collection resource | |||
identified by the Request-URI is to be copied to the location | identified by the Request-URI is to be copied to the location | |||
identified by the URI in the Destination header, and all its internal | identified by the URI in the Destination header, and all its internal | |||
member resources are to be copied to a location relative to it, | member resources are to be copied to a location relative to it, | |||
recursively through all levels of the collection hierarchy. | 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 | A COPY of "Depth: 0" only instructs that the collection and its | |||
properties but not resources identified by its internal member URIs, | properties but not resources identified by its internal member URLs, | |||
are to be copied. | are to be copied. | |||
Any headers included with a COPY MUST be applied in processing every | Any headers included with a COPY MUST be applied in processing every | |||
resource to be copied with the exception of the Destination header. | resource to be copied with the exception of the Destination header. | |||
The Destination header only specifies the destination URI for the | The Destination header only specifies the destination URI for the | |||
Request-URI. When applied to members of the collection identified by | 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 Request-URI the value of Destination is to be modified to reflect | |||
the current location in the hierarchy. So, if the Request- URI is | the current location in the hierarchy. So, if the Request-URI is /a/ | |||
/a/ with Host header value http://fun.com/ and the Destination is | with Host header value http://example.com/ and the Destination is | |||
http://fun.com/b/ then when http://fun.com/a/c/d is processed it must | http://example.com/b/ then when http://example.com/a/c/d is processed | |||
use a Destination of http://fun.com/b/c/d. | it must use a Destination of http://example.com/b/c/d. | |||
When the COPY method has completed processing it MUST have created a | When the COPY method has completed processing it MUST have created a | |||
consistent namespace at the destination (see Section 5.1 for the | consistent URL namespace at the destination (see Section 5.1 for the | |||
definition of namespace consistency). However, if an error occurs | definition of namespace consistency). However, if an error occurs | |||
while copying an internal collection, the server MUST NOT copy any | while copying an internal collection, the server MUST NOT copy any | |||
resources identified by members of this collection (i.e., the server | resources identified by members of this collection (i.e., the server | |||
must skip this subtree), as this would create an inconsistent | must skip this subtree), as this would create an inconsistent | |||
namespace. After detecting an error, the COPY operation SHOULD try | namespace. After detecting an error, the COPY operation SHOULD try | |||
to finish as much of the original copy operation as possible (i.e., | to finish as much of the original copy operation as possible (i.e., | |||
the server should still attempt to copy other subtrees and their | the server should still attempt to copy other subtrees and their | |||
members, that are not descendents of an error-causing collection). | members, that are not descendents of an error-causing collection). | |||
So, for example, if an infinite depth copy operation is performed on | So, for example, if an infinite depth copy operation is performed on | |||
collection /a/, which contains collections /a/b/ and /a/c/, and an | 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 | error occurs copying /a/b/, an attempt should still be made to copy | |||
/a/c/. Similarly, after encountering an error copying a non- | /a/c/. Similarly, after encountering an error copying a non- | |||
collection resource as part of an infinite depth copy, the server | collection resource as part of an infinite depth copy, the server | |||
SHOULD try to finish as much of the original copy operation as | SHOULD try to finish as much of the original copy operation as | |||
possible. | possible. | |||
If an error in executing the COPY method occurs with a resource other | If an error in executing the COPY method occurs with a resource other | |||
than the resource identified in the Request-URI then the response | than the resource identified in the Request-URI then the response | |||
MUST be a 207 (Multi-Status). | 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 | The 424 (Failed Dependency) status code SHOULD NOT be returned in the | |||
207 (Multi-Status) response from a COPY method. These responses can | 207 (Multi-Status) response from a COPY method. These responses can | |||
be safely omitted because the client will know that the progeny of a | 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 | resource could not be copied when the client receives an error for | |||
the parent. Additionally 201 (Created)/204 (No Content) status codes | the parent. Additionally 201 (Created)/204 (No Content) status codes | |||
SHOULD NOT be returned as values in 207 (Multi-Status) responses from | SHOULD NOT be returned as values in 207 (Multi-Status) responses from | |||
COPY methods. They, too, can be safely omitted because they are the | COPY methods. They, too, can be safely omitted because they are the | |||
default success codes. | default success codes. | |||
8.8.4. COPY and the Overwrite Header | 9.8.4. COPY and Overwriting Destination Resources | |||
If a resource exists at the destination and the Overwrite header is | If a COPY request has an Overwrite header with a value of "F", and a | |||
"T" then prior to performing the copy the server MUST perform a | resource exists at the Destination URL, the server MUST fail the | |||
DELETE with "Depth: infinity" on the destination resource. If the | request. | |||
Overwrite header is set to "F" then the operation will fail. | ||||
8.8.5. Status Codes | 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 | ||||
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 | 201 (Created) - The source resource was successfully copied. The | |||
copy operation resulted in the creation of a new resource. | COPY operation resulted in the creation of a new resource. | |||
204 (No Content) - The source resource was successfully copied to a | 204 (No Content) - The source resource was successfully copied to a | |||
pre-existing destination resource. | pre-existing destination resource. | |||
403 (Forbidden) - The source and destination URIs are the same. | 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. E.g. 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 | 409 (Conflict) - A resource cannot be created at the destination | |||
until one or more intermediate collections have been created. | until one or more intermediate collections have been created. The | |||
server MUST NOT create those intermediate collections automatically. | ||||
412 (Precondition Failed) - The server was unable to maintain the | 412 (Precondition Failed) - A precondition header check failed, e.g. | |||
liveness of the properties listed in the propertybehavior XML element | the Overwrite header is "F" and the destination URL is already mapped | |||
or the Overwrite header is "F" and the state of the destination | to a resource. | |||
resource is non-null. | ||||
423 (Locked) - The destination resource was locked. | 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 | 502 (Bad Gateway) - This may occur when the destination is on another | |||
server and the destination server refuses to accept the resource. | 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 | 507 (Insufficient Storage) - The destination resource does not have | |||
sufficient space to record the state of the resource after the | sufficient space to record the state of the resource after the | |||
execution of this method. | execution of this method. | |||
8.8.6. Example - COPY with Overwrite | 9.8.6. Example - COPY with Overwrite | |||
This example shows resource | This example shows resource | |||
http://www.ics.uci.edu/~fielding/index.html being copied to the | http://www.example.com/~fielding/index.html being copied to the | |||
location http://www.ics.uci.edu/users/f/fielding/index.html. The 204 | location http://www.example.com/users/f/fielding/index.html. The 204 | |||
(No Content) status code indicates the existing resource at the | (No Content) status code indicates the existing resource at the | |||
destination was overwritten. | destination was overwritten. | |||
>>Request | >>Request | |||
COPY /~fielding/index.html HTTP/1.1 | COPY /~fielding/index.html HTTP/1.1 | |||
Host: www.ics.uci.edu | Host: www.example.com | |||
Destination: http://www.ics.uci.edu/users/f/fielding/index.html | Destination: http://www.example.com/users/f/fielding/index.html | |||
>>Response | >>Response | |||
HTTP/1.1 204 No Content | HTTP/1.1 204 No Content | |||
8.8.7. Example - COPY with No Overwrite | 9.8.7. Example - COPY with No Overwrite | |||
The following example shows the same copy operation being performed, | The following example shows the same copy operation being performed, | |||
but with the Overwrite header set to "F." A response of 412 | but with the Overwrite header set to "F." A response of 412 | |||
(Precondition Failed) is returned because the destination resource | (Precondition Failed) is returned because the destination URL is | |||
has a non-null state. | already mapped to a resource. | |||
>>Request | >>Request | |||
COPY /~fielding/index.html HTTP/1.1 | COPY /~fielding/index.html HTTP/1.1 | |||
Host: www.ics.uci.edu | Host: www.example.com | |||
Destination: http://www.ics.uci.edu/users/f/fielding/index.html | Destination: http://www.example.com/users/f/fielding/index.html | |||
Overwrite: F | Overwrite: F | |||
>>Response | >>Response | |||
HTTP/1.1 412 Precondition Failed | HTTP/1.1 412 Precondition Failed | |||
8.8.8. Example - COPY of a Collection | 9.8.8. Example - COPY of a Collection | |||
>>Request | >>Request | |||
COPY /container/ HTTP/1.1 | COPY /container/ HTTP/1.1 | |||
Host: www.foo.bar | Host: www.example.com | |||
Destination: http://www.foo.bar/othercontainer/ | Destination: http://www.example.com/othercontainer/ | |||
Depth: infinity | Depth: infinity | |||
Content-Type: text/xml; charset="utf-8" | ||||
Content-Length: xxxx | ||||
<?xml version="1.0" encoding="utf-8" ?> | ||||
<d:propertybehavior xmlns:d="DAV:"> | ||||
<d:keepalive>*</d:keepalive> | ||||
</d:propertybehavior> | ||||
>>Response | >>Response | |||
HTTP/1.1 207 Multi-Status | HTTP/1.1 207 Multi-Status | |||
Content-Type: text/xml; charset="utf-8" | Content-Type: application/xml; charset="utf-8" | |||
Content-Length: xxxx | Content-Length: xxxx | |||
<?xml version="1.0" encoding="utf-8" ?> | <?xml version="1.0" encoding="utf-8" ?> | |||
<d:multistatus xmlns:d="DAV:"> | ||||
<d:response> | <d:multistatus xmlns:d="DAV:"> | |||
<d:href>http://www.foo.bar/othercontainer/R2/</d:href> | <d:response> | |||
<d:status>HTTP/1.1 412 Precondition Failed</d:status> | <d:href>http://www.example.com/othercontainer/R2/</d:href> | |||
</d:response> | <d:status>HTTP/1.1 423 Locked</d:status> | |||
</d:multistatus> | <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 | 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 | collection is to act as if a "Depth: infinity" header had been | |||
submitted. In this example most of the resources, along with the | submitted. In this example most of the resources, along with the | |||
collection, were copied successfully. However the collection R2 | collection, were copied successfully. However the collection R2 | |||
failed, most likely due to a problem with maintaining the liveness of | failed because the destination R2 is locked. Because there was an | |||
properties (this is specified by the propertybehavior XML element). | error copying R2, none of R2's members were copied. However no | |||
Because there was an error copying R2, none of R2's members were | errors were listed for those members due to the error minimization | |||
copied. However no errors were listed for those members due to the | rules. | |||
error minimization rules given in Section 8.8.3. | ||||
8.9. MOVE Method | 9.9. MOVE Method | |||
The MOVE operation on a non-collection resource is the logical | The MOVE operation on a non-collection resource is the logical | |||
equivalent of a copy (COPY), followed by consistency maintenance | equivalent of a copy (COPY), followed by consistency maintenance | |||
processing, followed by a delete of the source, where all three | processing, followed by a delete of the source, where all three | |||
actions are performed atomically. The consistency maintenance step | actions are performed in a single operation. The consistency | |||
allows the server to perform updates caused by the move, such as | maintenance step allows the server to perform updates caused by the | |||
updating all URIs other than the Request-URI which identify the | move, such as updating all URLs other than the Request-URI which | |||
source resource, to point to the new destination resource. | identify the source resource, to point to the new destination | |||
Consequently, the Destination header MUST be present on all MOVE | resource. | |||
methods and MUST follow all COPY requirements for the COPY part of | ||||
the MOVE method. All DAV compliant resources MUST support the MOVE | ||||
method. However, support for the MOVE method does not guarantee the | ||||
ability to move a resource to a particular destination. | ||||
For example, separate programs may actually control different sets of | The Destination header MUST be present on all MOVE methods and MUST | |||
resources on the same server. Therefore, it may not be possible to | follow all COPY requirements for the COPY part of the MOVE method. | |||
move a resource within a namespace that appears to belong to the same | All WebDAV compliant resources MUST support the MOVE method. | |||
server. | ||||
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 | If a resource exists at the destination, the destination resource | |||
will be DELETEd as a side-effect of the MOVE operation, subject to | will be deleted as a side-effect of the MOVE operation, subject to | |||
the restrictions of the Overwrite header. | the restrictions of the Overwrite header. | |||
8.9.1. MOVE for Properties | This method is idempotent, but not safe (see Section 9.1 of | |||
[RFC2616]). Responses to this method MUST NOT be cached. | ||||
The behavior of properties on a MOVE, including the effects of the | 9.9.1. MOVE for Properties | |||
propertybehavior XML element, MUST be the same as specified in | ||||
Section 8.8.2. | ||||
8.9.2. MOVE for Collections | 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 which 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 | A MOVE with "Depth: infinity" instructs that the collection | |||
identified by the Request-URI be moved to the URI specified in the | identified by the Request-URI be moved to the address specified in | |||
Destination header, and all resources identified by its internal | the Destination header, and all resources identified by its internal | |||
member URIs are to be moved to locations relative to it, recursively | member URLs are to be moved to locations relative to it, recursively | |||
through all levels of the collection hierarchy. | through all levels of the collection hierarchy. | |||
The MOVE method on a collection MUST act as if a "Depth: infinity" | 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 | header was used on it. A client MUST NOT submit a Depth header on a | |||
MOVE on a collection with any value but "infinity". | MOVE on a collection with any value but "infinity". | |||
Any headers included with MOVE MUST be applied in processing every | Any headers included with MOVE MUST be applied in processing every | |||
resource to be moved with the exception of the Destination header. | resource to be moved with the exception of the Destination header. | |||
The behavior of the Destination header is the same as given for COPY | The behavior of the Destination header is the same as given for COPY | |||
on collections. | on collections. | |||
When the MOVE method has completed processing it MUST have created a | When the MOVE method has completed processing it MUST have created a | |||
consistent namespace at both the source and destination (see section | consistent URL namespace at both the source and destination (see | |||
5.1 for the definition of namespace consistency). However, if an | section 5.1 for the definition of namespace consistency). However, | |||
error occurs while moving an internal collection, the server MUST NOT | if an error occurs while moving an internal collection, the server | |||
move any resources identified by members of the failed collection | MUST NOT move any resources identified by members of the failed | |||
(i.e., the server must skip the error-causing subtree), as this would | collection (i.e., the server must skip the error-causing subtree), as | |||
create an inconsistent namespace. In this case, after detecting the | this would create an inconsistent namespace. In this case, after | |||
error, the move operation SHOULD try to finish as much of the | detecting the error, the move operation SHOULD try to finish as much | |||
original move as possible (i.e., the server should still attempt to | of the original move as possible (i.e., the server should still | |||
move other subtrees and the resources identified by their members, | attempt to move other subtrees and the resources identified by their | |||
that are not descendents of an error-causing collection). So, for | members, that are not descendents of an error-causing collection). | |||
example, if an infinite depth move is performed on collection /a/, | So, for example, if an infinite depth move is performed on collection | |||
which contains collections /a/b/ and /a/c/, and an error occurs | /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/. | moving /a/b/, an attempt should still be made to try moving /a/c/. | |||
Similarly, after encountering an error moving a non-collection | Similarly, after encountering an error moving a non-collection | |||
resource as part of an infinite depth move, the server SHOULD try to | resource as part of an infinite depth move, the server SHOULD try to | |||
finish as much of the original move operation as possible. | finish as much of the original move operation as possible. | |||
If an error occurs with a resource other than the resource identified | 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). | 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 | The 424 (Failed Dependency) status code SHOULD NOT be returned in the | |||
207 (Multi-Status) response from a MOVE method. These errors can be | 207 (Multi-Status) response from a MOVE method. These errors can be | |||
safely omitted because the client will know that the progeny of a | 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 | resource could not be moved when the client receives an error for the | |||
parent. Additionally 201 (Created)/204 (No Content) responses SHOULD | parent. Additionally 201 (Created)/204 (No Content) responses SHOULD | |||
NOT be returned as values in 207 (Multi-Status) responses from a | NOT be returned as values in 207 (Multi-Status) responses from a | |||
MOVE. These responses can be safely omitted because they are the | MOVE. These responses can be safely omitted because they are the | |||
default success codes. | default success codes. | |||
8.9.3. MOVE and the Overwrite Header | 9.9.3. MOVE and the Overwrite Header | |||
If a resource exists at the destination and the Overwrite header is | If a resource exists at the destination and the Overwrite header is | |||
"T" then prior to performing the move the server MUST perform a | "T" then prior to performing the move the server MUST perform a | |||
DELETE with "Depth: infinity" on the destination resource. If the | DELETE with "Depth: infinity" on the destination resource. If the | |||
Overwrite header is set to "F" then the operation will fail. | Overwrite header is set to "F" then the operation will fail. | |||
8.9.4. Status Codes | 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 | 201 (Created) - The source resource was successfully moved, and a new | |||
resource was created at the destination. | URL mapping was created at the destination. | |||
204 (No Content) - The source resource was successfully moved to a | 204 (No Content) - The source resource was successfully moved to a | |||
pre-existing destination resource. | URL that was already mapped. | |||
403 (Forbidden) - The source and destination URIs are the same. | 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. E.g. 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 | 409 (Conflict) - A resource cannot be created at the destination | |||
until one or more intermediate collections have been created. | 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) - The server was unable to maintain the | 412 (Precondition Failed) - A condition header failed. Specific to | |||
liveness of the properties listed in the propertybehavior XML element | MOVE, this could mean that the Overwrite header is "F" and the | |||
or the Overwrite header is "F" and the state of the destination | destination URL is already mapped to a resource. | |||
resource is non-null. | ||||
423 (Locked) - The source or the destination resource was locked. | 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 | 502 (Bad Gateway) - This may occur when the destination is on another | |||
server and the destination server refuses to accept the resource. | 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. | ||||
8.9.5. Example - MOVE of a Non-Collection | 9.9.5. Example - MOVE of a Non-Collection | |||
This example shows resource | This example shows resource | |||
http://www.ics.uci.edu/~fielding/index.html being moved to the | http://www.example.com/~fielding/index.html being moved to the | |||
location http://www.ics.uci.edu/users/f/fielding/index.html. The | location http://www.example.com/users/f/fielding/index.html. The | |||
contents of the destination resource would have been overwritten if | contents of the destination resource would have been overwritten if | |||
the destination resource had been non-null. In this case, since | the destination URL was already mapped to a resource. In this case, | |||
there was nothing at the destination resource, the response code is | since there was nothing at the destination resource, the response | |||
201 (Created). | code is 201 (Created). | |||
>>Request | >>Request | |||
MOVE /~fielding/index.html HTTP/1.1 | MOVE /~fielding/index.html HTTP/1.1 | |||
Host: www.ics.uci.edu | Host: www.example.com | |||
Destination: http://www.ics.uci.edu/users/f/fielding/index.html | Destination: http://www.example/users/f/fielding/index.html | |||
>>Response | >>Response | |||
HTTP/1.1 201 Created | HTTP/1.1 201 Created | |||
Location: http://www.ics.uci.edu/users/f/fielding/index.html | Location: http://www.example.com/users/f/fielding/index.html | |||
8.9.6. Example - MOVE of a Collection | 9.9.6. Example - MOVE of a Collection | |||
>>Request | >>Request | |||
MOVE /container/ HTTP/1.1 | MOVE /container/ HTTP/1.1 | |||
Host: www.foo.bar | Host: www.example.com | |||
Destination: http://www.foo.bar/othercontainer/ | Destination: http://www.example.com/othercontainer/ | |||
Overwrite: F | Overwrite: F | |||
If: (<opaquelocktoken:fe184f2e-6eec-41d0-c765-01adc56e6bb4>) | If: (<urn:uuid:fe184f2e-6eec-41d0-c765-01adc56e6bb4>) | |||
(<opaquelocktoken:e454f3f3-acdc-452a-56c7-00a5c91e4b77>) | (<urn:uuid:e454f3f3-acdc-452a-56c7-00a5c91e4b77>) | |||
Content-Type: text/xml; charset="utf-8" | ||||
Content-Length: xxxx | ||||
<?xml version="1.0" encoding="utf-8" ?> | ||||
<d:propertybehavior xmlns:d='DAV:'> | ||||
<d:keepalive>*</d:keepalive> | ||||
</d:propertybehavior> | ||||
>>Response | >>Response | |||
HTTP/1.1 207 Multi-Status | HTTP/1.1 207 Multi-Status | |||
Content-Type: text/xml; charset="utf-8" | Content-Type: application/xml; charset="utf-8" | |||
Content-Length: xxxx | Content-Length: xxxx | |||
<?xml version="1.0" encoding="utf-8" ?> | <?xml version="1.0" encoding="utf-8" ?> | |||
<d:multistatus xmlns:d='DAV:'> | <d:multistatus xmlns:d='DAV:'> | |||
<d:response> | <d:response> | |||
<d:href>http://www.foo.bar/othercontainer/C2/</d:href> | <d:href>http://www.example.com/othercontainer/C2/</d:href> | |||
<d:status>HTTP/1.1 423 Locked</d:status> | <d:status>HTTP/1.1 423 Locked</d:status> | |||
</d:response> | <d:error><d:lock-token-submitted/></d:error> | |||
</d:multistatus> | </d:response> | |||
</d:multistatus> | ||||
In this example the client has submitted a number of lock tokens with | 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 | the request. A lock token will need to be submitted for every | |||
resource, both source and destination, anywhere in the scope of the | resource, both source and destination, anywhere in the scope of the | |||
method, that is locked. In this case the proper lock token was not | method, that is locked. In this case the proper lock token was not | |||
submitted for the destination http://www.foo.bar/othercontainer/C2/. | submitted for the destination | |||
http://www.example.com/othercontainer/C2/. This means that the | ||||
This means that the resource /container/C2/ could not be moved. | resource /container/C2/ could not be moved. Because there was an | |||
Because there was an error copying /container/C2/, none of | error moving /container/C2/, none of /container/C2's members were | |||
/container/C2's members were copied. However no errors were listed | moved. However no errors were listed for those members due to the | |||
for those members due to the error minimization rules given in | error minimization rules. User agent authentication has previously | |||
Section 8.8.3. User agent authentication has previously occurred via | occurred via a mechanism outside the scope of the HTTP protocol, in | |||
a mechanism outside the scope of the HTTP protocol, in an underlying | an underlying transport layer. | |||
transport layer. | ||||
8.10. LOCK Method | 9.10. LOCK Method | |||
The following sections describe the LOCK method, which is used to | The following sections describe the LOCK method, which is used to | |||
take out a lock of any access type. These sections on the LOCK | take out a lock of any access type and to refresh an existing lock. | |||
method describe only those semantics that are specific to the LOCK | These sections on the LOCK method describe only those semantics that | |||
method and are independent of the access type of the lock being | are specific to the LOCK method and are independent of the access | |||
requested. | type of the lock being requested. | |||
Any resource which supports the LOCK method MUST, at minimum, support | Any resource which supports the LOCK method MUST, at minimum, support | |||
the XML request and response formats defined herein. | the XML request and response formats defined herein. | |||
8.10.1. Operation | This method is neither idempotent nor safe (see Section 9.1 of | |||
[RFC2616]). Responses to this method MUST NOT be cached. | ||||
A LOCK method invocation creates the lock specified by the lockinfo | 9.10.1. Creating a Lock on an Existing Resource | |||
XML element on the Request-URI. Lock method requests SHOULD have a | ||||
XML request body which contains an owner XML element for this lock | ||||
request, unless this is a refresh request. The LOCK request may have | ||||
a Timeout header. | ||||
Clients MUST assume that locks may arbitrarily disappear at any time, | A LOCK request to an existing resource will create a lock on the | |||
regardless of the value given in the Timeout header. The Timeout | resource identified by the Request-URI, provided the resource is not | |||
header only indicates the behavior of the server if "extraordinary" | already locked with a conflicting lock. The resource identified in | |||
circumstances do not occur. For example, an administrator may remove | the Request-URI becomes the root of the lock. Lock method requests | |||
a lock at any time or the system may crash in such a way that it | to create a new lock MUST have an XML request body. The server MUST | |||
loses the record of the lock's existence. The response MUST contain | preserve the information provided by the client in the 'owner' field | |||
the value of the lockdiscovery property in a prop XML element. | in the request body when the lock information is requested. The LOCK | |||
request MAY have a Timeout header. | ||||
In order to indicate the lock token associated with a newly created | When a new lock is created, the LOCK response: | |||
lock, a Lock-Token response header MUST be included in the response | ||||
for every successful LOCK request for a new lock. Note that the | ||||
Lock-Token header would not be returned in the response for a | ||||
successful refresh LOCK request because a new lock was not created. | ||||
8.10.2. The Effect of Locks on Properties and Collections | 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. | ||||
The scope of a lock is the entire state of the resource, including | o MUST include the Lock-Token response header with the token | |||
its body and associated properties. As a result, a lock on a | associated with the new lock. | |||
resource MUST also lock the resource's properties. | ||||
For collections, a lock also affects the ability to add or remove | 9.10.2. Refreshing Locks | |||
members. The nature of the effect depends upon the type of access | ||||
control involved. | ||||
8.10.3. Locking Replicated Resources | 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. | ||||
A resource may be made available through more than one URI. However | If the resource has other (shared) locks, those locks are unaffected | |||
locks apply to resources, not URIs. Therefore a LOCK request on a | by a lock refresh. Additionally, those locks do not prevent the | |||
resource MUST NOT succeed if can not be honored by all the URIs | named lock from being refreshed. | |||
through which the resource is addressable. | ||||
8.10.4. Depth and Locking | 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 | 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 | 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 | method. All resources that support the LOCK method MUST support the | |||
Depth header. | Depth header. | |||
A Depth header of value 0 means to just lock the resource specified | A Depth header of value 0 means to just lock the resource specified | |||
by the Request-URI. | by the Request-URI. | |||
If the Depth header is set to infinity then the resource specified in | If the Depth header is set to infinity then the resource specified in | |||
the Request-URI along with all its internal members, all the way down | the Request-URI along with all its members, all the way down the | |||
the hierarchy, are to be locked. A successful result MUST return a | hierarchy, are to be locked. A successful result MUST return a | |||
single lock token which represents all the resources that have been | single lock token. Similarly, if an UNLOCK is successfully executed | |||
locked. If an UNLOCK is successfully executed on this token, all | on this token, all associated resources are unlocked. Hence, partial | |||
associated resources are unlocked. If the lock cannot be granted to | success is not an option for LOCK or UNLOCK. Either the entire | |||
all resources, a 409 (Conflict) status code MUST be returned with a | hierarchy is locked or no resources are locked. | |||
response entity body containing a multistatus XML element describing | ||||
which resource(s) prevented the lock from being granted. Hence, | If the lock cannot be granted to all resources, the server MUST | |||
partial success is not an option. Either the entire hierarchy is | return a Multi-Status response with a 'response' element for at least | |||
locked or no resources are locked. | one resource which 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 | If no Depth header is submitted on a LOCK request then the request | |||
MUST act as if a "Depth:infinity" had been submitted. | MUST act as if a "Depth:infinity" had been submitted. | |||
8.10.5. Interaction with other Methods | 9.10.4. Locking Unmapped URLs | |||
The interaction of a LOCK with various methods is dependent upon the | A successful LOCK method MUST result in the creation of an empty | |||
lock type. However, independent of lock type, a successful DELETE of | resource which is locked (and which is not a collection), when a | |||
a resource MUST cause all of its locks to be removed. | 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 | ||||
8.10.6. Lock Compatibility Table | 9.10.5. Lock Compatibility Table | |||
The table below describes the behavior that occurs when a lock | The table below describes the behavior that occurs when a lock | |||
request is made on a resource. | request is made on a resource. | |||
+-----------------------------------+-------------+----------------+ | +--------------------------+----------------+-------------------+ | |||
| Current lock state / Lock request | Shared Lock | Exclusive Lock | | | Current State | Shared Lock OK | Exclusive Lock OK | | |||
+-----------------------------------+-------------+----------------+ | +--------------------------+----------------+-------------------+ | |||
| None | True | True | | | None | True | True | | |||
| Shared Lock | True | False | | | | | | | |||
| Exclusive Lock | False | False* | | | Shared Lock | True | False | | |||
+-----------------------------------+-------------+----------------+ | | | | | | |||
| Exclusive Lock | False | False* | | ||||
+--------------------------+----------------+-------------------+ | ||||
Legend: True = lock may be granted. False = lock MUST NOT be | Legend: True = lock may be granted. False = lock MUST NOT be | |||
granted. *=It is illegal for a principal to request the same lock | granted. *=It is illegal for a principal to request the same lock | |||
twice. | twice. | |||
The current lock state of a resource is given in the leftmost column, | 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 | 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 | 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 | shared lock is held on a resource, and an exclusive lock is | |||
requested, the table entry is "false", indicating the lock must not | requested, the table entry is "false", indicating the lock must not | |||
be granted. | be granted. | |||
8.10.7. Status Codes | 9.10.6. LOCK Responses | |||
200 (OK) - The lock request succeeded and the value of the | In addition to the general status codes possible, the following | |||
lockdiscovery property is included in the body. | status codes have specific applicability to LOCK: | |||
412 (Precondition Failed) - The included lock token was not | 200 (OK) - The LOCK request succeeded and the value of the DAV: | |||
enforceable on this resource or the server could not satisfy the | lockdiscovery property is included in the response body. | |||
request in the lockinfo XML element. | ||||
423 (Locked) - The resource is locked, so the method has been | 201 (Created) - The LOCK request was to an unmapped URL, the request | |||
rejected. | succeeded and resulted in the creation of a new resource, and the | |||
value of the DAV:lockdiscovery property is included in the response | ||||
body. | ||||
8.10.8. Example - Simple Lock Request | 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 which 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 a 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 | >>Request | |||
LOCK /workspace/webdav/proposal.doc HTTP/1.1 | LOCK /workspace/webdav/proposal.doc HTTP/1.1 | |||
Host: webdav.sb.aol.com | Host: example.com | |||
Timeout: Infinite, Second-4100000000 | Timeout: Infinite, Second-4100000000 | |||
Content-Type: text/xml; charset="utf-8" | Content-Type: application/xml; charset="utf-8" | |||
Content-Length: xxxx | Content-Length: xxxx | |||
Authorization: Digest username="ejw", | Authorization: Digest username="ejw", | |||
realm="ejw@webdav.sb.aol.com", nonce="...", | realm="ejw@example.com", nonce="...", | |||
uri="/workspace/webdav/proposal.doc", | uri="/workspace/webdav/proposal.doc", | |||
response="...", opaque="..." | response="...", opaque="..." | |||
<?xml version="1.0" encoding="utf-8" ?> | <?xml version="1.0" encoding="utf-8" ?> | |||
<D:lockinfo xmlns:D='DAV:'> | <D:lockinfo xmlns:D='DAV:'> | |||
<D:lockscope><D:exclusive/></D:lockscope> | <D:lockscope><D:exclusive/></D:lockscope> | |||
<D:locktype><D:write/></D:locktype> | <D:locktype><D:write/></D:locktype> | |||
<D:owner> | <D:owner> | |||
<D:href>http://www.ics.uci.edu/~ejw/contact.html</D:href> | <D:href>http://example.org/~ejw/contact.html</D:href> | |||
</D:owner> | </D:owner> | |||
</D:lockinfo> | </D:lockinfo> | |||
>>Response | >>Response | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
Content-Type: text/xml; charset="utf-8" | Lock-Token: <urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4> | |||
Content-Length: xxxx | Content-Type: application/xml; charset="utf-8" | |||
Content-Length: xxxx | ||||
<?xml version="1.0" encoding="utf-8" ?> | <?xml version="1.0" encoding="utf-8" ?> | |||
<D:prop xmlns:D="DAV:"> | <D:prop xmlns:D="DAV:"> | |||
<D:lockdiscovery> | <D:lockdiscovery> | |||
<D:activelock> | <D:activelock> | |||
<D:locktype><D:write/></D:locktype> | <D:locktype><D:write/></D:locktype> | |||
<D:lockscope><D:exclusive/></D:lockscope> | <D:lockscope><D:exclusive/></D:lockscope> | |||
<D:depth>Infinity</D:depth> | <D:depth>infinity</D:depth> | |||
<D:owner> | <D:owner> | |||
<D:href> | <D:href>http://example.org/~ejw/contact.html</D:href> | |||
http://www.ics.uci.edu/~ejw/contact.html | </D:owner> | |||
</D:href> | <D:timeout>Second-604800</D:timeout> | |||
</D:owner> | <D:locktoken> | |||
<D:timeout>Second-604800</D:timeout> | <D:href | |||
<D:locktoken> | >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href> | |||
<D:href> | </D:locktoken> | |||
opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4 | <D:lockroot> | |||
</D:href> | <D:href | |||
</D:locktoken> | >http://example.com/workspace/webdav/proposal.doc</D:href> | |||
</D:activelock> | </D:lockroot> | |||
</D:lockdiscovery> | </D:activelock> | |||
</D:prop> | </D:lockdiscovery> | |||
</D:prop> | ||||
This example shows the successful creation of an exclusive write lock | This example shows the successful creation of an exclusive write lock | |||
on resource http://webdav.sb.aol.com/workspace/webdav/proposal.doc. | on resource http://example.com/workspace/webdav/proposal.doc. The | |||
The resource http://www.ics.uci.edu/~ejw/contact.html contains | resource http://example.org/~ejw/contact.html contains contact | |||
contact information for the owner of the lock. The server has an | information for the creator of the lock. The server has an activity- | |||
activity-based timeout policy in place on this resource, which causes | based timeout policy in place on this resource, which causes the lock | |||
the lock to automatically be removed after 1 week (604800 seconds). | to automatically be removed after 1 week (604800 seconds). Note that | |||
Note that the nonce, response, and opaque fields have not been | the nonce, response, and opaque fields have not been calculated in | |||
calculated in the Authorization request header. | the Authorization request header. | |||
8.10.9. Example - Refreshing a Write Lock | 9.10.8. Example - Refreshing a Write Lock | |||
>>Request | >>Request | |||
LOCK /workspace/webdav/proposal.doc HTTP/1.1 | LOCK /workspace/webdav/proposal.doc HTTP/1.1 | |||
Host: webdav.sb.aol.com | Host: example.com | |||
Timeout: Infinite, Second-4100000000 | Timeout: Infinite, Second-4100000000 | |||
If: (<opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>) | If: (<urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>) | |||
Authorization: Digest username="ejw", | Authorization: Digest username="ejw", | |||
realm="ejw@webdav.sb.aol.com", nonce="...", | realm="ejw@example.com", nonce="...", | |||
uri="/workspace/webdav/proposal.doc", | uri="/workspace/webdav/proposal.doc", | |||
response="...", opaque="..." | response="...", opaque="..." | |||
>>Response | >>Response | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
Content-Type: text/xml; charset="utf-8" | Content-Type: application/xml; charset="utf-8" | |||
Content-Length: xxxx | Content-Length: xxxx | |||
<?xml version="1.0" encoding="utf-8" ?> | <?xml version="1.0" encoding="utf-8" ?> | |||
<D:prop xmlns:D="DAV:"> | <D:prop xmlns:D="DAV:"> | |||
<D:lockdiscovery> | <D:lockdiscovery> | |||
<D:activelock> | <D:activelock> | |||
<D:locktype><D:write/></D:locktype> | <D:locktype><D:write/></D:locktype> | |||
<D:lockscope><D:exclusive/></D:lockscope> | <D:lockscope><D:exclusive/></D:lockscope> | |||
<D:depth>Infinity</D:depth> | <D:depth>infinity</D:depth> | |||
<D:owner> | <D:owner> | |||
<D:href> | <D:href>http://example.org/~ejw/contact.html</D:href> | |||
http://www.ics.uci.edu/~ejw/contact.html | </D:owner> | |||
</D:href> | <D:timeout>Second-604800</D:timeout> | |||
</D:owner> | <D:locktoken> | |||
<D:timeout>Second-604800</D:timeout> | <D:href | |||
<D:locktoken> | >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href> | |||
<D:href> | </D:locktoken> | |||
opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4 | <D:lockroot> | |||
</D:href> | <D:href | |||
</D:locktoken> | >http://example.com/workspace/webdav/proposal.doc</D:href> | |||
</D:activelock> | </D:lockroot> | |||
</D:lockdiscovery> | </D:activelock> | |||
</D:prop> | </D:lockdiscovery> | |||
</D:prop> | ||||
This request would refresh the lock, resetting any time outs. Notice | This request would refresh the lock, attempting to reset the timeout | |||
that the client asked for an infinite time out but the server choose | to the new value specified in the timeout header. Notice that the | |||
to ignore the request. In this example, the nonce, response, and | client asked for an infinite time out but the server choose to ignore | |||
opaque fields have not been calculated in the Authorization request | the request. In this example, the nonce, response, and opaque fields | |||
header. | have not been calculated in the Authorization request header. | |||
8.10.10. Example - Multi-Resource Lock Request | 9.10.9. Example - Multi-Resource Lock Request | |||
>>Request | >>Request | |||
LOCK /webdav/ HTTP/1.1 | LOCK /webdav/ HTTP/1.1 | |||
Host: webdav.sb.aol.com | Host: example.com | |||
Timeout: Infinite, Second-4100000000 | Timeout: Infinite, Second-4100000000 | |||
Depth: infinity | Depth: infinity | |||
Content-Type: text/xml; charset="utf-8" | Content-Type: application/xml; charset="utf-8" | |||
Content-Length: xxxx | Content-Length: xxxx | |||
Authorization: Digest username="ejw", | Authorization: Digest username="ejw", | |||
realm="ejw@webdav.sb.aol.com", nonce="...", | realm="ejw@example.com", nonce="...", | |||
uri="/workspace/webdav/proposal.doc", | uri="/workspace/webdav/proposal.doc", | |||
response="...", opaque="..." | response="...", opaque="..." | |||
<?xml version="1.0" encoding="utf-8" ?> | <?xml version="1.0" encoding="utf-8" ?> | |||
<D:lockinfo xmlns:D="DAV:"> | <D:lockinfo xmlns:D="DAV:"> | |||
<D:locktype><D:write/></D:locktype> | <D:locktype><D:write/></D:locktype> | |||
<D:lockscope><D:exclusive/></D:lockscope> | <D:lockscope><D:exclusive/></D:lockscope> | |||
<D:owner> | <D:owner> | |||
<D:href>http://www.ics.uci.edu/~ejw/contact.html</D:href> | <D:href>http://example.org/~ejw/contact.html</D:href> | |||
</D:owner> | </D:owner> | |||
</D:lockinfo> | </D:lockinfo> | |||
>>Response | >>Response | |||
HTTP/1.1 207 Multi-Status | HTTP/1.1 207 Multi-Status | |||
Content-Type: text/xml; charset="utf-8" | Content-Type: application/xml; charset="utf-8" | |||
Content-Length: xxxx | Content-Length: xxxx | |||
<?xml version="1.0" encoding="utf-8" ?> | <?xml version="1.0" encoding="utf-8" ?> | |||
<D:multistatus xmlns:D="DAV:"> | <D:multistatus xmlns:D="DAV:"> | |||
<D:response> | <D:response> | |||
<D:href>http://webdav.sb.aol.com/webdav/secret</D:href> | <D:href>http://example.com/webdav/secret</D:href> | |||
<D:status>HTTP/1.1 403 Forbidden</D:status> | <D:status>HTTP/1.1 403 Forbidden</D:status> | |||
</D:response> | </D:response> | |||
<D:response> | <D:response> | |||
<D:href>http://webdav.sb.aol.com/webdav/</D:href> | <D:href>http://example.com/webdav/</D:href> | |||
<D:propstat> | <D:status>HTTP/1.1 424 Failed Dependency</D:status> | |||
<D:prop><D:lockdiscovery/></D:prop> | </D:response> | |||
<D:status>HTTP/1.1 424 Failed Dependency</D:status> | </D:multistatus> | |||
</D:propstat> | ||||
</D:response> | ||||
</D:multistatus> | ||||
This example shows a request for an exclusive write lock on a | This example shows a request for an exclusive write lock on a | |||
collection and all its children. In this request, the client has | collection and all its children. In this request, the client has | |||
specified that it desires an infinite length lock, if available, | specified that it desires an infinite length lock, if available, | |||
otherwise a timeout of 4.1 billion seconds, if available. The | otherwise a timeout of 4.1 billion seconds, if available. The | |||
request entity body contains the contact information for the | request entity body contains the contact information for the | |||
principal taking out the lock, in this case a web page URL. | principal taking out the lock, in this case a web page URL. | |||
The error is a 403 (Forbidden) response on the resource | The error is a 403 (Forbidden) response on the resource | |||
http://webdav.sb.aol.com/webdav/secret. Because this resource could | http://example.com/webdav/secret. Because this resource could not be | |||
not be locked, none of the resources were locked. Note also that the | locked, none of the resources were locked. Note also that the a | |||
lockdiscovery property for the Request-URI has been included as | 'response' element for the Request-URI itself has been included as | |||
required. In this example the lockdiscovery property is empty which | required. | |||
means that there are no outstanding locks on the resource. | ||||
In this example, the nonce, response, and opaque fields have not been | In this example, the nonce, response, and opaque fields have not been | |||
calculated in the Authorization request header. | calculated in the Authorization request header. | |||
8.11. UNLOCK Method | 9.11. UNLOCK Method | |||
The UNLOCK method removes the lock identified by the lock token in | The UNLOCK method removes the lock identified by the lock token in | |||
the Lock-Token request header from the Request-URI, and all other | the Lock-Token request header. The Request-URI MUST identify a | |||
resources included in the lock. If all resources which have been | resource within the scope of the lock. | |||
locked under the submitted lock token can not be unlocked then the | ||||
UNLOCK request MUST fail. | Note that use of 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 which have been locked under the submitted lock | ||||
token can not 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 which supports the LOCK method MUST | Any DAV compliant resource which supports the LOCK method MUST | |||
support the UNLOCK method. | support the UNLOCK method. | |||
8.11.1. Example - UNLOCK | 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. | ||||
9.11.2. Example - UNLOCK | ||||
>>Request | >>Request | |||
UNLOCK /workspace/webdav/info.doc HTTP/1.1 | UNLOCK /workspace/webdav/info.doc HTTP/1.1 | |||
Host: webdav.sb.aol.com | Host: example.com | |||
Lock-Token: <opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7> | Lock-Token: <urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7> | |||
Authorization: Digest username="ejw", | Authorization: Digest username="ejw" | |||
realm="ejw@webdav.sb.aol.com", nonce="...", | realm="ejw@example.com", nonce="...", | |||
uri="/workspace/webdav/proposal.doc", | uri="/workspace/webdav/proposal.doc", | |||
response="...", opaque="..." | response="...", opaque="..." | |||
>>Response | >>Response | |||
HTTP/1.1 204 No Content | HTTP/1.1 204 No Content | |||
In this example, the lock identified by the lock token | In this example, the lock identified by the lock token | |||
"opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is | "urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is successfully | |||
successfully removed from the resource | removed from the resource | |||
http://webdav.sb.aol.com/workspace/webdav/info.doc. If this lock | http://example.com/workspace/webdav/info.doc. If this lock included | |||
included more than just one resource, the lock is removed from all | more than just one resource, the lock is removed from all resources | |||
resources included in the lock. The 204 (No Content) status code is | included in the lock. | |||
used instead of 200 (OK) because there is no response entity body. | ||||
In this example, the nonce, response, and opaque fields have not been | In this example, the nonce, response, and opaque fields have not been | |||
calculated in the Authorization request header. | calculated in the Authorization request header. | |||
9. HTTP Headers for Distributed Authoring | 10. HTTP Headers for Distributed Authoring | |||
9.1. DAV Header | 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. | ||||
DAV = "DAV" ":" "1" ["," "2"] ["," 1#extend] | WebDAV adds two new conditional headers to the set defined in HTTP: | |||
the If and Overwrite headers. | ||||
This header indicates that the resource supports the DAV schema and | 10.1. DAV Header | |||
protocol as specified. All DAV compliant resources MUST return the | ||||
DAV header on all OPTIONS responses. | ||||
The value is a list of all compliance classes that the resource | DAV = "DAV" ":" #( compliance-class ) | |||
supports. Note that above a comma has already been added to the 2. | compliance-class = ( "1" | "2" | "3" | extend ) | |||
This is because a resource can not be level 2 compliant unless it is | extend = Coded-URL | token | |||
also level 1 compliant. Please refer to Section 15 for more details. | Coded-URL = "<" absolute-URI ">" | |||
In general, however, support for one compliance class does not entail | ; No linear white space (LWS) allowed in Coded-URL | |||
support for any other. | ; absolute-URI is defined in RFC3986 | |||
9.2. Depth Header | 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") | Depth = "Depth" ":" ("0" | "1" | "infinity") | |||
The Depth header is used with methods executed on resources which | The Depth request header is used with methods executed on resources | |||
could potentially have internal members to indicate whether the | which could potentially have internal members to indicate whether the | |||
method is to be applied only to the resource ("Depth: 0"), to the | method is to be applied only to the resource ("Depth: 0"), to the | |||
resource and its immediate children, ("Depth: 1"), or the resource | resource and its internal members only, ("Depth: 1"), or the resource | |||
and all its progeny ("Depth: infinity"). | and all its members ("Depth: infinity"). | |||
The Depth header is only supported if a method's definition | The Depth header is only supported if a method's definition | |||
explicitly provides for such support. | explicitly provides for such support. | |||
The following rules are the default behavior for any method that | The following rules are the default behavior for any method that | |||
supports the Depth header. A method may override these defaults by | supports the Depth header. A method may override these defaults by | |||
defining different behavior in its definition. | defining different behavior in its definition. | |||
Methods which support the Depth header may choose not to support all | Methods which 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 | of the header's values and may define, on a case by case basis, the | |||
skipping to change at page 57, line 12 ¶ | skipping to change at page 77, line 41 ¶ | |||
hierarchies in any particular order or on the execution being atomic | hierarchies in any particular order or on the execution being atomic | |||
unless the particular method explicitly provides such guarantees. | unless the particular method explicitly provides such guarantees. | |||
Upon execution, a method with a Depth header will perform as much of | Upon execution, a method with a Depth header will perform as much of | |||
its assigned task as possible and then return a response specifying | its assigned task as possible and then return a response specifying | |||
what it was able to accomplish and what it failed to do. | 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 | So, for example, an attempt to COPY a hierarchy may result in some of | |||
the members being copied and some not. | the members being copied and some not. | |||
Any headers on a method that has a defined interaction with the Depth | By default, the Depth header does not interact with other headers. | |||
header MUST be applied to all resources in the scope of the method | That is, each header on a request with a Depth header MUST be applied | |||
except where alternative behavior is explicitly defined. For | only to the Request-URI if it applies to any resource, unless | |||
example, an If-Match header will have its value applied against every | specific Depth behavior is defined for that header. | |||
resource in the method's scope and will cause the method to fail if | ||||
the header fails to match. | ||||
If a resource, source or destination, within the scope of the method | If a resource, source or destination, within the scope of the method | |||
with a Depth header is locked in such a way as to prevent the | with a Depth header is locked in such a way as to prevent the | |||
successful execution of the method, then the lock token for that | successful execution of the method, then the lock token for that | |||
resource MUST be submitted with the request in the If request header. | resource MUST be submitted with the request in the If request header. | |||
The Depth header only specifies the behavior of the method with | The Depth header only specifies the behavior of the method with | |||
regards to internal children. If a resource does not have internal | regards to internal members. If a resource does not have internal | |||
children then the Depth header MUST be ignored. | members then the Depth header MUST be ignored. | |||
Please note, however, that it is always an error to submit a value | 10.3. Destination Header | |||
for the Depth header that is not allowed by the method's definition. | ||||
Thus submitting a "Depth: 1" on a COPY, even if the resource does not | ||||
have internal members, will result in a 400 (Bad Request). The | ||||
method should fail not because the resource doesn't have internal | ||||
members, but because of the illegal value in the header. | ||||
9.3. Destination Header | The Destination request header specifies the URI which identifies a | |||
destination resource for methods such as COPY and MOVE, which take | ||||
two URIs as parameters. | ||||
Destination = "Destination" ":" absoluteURI | Destination = "Destination" ":" Simple-ref | |||
The Destination header specifies the URI which identifies a | If the Destination value is an absolute-URI (Section 4.3 of | |||
destination resource for methods such as COPY and MOVE, which take | [RFC3986]), it may name a different server (or different port or | |||
two URIs as parameters. Note that the absoluteURI production is | scheme). If the source server cannot attempt a copy to the remote | |||
defined in [RFC2396]. | 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). | ||||
9.4. If Header | 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. | ||||
If = "If" ":" ( 1*No-tag-list | 1*Tagged-list) | 10.4. If Header | |||
No-tag-list = List | ||||
Tagged-list = Resource 1*List | ||||
Resource = Coded-URL | ||||
List = "(" 1*(["Not"](State-token | "[" entity-tag "]")) ")" | ||||
State-token = Coded-URL | ||||
Coded-URL = "<" absoluteURI ">" | ||||
The If header is intended to have similar functionality to the If- | The If request header is intended to have similar functionality to | |||
Match header defined in section 14.25 of [RFC2068]. However the If | the If-Match header defined in Section 14.24 of [RFC2616]. However | |||
header is intended for use with any URI which represents state | the If header handles any state token as well as ETags. A typical | |||
information, referred to as a state token, about a resource as well | example of a state token is a lock token, and lock tokens are the | |||
as ETags. A typical example of a state token is a lock token, and | only state tokens defined in this specification. | |||
lock tokens are the only state tokens defined in this specification. | ||||
All DAV compliant resources MUST honor the If header. | 10.4.1. Purpose | |||
The If header's purpose is to describe a series of state lists. If | The If header has two distinct purposes: | |||
the state of the resource to which the header is applied does not | ||||
match any of the specified state lists then the request MUST fail | ||||
with a 412 (Precondition Failed). If one of the described state | ||||
lists matches the state of the resource then the request may succeed. | ||||
Note that the absoluteURI production is defined in [RFC2396]. | 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 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 | ||||
Section 10.4.3 and Section 10.4.4. | ||||
9.4.1. No-tag-list Production | 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). | ||||
The No-tag-list production describes a series of state tokens and | Note that these two purposes need to be treated distinctly: a state | |||
ETags. If multiple No-tag-list productions are used then one only | token counts as being submitted independently of whether the server | |||
needs to match the state of the resource for the method to be allowed | actually has evaluated the state list it appears in, and also | |||
to continue. | independently of whether the condition it expressed was found to be | |||
true or not. | ||||
If a method, due to the presence of a Depth or Destination header, is | 10.4.2. Syntax | |||
applied to multiple resources then the No-tag-list production MUST be | ||||
applied to each resource the method is applied to. | ||||
9.4.1.1. Example - No-tag-list If Header | If = "If" ":" ( 1*No-tag-list | 1*Tagged-list ) | |||
If: (<locktoken:a-write-lock-token> ["I am an ETag"]) (["I am another | No-tag-list = List | |||
ETag"]) | Tagged-list = Resource-Tag 1*List | |||
The previous header would require that any resources within the scope | List = "(" 1*Condition ")" | |||
of the method must either be locked with the specified lock token and | Condition = ["Not"] (State-token | "[" entity-tag "]") | |||
in the state identified by the "I am an ETag" ETag or in the state | ; entity-tag: see Section 3.11 of [RFC2616] | |||
identified by the second ETag "I am another ETag". To put the matter | ; No LWS allowed between "[", entity-tag and "]" | |||
more plainly one can think of the previous If header as being in the | ||||
form (or (and <locktoken:a-write-lock-token> ["I am an ETag"]) (and | ||||
["I am another ETag"])). | ||||
9.4.2. Tagged-list Production | State-token = Coded-URL | |||
The tagged-list production scopes a list production. That is, it | Resource-Tag = "<" Simple-ref ">" | |||
specifies that the lists following the resource specification only | ; Simple-ref: see Section 8.3 | |||
apply to the specified resource. The scope of the resource | ; No LWS allowed in Resource-Tag | |||
production begins with the list production immediately following the | ||||
resource production and ends with the next resource production, if | ||||
any. | ||||
When the If header is applied to a particular resource, the Tagged- | The syntax distinguishes between untagged lists ("No-tag-list") and | |||
list productions MUST be searched to determine if any of the listed | tagged lists ("Tagged-list"). Untagged lists apply to the resource | |||
resources match the operand resource(s) for the current method. If | identified by the Request-URI, while tagged lists apply to the | |||
none of the resource productions match the current resource then the | resource identified by the preceding Resource-Tag. | |||
header MUST be ignored. If one of the resource productions does | ||||
match the name of the resource under consideration then the list | ||||
productions following the resource production MUST be applied to the | ||||
resource in the manner specified in the previous section. | ||||
The same URI MUST NOT appear more than once in a resource production | A Resource-Tag applies to all subsequent Lists, up to the next | |||
in an If header. | Resource-Tag. | |||
9.4.2.1. Example - Tagged List If header | 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. | ||||
COPY /resource1 HTTP/1.1 | Each List consists of one or more Conditions. Each Condition is | |||
Host: www.foo.bar | defined in terms of an entity-tag or state-token, potentially negated | |||
Destination: http://www.foo.bar/resource2 | by the prefix "Not". | |||
If: <http://www.foo.bar/resource1> (<locktoken:a-write-lock-token> | ||||
[W/"A weak ETag"]) (["strong ETag"]) | ||||
<http://www.bar.bar/random>(["another strong ETag"]) | ||||
In this example http://www.foo.bar/resource1 is being copied to | Note that the If header syntax does not allow multiple instances of | |||
http://www.foo.bar/resource2. When the method is first applied to | If headers in a single request. However, the HTTP header syntax | |||
http://www.foo.bar/resource1, resource1 must be in the state | allows extending single header values across multiple lines, by | |||
specified by "(<locktoken:a-write-lock-token> [W/"A weak ETag"]) | inserting a line break followed by whitespace (see [RFC2616], Section | |||
(["strong ETag"])", that is, it either must be locked with a lock | 4.2). | |||
token of "locktoken:a-write-lock-token" and have a weak entity tag | ||||
W/"A weak ETag" or it must have a strong entity tag "strong ETag". | ||||
That is the only success condition since the resource | 10.4.3. List Evaluation | |||
http://www.bar.bar/random never has the method applied to it (the | ||||
only other resource listed in the If header) and | ||||
http://www.foo.bar/resource2 is not listed in the If header. | ||||
9.4.3. not Production | 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). | ||||
Every state token or ETag is either current, and hence describes the | Each List production describes a series of conditions. The whole | |||
state of a resource, or is not current, and does not describe the | list evaluates to true if and only if each condition evaluates to | |||
state of a resource. The boolean operation of matching a state token | true (that is, the list represents a logical conjunction of | |||
or ETag to the current state of a resource thus resolves to a true or | Conditions). | |||
false value. The not production is used to reverse that value. The | ||||
scope of the not production is the state-token or entity-tag | ||||
immediately following it. | ||||
If: (Not <locktoken:write1> <locktoken:write2>) | 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). | ||||
When submitted with a request, this If header requires that all | Finally, the whole If header evaluates to true if and only if at | |||
operand resources must not be locked with locktoken:write1 and must | least one of the No-tag-list or Tagged-list productions evaluates to | |||
be locked with locktoken:write2. | 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. | ||||
9.4.4. Matching Function | 10.4.4. Matching State Tokens and ETags | |||
When performing If header processing, the definition of a matching | When performing If header processing, the definition of a matching | |||
state token or entity tag is as follows. | 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 | Matching entity tag: Where the entity tag matches an entity tag | |||
associated with that resource. | 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 | Matching state token: Where there is an exact match between the state | |||
token in the If header and any state token on the resource. | 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. | ||||
9.4.5. If Header and Non-DAV Compliant Proxies | 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. | ||||
Non-DAV compliant proxies will not honor the If header, since they | 10.4.5. If Header and Non-DAV Aware Proxies | |||
will not understand the If header, and HTTP requires non-understood | ||||
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 | headers to be ignored. When communicating with HTTP/1.1 proxies, the | |||
"Cache-Control: no-cache" request header MUST be used so as to | client MUST use the "Cache-Control: no-cache" request header so as to | |||
prevent the proxy from improperly trying to service the request from | prevent the proxy from improperly trying to service the request from | |||
its cache. When dealing with HTTP/1.0 proxies the "Pragma: no-cache" | its cache. When dealing with HTTP/1.0 proxies the "Pragma: no-cache" | |||
request header MUST be used for the same reason. | request header MUST be used for the same reason. | |||
9.5. Lock-Token Header | As 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. | ||||
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, as | ||||
lock tokens are assigned by the server, following the uniqueness | ||||
requirements described in Section 6.5, therefore in particular | ||||
exclude URIs in the "DAV:" scheme. Thus, by applying "Not" to a | ||||
known not to be current state token, 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, it either 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"]) | ||||
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. | ||||
10.5. Lock-Token Header | ||||
Lock-Token = "Lock-Token" ":" Coded-URL | Lock-Token = "Lock-Token" ":" Coded-URL | |||
The Lock-Token request header is used with the UNLOCK method to | The Lock-Token request header is used with the UNLOCK method to | |||
identify the lock to be removed. The lock token in the Lock-Token | identify the lock to be removed. The lock token in the Lock-Token | |||
request header MUST identify a lock that contains the resource | request header MUST identify a lock that contains the resource | |||
identified by Request-URI as a member. | identified by Request-URI as a member. | |||
The Lock-Token response header is used with the LOCK method to | The Lock-Token response header is used with the LOCK method to | |||
indicate the lock token created as a result of a successful LOCK | indicate the lock token created as a result of a successful LOCK | |||
request to create a new lock. | request to create a new lock. | |||
9.6. Overwrite Header | 10.6. Overwrite Header | |||
Overwrite = "Overwrite" ":" ("T" | "F") | Overwrite = "Overwrite" ":" ("T" | "F") | |||
The Overwrite header specifies whether the server should overwrite | The Overwrite request header specifies whether the server should | |||
the state of a non-null destination resource during a COPY or MOVE. | overwrite a resource mapped to the destination URL during a COPY or | |||
A value of "F" states that the server must not perform the COPY or | MOVE. A value of "F" states that the server must not perform the | |||
MOVE operation if the state of the destination resource is non-null. | COPY or MOVE operation if the destination URL does map to a resource. | |||
If the overwrite header is not included in a COPY or MOVE request | If the overwrite header is not included in a COPY or MOVE request | |||
then the resource MUST treat the request as if it has an overwrite | then the resource MUST treat the request as if it has an overwrite | |||
header of value "T". While the Overwrite header appears to duplicate | header of value "T". While the Overwrite header appears to duplicate | |||
the functionality of the If-Match: * header of HTTP/1.1, If-Match | the functionality of using a "If-Match: *" header (see [RFC2616]), | |||
applies only to the Request-URI, and not to the Destination of a COPY | If-Match applies only to the Request-URI, and not to the Destination | |||
or MOVE. | of a COPY or MOVE. | |||
If a COPY or MOVE is not performed due to the value of the Overwrite | If a COPY or MOVE is not performed due to the value of the Overwrite | |||
header, the method MUST fail with a 412 (Precondition Failed) status | header, the method MUST fail with a 412 (Precondition Failed) status | |||
code. | code. The server MUST do authorization checks before checking this | |||
or any conditional header. | ||||
All DAV compliant resources MUST support the Overwrite header. | All DAV compliant resources MUST support the Overwrite header. | |||
9.7. Status-URI Response Header | 10.7. Timeout Request Header | |||
The Status-URI response header may be used with the 102 (Processing) | ||||
status code to inform the client as to the status of a method. | ||||
Status-URI = "Status-URI" ":" *(Status-Code Coded-URL) ; Status-Code | ||||
is defined in Section 6.1.1 of [RFC2068] | ||||
The URIs listed in the header are source resources which have been | ||||
affected by the outstanding method. The status code indicates the | ||||
resolution of the method on the identified resource. So, for | ||||
example, if a MOVE method on a collection is outstanding and a 102 | ||||
(Processing) response with a Status-URI response header is returned, | ||||
the included URIs will indicate resources that have had move | ||||
attempted on them and what the result was. | ||||
9.8. Timeout Request Header | ||||
TimeOut = "Timeout" ":" 1#TimeType | TimeOut = "Timeout" ":" 1#TimeType | |||
TimeType = ("Second-" DAVTimeOutVal | "Infinite" | Other) | TimeType = ("Second-" DAVTimeOutVal | "Infinite") | |||
DAVTimeOutVal = 1*digit | ; No LWS allowed within TimeType | |||
Other = "Extend" field-value ; See section 4.2 of [RFC2068] | DAVTimeOutVal = 1*DIGIT | |||
Clients may include Timeout headers in their LOCK requests. However, | ||||
the server is not required to honor or even consider these requests. | ||||
Clients MUST NOT submit a Timeout request header with any method | ||||
other than a LOCK method. | ||||
A Timeout request header MUST contain at least one TimeType and may | ||||
contain multiple TimeType entries. The purpose of listing multiple | ||||
TimeType entries is to indicate multiple different values and value | ||||
types that are acceptable to the client. The client lists the | ||||
TimeType entries in order of preference. | ||||
Timeout response values MUST use a Second value, Infinite, or a | Clients MAY include Timeout request headers in their LOCK requests. | |||
TimeType the client has indicated familiarity with. The server may | However, the server is not required to honor or even consider these | |||
assume a client is familiar with any TimeType submitted in a Timeout | requests. Clients MUST NOT submit a Timeout request header with any | |||
header. | method other than a LOCK method. | |||
The "Second" TimeType specifies the number of seconds that will | The "Second" TimeType specifies the number of seconds that will | |||
elapse between granting of the lock at the server, and the automatic | elapse between granting of the lock at the server, and the automatic | |||
removal of the lock. The timeout value for TimeType "Second" MUST | removal of the lock. The timeout value for TimeType "Second" MUST | |||
NOT be greater than 2^32-1. | NOT be greater than 2^32-1. | |||
The timeout counter SHOULD be restarted any time an owner of the lock | See Section 6.6 for a description of lock timeout behavior. | |||
sends a method to any member of the lock, including unsupported | ||||
methods, or methods which are unsuccessful. However the lock MUST be | ||||
refreshed if a refresh LOCK method is successfully received. | ||||
If the timeout expires then the lock may be lost. Specifically, if | ||||
the server wishes to harvest the lock upon time-out, 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. Thus logs should be updated with the | ||||
disposition of the lock, notifications should be sent, etc., just as | ||||
they would be for an UNLOCK request. | ||||
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 off-line. | ||||
A client MUST NOT assume that just because the time-out has expired | ||||
the lock has been lost. | ||||
10. Status Code Extensions to HTTP/1.1 | 11. Status Code Extensions to HTTP/1.1 | |||
The following status codes are added to those defined in HTTP/1.1 | The following status codes are added to those defined in HTTP/1.1 | |||
[RFC2068]. | [RFC2616]. | |||
10.1. 102 Processing | ||||
The 102 (Processing) status code is an interim response used to | ||||
inform the client that the server has accepted the complete request, | ||||
but has not yet completed it. This status code SHOULD only be sent | ||||
when the server has a reasonable expectation that the request will | ||||
take significant time to complete. As guidance, if a method is | ||||
taking longer than 20 seconds (a reasonable, but arbitrary value) to | ||||
process the server SHOULD return a 102 (Processing) response. The | ||||
server MUST send a final response after the request has been | ||||
completed. | ||||
Methods can potentially take a long period of time to process, | ||||
especially methods that support the Depth header. In such cases the | ||||
client may time-out the connection while waiting for a response. To | ||||
prevent this the server may return a 102 (Processing) status code to | ||||
indicate to the client that the server is still processing the | ||||
method. | ||||
10.2. 207 Multi-Status | 11.1. 207 Multi-Status | |||
The 207 (Multi-Status) status code provides status for multiple | The 207 (Multi-Status) status code provides status for multiple | |||
independent operations (see Section 11 for more information). | independent operations (see Section 13 for more information). | |||
10.3. 422 Unprocessable Entity | 11.2. 422 Unprocessable Entity | |||
The 422 (Unprocessable Entity) status code means the server | The 422 (Unprocessable Entity) status code means the server | |||
understands the content type of the request entity (hence a | understands the content type of the request entity (hence a | |||
415(Unsupported Media Type) status code is inappropriate), and the | 415(Unsupported Media Type) status code is inappropriate), and the | |||
syntax of the request entity is correct (thus a 400 (Bad Request) | syntax of the request entity is correct (thus a 400 (Bad Request) | |||
status code is inappropriate) but was unable to process the contained | status code is inappropriate) but was unable to process the contained | |||
instructions. For example, this error condition may occur if an XML | instructions. For example, this error condition may occur if an XML | |||
request body contains well-formed (i.e., syntactically correct), but | request body contains well-formed (i.e., syntactically correct), but | |||
semantically erroneous XML instructions. | semantically erroneous XML instructions. | |||
10.4. 423 Locked | 11.3. 423 Locked | |||
The 423 (Locked) status code means the source or destination resource | The 423 (Locked) status code means the source or destination resource | |||
of a method is locked. | of a method is locked. This response SHOULD contain an appropriate | |||
precondition or postcondition code, such as 'lock-token-submitted' or | ||||
'no-conflicting-lock". | ||||
10.5. 424 Failed Dependency | 11.4. 424 Failed Dependency | |||
The 424 (Failed Dependency) status code means that the method could | The 424 (Failed Dependency) status code means that the method could | |||
not be performed on the resource because the requested action | not be performed on the resource because the requested action | |||
depended on another action and that action failed. For example, if a | depended on another action and that action failed. For example, if a | |||
command in a PROPPATCH method fails then, at minimum, the rest of the | command in a PROPPATCH method fails then, at minimum, the rest of the | |||
commands will also fail with 424 (Failed Dependency). | commands will also fail with 424 (Failed Dependency). | |||
10.6. 507 Insufficient Storage | 11.5. 507 Insufficient Storage | |||
The 507 (Insufficient Storage) status code means the method could not | The 507 (Insufficient Storage) status code means the method could not | |||
be performed on the resource because the server is unable to store | be performed on the resource because the server is unable to store | |||
the representation needed to successfully complete the request. This | the representation needed to successfully complete the request. This | |||
condition is considered to be temporary. If the request which | condition is considered to be temporary. If the request which | |||
received this status code was the result of a user action, the | received this status code was the result of a user action, the | |||
request MUST NOT be repeated until it is requested by a separate user | request MUST NOT be repeated until it is requested by a separate user | |||
action. | action. | |||
11. Multi-Status Response | 12. Use of HTTP Status Codes | |||
The default 207 (Multi-Status) response body is a text/xml or | These HTTP codes are not redefined, but their use is somewhat | |||
application/xml HTTP entity that contains a single XML element called | extended by WebDAV methods and requirements. In general, many HTTP | |||
multistatus, which contains a set of XML elements called response | status codes can be used in response to any request, not just in | |||
which contain 200, 300, 400, and 500 series status codes generated | cases described in this document. Note also that WebDAV servers are | |||
during the method invocation. 100 series status codes SHOULD NOT be | known to use 300-level redirect responses (and early interoperability | |||
recorded in a response XML element. | tests found clients unprepared to see those responses). A 300-level | |||
response MUST NOT be used when the server has created a new resource | ||||
in response to the request. | ||||
12. XML Element Definitions | 12.1. 412 Precondition Failed | |||
In the section below, the final line of each section gives the | Any request can contain a conditional header defined in HTTP (If- | |||
element type declaration using the format defined in [REC-XML]. The | Match, If-Modified-Since, etc.) or the "If" or "Overwrite" | |||
"Value" field, where present, specifies further restrictions on the | conditional headers defined in this specification. If the server | |||
allowable contents of the XML element using BNF (i.e., to further | evaluates a conditional header, and if that condition fails to hold, | |||
restrict the values of a PCDATA element). | then this error code MUST be returned. On the other hand, if the | |||
client did not include a conditional header in the request, then the | ||||
server MUST NOT use this status code. | ||||
12.1. activelock XML Element | 12.2. 414 Request-URI Too Long | |||
Name: activelock | This status code is used in HTTP 1.1 only for Request-URIs, not URIs | |||
in other locations. | ||||
Namespace: DAV: | 13. Multi-Status Response | |||
Purpose: Describes a lock on a resource. | A Multi-Status response conveys information about multiple resources | |||
in situations where multiple status codes might be appropriate. The | ||||
default Multi-Status response body is a text/xml or application/xml | ||||
HTTP entity with a 'multistatus' root element. Further elements | ||||
contain 200, 300, 400, and 500 series status codes generated during | ||||
the method invocation. 100 series status codes SHOULD NOT be recorded | ||||
in a 'response' XML element. | ||||
<!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?, | Although '207' is used as the overall response status code, the | |||
locktoken?) > | recipient needs to consult the contents of the multistatus response | |||
body for further information about the success or failure of the | ||||
method execution. The response MAY be used in success, partial | ||||
success and also in failure situations. | ||||
12.1.1. depth XML Element | The 'multistatus' root element holds zero or more 'response' elements | |||
in any order, each with information about an individual resource. | ||||
Each 'response' element MUST have an 'href' element to identify the | ||||
resource. | ||||
Name: depth | A Multi-Status response uses one out of two distinct formats for | |||
representing the status: | ||||
Namespace: DAV: | 1. A 'status' element as child of the 'response' element indicates | |||
the status of the message execution for the identified resource | ||||
as a whole (for instance, see Section 9.6.2). Some method | ||||
definitions provide information about specific status codes | ||||
clients should be prepared to see in a response. However, | ||||
clients MUST be able to handle other status codes, using the | ||||
generic rules defined in Section 10 of [RFC2616]. | ||||
Purpose: The value of the Depth header. | 2. For PROPFIND and PROPPATCH, the format has been extended using | |||
the 'propstat' element instead of 'status', providing information | ||||
about individual properties of a resource. This format is | ||||
specific to PROPFIND and PROPPATCH, and is described in detail in | ||||
Section 9.1 and Section 9.2. | ||||
Value: "0" | "1" | "infinity" | 13.1. Response Headers | |||
<!ELEMENT depth (#PCDATA) > | HTTP defines the Location header to indicate a preferred URL for the | |||
resource that was addressed in the Request-URI (e.g. in response to | ||||
successful PUT requests or in redirect responses). However, use of | ||||
this header creates ambiguity when there are URLs in the body of the | ||||
response, as with Multi-Status. Thus, use of the Location header | ||||
with the Multi-Status response is intentionally undefined. | ||||
12.1.2. locktoken XML Element | 13.2. Handling Redirected Child Resources | |||
Name: locktoken | Redirect responses (300-303, 305 and 307) defined in HTTP 1.1 | |||
normally take a Location header to indicate the new URI for the | ||||
single resource redirected from the Request-URI. Multi-Status | ||||
responses contain many resource addresses, but the original | ||||
definition in [RFC2518] did not have any place for the server to | ||||
provide the new URI for redirected resources. This specification | ||||
does define a 'location' element for this information (see | ||||
Section 14.9). Servers MUST use this new element with redirect | ||||
responses in Multi-Status. | ||||
Namespace: DAV: | Clients encountering redirected resources in Multi-Status MUST NOT | |||
rely on the 'location' element being present with a new URI. If the | ||||
element is not present, the client MAY reissue the request to the | ||||
individual redirected resource, because the response to that request | ||||
can be redirected with a Location header containing the new URI. | ||||
Purpose: The lock token associated with a lock. | 13.3. Internal Status Codes | |||
Description: The href contains one or more opaque lock token URIs | Section 9.2.1, Section 9.1.2, Section 9.6.1, Section 9.8.3 and | |||
which all refer to the same lock (i.e., the OpaqueLockToken-URI | Section 9.9.2 define various status codes used in Multi-Status | |||
production in Section 6.4). | responses. This specification does not define the meaning of other | |||
status codes that could appear in these responses. | ||||
<!ELEMENT locktoken (href+) > | 14. XML Element Definitions | |||
12.1.3. timeout XML Element | In this section, the final line of each section gives the element | |||
type declaration using the format defined in [REC-XML]. The "Value" | ||||
field, where present, specifies further restrictions on the allowable | ||||
contents of the XML element using BNF (i.e., to further restrict the | ||||
values of a PCDATA element). Note that all of the elements defined | ||||
here may be extended according to the rules defined in Section 17. | ||||
All elements defined here are in the "DAV:" namespace. | ||||
Name: timeout | 14.1. activelock XML Element | |||
Namespace: DAV: | Name: activelock | |||
Purpose: The timeout associated with a lock | Purpose: Describes a lock on a resource. | |||
Value: TimeType ;Defined in Section 9.8 | <!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?, | |||
locktoken?, lockroot)> | ||||
<!ELEMENT timeout (#PCDATA) > | 14.2. allprop XML Element | |||
12.2. collection XML Element | Name: allprop | |||
Name: collection | Purpose: Specifies that all names and values of dead properties and | |||
the live properties defined by this document existing on the | ||||
resource are to be returned. | ||||
Namespace: DAV: | <!ELEMENT allprop EMPTY > | |||
Purpose: Identifies the associated resource as a collection. The | 14.3. collection XML Element | |||
resourcetype property of a collection resource MUST have this | ||||
value. | ||||
<!ELEMENT collection EMPTY > | Name: collection | |||
12.3. href XML Element | Purpose: Identifies the associated resource as a collection. The | |||
DAV:resourcetype property of a collection resource MUST contain | ||||
this element. It is normally empty but extensions may add sub- | ||||
elements. | ||||
Name: href | <!ELEMENT collection EMPTY > | |||
Namespace: DAV: | ||||
Purpose: Identifies the content of the element as a URI. | 14.4. depth XML Element | |||
Value: URI ; See section 3.2.1 of [RFC2068] | Name: depth | |||
Purpose: Used for representing depth values in XML content (e.g. in | ||||
lock information). | ||||
<!ELEMENT href (#PCDATA)> | Value: "0" | "1" | "infinity" | |||
12.4. link XML Element | <!ELEMENT depth (#PCDATA) > | |||
Name: link | 14.5. error XML Element | |||
Namespace: DAV: | Name: error | |||
Purpose: Identifies the property as a link and contains the source | Purpose: Error responses, particularly 403 Forbidden and 409 | |||
and destination of that link. | Conflict, sometimes need more information to indicate what went | |||
wrong. In these cases, servers MAY return an XML response body | ||||
with a document element of 'error', containing child elements | ||||
identifying particular condition codes. | ||||
Description: The link XML element is used to provide the sources and | Description: Contains at least one XML element, and MUST NOT | |||
destinations of a link. The name of the property containing the | contain text or mixed content. Any element that is a child of the | |||
link XML element provides the type of the link. Link is a multi- | 'error' element is considered to be a precondition or | |||
valued element, so multiple links may be used together to indicate | postcondition code. Unrecognized elements MUST be ignored. | |||
multiple links with the same type. The values in the href XML | ||||
elements inside the src and dst XML elements of the link XML | ||||
element MUST NOT be rejected if they point to resources which do | ||||
not exist. | ||||
<!ELEMENT link (src+, dst+) > | <!ELEMENT error ANY > | |||
12.4.1. dst XML Element | 14.6. exclusive XML Element | |||
Name: dst | Name: exclusive | |||
Namespace: DAV: | Purpose: Specifies an exclusive lock. | |||
Purpose: Indicates the destination of a link | <!ELEMENT exclusive EMPTY > | |||
Value: URI | 14.7. href XML Element | |||
<!ELEMENT dst (#PCDATA) > | Name: href | |||
12.4.2. src XML Element | Purpose: MUST contain a URI or a relative reference. | |||
Name: src | ||||
Namespace: DAV: | Description: There may be limits on the value of 'href' depending | |||
on the context of its use. Refer to the specification text where | ||||
'href' is used to see what limitations apply in each case. | ||||
Purpose: Indicates the source of a link. | Value: Simple-ref | |||
Value: URI | <!ELEMENT href (#PCDATA)> | |||
<!ELEMENT src (#PCDATA) > | 14.8. include XML Element | |||
12.5. lockentry XML Element | Name: include | |||
Name: lockentry | Purpose: Any child element represents the name of a property to be | |||
included in the PROPFIND response. All elements inside an | ||||
'include' XML element MUST define properties related to the | ||||
resource, although possible property names are in no way limited | ||||
to those property names defined in this document or other | ||||
standards. This element MUST NOT contain text or mixed content. | ||||
Namespace: DAV: | <!ELEMENT include ANY > | |||
Purpose: Defines the types of locks that can be used with the | 14.9. location XML Element | |||
resource. | ||||
<!ELEMENT lockentry (lockscope, locktype) > | Name: location | |||
12.6. lockinfo XML Element | Purpose: HTTP defines the "Location" header (see [RFC2616], Section | |||
14.30) for use with some status codes (such as 201 and the 300 | ||||
series codes). When these codes are used inside a 'multistatus' | ||||
element, the 'location' element can be used to provide the | ||||
accompanying Location header value. | ||||
Name: lockinfo | Description: Contains a single href element with the same value | |||
that would be used in a Location header. | ||||
Namespace: DAV: | <!ELEMENT location (href)> | |||
Purpose: The lockinfo XML element is used with a LOCK method to | 14.10. lockentry XML Element | |||
Name: lockentry | ||||
Purpose: Defines the types of locks that can be used with the | ||||
resource. | ||||
<!ELEMENT lockentry (lockscope, locktype) > | ||||
14.11. lockinfo XML Element | ||||
Name: lockinfo | ||||
Purpose: The 'lockinfo' XML element is used with a LOCK method to | ||||
specify the type of lock the client wishes to have created. | specify the type of lock the client wishes to have created. | |||
<!ELEMENT lockinfo (lockscope, locktype, owner?) > | <!ELEMENT lockinfo (lockscope, locktype, owner?) > | |||
12.7. lockscope XML Element | 14.12. lockroot XML Element | |||
Name: lockscope | Name: lockroot | |||
Namespace: DAV: | Purpose: Contains the root URL of the lock, which is the URL | |||
through which the resource was addressed in the LOCK request. | ||||
Purpose: Specifies whether a lock is an exclusive lock, or a shared | Description: The href element contains the root of the lock. The | |||
server SHOULD include this in all DAV:lockdiscovery property | ||||
values and the response to LOCK requests. | ||||
<!ELEMENT lockroot (href) > | ||||
14.13. lockscope XML Element | ||||
Name: lockscope | ||||
Purpose: Specifies whether a lock is an exclusive lock, or a shared | ||||
lock. | lock. | |||
<!ELEMENT lockscope (exclusive | shared) > | <!ELEMENT lockscope (exclusive | shared) > | |||
12.7.1. exclusive XML Element | 14.14. locktoken XML Element | |||
Name: exclusive | Name: locktoken | |||
Namespace: DAV: | Purpose: The lock token associated with a lock. | |||
Purpose: Specifies an exclusive lock | Description: The href contains a single lock token URI which refers | |||
to the lock. | ||||
<!ELEMENT exclusive EMPTY > | <!ELEMENT locktoken (href) > | |||
12.7.2. shared XML Element | 14.15. locktype XML Element | |||
Name: shared | Name: locktype | |||
Namespace: DAV: | Purpose: Specifies the access type of a lock. At present, this | |||
specification only defines one lock type, the write lock. | ||||
Purpose: Specifies a shared lock | <!ELEMENT locktype (write) > | |||
<!ELEMENT shared EMPTY > | 14.16. multistatus XML Element | |||
12.8. locktype XML Element | Name: multistatus | |||
Name: locktype | Purpose: Contains multiple response messages. | |||
Namespace: DAV: | Description: The 'responsedescription' element at the top level is | |||
used to provide a general message describing the overarching | ||||
nature of the response. If this value is available an application | ||||
may use it instead of presenting the individual response | ||||
descriptions contained within the responses. | ||||
Purpose: Specifies the access type of a lock. At present, this | <!ELEMENT multistatus (response*, responsedescription?) > | |||
specification only defines one lock type, the write lock. | ||||
<!ELEMENT locktype (write) > | 14.17. owner XML Element | |||
12.8.1. write XML Element | Name: owner | |||
Name: write | Purpose: Provides information about the creator of a lock. | |||
Namespace: DAV: | Description: Allows a client to provide information sufficient for | |||
either directly contacting a principal (such as a telephone number | ||||
or Email URI), or for discovering the principal (such as the URL | ||||
of a homepage) who created a lock. The value provided MUST be | ||||
treated as a dead property in terms of XML Information Item | ||||
preservation. The server MUST NOT alter the value unless the | ||||
owner value provided by the client is empty. For a certain amount | ||||
of interoperability between different client implementations, if | ||||
clients have URI-formatted contact information for the lock | ||||
creator suitable for user display, then clients SHOULD put those | ||||
URIs in 'href' child elements of the 'owner' element. | ||||
Purpose: Specifies a write lock. | Extensibility: MAY be extended with child elements, mixed content, | |||
text content or attributes. | ||||
<!ELEMENT write EMPTY > | <!ELEMENT owner ANY > | |||
12.9. multistatus XML Element | 14.18. prop XML Element | |||
Name: multistatus | Name: prop | |||
Namespace: DAV: | Purpose: Contains properties related to a resource. | |||
Purpose: Contains multiple response messages. | Description: A generic container for properties defined on | |||
resources. All elements inside a 'prop' XML element MUST define | ||||
properties related to the resource, although possible property | ||||
names are in no way limited to those property names defined in | ||||
this document or other standards. This element MUST NOT contain | ||||
text or mixed content. | ||||
Description: The responsedescription at the top level is used to | <!ELEMENT prop ANY > | |||
provide a general message describing the overarching nature of the | ||||
response. If this value is available an application may use it | ||||
instead of presenting the individual response descriptions | ||||
contained within the responses. | ||||
<!ELEMENT multistatus (response+, responsedescription?) > | 14.19. propertyupdate XML Element | |||
12.9.1. response XML Element | Name: propertyupdate | |||
Name: response | Purpose: Contains a request to alter the properties on a resource. | |||
Namespace: DAV: | Description: This XML element is a container for the information | |||
required to modify the properties on the resource. | ||||
Purpose: Holds a single response describing the effect of a method | <!ELEMENT propertyupdate (remove | set)+ > | |||
on resource and/or its properties. | ||||
Description: A particular href MUST NOT appear more than once as the | 14.20. propfind XML Element | |||
child of a response XML element under a multistatus XML element. | ||||
This requirement is necessary in order to keep processing costs | ||||
for a response to linear time. Essentially, this prevents having | ||||
to search in order to group together all the responses by href. | ||||
There are, however, no requirements regarding ordering based on | ||||
href values. | ||||
<!ELEMENT response (href, ((href*, status)|(propstat+)), | Name: propfind | |||
responsedescription?) > | ||||
12.9.1.1. propstat XML Element | Purpose: Specifies the properties to be returned from a PROPFIND | |||
method. Four special elements are specified for use with | ||||
'propfind': 'prop', 'allprop', 'include' and 'propname'. If |