--- 1/draft-ietf-webdav-ordering-protocol-03.txt 2006-02-05 02:10:55.000000000 +0100 +++ 2/draft-ietf-webdav-ordering-protocol-04.txt 2006-02-05 02:10:55.000000000 +0100 @@ -1,52 +1,48 @@ Network Working Group J. Slein Internet Draft Xerox -Expires: March 2003 J. Whitehead +Expires: July 2003 J. Whitehead U.C. Santa Cruz - J. Davis - Intelligent Markets - C. Fay - FileNet J. Crawford IBM J. F. Reschke greenbytes - September 2002 + January 2003 WebDAV Ordered Collections Protocol - draft-ietf-webdav-ordering-protocol-03 + draft-ietf-webdav-ordering-protocol-04 Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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. 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 in March 2003. + This Internet-Draft will expire in July 2003. Copyright Notice - Copyright (C) The Internet Society (2002). All Rights Reserved. + Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract This specification extends the WebDAV Distributed Authoring Protocol to support server-side ordering of collection members. Of particular interest are orderings that are not based on property values, and so cannot be achieved using a search protocol's ordering option and cannot be maintained automatically by the server. Protocol elements are defined to let clients specify the position in the ordering of each collection member, as well as the semantics governing the @@ -55,72 +51,62 @@ Distribution of this document is unlimited. Please send comments to the Distributed Authoring and Versioning (WebDAV) working group at w3c-dist-auth@w3.org, which may be joined by sending a message with subject "subscribe" to w3c-dist-auth-request@w3.org. Discussions of the WEBDAV working group are archived at URL: http://lists.w3.org/Archives/Public/w3c-dist-auth/. Table of Contents - Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 - Table of Contents . . . . . . . . . . . . . . . . . . . . . . . . 3 - 1 Notational Conventions . . . . . . . . . . . . . . . . . . . . 5 - 2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 3 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 4 Overview of Ordered Collections . . . . . . . . . . . . . . . . 8 - 4.1 Additional Collection properties . . . . . . . . . . . . . 8 - 4.1.1 DAV:orderingtype (protected) . . . . . . . . . . . . . 9 - 5 Creating an Ordered Collection . . . . . . . . . . . . . . . . 10 - 5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . 10 - 5.2 Example: Creating an Ordered Collection . . . . . . . . . . 11 - 6 Setting the Position of a Collection Member . . . . . . . . . . 12 - 6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . 12 - 6.2 Status Codes . . . . . . . . . . . . . . . . . . . . . . . 12 - 6.3 Examples: Setting the Position of a Collection Member . . . 12 - 7 Changing a Collection Ordering . . . . . . . . . . . . . . . . 14 - 7.1 ORDERPATCH Method . . . . . . . . . . . . . . . . . . . . . 14 - 7.1.1 Status Codes . . . . . . . . . . . . . . . . . . . . . 14 - 7.1.2 Example: Changing a Collection Ordering . . . . . . . . 15 - 7.1.3 Example: Failure of an ORDERPATCH Request . . . . . . . 17 - 8 Listing the Members of an Ordered Collection . . . . . . . . . 19 - 8.1 Example: PROPFIND on an Ordered Collection . . . . . . . . 19 - 9 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 - 9.1 Position Request Header . . . . . . . . . . . . . . . . . . 23 - 10 XML Elements . . . . . . . . . . . . . . . . . . . . . . . . . 24 - 10.1 order XML Element . . . . . . . . . . . . . . . . . . . . 24 - 10.2 ordermember XML Element . . . . . . . . . . . . . . . . . 24 - 10.3 position XML Element . . . . . . . . . . . . . . . . . . . 25 - 10.4 first XML Element . . . . . . . . . . . . . . . . . . . . 25 - 10.5 last XML Element . . . . . . . . . . . . . . . . . . . . . 25 - 10.6 before XML Element . . . . . . . . . . . . . . . . . . . . 26 - 10.7 after XML Element . . . . . . . . . . . . . . . . . . . . 26 - 10.8 segment XML Element . . . . . . . . . . . . . . . . . . . 27 - 11 Capability Discovery . . . . . . . . . . . . . . . . . . . . . 28 - 11.1 Example: Using OPTIONS for the Discovery of Support for - Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 - 11.2 Example: Using Live Properties for the Discovery of - Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 - 12 Security Considerations . . . . . . . . . . . . . . . . . . . 31 - 12.1 Denial of Service and DAV:orderingtype . . . . . . . . . . 31 - 13 Internationalization Considerations . . . . . . . . . . . . . 32 - 14 IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 - 15 Copyright . . . . . . . . . . . . . . . . . . . . . . . . . . 34 - 16 Intellectual Property . . . . . . . . . . . . . . . . . . . . 35 - 17 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 36 - Normative References . . . . . . . . . . . . . . . . . . . . . . 37 - Author's Addresses . . . . . . . . . . . . . . . . . . . . . . . 37 - A Extensions to the WebDAV Document Type Definition . . . . . . . 39 - B Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 40 + Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 + Table of Contents . . . . . . . . . . . . . . . . . . . . . . 3 + 1 Notational Conventions . . . . . . . . . . . . . . . . . . . 4 + 2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 + 3 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 6 + 4 Overview of Ordered Collections . . . . . . . . . . . . . . 7 + 4.1 Additional Collection properties . . . . . . . . . . . . 7 + 4.1.1 DAV:orderingtype (protected) . . . . . . . . . . . . 8 + 5 Creating an Ordered Collection . . . . . . . . . . . . . . . 9 + 5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 9 + 5.2 Example: Creating an Ordered Collection . . . . . . . . 10 + 6 Setting the Position of a Collection Member . . . . . . . . 11 + 6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 11 + 6.2 Examples: Setting the Position of a Collection Member . 12 + 7 Changing a Collection Ordering: ORDERPATCH method . . . . . 14 + 7.1 Example: Changing a Collection Ordering . . . . . . . . 16 + 7.2 Example: Failure of an ORDERPATCH Request . . . . . . . 18 + 8 Listing the Members of an Ordered Collection . . . . . . . . 20 + 8.1 Example: PROPFIND on an Ordered Collection . . . . . . . 20 + 9 Relationship to versioned collections . . . . . . . . . . . 24 + 9.1 Additional semantics for collection version properties . 24 + 10 Capability Discovery . . . . . . . . . . . . . . . . . . . 25 + 10.1 Example: Using OPTIONS for the Discovery of Support for + Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 + 10.2 Example: Using Live Properties for the Discovery of + Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 + 11 Security Considerations . . . . . . . . . . . . . . . . . . 28 + 11.1 Denial of Service and DAV:orderingtype . . . . . . . . 28 + 12 Internationalization Considerations . . . . . . . . . . . . 29 + 13 IANA Considerations . . . . . . . . . . . . . . . . . . . . 30 + 14 Copyright . . . . . . . . . . . . . . . . . . . . . . . . . 31 + 15 Intellectual Property . . . . . . . . . . . . . . . . . . . 32 + 16 Acknowledgements . . . . . . . . . . . . . . . . . . . . . 33 + Normative References . . . . . . . . . . . . . . . . . . . . . 34 + Author's Addresses . . . . . . . . . . . . . . . . . . . . . . 34 + A Extensions to the WebDAV Document Type Definition . . . . . 36 + B Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 37 B.1 Since draft-ietf-webdav-ordering-protocol dated December - 1999 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 - B.2 Since draft-ietf-webdav-ordering-protocol-02 . . . . . . . 40 + 1999 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 + B.2 Since draft-ietf-webdav-ordering-protocol-02 . . . . . . 37 + B.3 Since draft-ietf-webdav-ordering-protocol-03 . . . . . . 37 + Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 1 Notational Conventions Since this document describes a set of extensions to the WebDAV Distributed Authoring Protocol [RFC2518], itself an extension to the HTTP/1.1 protocol, the augmented BNF used here to describe protocol elements is exactly the same as described in Section 2.1 of HTTP [RFC2616]. Since this augmented BNF uses the basic production rules provided in Section 2.2 of HTTP, these rules apply to this document as well. @@ -150,38 +136,38 @@ but orderings not based on properties cannot. These orderings generally need to be maintained by a human user. The ordering protocol defined here focuses on support for such human- maintained orderings. Its protocol elements allow clients to specify the position of each collection member in the collection's ordering, as well as the semantics governing the ordering. The protocol is designed to allow support to be added in the future for orderings that are maintained automatically by the server. - The remainder of this document is structured as follows: Section 3 + The remainder of this document is structured as follows: section 3 defines terminology that will be used throughout the specification. Section 4 provides an overview of ordered collections. Section 5 - describes how to create an ordered collection, and Section 6 + describes how to create an ordered collection, and section 6 discusses how to set a member's position in the ordering of a collection. Section 7 explains how to change a collection ordering. Section 8 discusses listing the members of an ordered collection. - Section 9 through Section 10 define the headers, properties, and XML - elements needed to support ordered collections. Section 11 describes - capability discovery. Section 12 through Section 14 discuss security, - internationalization, and IANA considerations. The remaining sections - provide supporting information. + section 9 discusses the impact on version-controlled collections (as + defined in [RFC3253]. Section 10 describes capability discovery. + Section 11 through section 13 discuss security, internationalization, + and IANA considerations. The remaining sections provide supporting + information. 3 Terminology - The terminology used here follows that in the [RFC2518]. Definitions - of the terms resource, Uniform Resource Identifier (URI), and Uniform - Resource Locator (URL) are provided in [RFC2396]. + The terminology used here follows that in [RFC2518]and [RFC3253]. + Definitions of the terms resource, Uniform Resource Identifier (URI), + and Uniform Resource Locator (URL) are provided in [RFC2396]. Ordered Collection A collection for which the results from a PROPFIND request are guaranteed to be in the order specified for that collection Unordered Collection A collection for which the client cannot depend on the repeatability of the ordering of results from a PROPFIND request @@ -212,45 +198,45 @@ Server-side orderings may be client-maintained or server-maintained. For client-maintained orderings, a client must specify the ordering position of each of the collection's members, either when the member is added to the collection (using the Position header) or later (using the ORDERPATCH method). For server-maintained orderings, the server automatically positions each of the collection's members according to the ordering semantics. This specification supports only client-maintained orderings, but is designed to allow future extension to server-maintained orderings. - A collection that supports ordering is not required to be ordered. It - is up to the client to decide whether a given collection is ordered - and, if so, to specify the semantics to be used for ordering its - members. + A collection that supports ordering is not required to be ordered. If a collection is ordered, each of its internal member URIs MUST be in the ordering exactly once, and the ordering MUST NOT include any URI that is not an internal member of the collection. The server is responsible for enforcing these constraints on orderings. The server MUST remove an internal member URI from the ordering when it is - removed from the collection. The server MUST an internal member URI - to the ordering when it is added to the collection. + removed from the collection. The server MUST add an internal member + URI to the ordering when it is added to the collection. Only one ordering can be attached to any collection. Multiple orderings of the same resources can be achieved by creating multiple collections referencing those resources, and attaching a different ordering to each collection. An ordering is considered to be part of the state of a collection resource. Consequently, the ordering is the same no matter which URI is used to access the collection and is protected by locks or access control constraints on the collection. 4.1 Additional Collection properties + A DAV:allprop PROPFIND request SHOULD NOT return any of the + properties defined in this document. + 4.1.1 DAV:orderingtype (protected) Indicates whether the collection is ordered and, if so, uniquely identifies the semantics of the ordering being used. May also point to an explanation of the semantics in human and / or machine-readable form. At a minimum, this allows human users who add members to the collection to understand where to position them in the ordering. This property cannot be set using PROPPATCH. Its value can only be set by including the Ordered header with a MKCOL request or by submitting an ORDERPATCH request. @@ -306,184 +292,262 @@ to be ordered, but the semantics of the ordering is not being advertised. Any other Coded-url value indicates that the collection is ordered, and identifies the semantics of the ordering. Additional Preconditions: (DAV:ordered-collections-supported): the server must support ordered collections where the new collection is to be created. + Additional Postconditions: + + (DAV:orderdingtype-set): the collection was created with the + specified ordering semantics. + 5.2 Example: Creating an Ordered Collection >> Request: MKCOL /theNorth/ HTTP/1.1 - Host: www.server.org - Ordered: + Host: example.org + Ordered: >> Response: HTTP/1.1 201 Created In this example a new, ordered collection was created. Its DAV:orderingtype property has as its value the URI from the Ordered - header, http://www.server.org/orderings/compass.html. In this case, - the URI identifies the semantics governing a client-maintained - ordering. As new members are added to the collection, clients or end - users can use the semantics to determine where to position the new - members in the ordering. + header, http://example.org/orderings/compass.html. In this case, the + URI identifies the semantics governing a client-maintained ordering. + As new members are added to the collection, clients or end users can + use the semantics to determine where to position the new members in + the ordering. 6 Setting the Position of a Collection Member 6.1 Overview When a new member is added to a collection with a client-maintained ordering (for example, with PUT, COPY, or MKCOL), its position in the - ordering can be set with the new Position header (defined in Section - 9.1). The Position header allows the client to specify that an - internal member URI should be first in the collection's ordering, - last in the collection's ordering, immediately before some other - internal member URI in the collection's ordering, or immediately - after some other internal member URI in the collection's ordering. + ordering can be set with the new Position header. The Position header + allows the client to specify that an internal member URI should be + first in the collection's ordering, last in the collection's + ordering, immediately before some other internal member URI in the + collection's ordering, or immediately after some other internal + member URI in the collection's ordering. If the Position request header is not used when adding a member to an ordered collection, then: o If the request is replacing an existing resource, the server MUST preserve the present ordering. o If the request is adding a new internal member URI to the collection, the server MUST append the new member to the end of the ordering. -6.2 Status Codes + Additional Marshalling: - 409 (Conflict): Several conditions may cause this response. The - request may specify a position that is before or after a URI that is - not an internal member URI of the collection, or before or after - itself. The request may attempt to specify the new member's position - in an unordered collection. + Position = "Position" ":" ("first" | "last" | + (("before" | "after") segment)) -6.3 Examples: Setting the Position of a Collection Member + segment is defined in Section 3.3 of [RFC2396]. + + The segment is interpreted relative to the collection to which the + new member is being added. + + The server MUST insert the new member into the ordering at the + location specified in the Position header, if one is present (and + if the collection is ordered). + + The "first" keyword indicates the new member is put in the + beginning position in the collection's ordering, while "last" + indicates the new member is put in the final position in the + collection's ordering. The "before" keyword indicates the new + member is added to the collection's ordering immediately prior to + the position of the member identified in the segment. Likewise, + the "after" keyword indicates the new member is added to the + collection's ordering immediately following the position of the + member identified in the segment. + + If the request is replacing an existing resource, and the Position + header is present, the server MUST remove the internal member URI + from its previous position, and then insert it at the requested + position. + + Additional Preconditions: + + (DAV:collection-must-be-ordered): the target collection must be + ordered. + + (DAV:segment-must-identify-member): the referenced segment must + identify a resource that exists and is different from the affected + resource. + + Additional Postconditions: + + (DAV:position-set): the newly created collection member was + created at the specified position. + +6.2 Examples: Setting the Position of a Collection Member >> Request: - COPY /~whitehead/dav/spec08.html HTTP/1.1 - Host: www.ics.uci.edu - Destination: http://www.xerox.com/~slein/dav/spec08.html + COPY /~user/dav/spec08.html HTTP/1.1 + Host: example.org + Destination: http://example.org/~slein/dav/spec08.html Position: after requirements.html + >> Response: HTTP/1.1 201 Created - This request resulted in the creation of a new resource at - www.xerox.com/~slein/dav/spec08.html. The Position header in this + example.org/~slein/dav/spec08.html. The Position header in this example caused the server to set its position in the ordering of the /~slein/dav/ collection immediately after requirements.html. >> Request: - MOVE /i-d/draft-webdav-protocol-08.txt HTTP/1.1 - Host: www.ics.uci.edu - Destination: http://www.ics.uci.edu/~whitehead/dav/draft-webdav- - protocol-08.txt + MOVE /i-d/draft-webdav-prot-08.txt HTTP/1.1 + Host: example.org + Destination: http://example.org/~user/dav/draft-webdav-prot-08.txt Position: first >> Response: HTTP/1.1 409 Conflict + Content-Type: text/xml; charset="utf-8" + Content-Length: xxxx + + + + + In this case, the server returned a 409 (Conflict) status code - because the /~whitehead/dav/ collection is an unordered collection. + because the /~user/dav/ collection is an unordered collection. Consequently, the server was unable to satisfy the Position header. -7 Changing a Collection Ordering - -7.1 ORDERPATCH Method +7 Changing a Collection Ordering: ORDERPATCH method The ORDERPATCH method is used to change the ordering semantics of a collection or to change the order of the collection's members in the ordering or both. - The ORDERPATCH method changes the ordering semantics of the - collection identified by the Request-URI, based on the value of - DAV:orderingtype submitted in the request entity body. - - The ORDERPATCH method alters the ordering of internal member URIs in - the collection identified by the Request-URI, based on instructions - in the ordermember XML elements in the request entity body. The - ordermember XML elements identify the internal member URIs whose - positions are to be changed, and describe their new positions in the - ordering. Each new position can be specified as first in the - ordering, last in the ordering, immediately before some other - internal member URI, or immediately after some other internal member - URI. - The server MUST apply the changes in the order they appear in the order XML element. The server MUST either apply all the changes or apply none of them. If any error occurs during processing, all executed changes MUST be undone and a proper error result returned. If an ORDERPATCH request changes the ordering semantics, but does not completely specify the order of the collection members, the server MUST assign a position in the ordering to each collection member for which a position was not specified. These server-assigned positions MUST all follow the last one specified by the client. The result is that all members for which the client specified a position are at the beginning of the ordering, followed by any members for which the server assigned positions. If an ORDERPATCH request does not change the ordering semantics, any member positions not specified in the request MUST remain unchanged. -7.1.1 Status Codes + A request to reposition a collection member at the same place in the + ordering is not an error. + + Additional Marshalling: + + The request body MUST be DAV:order element. + + + + + + + + + + + + PCDATA value: segment, as defined in section 3.3 of [RFC2396]. + + DAV:href value: segment part of collection member. + + The DAV:orderingtype property is modified according to the + DAV:orderingtype element. + + The ordering of internal member URIs in the collection identified + by the Request-URI is changed based on instructions in the + ordermember XML elements. The ordermember XML elements identify + the internal member URIs whose positions are to be changed, and + describe their new positions in the ordering. Each new position + can be specified as first in the ordering, last in the ordering, + immediately before some other internal member URI, or immediately + after some other internal member URI. + + If a response body for a successful request is included, it MUST + be a DAV:orderpatch-response XML element. Note that this document + does not define any elements for the ORDERPATCH response body, but + the DAV:orderpatch-response element is defined to ensure + interoperability between future extensions that do define elements + for the ORDERPATCH response body. + + Since multiple changes can be requested in a single ORDERPATCH request, if any problems are encountered, the server MUST return a - 207 (Multi-Status) response, as defined in [RFC2518]. + 207 (Multi-Status) response (defined in [RFC2518]), containing + DAV:response elements for either the request-URI (when the + DAV:orderingtype could not be modified) or URIs of collection + members to be repositioned (when an invidual positioning request + expressed as DAV:ordermember could not be fulfilled). - The following are examples of response codes one would expect to be - used in a 207 (Multi-Status) response for this method: + Preconditions: - 200 (OK): The change in ordering was successfully made. + (DAV:collection-must-be-ordered): see section 6.1. - 409 (Conflict): Several conditions may cause this response. The - request may specify a position that is before or after a URI that is - not an internal member URI of the collection, or before or after - itself. The request may attempt to set the positions of members of an - unordered collection. + (DAV:segment-must-identify-member): see section 6.1. - A request to reposition a collection member at the same place in the - ordering is not an error. + Postconditions: -7.1.2 Example: Changing a Collection Ordering + (DAV:orderdingtype-set): if the request body contained a + DAV:orderingtype element, the DAV:orderingtype property (see + section 4.1.1) of the collection identified by the request-URI was + set accordingly. + + (DAV:orderding-modified): if the request body contained + DAV:ordermember elements, the ordering of internal member URIs in + the collection identified by the request-URI has been changed + based on instructions in the DAV:ordermember elements. + +7.1 Example: Changing a Collection Ordering Consider a collection /coll-1/ whose DAV:orderingtype is DAV:whim, with bindings ordered as follows: three.html four.html one.html two.html >> Request: ORDERPATCH /coll-1/ HTTP/1.1 - Host: www.myserver.com + Host: example.org Content-Type: text/xml; charset="utf-8" Content-Length: xxx - http://www.myserver.com/inorder.ord + http://example.org/inorder.ord two.html one.html @@ -503,40 +567,40 @@ >> Response: HTTP/1.1 200 OK In this example, after the request has been processed, the collection's ordering semantics are identified by the URI - http://www.myserver.com/inorder.ord. The value of the collection's + http://example.org/inorder.ord. The value of the collection's DAV:orderingtype property has been set to this URI. The request also contains instructions for changing the positions of the collection's internal member URIs in the ordering to comply with the new ordering semantics. If href elements are relative URIs, as in this example, they are interpreted relative to the collection whose ordering is being modified. The DAV:ordermember elements are required to be processed in the order they appear in the request. Consequently, two.html is moved to the beginning of the ordering, and then one.html is moved to the beginning of the ordering. Then three.html is moved to the end of the ordering, and finally four.html is moved to the end of the ordering. After the request has been processed, the collection's ordering is as follows: one.html two.html three.html four.html -7.1.3 Example: Failure of an ORDERPATCH Request +7.2 Example: Failure of an ORDERPATCH Request Consider a collection /coll-1/ with members ordered as follows: nunavut.map nunavut.img baffin.map baffin.desc baffin.img iqaluit.map nunavut.desc @@ -562,47 +626,46 @@ iqaluit.map pangnirtung.img - >> Response: HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxx - http://www.nunanet.com/coll-1/nunavut.desc - HTTP/1.1 424 Failed Dependency - - http://www.nunanet.com/coll-1/iqaluit.map - HTTP/1.1 409 Conflict - pangnirtung.img is not a collection - member. + HTTP/1.1 403 Forbidden + + + pangnirtung.img is not a collection member. + In this example, the client attempted to position iqaluit.map after a URI that is not an internal member of the collection /coll-1/. The - server responded to this client error with a 409 (Conflict) status - code. Because ORDERPATCH is an atomic method, the request to + server responded to this client error with a 403 (Forbidden) status + code, indicating the failed precondition DAV:segment-must-identify- + member. Because ORDERPATCH is an atomic method, the request to reposition nunavut.desc (which would otherwise have succeeded) failed - with a 424 (Failed Dependency) status code. + as well, but doesn't need to be expressed in the multistatus response + body. 8 Listing the Members of an Ordered Collection A PROPFIND request is used to retrieve a listing of the members of an ordered collection, just as it is used to retrieve a listing of the members of an unordered collection. However, when responding to a PROPFIND on an ordered collection, the server MUST order the response elements according to the ordering defined on the collection. If a collection is unordered, the client @@ -626,281 +689,167 @@ it would be acceptable for the server to return response elements in the order A B E C F G H D. In this response, B, C, and D appear in the correct order, separated by members of other collections. Clients can use a series of Depth: 1 PROPFIND requests to avoid the complexity of processing Depth: infinity responses based on depth- first traversals. 8.1 Example: PROPFIND on an Ordered Collection - Suppose a PROPFIND request is submitted to /MyCollection/, which has - its members ordered as follows. + Suppose a PROPFIND request is submitted to /MyColl/, which has its + members ordered as follows. - /MyCollection/ + /MyColl/ lakehazen.html siorapaluk.html iqaluit.html newyork.html >> Request: - PROPFIND /MyCollection/ HTTP/1.1 - Host: www.svr.com + PROPFIND /MyColl/ HTTP/1.1 + Host: example.org Depth: 1 Content-Type: text/xml; charset="utf-8" Content-Length: xxxx - + >> Response: HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx + xmlns:J="http://example.org/jsprops/"> - http://www.svr.com/MyCollection/ + http://example.org/MyColl/ HTTP/1.1 200 OK HTTP/1.1 404 Not Found - http://www.svr.com/MyCollection/lakehazen.html + http://example.org/MyColl/lakehazen.html 82N HTTP/1.1 200 OK HTTP/1.1 404 Not Found http://www.svr.com/MyCollection/siorapaluk.html + >http://example.org/MyColl/siorapaluk.html 78N HTTP/1.1 200 OK HTTP/1.1 404 Not Found - http://www.svr.com/MyCollection/iqaluit.html + http://example.org/MyColl/iqaluit.html 62N HTTP/1.1 200 OK HTTP/1.1 404 Not Found - http://www.svr.com/MyCollection/newyork.html + http://example.org/MyColl/newyork.html 45N HTTP/1.1 200 OK HTTP/1.1 404 Not Found In this example, the server responded with a list of the collection members in the order defined for the collection. -9 Headers - -9.1 Position Request Header - - Position = "Position" ":" ("first" | "last" | - (("before" | "after") segment)) - - segment is defined in Section 3.3 of [RFC2396]. - - The Position header may be used with any method that adds a member to - an ordered collection, to tell the server where in the collection - ordering to position the new member being added to the collection. - Examples of methods that add members to collections are BIND, PUT, - COPY, MOVE, etc. - - The segment is interpreted relative to the collection to which the - new member is being added. - - The server MUST insert the new member into the ordering at the - location specified in the Position header, if one is present (and if - the collection is ordered). - - The "first" keyword indicates the new member is put in the beginning - position in the collection's ordering, while "last" indicates the new - member is put in the final position in the collection's ordering. The - "before" keyword indicates the new member is added to the - collection's ordering immediately prior to the position of the member - identified in the segment. Likewise, the "after" keyword indicates - the new member is added to the collection's ordering immediately - following the position of the member identified in the segment. - - If the request is replacing an existing resource, and the Position - header is present, the server MUST remove the internal member URI - from its previous position, and then insert it at the requested - position. - - If an attempt is made to use the Position header on a collection that - is unordered, the server MUST fail the request with a 409 (Conflict) - status code. - -10 XML Elements - -10.1 order XML Element - - Name: order - Namespace: DAV: - Purpose: For use with the new ORDERPATCH method. Describes a change - to be made in a collection's ordering semantics or in the - positions of its members in the ordering or both. - Value: An optional identifier of an ordering semantics for the - collection, followed by a list of changes to be made in - the positions of the members in the collection's ordering. - - - -10.2 ordermember XML Element - - Name: ordermember - Namespace: DAV: - Purpose: Occurs in the order XML element, and describes the new - position of a single internal member URI in the - collection's ordering. - Value: An href containing a member's path segment, and a - description of its new position in the ordering. The href - XML element is defined in [RFC2518], Section 11.3. - - - -10.3 position XML Element - - Name: position - Namespace: DAV: - Purpose: Occurs in the ordermember XML element. Describes the new - position in a collection's ordering of one of the members - it contains. - Value: The new position can be described as first in the - collection's ordering, last in the collection's ordering, - immediately before some other collection member, or - immediately after some other collection member. - - - -10.4 first XML Element - - Name: first - Namespace: DAV: - Purpose: Occurs in the position XML element. Specifies that the - member should be placed first in the collection's - ordering. - - - -10.5 last XML Element - Name: last - Namespace: DAV: - Purpose: Occurs in the position XML element. Specifies that the - member should be placed last in the collection's ordering. - - - -10.6 before XML Element - - Name: before - Namespace: DAV: - Purpose: Occurs in the position XML element. Specifies that the - member should be placed immediately before the member in - the enclosed segment XML element in the collection's - ordering. - Value: URI (relative to the parent collection) of the member it - precedes in the ordering - - - -10.7 after XML Element - - Name: after - Namespace: DAV: - Purpose: Occurs in the position XML element. Specifies that the - member should be placed immediately after the member in - the enclosed segment XML element in the collection's - ordering. +9 Relationship to versioned collections - Value: URI (relative to the parent collection) of the member it - follows in the ordering + The Versioning Extensions to WebDAV [RFC3253] introduce the concept + of versioned collections, recording both the dead properties and the + set of internal version-controlled bindings. This section defines how + this feature interacts with ordered collections. - + This specification considers both the ordering type (DAV:orderingtype + property) and the ordering of collection members to be part of the + state of a collection. Therefore both MUST be recorded upon CHECKIN + or VERSION-CONTROL, and both MUST be restored upon CHECKOUT, + UNCHECKOUT or UPDATE (where for compatibility with RFC3253, only the + ordering of version-controlled members needs to be maintained). -10.8 segment XML Element +9.1 Additional semantics for collection version properties - Name: segment - Namespace: DAV: - Purpose: Identifies a member of a collection, used in the - DAV:before and DAV:after elements, to define one member's - position in a collection ordering relative to another - member of the collection. - Value: segment ; as defined in section 3.3 of [RFC2396]. + Although this specification defines the property DAV:orderingtype to + be protected, it MUST be recorded in a collection version. - + The property DAV:version-controlled-binding-set ([RFC3253], section + 14.2.1) records the set of version-controlled bindings in the + collection. For ordered collections, the DAV:version-controlled- + binding elements MUST appear in the ordering defined for the checked- + in ordered collection. -11 Capability Discovery +10 Capability Discovery Sections 9.1 and 15 of [RFC2518] describe the use of compliance classes with the DAV header in responses to OPTIONS, to indicate which parts of the Web Distributed Authoring protocols the resource supports. This specification defines an OPTIONAL extension to [RFC2518]. It defines a new compliance class, called orderedcoll, for use with the DAV header in responses to OPTIONS requests. If a collection resource does support ordering, its response to an OPTIONS request may indicate that it does, by listing the new ORDERPATCH method as one it supports, and by listing the new orderedcoll @@ -910,48 +859,45 @@ resource can include orderedcoll in the value of the DAV header. By including orderedcoll, the resource indicates that its internal member URIs can be ordered. It implies nothing about whether any collections identified by its internal member URIs can be ordered. Furthermore, RFC 3253 [RFC3253] introduces the live properties DAV:supported-method-set (section 3.1.3) and DAV:supported-live- property-set (section 3.1.4). Servers MUST support these properties as defined in RFC 3253. -11.1 Example: Using OPTIONS for the Discovery of Support for Ordering +10.1 Example: Using OPTIONS for the Discovery of Support for Ordering >> Request: OPTIONS /somecollection/ HTTP/1.1 - HOST: somehost.org + Host: example.org >> Response: HTTP/1.1 200 OK - Date: Tue, 20 Jan 1998 20:52:29 GMT - Connection: close - Accept-Ranges: none - Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, - MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH + Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE + Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, ORDERPATCH DAV: 1, 2, orderedcoll + The DAV header in the response indicates that the resource /somecollection/ is level 1 and level 2 compliant, as defined in [RFC2518]. In addition, /somecollection/ supports ordering. The Allow header indicates that ORDERPATCH requests can be submitted to /somecollection/. -11.2 Example: Using Live Properties for the Discovery of Ordering +10.2 Example: Using Live Properties for the Discovery of Ordering >> Request: PROPFIND /somecollection HTTP/1.1 - Host: somehost.org Depth: 0 Content-Type: text/xml; charset="utf-8" Content-Length: xxx @@ -959,21 +905,21 @@ >> Response: HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxx - http://somehost.org/somecollection + http://example.org/somecollection ... other live properties omitted for brevity ... @@ -994,42 +940,42 @@ HTTP/1.1 200 OK Note that actual responses MUST contain a complete list of supported live properties. -12 Security Considerations +11 Security Considerations This section is provided to make WebDAV applications aware of the security implications of this protocol. All of the security considerations of HTTP/1.1 and the WebDAV Distributed Authoring Protocol specification also apply to this protocol specification. In addition, ordered collections introduce a new security concern. This issue is detailed here. -12.1 Denial of Service and DAV:orderingtype +11.1 Denial of Service and DAV:orderingtype There may be some risk of denial of service at sites that are advertised in the DAV:orderingtype property of collections. However, it is anticipated that widely-deployed applications will use hard- coded values for frequently-used ordering semantics rather than looking up the semantics at the location specified by DAV:orderingtype. This risk will be further reduced if clients - observe the recommendation of Section 5.1 that they not send requests + observe the recommendation of section 5.1 that they not send requests to the URI in DAV:orderingtype. -13 Internationalization Considerations +12 Internationalization Considerations This specification follows the practices of [RFC2518] in encoding all human-readable content using [XML] and in the treatment of names. Consequently, this specification complies with the IETF Character Set Policy [RFC2277]. WebDAV applications MUST support the character set tagging, character set encoding, and the language tagging functionality of the XML specification. This constraint ensures that the human-readable content of this specification complies with [RFC2277]. @@ -1046,44 +992,45 @@ description of the code (e.g., 423 Locked). Internationalized applications will ignore this message, and display an appropriate message in the user's language and character set. This specification introduces no new strings that are displayed to users as part of normal, error-free operation of the protocol. For rationales for these decisions and advice for application implementors, see [RFC2518]. -14 IANA Considerations +13 IANA Considerations This document uses the namespaces defined by [RFC2518] for properties and XML elements. All other IANA considerations mentioned in [RFC2518] also apply to this document. -15 Copyright +14 Copyright To be supplied by the RFC Editor. -16 Intellectual Property +15 Intellectual Property To be supplied by the RFC Editor. -17 Acknowledgements +16 Acknowledgements This draft has benefited from thoughtful discussion by Jim Amsden, Steve Carter, Tyson Chihaya, Geoff Clemm, Ken Coar, Ellis Cohen, - Bruce Cragun, Spencer Dawkins, Mark Day, Rajiv Dulepet, David Durand, - Roy Fielding, Yaron Goland, Fred Hitt, Alex Hopmann, Marcus Jager, - Chris Kaler, Manoj Kasichainula, Rohit Khare, Daniel LaLiberte, Lisa - Lippert, Steve Martin, Larry Masinter, Jeff McAffer, Surendra Koduru - Reddy, Max Rible, Sam Ruby, Bradley Sergeant, Nick Shelness, John - Stracke, John Tigue, John Turner, Kevin Wiggen, and others. + Bruce Cragun, Jim Davis, Spencer Dawkins, Mark Day, Rajiv Dulepet, + David Durand, Chuck Fay, Roy Fielding, Yaron Goland, Fred Hitt, Alex + Hopmann, Marcus Jager, Chris Kaler, Manoj Kasichainula, Rohit Khare, + Daniel LaLiberte, Lisa Lippert, Steve Martin, Larry Masinter, Jeff + McAffer, Surendra Koduru Reddy, Max Rible, Sam Ruby, Bradley + Sergeant, Nick Shelness, John Stracke, John Tigue, John Turner, Kevin + Wiggen, and others. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2277] Alvestrand, H.T., "IETF Policy on Character Sets and Languages", BCP 18, RFC 2277, January 1998. [RFC2396] Berners-Lee, T., Fielding, R.T. and Masinter, L., "Uniform @@ -1114,34 +1061,20 @@ EMail: jslein@crt.xerox.com Jim Whitehead UC Santa Cruz, Dept. of Computer Science 1156 High Street Santa Cruz, CA 95064 US EMail: ejw@cse.ucsc.edu - Jim Davis - Intelligent Markets - 410 Jessie Street 6th floor - San Francisco, CA 94103 - - EMail: jrd3@alum.mit.edu - - Chuck Fay - FileNet Corporation - 3565 Harbor Boulevard - Costa Mesa, CA 92626-1420 - - EMail: cfay@filenet.com - Jason Crawford IBM Research P.O. Box 704 Yorktown Heights, NY 10598 EMail: ccjason@us.ibm.com Julian F. Reschke greenbytes GmbH Salzmannstrasse 152 @@ -1187,42 +1120,108 @@ Updated change log to refer to expired draft version as "December 1999" version. Started rewrite marshalling in RFC3253-style and added precondition and postcondition definitions. On his request, removed Geoff Clemm's name from the author list (moved to Acknowledgments). Renamed "References" to "Normative References". Removed reference to "MKREF" method. +B.3 Since draft-ietf-webdav-ordering-protocol-03 + + Added a set of issues regarding marshalling. + Changed host names to use proper "example" domain names (no change + tracking). Fixed host/destination header conflicts. Fixed "allow" + header (multiline). Removed irrelevant response headers. Abbreviated + some URIs (no change tracking). + Removed Jim Davis and Chuck Fay from the author list (and added them + to the Acknowledgements section). + Updated section on setting the position when adding new members, + removed old section on Position header. + Started work on Index section. + Changed structure for section 7 (no change tracking). + Removed header and XML elements section (contents moved to other + sections). + Started new section on relation to versioned collections as per + RFC3253. + Do not return 424's for in ODERPATCH multistatus (it's atomic + anyway). + +Index + + C O + + Client-Maintained Ordering Ordered Collection + 3 3 + Ordered header + 5.1 + ORDERPATCH method + D 7 + + DAV:collection-must-be-ordered + precondition P + 6.1 + DAV:custom ordering type + 4.1.1 Postconditions + DAV:ordered-collections- DAV:orderingtype-set 5.1,7 + supported precondition DAV:position-set 6.1 + 5.1 DAV:orderingtype-set 5.1,7 + DAV:ordering-modified DAV:ordering-modified 7 + postcondition + 7 Preconditions + DAV:orderingtype property DAV:ordered-collections- + 4.1.1 supported 5.1 + DAV:orderingtype-set DAV:collection-must-be- + postcondition ordered 6.1 + 5.1,7 DAV:segment-must-identify- + DAV:position-set postcondition member 6.1 + 6.1 + DAV:segment-must-identify- Protected properties + member precondition DAV:orderingtype 4.1.1 + 6.1 + DAV:unordered ordering type + 4.1.1 + + S + + H + Server-Maintained Ordering + 3 + Headers + Ordered 5.1 + U + + Unordered Collection + 3 Full Copyright Statement - Copyright (C) The Internet Society (2002). All Rights Reserved. + Copyright (C) The Internet Society (2003). All Rights Reserved. - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. + This document and translations of it may be copied and furnished + to others, and derivative works that comment on or otherwise + explain it or assist in its implementation may be prepared, + copied, published and distributed, in whole or in part, without + restriction of any kind, provided that the above copyright notice + and this paragraph are included on all such copies and derivative + works. However, this document itself may not be modified in any + way, such as by removing the copyright notice or references to the + Internet Society or other Internet organizations, except as needed + for the purpose of developing Internet standards in which case the + procedures for copyrights defined in the Internet Standards + process must be followed, or as required to translate it into + languages other than English. - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. + The limited permissions granted above are perpetual and will not + be revoked by the Internet Society or its successors or assigns. - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + This document and the information contained herein is provided on + an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC editor function is currently provided by the Internet Society.