rfc3253.txt

RFC 的详细文档！

   DAV:resourcetype is DAV:collection) is a versionable resource if it
   supports the VERSION-CONTROL method, and is a version-controlled
   resource if it supports the version-controlled resource methods and
   live properties.

   In the following example, foo.html is a versionable resource that is
   put under version control.  After the VERSION-CONTROL request
   succeeds, there are two additional resources: a new version history
   resource and a new version resource in that version history.  The
   versionable resource is converted into a version-controlled resource,
   whose DAV:checked-in property identifies the new version resource.




Clemm, et al.               Standards Track                    [Page 16]

RFC 3253            Versioning Extensions to WebDAV           March 2002


   The content and dead properties of a resource are represented by the
   symbol appearing inside the box for that resource (e.g., "S1" in the
   following example).

            ===VERSION-CONTROL==>

                      |                       +----+ version
                      |   version-            |    | history
         versionable  |   controlled          +----+ resource
         resource     |   resource              |
         /foo.html    |   /foo.html             |
                      |                         v
           +----+     |     +----+ checked-in +----+ version
           | S1 |     |     | S1 |----------->| S1 | resource
           +----+     |     +----+            +----+ /his/73/ver/1

   Thus, whereas before the VERSION-CONTROL request there was only one,
   non-version-controlled resource, after VERSION-CONTROL there are
   three separate, distinct resources, each containing its own state and
   properties: the version-controlled resource, the version resource,
   and the version history resource.  Since the version-controlled
   resource and the version resource are separate, distinct resources,
   when a method is applied to a version-controlled resource, it is only
   applied to that version-controlled resource, and is not applied to
   the version resource that is currently identified by the
   DAV:checked-in property of that version-controlled resource.
   Although the content and dead properties of a checked-in version-
   controlled resource are required to be the same as those of its
   current DAV:checked-in version, its live properties may differ.  An
   implementation may optimize storage by retrieving the content and
   dead properties of a checked-in version-controlled resource from its
   current DAV:checked-in version rather than storing them in the
   version-controlled resource, but this is just an implementation
   optimization.

   Normally, a resource is placed under version control with an explicit
   VERSION-CONTROL request.  A server MAY automatically place every new
   versionable resource under version control.  In this case, the
   resulting state on the server MUST be the same as if the client had
   explicitly applied a VERSION-CONTROL request to the versionable
   resource.

2.2.2 Modifying a Version-Controlled Resource

   In order to use methods like PUT and PROPPATCH to directly modify the
   content or dead properties of a version-controlled resource, the
   version-controlled resource must first be checked out.  When the
   checked-out resource is checked in, a new version is created in the



Clemm, et al.               Standards Track                    [Page 17]

RFC 3253            Versioning Extensions to WebDAV           March 2002


   version history of that version-controlled resource.  The version
   that was checked out is remembered as the predecessor of the new
   version.

   The DAV:auto-version property (see Sections 3.2.2) of a checked-in
   version-controlled resource determines how it responds to a method
   that attempts to modify its content or dead properties.  Possible
   responses include:

   -  Fail the request.  The resource requires an explicit CHECKOUT
      request for it to be modified (see Sections 4 and 9.2.1).

   -  Automatically checkout the resource, perform the modification, and
      automatically checkin the resource.  This ensures that every state
      of the resource is tracked by the server, but can result in an
      excessive number of versions being created.

   -  Automatically checkout the resource, perform the modification, and
      then if the resource is not write-locked, automatically checkin
      the resource.  If the resource is write-locked, it remains
      checked-out until the write-lock is removed (either explicitly
      through a subsequent UNLOCK request or implicitly through a time-
      out of the write-lock).  This helps a locking client avoid the
      proliferation of versions, while still allowing a non-locking
      client to update the resource.

   -  Automatically checkout the resource, perform the modification, and
      then leave the resource checked out.  If the resource is write-
      locked, it will be automatically checked in when the write-lock is
      removed, but an explicit CHECKIN operation (see Section 4.4) is
      required for a non-write-locked resource.  This minimizes the
      number of new versions that will be created by a versioning
      unaware client, but only a versioning aware client can create new
      versions of a non-write-locked resource.

   -  Fail the request unless the resource is write-locked.  If it is
      write-locked, automatically checkout the resource and perform the
      modification.  The resource is automatically checked in when the
      write-lock is removed.  This minimizes the number of new versions
      that will be created by a versioning unaware client, but never
      automatically checks out a resource that will not subsequently be
      automatically checked in.









Clemm, et al.               Standards Track                    [Page 18]

RFC 3253            Versioning Extensions to WebDAV           March 2002


   The following diagram illustrates the effect of the checkout/checkin
   process on a version-controlled resource and its version history.
   The symbol inside a box (S1, S2, S3) represents the current content
   and dead properties of the resource represented by that box.  The
   symbol next to a box (V1, V2, V3) represents the URL for that
   resource.

              ===checkout==>     ===PUT==>     ===checkin==>


           /foo.html (version-controlled resource)

            +----+    |    +----+    |    +----+    |    +----+
            | S2 |    |    | S2 |    |    | S3 |    |    | S3 |
            +----+    |    +----+    |    +----+    |    +----+
         Checked-In=V2|Checked-Out=V2|Checked-Out=V2|Checked-In=V3


           /his/73 (version history for /foo.html)

           +----+     |   +----+     |   +----+     |   +----+
           | S1 | V1  |   | S1 | V1  |   | S1 | V1  |   | S1 | V1
           +----+     |   +----+     |   +----+     |   +----+
              |       |      |       |      |       |      |
              |       |      |       |      |       |      |
           +----+     |   +----+     |   +----+     |   +----+
           | S2 | V2  |   | S2 | V2  |   | S2 | V2  |   | S2 | V2
           +----+     |   +----+     |   +----+     |   +----+
                      |              |              |      |
                      |              |              |      |
                      |              |              |   +----+
                      |              |              |   | S3 | V3
                      |              |              |   +----+

   Note that a version captures only a defined subset of the state of a
   resource.  In particular, a version of a basic resource captures its
   content and dead properties, but not its live properties.

2.2.3 Reporting

   Some versioning information about a resource requires that parameters
   be specified along with that request for information.  Included in
   basic versioning is the required support for an extensible reporting
   mechanism, which includes a REPORT method as well as a live property
   for determining what reports are supported by a particular resource.
   The REPORT method is required by versioning, but it can be used in
   non-versioning WebDAV extensions.




Clemm, et al.               Standards Track                    [Page 19]

RFC 3253            Versioning Extensions to WebDAV           March 2002


   To allow a client to query the properties of all versions in the
   version history of a specified version-controlled resource, basic
   versioning provides the DAV:version-tree report (see Section 3.7).  A
   more powerful version history reporting mechanism is provided by
   applying the DAV:expand-property report (see Section 3.8) to a
   version history resource (see Section 5).

3  Version-Control Feature

   The version-control feature provides support for putting a resource
   under version control, creating an associated version-controlled
   resource and version history resource as described in Section 2.2.1.
   A server indicates that it supports the version-control feature by
   including the string "version-control" as a field in the DAV header
   in the response to an OPTIONS request.  The version-control feature
   MUST be supported if any other versioning feature is supported.

3.1 Additional Resource Properties

   The version-control feature introduces the following REQUIRED
   properties for any WebDAV resource.

3.1.1 DAV:comment

   This property is used to track a brief comment about a resource that
   is suitable for presentation to a user.  The DAV:comment of a version
   can be used to indicate why that version was created.

   <!ELEMENT comment (#PCDATA)>
   PCDATA value: string

3.1.2 DAV:creator-displayname

   This property contains a description of the creator of the resource
   that is suitable for presentation to a user.  The DAV:creator-
   displayname of a version can be used to indicate who created that
   version.

   <!ELEMENT creator-displayname (#PCDATA)>
   PCDATA value: string

3.1.3 DAV:supported-method-set (protected)

   This property identifies the methods that are supported by the
   resource.  A method is supported by a resource if there is some state
   of that resource for which an application of that method will





Clemm, et al.               Standards Track                    [Page 20]

RFC 3253            Versioning Extensions to WebDAV           March 2002


   successfully satisfy all postconditions of that method, including any
   additional postconditions added by the features supported by that
   resource.

   <!ELEMENT supported-method-set (supported-method*)>
   <!ELEMENT supported-method ANY>
   <!ATTLIST supported-method name NMTOKEN #REQUIRED>
   name value: a method name

3.1.4 DAV:supported-live-property-set (protected)

   This property identifies the live properties that are supported by
   the resource.  A live property is supported by a resource if that
   property has the semantics defined for that property.  The value of
   this property MUST identify all live properties defined by this
   document that are supported by the resource, and SHOULD identify all
   live properties that are supported by the resource.

   <!ELEMENT supported-live-property-set (supported-live-property*)>
   <!ELEMENT supported-live-property name>
   <!ELEMENT prop ANY>
   ANY value: a property element type

3.1.5 DAV:supported-report-set (protected)

   This property identifies the reports that are supported by the
   resource.

   <!ELEMENT supported-report-set (supported-report*)>
   <!ELEMENT supported-report report>
   <!ELEMENT report ANY>
   ANY value: a report element type

3.2 Version-Controlled Resource Properties

   The version-control feature introduces the following REQUIRED
   properties for a version-controlled resource.

3.2.1 DAV:checked-in (protected)

   This property appears on a checked-in version-controlled resource,
   and identifies a version that has the same content and dead
   properties as the version-controlled resource.  This property is
   removed when the resource is checked out, and then added back
   (identifying a new version) when the resource is checked back in.

   <!ELEMENT checked-in (href)>