[Docs] [txt|pdf] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04 05 06 07 08 09 10 RFC 3648

Network Working Group                                           J. Slein
Internet Draft                                                     Xerox
Expires: March 2003                                         J. Whitehead
                                                         U.C. Santa Cruz
                                                                J. Davis
                                                     Intelligent Markets
                                                                  C. Fay
                                                                 FileNet
                                                             J. Crawford
                                                                     IBM
                                                           J. F. Reschke
                                                              greenbytes
                                                          September 2002


                  WebDAV Ordered Collections Protocol
                 draft-ietf-webdav-ordering-protocol-03



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.


Copyright Notice

   Copyright (C) The Internet Society (2002). All Rights Reserved.






Slein, et al.              Expires March 2003                   [Page 1]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


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

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

































Slein, et al.              Expires March 2003                   [Page 2]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


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



Slein, et al.              Expires March 2003                   [Page 3]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


   Author's Addresses  . . . . . . . . . . . . . . . . . . . . . . .  37
   A Extensions to the WebDAV Document Type Definition . . . . . . .  39
   B Change Log  . . . . . . . . . . . . . . . . . . . . . . . . . .  40
     B.1 Since draft-ietf-webdav-ordering-protocol dated December
   1999  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  40
     B.2 Since draft-ietf-webdav-ordering-protocol-02  . . . . . . .  40













































Slein, et al.              Expires March 2003                   [Page 4]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


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.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].






































Slein, et al.              Expires March 2003                   [Page 5]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


2 Introduction

   This specification builds on the collection infrastructure provided
   by the WebDAV Distributed Authoring Protocol, adding support for the
   server-side ordering of collection members.

   There are many scenarios where it is useful to impose an ordering on
   a collection at the server, such as expressing a recommended access
   order, or a revision history order. The members of a collection might
   represent the pages of a book, which need to be presented in order if
   they are to make sense. Or an instructor might create a collection of
   course readings, which she wants to be displayed in the order they
   are to be read.

   Orderings may be based on property values, but this is not always the
   case. The resources in the collection may not have properties that
   can be used to support the desired ordering. Orderings based on
   properties can be obtained using a search protocol's ordering option,
   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
   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
   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.











Slein, et al.              Expires March 2003                   [Page 6]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


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

   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


   Client-Maintained Ordering

      An ordering of collection members that is maintained on the server
      based on client requests specifying the position of each
      collection member in the ordering


   Server-Maintained Ordering

      An ordering of collection members that is maintained automatically
      by the server, based on a client's choice of ordering semantics


   This document uses the terms "precondition" as "postcondition" as
   defined in [RFC3253]. Servers should report pre-/postcondition
   failures as described in section 1.6 of this document.

















Slein, et al.              Expires March 2003                   [Page 7]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


4 Overview of Ordered Collections

   If a collection is unordered, the client cannot depend on the
   repeatability of the ordering of results from a PROPFIND request. By
   specifying an ordering for a collection, a client requires the server
   to follow that ordering whenever it responds to a PROPFIND request on
   that collection.

   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.

   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.

   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








Slein, et al.              Expires March 2003                   [Page 8]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


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.

   The value DAV:unordered indicates that the collection is not ordered.
   That is, the client cannot depend on the repeatability of the
   ordering of results from a PROPFIND request.

   The value DAV:custom indicates that the collection is ordered, but
   the semantics governing the ordering are not being advertised.

   If the value is a DAV:href element, it contains a URI that uniquely
   identifies the semantics of the collection's ordering.

   An ordering-aware client interacting with an ordering-unaware server
   (e.g., one that is implemented only according to [RFC2518]) SHOULD
   assume that if a collection does not have the DAV:orderingtype
   property, the collection is unordered.




   <!ELEMENT orderingtype (unordered | custom | href) >
   <!ELEMENT custom EMPTY >
   <!ELEMENT unordered EMPTY >



















Slein, et al.              Expires March 2003                   [Page 9]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


5 Creating an Ordered Collection


5.1 Overview

   When a collection is created, the client MAY request that it be
   ordered and specify the semantics of the ordering by using the new
   Ordered header (defined below)  with a MKCOL request.

   For collections that are ordered, the client SHOULD identify the
   semantics of the ordering with a URI in the Ordered header, although
   the client MAY simply set the header value to DAV:custom to indicate
   that the collection is ordered but the semantics of the ordering are
   not being advertised. Setting the value to a URI that identifies the
   ordering semantics provides the information a human user or software
   package needs to insert new collection members into the ordering
   intelligently. Although the URI in the Ordered header MAY point to a
   resource that contains a definition of the semantics of the ordering,
   clients SHOULD NOT access that resource, in order to avoid
   overburdening its server. A value of DAV:unordered in the Ordering
   header indicates that the client wants the collection to be
   unordered. If the Ordered header is not present, the collection will
   be unordered.

   Additional Marshalling:




      Ordered = "Ordered" ":" ("DAV:unordered" | "DAV:custom" | Coded-url)



      A value of "DAV:unordered" indicates that the collection is not
      ordered. A value of "DAV:custom" indicates that the collection is
      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.






Slein, et al.              Expires March 2003                  [Page 10]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


5.2 Example: Creating an Ordered Collection


   >> Request:

   MKCOL /theNorth/ HTTP/1.1
   Host: www.server.org
   Ordered: <http://www.server.org/orderings/compass.html>




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


























Slein, et al.              Expires March 2003                  [Page 11]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


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.

   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

   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.


6.3 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
   Position: after requirements.html








Slein, et al.              Expires March 2003                  [Page 12]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


   >> 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 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
   Position: first




   >> Response:

   HTTP/1.1 409 Conflict



   In this case, the server returned a 409 (Conflict) status code
   because the /~whitehead/dav/ collection is an unordered collection.
   Consequently, the server was unable to satisfy the Position header.



















Slein, et al.              Expires March 2003                  [Page 13]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


7 Changing a Collection Ordering


7.1 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

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





Slein, et al.              Expires March 2003                  [Page 14]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


   The following are examples of response codes one would expect to be
   used in a 207 (Multi-Status) response for this method:

   200 (OK): The change in ordering was successfully made.

   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.

   A request to reposition a collection member at the same place in the
   ordering is not an error.


7.1.2 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
   Content-Type: text/xml; charset="utf-8"
   Content-Length: xxx

   <?xml version="1.0" ?>
   <d:order xmlns:d="DAV:">
      <d:orderingtype>
         <d:href>http://www.myserver.com/inorder.ord</d:href>
      </d:orderingtype>
      <d:ordermember>
         <d:href>two.html</d:href>
         <d:position>
            <d:first/>
         </d:position>



Slein, et al.              Expires March 2003                  [Page 15]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


      </d:ordermember>
      <d:ordermember>
         <d:href>one.html</d:href>
         <d:position>
            <d:first/>
         </d:position>
      </d:ordermember>
      <d:ordermember>
         <d:href>three.html</d:href>
         <d:position>
            <d:last/>
         </d:position>
      </d:ordermember>
      <d:ordermember>
         <d:href>four.html</d:href>
         <d:position>
            <d:last/>
         </d:position>
      </d:ordermember>
   </d:order>




   >> 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
   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:






Slein, et al.              Expires March 2003                  [Page 16]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


   one.html
   two.html
   three.html
   four.html




7.1.3 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
   iqaluit.img
   iqaluit.desc




   >> Request:

   ORDERPATCH /coll-1/ HTTP/1.1
   Host: www.nunanet.com
   Content-Type: text/xml; charset="utf-8"
   Content-Length: xxx

   <?xml version="1.0" ?>
   <d:order xmlns:d="DAV:">
      <d:ordermember>
         <d:href>nunavut.desc</d:href>
         <d:position>
            <d:after>
               <d:segment>nunavut.map</d:segment>
            </d:after>
         </d:position>
      </d:ordermember>
      <d:ordermember>
         <d:href>iqaluit.map</d:href>
         <d:position>



Slein, et al.              Expires March 2003                  [Page 17]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


            <d:after>
               <d:segment>pangnirtung.img</d:segment>
            </d:after>
         </d:position>
      </d:ordermember>
   </d:order>




   >> Response:

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

   <?xml version="1.0" ?>
   <d:multistatus xmlns:d="DAV:">
      <d:response>
         <d:href>http://www.nunanet.com/coll-1/nunavut.desc</d:href>
         <d:status>HTTP/1.1 424 Failed Dependency</d:status>
      </d:response>
      <d:response>
         <d:href>http://www.nunanet.com/coll-1/iqaluit.map</d:href>
         <d:status>HTTP/1.1 409 Conflict</d:status>
         <d:responsedescription>pangnirtung.img is not a collection
                   member.</d:responsedescription>
      </d:response>
   </d:multistatus>



   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
   reposition nunavut.desc (which would otherwise have succeeded) failed
   with a 424 (Failed Dependency) status code.













Slein, et al.              Expires March 2003                  [Page 18]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


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
   cannot depend on the repeatability of the ordering of results from a
   PROPFIND request.

   In a response to a PROPFIND with Depth: infinity, members of
   different collections may be interleaved. That is, the server is not
   required to do a breadth-first traversal. The only requirement is
   that the members of any ordered collection appear in the order
   defined for the collection. Thus for the hierarchy illustrated in the
   following figure, where collection A is an ordered collection with
   the ordering B C D,




                       A
                      /|\
                     / | \
                    B  C  D
                   /  /|\
                  E  F G H



   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.







Slein, et al.              Expires March 2003                  [Page 19]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


   /MyCollection/
      lakehazen.html
      siorapaluk.html
      iqaluit.html
      newyork.html




   >> Request:

   PROPFIND /MyCollection/ HTTP/1.1
   Host: www.svr.com
   Depth: 1
   Content-Type: text/xml; charset="utf-8"
   Content-Length: xxxx

   <?xml version="1.0" ?>
   <D:propfind xmlns:D="DAV:">
     <D:prop xmlns:J="http://www.svr.com/jsprops/">
       <D:orderingtype/>
       <D:resourcetype/>
       <J:latitude/>
    </D:prop>
   </D:propfind>




   >> Response:

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

   <?xml version="1.0" ?>
   <D:multistatus xmlns:D="DAV:"
                  xmlns:J="http:www.svr.com/jsprops/">
      <D:response>
         <D:href>http://www.svr.com/MyCollection/</D:href>
         <D:propstat>
            <D:prop>
               <D:orderingtype><D:custom/></D:orderingtype>
               <D:resourcetype><D:collection/></D:resourcetype>
            </D:prop>
            <D:status>HTTP/1.1 200 OK</D:status>
         </D:propstat>
         <D:propstat>



Slein, et al.              Expires March 2003                  [Page 20]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


            <D:prop>
               <J:latitude/>
            </D:prop>
            <D:status>HTTP/1.1 404 Not Found</D:status>
         </D:propstat>
      </D:response>
      <D:response>
         <D:href>http://www.svr.com/MyCollection/lakehazen.html</D:href>
         <D:propstat>
            <D:prop>
               <D:resourcetype/>
               <J:latitude>82N</J:latitude>
            </D:prop>
            <D:status>HTTP/1.1 200 OK</D:status>
         </D:propstat>
         <D:propstat>
            <D:prop>
               <D:orderingtype/>
            </D:prop>
            <D:status>HTTP/1.1 404 Not Found</D:status>
         </D:propstat>
      </D:response>
      <D:response>
         <D:href
         >http://www.svr.com/MyCollection/siorapaluk.html</D:href>
         <D:propstat>
            <D:prop>
               <D:resourcetype/>
               <J:latitude>78N</J:latitude>
            </D:prop>
            <D:status>HTTP/1.1 200 OK</D:status>
         </D:propstat>
         <D:propstat>
            <D:prop>
               <D:orderingtype/>
            </D:prop>
            <D:status>HTTP/1.1 404 Not Found</D:status>
         </D:propstat>
      </D:response>
      <D:response>
         <D:href>http://www.svr.com/MyCollection/iqaluit.html</D:href>
         <D:propstat>
            <D:prop>
               <D:resourcetype/>
               <J:latitude>62N</J:latitude>
            </D:prop>
            <D:status>HTTP/1.1 200 OK</D:status>
         </D:propstat>



Slein, et al.              Expires March 2003                  [Page 21]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


         <D:propstat>
            <D:prop>
               <D:orderingtype/>
            </D:prop>
            <D:status>HTTP/1.1 404 Not Found</D:status>
         </D:propstat>
      </D:response>
      <D:response>
         <D:href>http://www.svr.com/MyCollection/newyork.html</D:href>
         <D:propstat>
            <D:prop>
               <D:resourcetype/>
               <J:latitude>45N</J:latitude>
            </D:prop>
            <D:status>HTTP/1.1 200 OK</D:status>
         <D:propstat>
            <D:prop>
               <D:orderingtype/>
            </D:prop>
            <D:status>HTTP/1.1 404 Not Found</D:status>
         </D:propstat>
         </D:propstat>
      </D:response>
   </D:multistatus>



   In this example, the server responded with a list of the collection
   members in the order defined for the collection.






















Slein, et al.              Expires March 2003                  [Page 22]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


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.






Slein, et al.              Expires March 2003                  [Page 23]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


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.





      <!ELEMENT order (orderingtype?, ordermember*) >





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.





      <!ELEMENT ordermember (href, position) >







Slein, et al.              Expires March 2003                  [Page 24]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


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.





      <!ELEMENT position (first | last | before | after)>





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.





      <!ELEMENT first EMPTY >





10.5 last XML Element






Slein, et al.              Expires March 2003                  [Page 25]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


   Name:      last
   Namespace: DAV:
   Purpose:   Occurs in the position XML element. Specifies that the
              member should be placed last in the collection's ordering.





      <!ELEMENT last EMPTY >





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





      <!ELEMENT before segment >





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.



Slein, et al.              Expires March 2003                  [Page 26]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


   Value:     URI (relative to the parent collection) of the member it
              follows in the ordering





      <!ELEMENT after segment >





10.8 segment XML Element



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





      <!ELEMENT segment (#PCDATA)>





















Slein, et al.              Expires March 2003                  [Page 27]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


11 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
   compliance class in the DAV header.

   When responding to an OPTIONS request, only a collection or a null
   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


   >> Request:

   OPTIONS /somecollection/ HTTP/1.1
   HOST: somehost.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
   DAV: 1, 2, orderedcoll






Slein, et al.              Expires March 2003                  [Page 28]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


   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


   >> Request:

   PROPFIND /somecollection HTTP/1.1
   Host: somehost.org
   Depth: 0
   Content-Type: text/xml; charset="utf-8"
   Content-Length: xxx

   <?xml version="1.0" encoding="UTF-8" ?>
   <propfind xmlns="DAV:">
     <prop>
       <supported-live-property-set/>
       <supported-method-set/>
     </prop>
   </propfind>




   >> Response:

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

   <?xml version="1.0" encoding="utf-8" ?>
   <multistatus xmlns="DAV:">
     <response>
       <href>http://somehost.org/somecollection</href>
       <propstat>
         <prop>
           <supported-live-property-set>
             <supported-live-property>
               <prop><orderingtype/></prop>
             </supported-live-property>
             ... other live properties omitted for brevity ...
           </supported-live-property-set>
           <supported-method-set>



Slein, et al.              Expires March 2003                  [Page 29]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


             <supported-method name="COPY" />
             <supported-method name="DELETE" />
             <supported-method name="GET" />
             <supported-method name="HEAD" />
             <supported-method name="LOCK" />
             <supported-method name="MKCOL" />
             <supported-method name="MOVE" />
             <supported-method name="OPTIONS" />
             <supported-method name="ORDERPATCH" />
             <supported-method name="POST" />
             <supported-method name="PROPFIND" />
             <supported-method name="PROPPATCH" />
             <supported-method name="PUT" />
             <supported-method name="TRACE" />
             <supported-method name="UNLOCK" />
           </supported-method-set>
         </prop>
         <status>HTTP/1.1 200 OK</status>
       </propstat>
     </response>
   </multistatus>



   Note that actual responses MUST contain a complete list of supported
   live properties.

























Slein, et al.              Expires March 2003                  [Page 30]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


12 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

   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
   to the URI in DAV:orderingtype.






























Slein, et al.              Expires March 2003                  [Page 31]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


13 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].

   As in [RFC2518], names in this specification fall into three
   categories: names of protocol elements such as methods and headers,
   names of XML elements, and names of properties. Naming of protocol
   elements follows the precedent of HTTP, using English names encoded
   in USASCII for methods and headers. The names of XML elements used in
   this specification are English names encoded in UTF-8.

   For error reporting, [RFC2518] follows the convention of HTTP/1.1
   status codes, including with each status code a short, English
   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].





















Slein, et al.              Expires March 2003                  [Page 32]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


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














































Slein, et al.              Expires March 2003                  [Page 33]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


15 Copyright

   To be supplied by the RFC Editor.
















































Slein, et al.              Expires March 2003                  [Page 34]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


16 Intellectual Property

   To be supplied by the RFC Editor.
















































Slein, et al.              Expires March 2003                  [Page 35]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


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









































Slein, et al.              Expires March 2003                  [Page 36]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


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
              Resource Identifiers (URI): Generic Syntax", RFC 2396,
              August 1998.

   [RFC2518]  Goland, Y., Whitehead, E., Faizi, A., Carter, S.R. and
              Jensen, D., "HTTP Extensions for Distributed Authoring --
              WEBDAV", RFC 2518, February 1999.

   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
              Masinter, L., Leach, P. and Berners-Lee, T., "Hypertext
              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

   [RFC3253]  Clemm, G., Amsden, J., Ellison, T., Kaler, C. and
              Whitehead, J., "Versioning Extensions to WebDAV", RFC
              3253, March 2002.

   [XML]      World Wide Web Consortium, "Extensible Markup Language
              (XML) 1.0", W3C XML, February 1998.


Author's Addresses

   Judith Slein
   Xerox Corporation
   800 Phillips Road, 105-50C
   Webster, NY 14580

   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






Slein, et al.              Expires March 2003                  [Page 37]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


   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
   Muenster, NW 48159
   Germany

   Phone: +49 251 2807760
   Fax:   +49 251 2807761
   EMail: julian.reschke@greenbytes.de
   URI:   http://greenbytes.de/tech/webdav/




















Slein, et al.              Expires March 2003                  [Page 38]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


A Extensions to the WebDAV Document Type Definition




   <!--============= XML Elements from Section 11 ================-->
   <!ELEMENT unordered EMPTY >
   <!ELEMENT custom EMPTY >
   <!ELEMENT order (orderingtype?, ordermember*) >
   <!ELEMENT ordermember (href, position) >
   <!ELEMENT position (first | last | before | after)>
   <!ELEMENT first EMPTY >
   <!ELEMENT last EMPTY >
   <!ELEMENT before segment >
   <!ELEMENT after segment >
   <!ELEMENT segment (#PCDATA)>
   <!--============= Property Elements from Section 10 =============-->
   <!ELEMENT orderingtype (unordered | custom | href) >

































Slein, et al.              Expires March 2003                  [Page 39]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


B Change Log


B.1 Since draft-ietf-webdav-ordering-protocol dated December 1999

   Updated contact information for all previous authors.
   Specify charset when using text/xml media type.
   Made sure artwork fits into 72 columns.
   Removed "Public" header from OPTIONS example.
   Added Julian Reschke to list of authors.
   Fixed broken XML in PROPFIND example and added DAV:orderingtype to
   list of requested properties.
   Added support for DAV:supported-live-property-set and DAV:supported-
   method-set as mandatory features.


B.2 Since draft-ietf-webdav-ordering-protocol-02

   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.


Full Copyright Statement

   Copyright (C) The Internet Society (2002). 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.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.



Slein, et al.              Expires March 2003                  [Page 40]


Internet Draft     WebDAV Ordered Collections Protocol    September 2002


   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.







































Slein, et al.              Expires March 2003                  [Page 41]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/