--- 1/draft-ietf-webdav-versioning-00.txt 2006-02-05 02:11:58.000000000 +0100 +++ 2/draft-ietf-webdav-versioning-01.txt 2006-02-05 02:11:58.000000000 +0100 @@ -1,20 +1,22 @@ - INTERNET-DRAFT Christopher Kaler, - draft-ietf-webdav-versioning-00.txt Microsoft - Editor + INTERNET-DRAFT Chris Kaler, Microsoft, Editor + draft-ietf-webdav-versioning-01.txt Jim Amsden, IBM + Goeff Clemm, Rational + Bruce Cragun, Novell + David Durand, BU + Bradley Sergeant, Microfocus + Jim Whitehead, UC Irvine - Expires April 26, 1999 - October 26, 1998 + Expires June 20, 1999 January 20, 1999 Versioning Extensions to WebDAV - Status of this Memo This document is an Internet draft. 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 information as Internet drafts. Internet Drafts are draft documents valid for a maximum of six months and can be updated, replaced or obsoleted by other documents at any time. It is inappropriate to use Internet drafts as @@ -41,114 +43,107 @@ This document specifies a set of methods, headers, and content- types composing DAV Versioning extensions, an application of the HTTP/1.1 protocol to version DAV resources. Table of Contents VERSIONING EXTENSIONS TO WEBDAV...........................1 TABLE OF CONTENTS.........................................2 - 1.INTRODUCTION...........................................4 - 1.1. DAV Versioning......................................4 - 1.2. Relationship to DAV.................................4 - 1.3. Terms...............................................4 - 1.4. Definitions.........................................4 - 1.5. Notational Conventions..............................5 + 1. INTRODUCTION ..........................................4 + 1.1.DAV Versioning ........................................4 + 1.2.Relationship to DAV ...................................4 + 1.3.Terms .................................................4 + 1.4.Definitions ...........................................4 + 1.5.Notational Conventions ................................5 - 2.BASIC VERSIONING.......................................5 - 2.1. Discovery...........................................5 - 2.2. Immutable and Mutable Properties....................6 - 2.3. Automatic Versioning................................7 - 2.4. Resource Properties.................................7 - 2.5. Basic Versioning Headers............................8 - 2.5.1.Versioning-Support................................8 - 2.5.2.Revision-Id.......................................8 - 2.5.3.Merged-From.......................................9 - 2.6. Checking Out/In Resources...........................9 - 2.6.1.Checkout..........................................9 - 2.6.2.Branching Resources..............................11 - 2.6.3.Checkin..........................................12 - 2.6.4.Undo Checkout....................................13 - 2.6.5.Enumeration......................................13 - 2.7. Default Revision...................................13 - 2.8. Sharing............................................14 - 2.9. Collection Versioning..............................15 - 2.9.1.Default Revisions................................16 - 2.9.2.Headers..........................................16 - 2.9.3.Properties.......................................16 - 2.10.Resource Reports...................................17 - 2.10.1.Example.........................................17 - 2.10.2.Default History.................................18 - 2.10.3.Direct Lineage..................................19 - 2.10.4.Full Lineage....................................20 + 2. BASIC VERSIONING ......................................5 + 2.1.Discovery .............................................6 + 2.2.Immutable and Mutable Properties ......................7 + 2.3.Versioning a Resource .................................8 + 2.4.Immutable and Mutable Revisions .......................8 + 2.5.Versioning and COPY/MOVE ..............................9 + 2.6.Sharing ...............................................9 + 2.7.Default Revision .....................................10 + 2.8.Collection Versioning ................................11 + 2.9.Basic Revision Properties ............................11 + 2.10. Basic Versioning Headers ...........................13 + 2.10.1. Revision-Id .....................................13 + 2.10.2. Branch-Id .......................................14 + 2.10.3. Override-Checkin ................................14 + 2.10.4. Revision-Path ...................................14 - 3.CONFIGURATIONS........................................21 - 3.1. Discovery..........................................22 - 3.2. Creating Configurations............................22 - 3.3. Configuration Properties...........................24 - 3.4. Headers............................................25 - 3.5. Deleting Configurations............................25 - 3.6. Managing Configuration Content.....................25 - 3.6.1.Access Using Configurations......................26 - 3.6.2.Adding Resources to a Configuration..............26 - 3.6.3.Removing Resources from a Configuration..........26 - 3.7. Workspace Configurations...........................27 - 3.7.1.Default Workspace Configurations.................27 - 3.7.2.Synchronizing Worksapce Configurations...........27 - 3.7.3.Condensing Workspace Configurations..............29 - 3.8. Configuration Reports..............................29 - 3.8.1.Configuration Derivation.........................30 - 3.8.2.Configuration Merge Graph........................31 - 3.9. Resolution Queues..................................31 - 3.9.1.Discovery........................................32 - 3.9.2.Obtaining Resolutions............................32 - 3.9.3.Processing Resolution Items......................32 - 3.10.Checkin Sets.......................................33 - 3.10.1.Discovery.......................................33 - 3.10.2.Usage...........................................34 + 3. CHECKING OUT/IN RESOURCES ............................15 + 3.1.Checkout .............................................15 + 3.2.Checkin ..............................................17 + 3.3.Cancelling Checkout ..................................17 + 3.4.Enumeration ..........................................18 - 4.VERSION MAPPING.......................................34 - 4.1. Discovery..........................................35 - 4.2. Mapping Configurations.............................35 - 4.3. Mapping Resource Versions..........................36 + 4. BRANCHING RESOURCES ..................................18 - 5.MISCELLANEOUS FUNCTIONS...............................37 - 5.1. Destroy............................................37 - 5.1.1.Discovery........................................37 - 5.1.2.Usage............................................37 - 5.1.3.Headers..........................................38 - 5.1.4.Properties.......................................38 + 5. RESOURCE REPORTS .....................................19 + 5.1.Available Reports ....................................20 + 5.2.Default History ......................................21 + 5.3.Active Checkouts .....................................22 + 5.4.Direct Lineage .......................................23 + 5.5.Full Lineage .........................................24 - 6.THE DAV VERSIONING GRAMMAR............................38 + 6. CONFIGURATION BASICS .................................26 + 6.1.Discovery ............................................27 + 6.2.Creating Configurations ..............................28 + 6.3.Access Using Configurations ..........................30 + 6.4.Deleting Configurations ..............................30 + 6.5.Resolution Queues ....................................30 + 6.6.Configuration Properties .............................31 + 6.7.Headers ..............................................32 - 7.INTERNATIONALIZATION CONSIDERATIONS...................38 + 7. CONFIGURATION REPORTS ................................33 + 7.1.Configuration Derivation .............................33 + 7.2.Configuration Merge Graph ............................34 - 8.SECURITY CONSIDERATIONS...............................38 + 8. DYNAMIC CONFIGURATIONS ...............................35 - 9.SCALABILITY...........................................38 + 9. WORKSPACE CONFIGURATIONS .............................37 + 9.1.Managing Configuration Content .......................37 + 9.2.Default Workspace Configurations .....................38 - 10. AUTHENTICATION......................................38 + 10. CHECKIN SETS .........................................38 - 11. IANA CONSIDERATIONS.................................38 + 11. VERSION MAPPING ......................................39 + 11.1. Discovery ..........................................40 + 11.2. Mapping Configurations .............................41 + 11.3. Mapping Resource Versions ..........................41 - 12. COPYRIGHT...........................................39 + 12. THE DAV VERSIONING GRAMMAR ...........................42 - 13. INTELLECTUAL PROPERTY...............................39 + 13. INTERNATIONALIZATION CONSIDERATIONS ..................42 - 14. REFERENCES..........................................39 + 14. SECURITY CONSIDERATIONS ..............................43 - 15. AUTHOR'S ADDRESSES..................................39 + 15. SCALABILITY ..........................................43 - 16. OPEN ISSUES.........................................39 + 16. AUTHENTICATION .......................................43 - 17. CHANGE HISTORY......................................40 + 17. IANA CONSIDERATIONS ..................................43 + + 18. COPYRIGHT ............................................43 + + 19. INTELLECTUAL PROPERTY ................................43 + + 20. REFERENCES ...........................................43 + + 21. AUTHOR'S ADDRESSES ...................................44 + + 22. OPEN ISSUES ..........................................44 + + 23. CHANGE HISTORY .......................................45 1. INTRODUCTION 1.1. DAV Versioning This document defines DAV Versioning extensions, an application of HTTP/1.1 for handling resource versioning in a DAV environment. [DAVVERREQ] describes the motivation and requirements for DAV Versioning. DAV Versioning will minimize the complexity of clients so as to @@ -177,34 +172,39 @@ This draft uses the terms defined in [RFC2068], [WebDAV], and [DAVVERREQ]. 1.4. Definitions The section defines several terms that are used throughout the document specific to DAV versioning. Versioned Resource - This refers to a resource that is subject to - versioning + versioning (independent of any specific version) Revision - This refers to a specific version of a versioned resource Revision History - This refers to the set of changes to a versioned resource - Working Resource - This refers to a resource that is an intermediate revision of a versioned resource. That is, the versioned resource has been "checked out" and this is where changes are made until it is ready to be "checked in". Note that working resources are not versioned. + Revision Thread - This refers to a sequence of revisions that have + been branched for a specific purpose. + + Line of Descent - This refers to the sequence of revisions that + have occurred from the initial revision to a specified revision. + 1.5. Notational Conventions The augmented BNF used by this document to describe protocol elements is exactly the same as the one described in Section 2.1 of [RFC2068]. Because this augmented BNF uses the basic production rules provided in Section 2.2 of [RFC2068], those 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 @@ -215,22 +215,22 @@ The base level of versioning support defined by this specification includes both automatic versioning and the basic versioning properties defined for all resources. To support basic versioning, resources MUST allow for versioning to occur automatically on selected resources whenever immutable aspects are changed, and support the properties defined in this section. Resources that support DAV:versioning MUST also provide additional versioning semantics for versioning-aware clients. This section describes these new semantics which include enhancements to - existing DAV methods, new headers, and a new versioning-specific - method. + existing DAV methods, new headers, and new versioning-specific + methods. Although the semantics can vary, most versioning systems support the notion of indicating intent to modify a document (check-out) and then submission of the modified version (check-in). Typically this involves some form of locking (either shared or exclusive). As well, many systems support the ability to cancel a check-out or undo a recent check-in. These options are available to the owner or to the Administrator. Users can generally enumerate the current check-outs although they @@ -238,659 +238,711 @@ users can review check-ins to see the change history. Most systems allow users to select different versions from the change history and present a comparison of the versions. Note that locks are not covered in this specification as they are addressed by [WebDAV]. 2.1. Discovery The OPTIONS method allows the client to discover if a resource - supports versioning. + supports versioning. The presence of Versioning in the response + header indicates support for DAV versioning. This header indicates + the level of support. - The client issues the OPTIONS method against a resource named by - the Request-URI. This is a normal invocation of OPTIONS defined in - [RFC2068] with an extension. If the client includes the Verify- - Extension header, then the reply includes additional information - beyond that which is defined in [RFC2068]. + The following defines the BNF for the Versioning header: - Using this header with the extension DAV:versioning, clients can - determine what versioning support is available. + Versioning := "Versioning" ":" URI - The following defines the BNF for the Verify-Extension header: + The valid values of the URI are: - Verify-Extension := "Verify-Extension" ":" URI-list - URI-list := URI | (URI-list "," URI) + - DAV:basicversioning + + - TBD This example shows that the /somefolder resource supports versioning. >> Request OPTIONS /somefolder/ HTTP/1.1 - Verify-Extension: DAV:versioning Host: foobar.com Content-Length: 0 >> 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, PIN, MKREF + MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, FREEZE, THAW, + CHECKIN, + CHECKOUT, UNCHECKOUT, BRANCH Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, - MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF - Verify-Extension: DAV:versioning - Versioning-Support: DAV:basicversioning + MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, FREEZE, THAW, + CHECKIN, + CHECKOUT, UNCHECKOUT, BRANCH + Versioning: DAV:basicversioning Content-Length: 0 - The Verify-Extension header in the reply indicates that the server - understood the request with Verify-Extension and that - DAV:versioning is supported. As well, the Versioning-Support - header indicates the level of versioning support provided. The BNF - for this header is provided later in this document. + Since some aspects of DAV versioning require clients to know + additional information, clients can include a request body that + specifies that DAV versioning information is desired. The + information is returned in the response body, formatted in XML. + + >> Request + + OPTIONS /somefolder/ HTTP/1.1 + Host: foobar.com + Content-Length: xxx + Content-Type: text/xml + + + + + + + >> 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, MKREF, FREEZE, THAW, + CHECKIN, + CHECKOUT, UNCHECKOUT, BRANCH + Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, + MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, FREEZE, THAW, + CHECKIN, + CHECKOUT, UNCHECKOUT, BRANCH + Versioning: DAV:basicversioning + Content-Type: text/xml + Content-Length: xxx + + + + + ... + + + + The details of the tags returned are described throughout this + specification. 2.2. Immutable and Mutable Properties An immutable property is defined as a property that, when changed, causes a new revision of a versioned resource to be created. Likewise, a mutable property is a property that can be changed without having a new revision created. Resources can support both mutable and immutable properties although there MAY be restrictions that the mutability is consistent across all resources. - This specification doesnÆt cover the discovery or management of + This specification doesn't cover the discovery or management of property mutability. - 2.3. Automatic Versioning + 2.3. Versioning a Resource - The DAV:autoversion property indicates if a resource is + By default, a resource may not be subject to versioning. This can + be discovered by examining the DAV:isversioned property. To place + a non-versioned resource under version control, clients use the + VERSION method and specify the URI of the resource to version. + Note that if the specified resource is a collection, then the Depth + header is used to identify the scope of the operation. A depth of + infinity is assumed by default. + + The DAV:isautoversioned property indicates if a resource is automatically versioned when any immutable aspect of it is changed. Resources with automatic versioning allow HTTP/1.1 clients to have - changes versioned without explicit versioning commands. + changes versioned without explicit versioning commands. This + applies to any method that modifies a resource (e.g., PUT, MKCOL, + COPY, MOVE, DELETE, PROPPATCH, ...) - Automatic versioning includes the following methods: + Using the DAV:versioningenabled and DAV:autoversioning tags, + clients can establish the versioning policy. - - Updates via PUT, MKCOL, COPY, MOVE, or DELETE + >> Request - - Immutable properties updates via PROPPATCH + VERSION /somefolder/ HTTP/1.1 + Host: foobar.com + Depth: infinity + Content-Type: text/xml + Content-Length: xxx - 2.4. Resource Properties + + + On + On + + + >> Response + + HTTP/1.1 200 OK + Content-Length: 0 + + 2.4. Immutable and Mutable Revisions + + By default, the contents of a revision are immutable. That is, + once a revision is created, it cannot be altered. However, in many + document management systems this is not the case. To address these + scenarios, the THAW/FREEZE methods are introduced. Note that + support for THAW and FREEZE are optional, but these operations MUST + fail if not supported. + + The THAW method specifies that the indicated revision should be + made mutable so that subsequent methods can alter the immutable + aspects of the resource. The FREEZE method indicates that all + changes have been made and the revision should be marked immutable + again. + + The DAV:canthaw property indicates if a revision can be thawed. + Similarly, the DAV:hasthawed property indicates if a revision has + ever been thawed. Finally, the DAV:isthawed property specifies if + the revision is currently thawed (frozen if not). + + The following example shows the use of THAW and FREEZE. + + >>Request + + THAW /foo/bar.htm HTTP/1.1 + Revision-Id: VER:FHF45409 + Host: www.foobar.com + Content-Length: 0 + ... + + PUT /foo/bar.htm HTTP/1.1 + Revision-Id: VER:FHF45409 + Host: www.foobar.com + Content-Length: xxx + ... + + FREEZE /foo/bar.htm HTTP/1.1 + Revision-Id: VER:FHF45409 + Host: www.foobar.com + Content-Length: 0 + ... + + 2.5. Versioning and COPY/MOVE + + When a COPY method is issued against a versioned resource or + revision, only the "current" revision of the versioned resource or + the specified revision is copied to the specified destination. + That is, the entire history is NOT copied. + + When a MOVE method is issued against a versioned resource the + "move" SHOULD be represented in the revision history. That is, a + MOVE operation CANNOT be represented as a delete and an add. A + MOVE operation cannot be issued against a specific revision. + + 2.6. Sharing + + Many versioning systems today provide the ability to have a given + resource visible in multiple parts of the namespace. In these + situations, a resource is shared. That is, changes to the resource + are visible to all versions. + + The WebDAV Advanced Collections working group addresses this need + with direct referential members. Support for direct referential + members is required for DAV versioning. + + 2.7. Default Revision + + If a Revision-Id (or Branch-Id) header is not specified when + referring to a resource, then the tip (latest) revision (from the + primary branch) is used, unless a default revision has been + identified. To mark a specified revision as the default revision, + clients use the SETDEFAULT method. Note that PUT or CHECKIN will + remove any default version. Also note that branching a resource + has no effect on the default revision of the resource, even if the + default revision is branched. If the default is removed, the + default revision is the tip revision of the initial (primary) + branch of the versioned resource. + + Setting the default revision to DAV:none cancels the default + revision. + + >>Request + + SETDEFAULT /foo/bar.htm HTTP/1.1 + Host: www.foobar.com + Content-Type: text/xml + Content-Length: xxx + + + + VER:HT58GHDW49 + + + >>Response + + HTTP/1.1 200 OK + Content-Length: 0 + + >>Request + + SETDEFAULT /foo/bar.htm HTTP/1.1 + Host: www.foobar.com + Content-Type: text/xml + Content-Length: xxx + + + + + + + >>Response + + HTTP/1.1 200 OK + Content-Length: 0 + + If a resource is shared, servers MUST support the ability to set + different default revisions at each point of the share. + + Clients can determine the default revision by examining the + DAV:revisionid from the default revision. + + >>Request + + PROPFIND /foo/bar.htm HTTP/1.1 + Host: www.foobar.com + Content-Type: text/xml + Content-Length: xxx + + + + + + + + + 2.8. Collection Versioning + + Collections can be versioned just like non-collection resources, + however, they are only versioned when a direct change is made to + the collection. + + It is up to each collection resource to determine if it supports + default versions. If it doesn't, then SETDEFAULT requests MUST + fail. + + The Revision-Path header is used to identify specific revisions + that are part of the "path" to the resource. This header servers + as an alternative to "URL munging". This header can be specified + on all methods and qualifies the resource named in the method. + + 2.9. Basic Revision Properties For resources that support versioning, they MUST support the following properties using the "DAV:" namespace. Note that 0/1 is used as a FALSE (0) / TRUE (1) indicator. DAV:isversioned - 0/1 to indicate if the resource is versionable. Note that this can be implemented as a read-only property. DAV:autoversion - 0/1 to indicate if the resource is automatically - versioned when modified. Note that this can be implemented this - as a read-only property. + versioned when modified. Note that this can be implemented this as + a read-only property. DAV:revisionid - This is a read-only property that returns a server determined id for this specific revision of the resource. Every revision of a resource will have a unique DAV:revisionid. A - revision id may be a URI or it may be an arbitrary server-defined + revision id may be a URL or it may be an arbitrary server-defined string. However, it cannot contain the "," character. Because it - is not required to be a URI, the DAV:revisionuri property is + is not required to be a URL, the DAV:revisionurl property is required to obtain a URI for the specific revision of the resource. DAV:vresourceid - This is a read-only property that returns a server determined id for the versioned resource. That is, all revisions of the resource have the same DAV:vresourceid. This MUST - be preserved over MOVE requests. + be preserved over MOVE requests and should be globally unique. - DAV:previousversionids - This is a read-only property that returns + DAV:previousrevisionids - This is a read-only property that returns the server defined id for the previous revision of the resource. An empty value indicates that there are no previous revisions. Note that there could be multiple previous versions. If there are multiple revisions, they are returned as a comma-separated list. Note that this property returns previous revisions that the server determines. That is, this does not include user identified merged revisions. - DAV:nextversionids - This is a read-only property that returns the + DAV:distinguishedpredecessorid - This read-only property indicates + the primary predecessor for a revision in the event they are + multiple predecessors. + + DAV:nextrevisionids - This is a read-only property that returns the server defined id for the next revision of the resource. An empty value indicates that there is no subsequent revision. Note that there could be multiple next revisions. If there are multiple revisions, they are returned as a comma-separated list. Note that this property returns successor revisions that the server determines. That is, this does not include user identified merged revisions. - DAV:revisionuri - This is a read-only property that returns a URI + DAV:revisionurl - This is a read-only property that returns a URL for this specific revision. - DAV:revisiondisplayname - This is a read-only property that returns - a string that clients may use to display this revision. This is - often a more user friendly string than DAV:revisionid. - DAV:revisionlabel - This property allows the specification of textual names that refer to this version of the resource. If there are multiple labels, they are returned as a comma separated list. Labels MUST be unique for the versioned resource. That is, no two revisions of the same versioned resource can have the same - DAV:revisionlabel. As well, DAV:revisionlabel, DAV:revisionid, and - DAV:vresourceid all share the same namespace and there can be no - duplicates. Servers MAY reserve specific portions of this - namespace and return an error if a client uses a reserved name as a - revision label. This property MUST be mutable. + DAV:revisionlabel. As well, DAV:revisionlabel and DAV:revisionid + properties share the same namespace and there can be no duplicates. + Servers MAY reserve specific portions of this namespace and return + an error if a client uses a reserved name as a revision label. + This property MUST be mutable. DAV:mergedfrom - This property specifies a comma separated list of revision ids from which this revision is purported to be derived. - This information is provided and managed by the client. + This information is provided and managed by the client. This is a + mutable property. + + DAV:mergedto - This property specifies a comma separated list of + revision ids from which this revision is purported to be merged + into. This information is provided and managed by the client. This + is a mutable property. + + DAV:mergedfromunion - This read-only property specified a comma + separated list of revision ids from which this revision is derived. + + This is a union of the DAV:mergedfrom and DAV:previousrevisionids + properties. DAV:revisioncomment - This property contains a client-defined property associated with the revision. This as a mutable property. + This is a mutable property. - 2.5. Basic Versioning Headers + DAV:author - The creator of the revision. This is an arbitrary + string. - The following sub-sections describe the new version headers that - MUST be supported for resources that support DAV:versioning. + DAV:canthaw - This property indicates if the revision can be THAWed + for modification. Servers MAY implement this as read-only. - 2.5.1. Versioning-Support + DAV:hasthawed - This read-only property indicates if the revision + has ever been thawed. - The Versioning-Support header specifies the type of versioning that - is available. The following BNF defines this header. + DAV:isthawed - This read-only property indicates if the revision is + currently thawed (or frozen if not). - Versioning-Support := "Versioning-Support" ":" URI-list + DAV:lastcheckin - This read-only property specifies the date this + revision was "checked in" in ISO8601 format. - To support versioning, the URI list MUST include - DAV:basicversioning. Later sections of this document specify other - optional support. + 2.10. Basic Versioning Headers - 2.5.2. Revision-Id + The following sub-sections describe the new version headers that + MUST be supported for resources that support DAV:versioning. + + 2.10.1. Revision-Id The Revision-Id header is used to identify a specific revision of a versioned resource. This header can be specified on all methods and qualifies the resource named in the method. As well, this header is included in all replies to indicate the revision of the versioned resource used or created. The BNF for this header is as follows. Revision-Id := "Revision-Id" ":" RID - RID := "*" | ANY - Clients can specify a DAV:revisionid or any of the - DAV:revisionlabel values to refer to a specific revision of the - resource. + RID := "*" | Time-Ref | ANY + Time-Ref := "Time" "(" ISO8601 ")" + + This property allows the specification of criteria that selects a + specific revision of a resource. This includes a DAV:revisionid or + any of the DAV:revisionlabel values to refer to a specific revision + of the resource. As well, a configuration (described later) can be + referenced here to select the default revision associated with the + configuration. + + The use of the Time operator is to select the "current" revision as + of the specified time. The use of Revision-Id: * is only permitted with PROPFIND to obtain properties across all revisions of a versioned resource. - 2.5.3. Merged-From + 2.10.2. Branch-Id - When clients use resource branching, they will likely need to - perform merge operations. A merge is the process by which changes - from different versions are combined to produce a new version. It - is likely that clients will want to track this semantic - information. When the Merged-From header is specified on a PUT, - UNLOCK, or PROPPATCH method, it indicates the revision (or - revisions) from which the change is derived. The server tracks - this information and makes it available in the DAV:mergedfrom - property. + The Branch-Id header is used to identify a branch (revision + thread). The BNF for the header is as follows: - Merged-Item := ANY - Merged-List := Merged-Item | (Merged-List "," Merged-Item) - Merged-From := "Merged-From" ":" Merged-List + Branch-Id := "Branch-Id" ":" ANY - >>Request + The Branch-Id can be used anywhere a revision-id is used. When + specified, it indicates that the latest version of the indicated + branch is to be selected as the revision to use for the operation. - PUT /foo/bar HTTP/1.1 - Host: www.foobar.com - Merged-From: VER:FDHJ43058 - Content-Type: text/html - Content-Length: xxxx + 2.10.3. Override-Checkin - ... + It is possible that the check-in operation will detect a conflict. + For example, version 5 was checked out shared, and before it is + checked back in, version 6 was created. In these situations, the + check-in MUST fail indicating a conflict. Clients can choose to + branch the resource, merge on the client, or overwrite. To + circumvent this check, clients can use the Override-Checkin header. + This specifies that the check-in operation SHOULD NOT fail (either + the client has merged to resolve the conflict, or desires an + overwrite). The BNF is as follows: - >>Response + Override-Checkin := "Override-Checkin" ":" ("Yes" | "No") - HTTP/1.1 200 OK + 2.10.4. Revision-Path + + The Revision-Path header allows clients to identify specific + versions of collections that should be used rather than the default + revisions. + + The BNF for this header is as follows. + + Revision-Path := "Revision-Path" ":" Path + Path := PItem | (Path PItem) + PItem := "/" ANY Rev + Rev := | (";" RID) + RID := "*" | ANY | "(" ANY ")" + + >>Request + + GET /foo/bar.htm HTTP/1.1 + Host: www.foobar.com + Revision-Path: /foo;VER:HT58GHDW49/bar.htm Content-Length: 0 - 2.6. Checking Out/In Resources + The use of * for a revision is only permitted with PROPFIND to + obtain properties across all revisions of a versioned resource. + + 3. CHECKING OUT/IN RESOURCES For versioning-aware clients, more advanced requests allow them to perform specific versioning operations. These methods are directed - at a specific URI and the body contains XML indicating the action - to take. + at a specific URI to alter. If a resource supports DAV:versioning then it MUST support the - LOCK/UNLOCK extensions defined in this section. + methods defined in this section. - 2.6.1. Checkout + 3.1. Checkout - Using the LOCK method, clients can request resources to be "checked - out". This involves creating a working resource that is not - automatically versioned. Checked out resources must be checked in - or aborted, using the UNLOCK method. The diagram below illustrates - this process: + Using the CHECKOUT method, clients can request resources to be + "checked out". This involves creating a working resource that is + not automatically versioned. Checked out resources must be checked + in or cancelled. The diagram below illustrates this process: Revisions of foo.htm: V1 Checkout is performed: V1 | +-> Working Resource Checkin is performed: V1 -> V2 The body XML indicates an optional checkout comment, an optional - user token, and locking actions. Clients specify the checkout lock - in all update operations (e.g., PUT or PROPPATCH) to alter the - working resource. - - The working resource will always be DAV:checkout locked. Clients - can choose to make the appropriate scope (DAV:shared, - DAV:exclusive, ...). Optionally, using the DAV:vresoucelockscope - tag, clients can have the versioned resource DAV:checkout locked - for a specified scope (DAV:shared, DAV:exclusive, ...). If a client - requests the versioned resource to be locked, and it cannot be, - then the lock operation MUST fail. - - The DAV:checkout lock state is equivalent to the DAV:write lock - state in terms of interoperability with other locks. - - Resources SHOULD allow clients to propose a DAV:locktoken in the - LOCK request. If a resource does not accept a clientÆs proposed - lock token, it MUST fail the LOCK request. - - >>Request - - LOCK /foo/bar HTTP/1.1 - Host: www.foobar.com - Content-Type: text/xml - Content-Length: xxxx - - - - - checkout comment - client-defined token - - - - - >>Response - - HTTP/1.1 201 CREATED - Content-Type: text/xml - Content-Length: xxxx - - - - - - - - client-define token - - opaquelocktoken:rejrei-43343-rereffre - - - - - - 2.6.2. Branching Resources - - For more sophisticated clients, basic resource branching is - required. Resource branching means that for a given resource, the - history is not linear. That is, there are different lines of - descent. The diagram below illustrates this. - - Revision history V1 -> V2 -> V3 - Of foo.htm: | - +-> V1.1 -> V1.2 - | - +-> V1.1.1 - - Individual resource branching is common in many versioning systems - today. Project branching (configurations) are described in a later - section. Note that when a collection is branched, the depth of the - branch is infinity. There is no way to change this. + user token, and locking actions. The response indicates the + working resource as well as any requested locks. - If a resource supports branching, it MUST return - DAV:resourcebranching in the Versioning-Support header reply from - OPTIONS. + The CHECKOUT method causes the creation of the working copy which + is specified by the Location header in the response. - A resource is branched using the LOCK method and the DAV:checkout - lock type. The resource to be branched is specified as the target - URI for the method. + Clients can optionally request locks to be taken as part of the + CHECKOUT operation. If the locks cannot be obtained, the CHECKOUT + operation MUST fail. The following table identifies the different + lock options: - Clients have a choice of three approaches to branching which are - specified with specific tags in the request: + Lock Tags Used Description + Target (DAV: assumed) - - perform a branch + working wrlocktype, Limits access to the newly created + resource wrlockscope working resource - - do not branch, error if necessary + revision revisionlockty Blocks CHECKOUT/INs against this + pe, revision + revisionlocksc + ope + branch branchlocktype Blocks CHECKOUT/INs against + , revisions in this branch + branchlockscop + e - - branch if necessary + versioned vrlocktype, Blocks CHECKOUT/INs against any + resource vrlockscope revision of the versioned + resource. - As well, clients can specify a branch label to identify a created - branch using the DAV:branchlabel tag. The reply MUST include a - Branch-Id header specifying a resource defined branch id or the - specified branch label if a branch is created. The label or id can - be specified in a Branch-Id or Revision-Id header to determine the - revision to access. + The semantics of the tags match those of DAV:locktype and + DAV:lockscope as specified for the LOCK method. >>Request - LOCK /foo/bar.htm HTTP/1.1 + CHECKOUT /foo/bar HTTP/1.1 Host: www.foobar.com - Content-Type: text/html + Content-Type: text/xml Content-Length: xxxx - - - MyBranch - + checkout comment client-defined token - - - + + + >>Response HTTP/1.1 201 CREATED - Branch-Id: MyBranch + Location: http://www.foobar.com/tmp/VRJHJWE3493409 Content-Type: text/xml Content-Length: xxxx - - + + client-define token opaquelocktoken:rejrei-43343-rereffre - When a branch is created, the reply MUST include a Branch-Id - header. The BNF for the header is as follows: - - Branch-Id := "Branch-Id" ":" ANY - - The Branch-Id can be used anywhere a revision-id is used. When - specified, it indicates that the latest version of the indicated - branch is to be selected as the revision to use for the operation. + Servers MUST fail this operation if a branch is required. - 2.6.3. Checkin + 3.2. Checkin When the client has completed changes to a resource and wishes it to become part of the revision history, the client must check in - the resource. This is performed using the UNLOCK method against - the versioned resource with special body tags and identification of - the checkout lock in the header. + the resource. This is performed using the CHECKIN method against + the working copy. + + The DAV:keepcheckedout tag can be specified to indicate that the + resource should remain checked out. That is, create a new + revision, but leave the working copy checked out. + + Using XML tags in the request body, clients can specify optional + checkin information. >>Request - UNLOCK /foo/bar.htm HTTP/1.1 + CHECKIN /tmp/VRJHJWE3493409 HTTP/1.1 Host: www.foobar.com Lock-Token: Content-Type: text/xml Content-Length: xxx + - + checkin comment - + >>Response - HTTP/1.1 204 CREATED + HTTP/1.1 201 CREATED Revision-Id: VER:FREFRI49349 Content-Length: 0 The reply MUST include the Revision-Id of the newly created revision. - 2.6.4. Undo Checkout + It is possible that the check-in operation will detect a conflict. + Servers MUST fail this operation if a branch is required. The + Override-Checkin header is used to resolve these conflicts. - If a client chooses to cancel a checkout request, the UNLOCK method - is used with optional body tags and identification of the checkout - lock. + 3.3. Cancelling Checkout + + If a client chooses to cancel a checkout request, the UNCHECKOUT + method against the working copy. As well, optional XML body tags + can be used to supply additional information. >>Request - UNLOCK /foo/bar.htm HTTP/1.1 + UNCHECKOUT /tmp/VRJHJWE3493409 HTTP/1.1 Host: www.foobar.com Lock-Token: Content-Type: text/xml Content-Length: xxxxx - - - + cancel checkout comment - + >>Response HTTP/1.1 200 OK Content-Length: 0 - 2.6.5. Enumeration - - Clients can enumerate the current checkouts to a resource using the - PROPFIND method and standard lock discovery. All attributes - specified in the lock request (e.g. DAV:comment) MUST be returned - in lock discovery. - - 2.7. Default Revision + 3.4. Enumeration - If a Revision-Id (or Branch-Id) header is not specified when - referring to a resource, then the tip (latest) revision (from the - primary branch) is used, unless a default revision has been - identified. To mark a specified revision as the default revision, - clients use the PIN method. Note that PUT or checkin will create - new revisions which will be returned unless a PIN is defined. When - a revision is PINned, new revisions can be created with PUT or - checkin, but they will not be returned unless they are referenced - explicitly. + Refer to the Resource Reports section for details on check-out + enumeration. - Note that branching a resource has no effect on the default - revision of the resource, even if the default revision is branched. - If unpinned, the default revision is the tip revision of the - initial (primary) branch of the versioned resource. + 4. BRANCHING RESOURCES - >>Request + For more sophisticated clients, basic resource branching is + required. Resource branching means that for a given resource, the + history is not linear. That is, there are different lines of + descent. The diagram below illustrates this. - PIN /foo/bar.htm HTTP/1.1 - Host: www.foobar.com - Content-Type: text/xml - Content-Length: xxx + Revision history V1 -> V2 -> V3 + Of foo.htm: | + +-> V1.1 -> V1.2 + | + +-> V1.1.1 - - VER:HT58GHDW49 + Individual resource branching is common in many versioning systems + today. Project branching (configurations) are described in a later + section. Note that when a collection is branched, the depth of the + branch is infinity. There is no way to change this. - >>Response + A revision is branched using the BRANCH method. The resource to be + branched is specified as the target URI for the method. - HTTP/1.1 200 OK - Content-Length: 0 + As well, clients can specify a branch label to identify a created + branch using the DAV:branchlabel tag. The reply MUST include a + Branch-Id header specifying a resource defined branch id or the + specified branch label if a branch is created. The label or id can + be specified in a Branch-Id or Revision-Id header to determine the + revision to access. >>Request - PIN /foo/bar.htm HTTP/1.1 + BRANCH VER:FHHR4959 HTTP/1.1 Host: www.foobar.com - Content-Type: text/xml - Content-Length: xxx + Content-Type: text/html + Content-Length: xxxx - - - >>Response - - HTTP/1.1 200 OK - Content-Length: 0 - - It should be noted that setting a default revision may impact - automatic versioning. If a client performs a PUT operation that is - automatically versioned, it MUST fail if a GET will not return the - new version (possibly because of a PIN). - - 2.8. Sharing - - Many versioning systems today provide the ability to have a given - resource visible in multiple parts of the namespace. In these - situations, a resource is shared. That is, changes to the resource - are visible to all versions. - - The WebDAV advanced collections adds support for referential - members, however, this is not sufficient for sharing in a - versioning environment because of the requirement to establish - default revisions. Indirect references cannot map to specific - versions for down-level (e.g. HTTP/1.1) clients and direct - references map directly to the shared resource. - - This specification introduces a new type of referential member, - semi-direct. A semi-direct reference is like a direct reference - except that it can have attributes of its own or it can map - directly to the shared resource. By default, when a semi-direct - reference is used in a request, it behaves like a direct reference. - However, if the Pass-Through header is specified on the request - with a value of "*", then the operation is performed against the - semi-direct reference not the object it points to. This is an - extension of the WebDAV advanced collection specification in value - and because the header can be specified with any request against a - semi-direct reference. - - In the example below, a semi-direct reference is created. - - >>Request - - MKREF /bing/bar.htm HTTP/1.1 - Host: www.foobar.com - Ref-Target: /foo/bar.htm - Ref-Integrity: DAV:semidirect - Content-Length: 0 + + MyBranch + branch comment + >>Response HTTP/1.1 201 CREATED - ... - - In the example below, a request is made to a semi-direct reference. - The object that the reference refers to is returned. - - >>Request - - GET /bing/bar.htm HTTP/1.1 - Host: www.foobar.com - Content-Length: 0 - - In the example below, the semi-direct reference is PINned to a - specific revision. - - >>Request - - PIN /foo/bar.htm HTTP/1.1 - Host: www.foobar.com - Pass-Through: * - Content-Type: text/xml - Content-Length: xxx - - - VER:HT58GHDW49 - - 2.9. Collection Versioning - - Collections can be versioned just like non-collection resources, - however, there are special situations that must be taken into - account. Collections are versioned in the following ways: - - - DonÆt version the collection regardless of the changes. - - - Version the collection only if there is a direct change to the - resource. - - - Version the collection if there is a change anywhere under the - collection (i.e., bubble of the changes). - - Each collection resource MAY choose the behavior it supports. The - behavior is specified through properties, which resources MAY - choose to make read-only. - - The DAV:autoversion property indicates if a collection resource - supports versioning when changes are made to it. The - DAV:autocollectionversion property indicates if the collection - resource supports versioning when changes are made anywhere in the - namespace below it. - - 2.9.1. Default Revisions - - It is up to each collection resource to determine if it supports - default versions. If it doesnÆt, then PIN requests MUST fail. If - a collection resource doesnÆt support versioning, then is MUST also - fail PIN requests. - - 2.9.2. Headers - - If collections are versioned, then clients may choose to access - resources that are part of specific revisions. The Revision-Path - header is used to identify specific revisions that are part of the - "path" to the resource. This header servers as an alternative to - "URL munging". This header can be specified on all methods and - qualifies the resource named in the method. - - The BNF for this header is as follows. - - Revision-Path := "Revision-Path" ":" Path - Path := PItem | (Path PItem) - PItem := "/" ANY Rev - Rev := | (";" RID) - RID := "*" | ANY | "(" ANY ")" - - >>Request - - GET /foo/bar.htm HTTP/1.1 - Host: www.foobar.com - Revision-Path: /foo;VER:HT58GHDW49/bar.htm;VER:HT58GHDW49 + Branch-Id: MyBranch + Revision-Id: VER:REUU48583 Content-Length: 0 - The use of * for a revision is only permitted with PROPFIND to - obtain properties across all revisions of a versioned resource. - - 2.9.3. Properties - - DAV:autocollectionversion - This propertyÆs value (0/1) specifies - if a collection is automatically versioned when its contents - (anywhere under it) change. That is, if /foo/bar.htm is versioned, - is /foo/ versioned as well. Resources MAY implement this as a - read-only property. - - DAV:canautocollectionversion - This propertyÆs value (0/1) - specifies if the resource supports the ability to automatically - version collections when a contained resource changes. This is a - read-only property. + When a branch is created, the reply MUST include a Branch-Id + header. - 2.10. Resource Reports + 5. RESOURCE REPORTS Revision history graphs and other reports of a resource are - accessed via PROPFIND. Note that resources MAY support multiple - styles of history and reports. To enumerate the supported history - graphs and reports, clients use PROPFIND and the - property. The results indicate the different reports which can, - themselves, be requested via PROPFIND. + accessed via PROPFIND. - Note that clients can request properties to be included in reports - by specifying the desired properties inside the DAV:enumreport tag. + Note that resources MAY support multiple styles of history and + reports. To enumerate the supported history graphs and reports, + clients use PROPFIND and the property. The + results indicate a list of the different reports which can, + themselves, be requested via PROPFIND. For the examples in this section, assume that the resource /foo.htm has the following revision graph: Revision history V1 -> V2 -> V3 Of foo.htm: | +-> V1.1 -> V1.2 | +-> V1.1.1 @@ -915,1251 +967,1318 @@ - V2: Test1 - V1.1: Test2, Good - V1.2: Tested Additionally, when the V1.1 branch was created, it was labeled "MyBranch". - 2.10.1. Example + 5.1. Available Reports + + Clients can obtain the available reports for a resource by + obtaining its DAV:availablereports property. >>Request + PROPFIND /foo/bar.htm HTTP/1.1 Host: www.foobar.com + Depth: 0 Content-Type: text/xml Content-Length: xxxx - + + + >>Response ... - + + + http:/www.foobar.com/foo/bar.htm + - - DAV:defaulthistory - DAV:directlineage - DAV:fulllineage - + + DAV:defaulthistory + DAV:directlineage + DAV:fulllineage + - + + HTTP/1.1 200 OK + + ... Note that the report styles MUST be specified as DAV:href values. - 2.10.2. Default History + When clients issue PROPFIND requests to obtain reports, they may + include other properties in the request. These properties are + returned for each report item. + + 5.2. Default History Resources MUST support the DAV:defaulthistory report. This enumerates the historical record of revisions that have been - visible as the default revision of the versioned resource. + visible as the default revision. Clients can specify the limit parameter to limit the number revisions returned. By definition, revisions are returned in reverse chronological order starting with the most recent. >>Request PROPFIND /foo/bar.htm HTTP/1.1 Host: www.foobar.com + Depth: 0 Content-Type: text/xml Content-Length: xxxx - + >>Response ... - + + + http://www.foobar.com/foo/bar.htm + - - - Update it - - - Update it - Test1 - - - Update it - - - Update it - - + V3 + Update it + + HTTP/1.1 200 OK + + + http://www.foobar.com/foo/bar.htm + + + V1 + Update it + + + HTTP/1.1 200 OK + + + http://www.foobar.com/foo/bar.htm + + + V2 + Update it + + + HTTP/1.1 200 OK + + + http://www.foobar.com/foo/bar.htm + + + V1 + Update it + + + HTTP/1.1 200 OK + + + + 5.3. Active Checkouts + + Clients can obtain a list of the active checkouts against a + resource using PROPFIND and DAV:activecheckouts. + + >>Request + + PROPFIND /foo/bar.htm HTTP/1.1 + Host: www.foobar.com + Revision-Id: VER:FHRJ494059 + Depth: 0 + Content-Type: text/xml + Content-Length: xxxxx + + + + - 2.10.3. Direct Lineage + >>Response - Resources MUST support the DAV:directlineage report. This - enumerates the direct parent revisions of the versioned resource. - This report is from the default revision or the specified revision. + HTTP/1.1 207 Multi-Status + Content-Type: text/xml + Content-Length: xxx + + + + + http://www.foobar.com/foo/bar.htm + + + + user-specified + VER:FHER4949 + http://www.foobar.com/foo/bar.htm + + http://www.foobar.com/tmp/FHFH34949 + + + + + HTTP/1.1 200 OK + + + + 5.4. Direct Lineage + + Resources SHOULD support the DAV:directlineage report. This + enumerates the direct parent revisions of the resource. Clients can request that a report be based on the namespace entry specified, or the associated DAV:vresourceid. Clients use the scope parameter to specify (name or id). + Clients can specify the limit parameter to limit the number + revisions returned. + >>Request PROPFIND /foo/bar.htm HTTP/1.1 Host: www.foobar.com - Revision-Id: V3 + Depth: 0 Content-Type: text/xml Content-Length: xxxx - + >>Response ... - + + + http://www.foobar.com/foo/bar.htm + - - - Update it - - Update it - Test1 - - Update it - - - - - - + V1 + VER:FFHJE + Update it - + + HTTP/1.1 200 OK + + + http://www.foobar.com/foo/bar.htm + + + V2 + VER:FFHJE + Update it + V1 + + + HTTP/1.1 200 OK + + + http://www.foobar.com/foo/bar.htm + + + V3 + VER:FFHJE + Update it + V3 + Test1 + V2 + V1.2 + + + HTTP/1.1 200 OK + + - 2.10.4. Full Lineage + 5.5. Full Lineage - Resources MUST support the DAV:fulllineage report. This enumerates - the full graph of revisions for this resource. + Resources SHOULD support the DAV:fulllineage report. This + enumerates the full graph of revisions for this resource. Clients can request that a report be based on the namespace entry specified, or the associated DAV:vresourceid. Clients use the scope parameter to specify (name or id). + Clients can specify the limit parameter to limit the number + revisions returned. + >>Request PROPFIND /foo/bar.htm HTTP/1.1 Host: www.foobar.com - Revision-Id: VER:FHJRH3994 + Depth: 0 Content-Type: text/xml Content-Length: xxxx - + >>Response ... - + + + + http://www.foobar.com/foo/bar.htm + - - - Update it - - Update it - Test1 - - Update it - - - - - Test2, Good - Update it - - Tested - Update it - - - - - Update it - - - - - + V1 + VER:FFHJE + Update it - + + HTTP/1.1 200 OK + + + http://www.foobar.com/foo/bar.htm + + + V2 + VER:FFHJE + Update it + V1 + + + HTTP/1.1 200 OK + + + http://www.foobar.com/foo/bar.htm + + + V3 + VER:FFHJE + Update it + V2 + Test1 + V2 + V1.2 + + + HTTP/1.1 200 OK + + + http://www.foobar.com/foo/bar.htm + + + V1.1 + VER:FFHJE + Update it + V1 + Test2 + + + HTTP/1.1 200 OK + + + http://www.foobar.com/foo/bar.htm + + + V1.2 + VER:FFHJE + Update it + V1.1 + MyBranch + + + HTTP/1.1 200 OK + + + http://www.foobar.com/foo/bar.htm + + + V1.1.1 + VER:FFHJE + Update it + V1.1 + + + HTTP/1.1 200 OK + + - 3. CONFIGURATIONS + 6. CONFIGURATION BASICS Many clients require more sophisticated management and organization of their versioned data. For this reason, configuration support is defined as part of this specification. Configuration management is a large space. This specification addresses several types of configurations: - - Label: A label configuration is a collection of specific - revisions of selected versioned resources. Changes to the - versioned resources do not effect the contents of the label - configuration. - - - Floating Label: A floating label configuration is a collection of - the default revisions of selected versioned resources. When the - default revision of a selected resource changes, the contents of - the floating label configuration is updated automatically. Note - that when a versioned resource is added to a floating level - configuration, the Branch-Id header can be specified. In this - case, the floating label will contain the tip revision the - specified branch. + - Dynamic: A dynamic configuration is a collection of specific + revisions of selected versioned resources based on selection + rules. This can be used for labels, floating labels, etc. - - Workspace: A workspace configuration is a collection of multiple - revisions of selected versioned resources. As the selected - versioned resources are changed, in the context of the workspace - configuration, the workspace tracks the version history. + - Workspace: A workspace configuration is a mechanism for tracking + and managing parallel changes to multiple resources. Configurations provide a mechanism for organizing resources and quick access to specific revisions of resources. Clients can access resources in the context of a configuration. By referencing a configuration, requests are automatically mapped to the correct - revision of the versioned resource. - - Note that servers provide a default workspace configuration. This - is were all resources exist. Clients can request other workspace - configurations to be created and have operations performed within - their context if workspace configurations are supported. + revision of the versioned resource. This allows configurations to + be used as a reference mechanism without breaking URL hyperlinks. A configuration can be derived from another configuration. That is, the new configuration is based on the versions in the "parent" configuration. Optionally, derived configurations can automatically inherit new versions in the parent configuration (assuming there are no conflicts). However, a configuration can be derived from at most one other configuration. Clients can specify configuration ids wherever a revision id can be specified. This requests that the default revision for the specified configuration be used. Requests that include both a revision id and a configuration id MUST fail if the specified - revision is not part of the specified configuration. + revision is not part of the specified configuration. Typically + both a revision id and a configuration id are not needed since the + revision URI is unique across all configurations. - 3.1. Discovery + 6.1. Discovery Configuration support is optional. This example shows that the /somefolder resource supports configurations. >> Request OPTIONS /somefolder/ HTTP/1.1 - Verify-Extension: DAV:versioning - Host: foobar.com - Content-Length: 0 + Host: www.foobar.com + Content-Length: xxx + Content-Type: text/xml + + + + + >> 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, PIN, MKREF + MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, FREEZE, THAW, + CHECKIN, + CHECKOUT, UNCHECKOUT, BRANCH Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, - MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF - Verify-Extension: DAV:versioning - Versioning-Support: DAV:basicversioning, DAV:configurations - Configuration-Types: DAV:Label, DAV:Floating, DAV:Workspace - Configuration-Root: /cfgs/ - Content-Length: 0 - - The Configuration-Types header in the OPTIONS reply indicates the - types of configurations supported. Presence of this header - indicates support for configurations. The BNF for this header is: - - Configuration-Types := "Configuration-Types" ":" Ctypes - CTypes := CType | (CTypes "," CType) - CType := "Label" | "Floating" | "Workspace" | - URI - - The Configuration-Root header in the OPTIONS reply indicates the - root of the configuration namespace. Note that there could be - multiple configuration roots. The BNF for this headers is: - - Configuration-Root := "Configuration-Root" ":" URI-List + MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, FREEZE, THAW, + CHECKIN, + CHECKOUT, UNCHECKOUT, BRANCH + Versioning: DAV:basicversioning + Content-Type: text/xml + Content-Length: xxx - 3.2. Creating Configurations + + + + + http://www.foobar.com/cfgs/ + + + + 6.2. Creating Configurations Servers maintain configurations in a private portion of the namespace. The root of this namespace is determined by examining - the OPTIONS reply. All configurations names MUST be unique on a - server. Using the configuration namespace, clients can create and - manage configurations. + the OPTIONS extended reply. All configurations names MUST be + unique on a server. Using the configuration namespace, clients can + create and manage configurations. - Clients create new configurations by issuing the MKCOL method + Clients create new configurations by issuing the MKCONFIG method against the configuration namespace. This requests the server to create a new configuration. When a configuration is created, special tags can be used to define the characteristics and relationships (e.g. derivations) for the configuration. The following table enumerates these tags. Tag Description This tag defines the type - xxx of configuration: - DAV:Label, DAV:Floating, - or DAV:Workspace. + of configuration: + xxx DAV:Dynamic or + DAV:Workspace. This tag allows the client - xxx to specify a URI to + "xxx" to specify a URI to identify another configuration from which this new configuration is to be derived. The configuration - DAV:Auto automatically inherits - changes from its derived- - from configuration. + automatically inherits + DAV:Auto changes from its derived- + from configuration. Conflicts are recorded in resolution queues (see later section). The configuration inherits - DAV:Manual changes from its derived- - from configuration, but - they are not automatically + changes from its derived- + DAV:Manual from configuration, but + they are not automatically inserted into the configuration. Instead they are recorded in resolution queues (see + Tag Description + later section). - The configuration is a - DAV:None snapshot of the current - versions in the derived- - from configuration. There + + snapshot of the current + DAV:None versions in the derived- + DAV:inheritancetype> from configuration. There + The configuration is a is no inheritance of changes. This is the default type if no type is specified. "xxx" The configuration is based on the current versions in the derived-from configuration at the indicated time. Note that use of this tag is incompatible with DAV:Auto inheritance types and usage in this way MUST return an error. When a non-derived configuration is created, it contains no resources. Configurations that are derived from another configuration include the resources in the derived from - configuration. + configuration at the specified time or using the default revisions. The example below illustrates creating a new configuration that is derived from, and auto-inherits another configuration. For this example, the root of the configuration namespace has been determined to be /cfgs. >>Request - MKCOL /cfgs/ HTTP/1.1 + MKCONFIG /cfgs/ HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx DAV:Workspace - http://www.foobar.com/cfgs/DDEJRJ445 - + + http://www.foobar.com/cfgs/DDEJRJ445 Auto >>Response HTTP/1.1 201 Created Location: http://www.foobar.com/cfgs/RYURUS99009 Content-Length: 0 - 3.3. Configuration Properties - - The standard PROPFIND and PROPPATCH methods can be used on the - configuration resource to get and set properties on a - configuration. Configurations MUST provide configuration - properties if configurations are supported. The following list - identifies pre-defined properties that MUST be supported: - - DAV:configurationtype - The type of the configuration. - Configurations can choose to make this a read-only property. - - DAV:derivedfrom - The configuration from which the configuration is - derived. Configurations can choose to make this a read-only - property. - - DAV:inheritancetype - The type of inheritance for the - configuration. Configurations can choose to make this a read-only - property. - - DAV:basetime - The base time used to create the configuration. - Configurations can choose to make this a read-only property. - - DAV:configurationame - A user-defined display name for the - configuration. - - DAV:defaultconfiguration - This property on the configuration root - identifies the default workspace configuration to use if one is not - specified. - - 3.4. Headers - - To support configurations, two new headers are introduced that can - be used with a variety of the DAV and HTTP methods. The following - list identifies these headers: - - Configuration-Id - This header is used to identify the - configuration that is to be used when performing an operation. - - For workspace configurations, this can be specified to set default - revisions per-configuration, enumeration of checkouts/checkins - against a specific configuration, or to establish locks specific to - a configuration. - - If a configuration is not specified, the default workspace - configuration is used. All servers have a default workspace where - resources reside. The configuration "*" can be specified with - PROPFIND to locate properties irrespective of configuration. - - Configuration-Id := "Configuration-Id" ":" (URL | "*") - - Note that the configuration id can be used in place of a revision - id. In this case, the revision selected is the default revision of - the versioned resource within the specified configuration. - - Target-Configuration - This header is used to specify a target - configuration when dealing with cross-configuration operations. - For example, resources can be copied from one configuration to - another using the Configuration-Id and Target-Configuration headers - with the COPY method. - - Target-Configuration := "Target-Configuration" ":" URL - - 3.5. Deleting Configurations - - To delete a configuration, use the location returned from the - configuration creation. Note that configurations SHOULD NOT allow - delete if other configurations are derived from them. - - >>Request - - DELETE /cfgs/RYURUS99009 HTTP/1.1 - Host: www.foobar.com - Content-Length: 0 - - 3.6. Managing Configuration Content - - Clients need to be able to access and manage the contents of a - configuration. This is done using the GET, COPY, and DELETE - methods. - - 3.6.1. Access Using Configurations + 6.3. Access Using Configurations Configurations are maintained as a special collection. Configurations maintain referential members to all revisions that are part of the configuration. Consequently, one approach to enumerating the contents of a configuration is to use PROPFIND to discover the contents of the collection. Alternatively, clients can request a specific resource from a configuration. This approach allows clients to use the URL they are familiar with. If a client requests a resource that is not part of a configuration, then an error is returned. >>Request GET /foo/bar.htm HTTP/1.1 Host: www.foobar.com Configuration-Id: /cfgs/DFEE2034 - Version-Id: VER:JKGRKJ9094 Content-Length: 0 - 3.6.2. Adding Resources to a Configuration + 6.4. Deleting Configurations - Resources are added to a configuration using the COPY method. A - special body tag is used to indicate that the resource is being - added to the configuration. + To delete a configuration, use the location returned from the + configuration creation. Note that configurations SHOULD NOT allow + delete if other configurations are derived from them. >>Request - COPY /foo/bar.htm HTTP/1.1 - Host: www.foobar.com - Depth: infinity - Configuration-Id: /cfgs/DFEE2034 - Target-Configuration: /cfgs/ERRJ3440 - Content-Type: text/xml - Content-Length: xxxx - - - - - If a specific revision is not specified, then the default revision - is copied. - - Note that clients can also create referential members within the - configuration collection to add them to the collection. - - 3.6.3. Removing Resources from a Configuration - - Resources are removed from a configuration using the DELETE. The - target URI indicates the resource to delete and the Configuration- - Id header to identify the configuration. The Depth header can be - used to remove collection contents. A special tag is used to - indicate that the resource is being removed from the configuration - (not deleted). - - >>Request - DELETE /foo/bar.htm HTTP/1.1 + DELETE /cfgs/RYURUS99009 HTTP/1.1 Host: www.foobar.com - Depth: infinity - Configuration-Id: /cfgs/DFEE2034 - Content-Type: text/xml - Content-Length: xxxx - - - - - Note that clients can also delete referential members within the - configuration collection to remove them from the collection. + Content-Length: 0 - 3.7. Workspace Configurations + 6.5. Resolution Queues - Workspace configurations provide the ability to track multiple - revisions of a resource independent of the resource in other - workspace configurations. This section describes aspects of the - protocol specific to workspace configurations. + There are times when an operation cannot be blocked that will + result in a state that requires user action. For example, when + configurations inherit, there is the potential for conflicts. + Resolution queues provide a mechanism for discovering these + conditions. - 3.7.1. Default Workspace Configurations + Configurations track and maintain a list of issues that need to be + resolved as a result of actions. These lists are referred to as + resolution queues. Clients can request the resolution issues and + react accordingly. The configuration will continue to report the + condition until it is resolved. - Clients can establish a default workspace configuration that is to - be used, for all clients, if they do not specify a workspace - configuration. To do this, clients set a property on the - configuration namespace root collection identifying the default - workspace configuration. + The resolution queue is obtained by obtaining the + DAV:resolutionqueue property from the configuration. This property + contains all of the identified issues. >>Request - PROPPATCH /cfgs/ HTTP/1.1 + PROPFIND /cfgs/FDJE4949 HTTP/1.1 Host: www.foobar.com Content-Type: text/xml - Content-Length: xxxx + Content-Length: xxxxx - - + - /cfgs/RYURUS99009 - + - - - - 3.7.2. Synchronizing Worksapce Configurations - - In some scenarios, clients are working on separate workspace - configurations to keep themselves isolated from other team members. - However, they occasionally need to synchronize their workspace - configuration with the derived-from workspace configuration so that - they donÆt get too far out of synchronization. As well, changes - (or entire configurations) can be copied from one workspace - configuration to another. Both operations are performed using the - COPY method and special body tags. - - Clients can request that specific resources are copied by including - the resource tag. If no resources are specified, then all - resources are copied. Note that configurations MAY fail requests - that do not fully synchronize. - - The example below shows the synchronization of one configuration - against another. All resources are synchronized. + - >>Request + >>Response - COPY /cfgs/DHFHR99392 HTTP/1.1 - Host: www.foobar.com - Destination: http://www.foobar.com/cfgs/RRURU329049 + HTTP/1.1 207 Multi-Status Content-Type: text/xml Content-Length: xxx - + + + http://www.foobar.com/cfgs/FDJE4949 + + + + + + http:/foo/bar.htm + DAV:FDFEE55544 + + + + + + - The example below shows the synchronization of one configuration - against another. The specified resources are synchronized to the - indicated time. + Once a client has resolved an issue it will automatically be + removed from the resolution queue. - >>Request + 6.6. Configuration Properties - COPY /cfgs/DHFHR99392 HTTP/1.1 - Host: www.foobar.com - Destination: http://www.foobar.com/cfgs/RRURU329049 - Content-Type: text/xml - Content-Length: xxx + The standard PROPFIND and PROPPATCH methods can be used on the + configuration resource to get and set properties on a + configuration. Configurations MUST provide configuration + properties if configurations are supported. The following list + identifies pre-defined properties that MUST be supported: - - - /foo/bar.htm - /bing/bop.htm - ... - + DAV:configurationtype - The type of the configuration. + Configurations can choose to make this a read-only property. - A synchronization request could result in conflicts. By default, - if conflicts exist, the synchronization fails and the conflicts are - returned (as shown below). To override, clients should include the - tag. This tag indicates that the synchronization - should do as much as possible and return any conflicts. + DAV:derivedfrom - The configuration from which the configuration is + derived. Configurations can choose to make this a read-only + property. - >>Response + DAV:inheritancetype - The type of inheritance for the + configuration. Configurations can choose to make this a read-only + property. - TBD - show failure response - ... - - - http://www.foobar.com/foo/bar.htm - - VER:DJHFH443 - VER:DJHFH443 - VER:FDFEE55544 - - - ... - - ... + DAV:basetime - The base time used to create the configuration. + Configurations can choose to make this a read-only property. - The sample response above shows that each conflict includes an ID - and a reference to the resource in conflict. A configuration MAY - choose to restrict operations until conflicts have been resolved. - To inform the configuration that a conflict has been resolved, - clients should include a Conflict-ID header on PUT, PROPPATCH, etc. - methods specifying the ID returned in the synchronization response. + DAV:defaultconfiguration - This property on the configuration root + identifies the default workspace configuration to use if one is not + specified. - Conflict-ID := "Conflict-ID" ":" URI + DAV:resolutionqueue - A list of identified issues that require + client attention. - It is permitted for servers to refuse (fail) synchronization - requests that do not originate at the root. That is, arbitrary - resources. + 6.7. Headers - 3.7.3. Condensing Workspace Configurations + To support configurations, two new headers are introduced that can + be used with a variety of the DAV and HTTP methods. The following + list identifies these headers: - Condensing a configuration means reducing the number of revisions - in a configuration. That is, collapse the changes into a single - revision. This is performed by extending the DELETE method. In - the example below, all but the latest three versions are condensed - into a single revision. + Configuration-Id - This header is used to identify the + configuration that is to be used when performing an operation. - >>Request + For workspace configurations, this can be specified to set default + revisions per-configuration, enumeration of checkouts/checkins + against a specific configuration, or to establish locks specific to + a configuration. - DELETE /cfgs/BHFR59593 HTTP/1.1 - Host: www.foobar.com - Content-Type: text/xml - Content-Length: xxxx + If a configuration is not specified, the default workspace + configuration is used. All servers have a default workspace where + resources reside. The configuration "*" can be specified with + PROPFIND to locate properties irrespective of configuration. - - - /foo/bar.htm3 - + Configuration-Id := "Configuration-Id" ":" (URL | "*") - Note that the DAV:maxrevisions property can be used to set the - maximum number of revisions that are maintained for a versioned - resource. + Note that the configuration id can be used in place of a revision + id. In this case, the revision selected is the default revision of + the versioned resource within the specified configuration. - If the DAV:revisionid header is specified, the condensing starts - with the specified revision. This means that if a versioned - resource has 10 revisions, revisions 3-6 can be condensed. + Target-Configuration - This header is used to specify a target + configuration when dealing with cross-configuration operations. + For example, resources can be copied from one configuration to + another using the Configuration-Id and Target-Configuration headers + with the COPY method. Note that resources CANNOT be MOVEd from one + configuration to another. - Servers MUST fail this request if there are dependencies on - revisions that will be eliminated. + Target-Configuration := "Target-Configuration" ":" URL - 3.8. Configuration Reports + 7. CONFIGURATION REPORTS Revision history and configuration dependency graphs are accessed via PROPFIND. Note that configurations MAY support multiple styles of history and dependency. To enumerate the supported history - graphs, clients use PROPFIND and the property. - The results indicate the different graphs and reports which can, - themselves, be requested via PROPFIND. + graphs, clients use PROPFIND and the + property. The results indicate the different graphs and reports, + which can, themselves, be requested via PROPFIND. >>Request PROPFIND /cfgs/FHJRH3994 HTTP/1.1 Host: www.foobar.com + Depth: 0 Content-Type: text/xml Content-Length: xxxx + + >>Response ... - + + + http://www.foobar.com/cfgs/FHJRH3994 + - DAV:configurationderivation - - DAV:configurationmerge + DAV:configurationderivation + DAV:configurationmerge - + + HTTP/1.1 200 OK + + ... - Note that the report styles MUST be specified as DAV:href values. + When clients issue PROPFIND requests to obtain reports, they may + include other properties in the request. These properties are + returned for each report item. - 3.8.1. Configuration Derivation + 7.1. Configuration Derivation Configurations MUST support the DAV:configurationderivation report. This enumerates the full derivation of a configuraiton. Note that the limit parameter can be specified to limit the number of items returned. By definition the order of the configurations is immediate predecessor. >>Request PROPFIND /cfgs/BHFR59593 HTTP/1.1 Host: www.foobar.com + Depth: 0 Content-Type: text/xml Content-Length: xxxx - + >>Response ... - - - - - - - - + + + http:/www.foobar.com/cfgs/234 + HTTP/1.1 200 OK + + + http:/www.foobar.com/cfgs/345 + HTTP/1.1 200 OK + + ... - 3.8.2. Configuration Merge Graph + 7.2. Configuration Merge Graph Configurations SHOULD support the DAV:configurationmerge report. This enumerates the derivation of a configuration including merges from one configuration to another. >>Request PROPFIND /cfgs/BHFR59593 HTTP/1.1 Host: www.foobar.com + Depth: 0 Content-Type: text/xml Content-Length: xxxx - + >>Response ... - + + + + http:/www.foobar.com/cfgs/234 + HTTP/1.1 200 OK + + + http:/www.foobar.com/cfgs/3FF + HTTP/1.1 200 OK + + + ... + + 8. DYNAMIC CONFIGURATIONS + + Dynamic configurations provide a mechanism to identify all + revisions that match specific criteria. For example, "all + revisions that have the label Beta1". The dynamic configuration is + a view onto the resources and is updated automatically as resources + and revisions are created, deleted, and modified. + + All dynamic configurations support the DAV:rsrtypes property. This + identifies the different styles of dynamic configurations to be + supported. This specification defines a single common type, + DAV:basicrsr. + + >>Request + + PROPFIND /cfgs/FHHE49495 HTTP/1.1 + Host: www.foobar.com + Content-Type: text/xml + Content-Length: xxxxx + + + - - - - - - - - - - + + + >>Response + + HTTP/1.1 207 Multi-Status + Content-Type: text/xml + Content-Length: xxx + + + + + http://www.foobar.com/cfgs/FHHE49495 + + + + + + + + + + + Clients establish a selection criteria by setting the + DAV:selectionrule property. Once set, the dynamic configuration + collection contains references to the matching resources. + + >>Request + + PROPPATCH /cfgs/FHHE49495 HTTP/1.1 + Host: www.foobar.com + Content-Type: text/xml + Content-Length: xxxxx + + + + + + + ... + + + + + - 3.9. Resolution Queues + The DAV:basicrsr tag groups the selection criteria that are used to + populate the dynamic configuration. The selection criteria is + specified as a set of tags where nesting represents the + expressional ordering. The following tags are available: - When configurations inherit, there is the potential for conflicts. - Configurations have the option to help clients manage these - conflicts. However, if they do not, then configurations MUST - return an error if the operation would result in a conflict. + - DAV:and - The included tags MUST all be true to select - Configurations that help resolve conflicts track and maintain lists - of issues that need to be resolved as a result of actions. These - lists are referred to as resolution queues. Clients can request - the resolution issues and react accordingly. Note that the - configuration only manages the list. That is, the client is - responsible for resolving the issue (or deciding not to) and then - removing the resolution item. + - DAV:or - Any of the included tags MUST be true to select - 3.9.1. Discovery + - DAV:not - The include tag should be inverted (logically) - Resolution queue support is optional for configurations. Support - for resolution queues is determined by examining the - DAV:resolutionqueue property on a configuration. If this property - is not blank, then the configuration supports a resolution queue at - the specified URL. If this property is blank, then it doesnÆt - support resolution queues. + - DAV:href - The resource URL MUST be the included URL - 3.9.2. Obtaining Resolutions + - DAV:label - A revision MUST have the specified label - Conflicts can arise against any resource, however, they are always - associated with a configuration. Pending resolutions items are - obtained by examining the resolution queue for a configuration. - The resolution queue is actually a configuration-specific - collection in the DAV namespace. The collection resource - identifying the resolution queue for a configuration is obtained - via the DAV:resolutionqueue property on the configuration. To - enumerate the pending resolutions, clients use PROPFIND to obtain - the resources within the collection. + - DAV:tip - The "tip" revision is selected - Each resource within the collection represents a separate - resolution queue item and are named such that a standard ANSI sort - on the resource name will ensure correct temporal ordering. + - DAV:revisionid - The specified revision is selected - 3.9.3. Processing Resolution Items + - DAV:configurationid - The configuration MUST be the specified + value - Clients can GET the contents of a resolution item. This is an XML - document that describes the action that caused the resolution item - to be created. For example: + - DAV:branchid - The branch MUST be the specified value + + - DAV:depth - Used with DAV:href to indicate a recursive match + TBD - provide full DTD + + The following example illustrates a selection rule that includes + all revisions in the /Foo/Bar folder (and below) that have been + labeled as "Beta1". - - http://foobar.com/reso/ZZZZ3493 - http:/foo/bar.htm - DAV:FDFEE55544 - + + - Once a client has resolved an issue (or decided to ignore it), the - client is responsible for canceling the resolution item. This is - done using the DELETE method on the resolution item. + http:/www.foobar.com/Foo/Bar/infinity< + /D:href> + Beta1 + + - >>Request - DELETE http://foobar.com/reso/ZZZZ3493 HTTP/1.1 - Host: www.foobar.com - Content-Type: text/xml - Content-Length: 0 + 9. WORKSPACE CONFIGURATIONS - 3.10. Checkin Sets + Branching provides a mechanism for parallel changes to a resource. + A workspace configuration is a mechanism for parallel changes of + multiple resources. - Clients may desire the ability to track a set of changes as a unit. - That is, create a grouping of related changes. This is achieved - using the MKCOL method to create a special collection. Clients - refer to the checkin set on all checkin (or change) requests. The - server automatically creates a "share" to the newly created - revision in the identified collection. + For example, /MySite/ might contain all of the Web pages for V1 of + my companies e-commerce site. These have been put in the V1 + workspace. A team responsible for developing V2 of the site would + create a new workspace configuration based on V1. The V2 workspace + is populated with the V1 versions, but these resources can be + versioned independently. Essentially all resources have been + "branched" in a coordinated fashion. Since this is a branch, both + the V1 and the V2 revisions refer to the same versioned resource. + This allows history and reports to be generated across workspaces. - 3.10.1. Discovery + 9.1. Managing Configuration Content - Servers may choose to restrict where checkin sets can be created in - the namespace. Clients can discover this using OPTIONS. The - Checkin-Sets-Root header identifies valid portions in the - namespace. Each header (there can be multiple specified) identify - a root and a depth. The BNF for this header is: + Clients need to be able to access and manage the contents of a + configuration. This is done using several different DAV methods. - Checkin-Sets-Root:= "Checkin-Sets-Root" ":" URL "," Depth - Depth := "inifinity" | number + The COPY method can be used to copy a specific revision of a + resource. However, this results in a new versioned resource being + created. - Note that if a resourceÆs parent in the namespace has a defined - checkin set root, the resource CANNOT define a separate root for - itself. + Resources are added to and removed from workspace configurations + using the MKREF and DELREF methods defined by the DAV Advanced + Collections Working Group. Note that direct references are + required. - This example shows how to discover the checkin set root for the - /somefolder resource. + Clients can obtain the contents of a configuration using PROPFIND + to enumerate the hierarchy under the configuation's collection. As + well, as stated above, clients can use the Configuration-Id header + as described previously. + + 9.2. Default Workspace Configurations + + Clients can establish a default workspace configuration that is to + be used, for all clients, if they do not specify a workspace + configuration. To do this, use the SETDEFAULT method against the + configuration root identifying the default configuration. >> Request - OPTIONS /somefolder/ HTTP/1.1 - Verify-Extension: DAV:versioning - Host: foobar.com - Content-Length: 0 + SETDEFAULT /cfgs/ HTTP/1.1 + Host: www.foobar.com + Content-Type: text/xml + Content-Length: xxx + + + + http://www.foobar.com/cfgs/CHFH49594/ + >> 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, PIN, MKREF - Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, - MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF - Verify-Extension: DAV:versioning - Versioning-Support: DAV:basicversioning, DAV:configurations, - DAV:checkinsets - Checkin-Sets-Root: /, infinity Content-Length: 0 - 3.10.2. Usage - Clients create checkin sets using MKCOL and specify a special body - tag to indicate that a checkin set collection is being created. + 10. CHECKIN SETS + + Clients may desire the ability to track a set of changes as a unit. + That is, create a grouping of related changes. This is achieved + using the MKCHECKINSET method to create a special collection. + Clients refer to the checkin set on all checkin (or change) + requests. The server automatically creates a "share" to the newly + created revision in the identified collection. + + Checkin sets are specific to a configuration and are created using + the MKCHECKINSET method. The DAV:checkinsetroot property on a + configuration specifies the URL of a collection where checkin sets + for the configuration exist. This can be used for discovery or + creation. If a configuration doesn't support checkin sets, then + this property will be empty. + + Clients create checkin sets using MKCHECKINSET. The response + includes the location of the new checkin set. >>Request - MKCOL /cs/244 HTTP/1.1 + MKCHECKINSET /cs/244 HTTP/1.1 Host: www.foobar.com - Content-Type: text/xml - Content-Length: xxxx - - - + Content-Length: 0 - Clients refer to this checkin set using the Checkin-Set header. - The BNF for this header is as follows: + >>Response - Checkin-Set := "Checkin-Set" ":" URI + HTTP/1.1 201 CREATED + Host: www.foobar.com + Location: http://www.foobar.com/cs/244 + Content-Length: 0 The following example illustrates use of checkin sets. >>Request - UNLOCK /foo/bar HTTP/1.1 + CHECKIN /foo/bar HTTP/1.1 Host: www.foobar.com Lock-Token: Checkin-Set: /cs/244 Content-Type: text/html Content-Length: xxxx - + ... - + The following properties MUST be supported on all checkin set collections: DAV:closed - This is a true (1) / false (0) property that indicates if this checkin set can be referenced in CHECKIN requests. When a checkin set is created, this property is defaulted to 0. Note that resources MAY choose to disallow clients from setting this property to 0 once a client has set it to 1. The following properties MUST be supported on all resources: DAV:checkinid - This read-only property returns the checkin id associated with this revision of the resource. - 4. VERSION MAPPING + A checkin that references a checkin set MUST be made to the + configuration associated with the checkin set. + + 11. VERSION MAPPING This specification defines headers to specify configurations and resource versions. However, there are times when clients require a single URI for when working against configurations or versions. Version mapping support allows servers to create namespaces that map to configurations and versions. Note that mappings are dynamic. That is, as resources are added, removed, and modified, the changes are reflected in any active maps. - 4.1. Discovery + To delete a mapping, use DELETE against the URI specified in the + MKMAP request. - Version mapping support is optional. This example shows that the - /cfgs/DFEE2034 configuration supports mapping to the /map/ root in - the namespace. + 11.1. Discovery + + Mapping support is optional and support is discovered using OPTIONS + to verify if the MKMAP method is supported. Using the request body + and the DAV:verinfo tag, clients can obtain the supported map + styles. + + This example shows that the /cfgs/DFEE2034 configuration supports + mapping to the /map/ root in the namespace. >> Request OPTIONS /cfgs/DFEE2034 HTTP/1.1 - Verify-Extension: DAV:versioning Host: foobar.com - Content-Length: 0 + Content-Type: text/xml + Content-Length: xxx + + + + + >> 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, PIN, MKREF + MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, FREEZE, THAW, + CHECKIN, + CHECKOUT, UNCHECKOUT, BRANCH Public: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, - MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, PIN, MKREF - Verify-Extension: DAV:versioning - Versioning-Support: DAV:basicversioning, DAV:mapping - Mapping-Root: /map/ - Mapping-Styles: DAV:detailedmap, DAV:branchmap, DAV:nestedbranch - Content-Length: 0 - - The BNF for this OPTIONS header is as follows: - - Mapping-Root := "Mapping-Root" ":" URL - - Mapping-Styles := "Mapping-Styles" ":" URL-List - - Note that multiple Mapping-Root headers is permitted. + MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, MKREF, FREEZE, THAW, + CHECKIN, + CHECKOUT, UNCHECKOUT, BRANCH + Versioning: DAV:versioning + Content-Type: text/xml + Content-Length: xxx - 4.2. Mapping Configurations + + + + + DAV:detailedmap + DAV:branchmap + DAV:nestedbranch + + + + 11.2. Mapping Configurations - The MKCOL method is used to create namespaces based on a + The MKMAP method is used to create namespaces based on a configuration. When a configuration is mapped to a new namespace, all elements within the configuration can be directly accessed within the namespace without requiring the configuration to be identified in the header. In the example below, a new namespace is created for accessing the contents of the /cfgs/DFEE2034 configuration. >> Request - MKCOL /map/mymap HTTP/1.1 + MKMAP /maps/mymap HTTP/1.1 Host: foobar.com Configuration-Id: /cfgs/DFEE2034 Content-Type: text/xml Content-Length: xxxx >> Response HTTP/1.1 201 CREATED Context-Length: 0 - 4.3. Mapping Resource Versions + 11.3. Mapping Resource Versions - The MKCOL method is also used to create namespaces based on a - resourceÆs versions (i.e., its revision graph). When a resource is + The MKMAP method is also used to create namespaces based on a + resource's versions (i.e., its revision graph). When a resource is mapped, its revision history (revision graph) within the configuration is made available without requiring the Revision-Id header. Within the mapped namespace, a hierarchy is created for the revisions. However, there are different ways to map the history. Consider the following revision history of the versioned resource bar.htm: V1 -> V2 -> V3 (primary branch) | +-> V1.1 -> V1.2 ("test" branch) The following diagrams illustrate possible mappings: - (DAV:detailedmap) (DAV:branchmap) (DAV:nestedbranchmap) + (DAV:detailedmap) (DAV:branchmap) + (DAV:nestedbranchmap) V1 Primary Test Primary | | | | +----+--------+ V1 V1.1 +------Test | | | | | | | V2 bar.htm V1.1 V2 V1.2 V1 V1.1 | | | | | +----+ +-----+ V3 V2 V1.2 | | | | | V3 bar.htm V1.2 bar.htm V3 | | bar.htm bar.htm In the example below, a new namespace is created for accessing the versions of the /foo/bar.htm resource in the /cfgs/DFEE2034 configuration. >> Request - MKCOL /map/mymap2 HTTP/1.1 + + MKMAP /maps/mymap2 HTTP/1.1 Host: foobar.com Configuration-Id: /cfgs/DFEE2034 Content-Type: text/xml Content-Length: xxx /foo/bar.htm DAV:detailedmap >> Response HTTP/1.1 201 CREATED Context-Length: 0 Note that resources MAY support any mapping styles, however, if - they support DAV:detailedmap, DAV:branchmap, or - DAV:nestedbranchmap, they must map as illustrated above. - - 5. MISCELLANEOUS FUNCTIONS - - The following sub-sections detail miscellaneous versioning - functions. - - 5.1. Destroy - - Many version management systems use tombstones to note deleted - items. These systems also support the ability to permanently - destroy tombstones for an object. The DESTROY method provides this - functionality and resources SHOULD support it, but resources are - not required to implement it. Resources MUST return an error for - DESTROY requests that are not honored. - - 5.1.1. Discovery - - Discovery of this feature is determined by seeing if the resource - options include the DESTROY method. - - 5.1.2. Usage - - The DESTROY method is used against a specific resource to - permanently remove it. This is a namespace level-operation. That - is, all resources matching the specified URI are destroyed. - - >>Request - - DESTROY /foo/bar/x.cpp HTTP/1.1 - Host: www.foobar.com - Content-Type: text/xml - Content-Length: xxxx - Note that this request can be qualified by a configuration. - Requests to DESTROY resources that are in use by other - configurations MAY fail or delay the destruction until all - references are removed. - - 5.1.3. Headers - - Clients may chose to display deleted but not destroyed objects - however they choose. The header keyword Show-Deleted is used to - indicate if deleted items should be included in the GET request. - By default, they are not. Inclusion of "Show-Deleted: Y" indicates - that deleted resources should be included. Using "Show-Deleted: O" - indicates that only resources that have been deleted should be - returned. Using "Show-Deleted: N" indicates that deleted resources - shouldnÆt be returned. - - Show-Deleted := "Show-Deleted" ":" ("Y" | "N" | "O") - - 5.1.4. Properties - - DAV:isdeleted - A 0/1 property where 1 indicates that the resource - has been deleted. + they support MKMAP, then it MUST support DAV:detailedmap as + illustrated above. - 6. THE DAV VERSIONING GRAMMAR + 12. THE DAV VERSIONING GRAMMAR To be supplied - Describe and detail the DTDs - 7. INTERNATIONALIZATION CONSIDERATIONS + 13. INTERNATIONALIZATION CONSIDERATIONS To be supplied. - 8. SECURITY CONSIDERATIONS + 14. SECURITY CONSIDERATIONS To be supplied. - 9. SCALABILITY + 15. SCALABILITY To be supplied. - 10. AUTHENTICATION + 16. AUTHENTICATION Authentication mechanisms defined in WebDAV will also apply to DAV Versioning. - 11. IANA CONSIDERATIONS + 17. IANA CONSIDERATIONS This document uses the namespace defined by [WebDAV] for XML elements. All other IANA considerations mentioned in [WebDAV] also applicable to DAV Versioning. - 12. COPYRIGHT + 18. COPYRIGHT To be supplied. - 13. INTELLECTUAL PROPERTY + 19. INTELLECTUAL PROPERTY To be supplied. - 14. REFERENCES + 20. REFERENCES [DAVVERREQ] TBD, "Requirements for DAV Versioning and Variant - Authoring", October 1998, work-in-progress, draft-ietf-webdav- - versionreqs-00.txt + Authoring", October 1998, internet-draft, work-in-progress, draft- + ietf-webdav-versionreqs-00.txt [Kaler] C. Kaler, "Versioning Extensions for WebDAV", September 1998, internet-draft, work-in-progress, draft-kaler-webdav- versioning-00. [RFC2068] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, U.C. Irvine, DEC, MIT/LCS, January 1997. [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels." RFC 2119, BCP 14. Harvard University. March, 1997. [WebDAV] Y. Goland, E.J. Whitehead, A. Faizi, S.R. Carter, D. Jenson, "Extensions for Distributed Authoring on the World Wide - Web", October 1998, internet-draft, work-in-progress, draft-ietf- - webdav-protocol-09. + Web", April. 1998, internet-draft, work-in-progress, draft-ietf- + webdav-protocol-08. [White] E.J. Whitehead, "A Web Versioning Protocol", June 1998, internet-draft, work-in-progress, draft-whitehead-webdav- versioning-00. - 15. AUTHOR'S ADDRESSES + 21. AUTHOR'S ADDRESSES Christopher Kaler, Editor Microsoft One Microsoft Way Redmond WA, 9085-6933 Email:ckaler@microsoft.com + Jim Amsden + IBM + Email: jamsden@us.ibm.com + + Geoff Clemm + Rational + Email: gclemm@atria.com + + Bruce Cragun + Novell Inc. + 1555 N. Technology Way + Orem, UT 84097 + Email: bcragun@novell.com + + David Durand + Email: dgd@cs.bu.edu + + Bradley Sergeant + MicroFocus + Email: bradley_sergeant@intersolv.com + E. James Whitehead, Jr. Dept. of Information and Computer Science University of California, Irvine Irvine, CA 92697-3425 Email: ejw@ics.uci.edu - TBD - list all members of the working group - - 16. OPEN ISSUES + 22. OPEN ISSUES The following list identifies key open issues against this document: - - Can you checkout a collection? What does it mean? + . Can you checkout a collection? What does it mean? - - What tags do we want to use for resource/configuration report + . What tags do we want to use for resource/configuration report results? + . What structure do we create for maps? - - What structure do we create for maps? - - - What time format should we use? - - - Should PIN be a method or a property? - - - What additional resource branching support is needed? + . What additional resource branching support is needed? - - Schema discovery is an issue. For example, how to + . Schema discovery is an issue. For example, how to discover/change mutable/immutable properties? - - There are several missing examples / replies that need to be + . There are several missing examples / replies that need to be specified. - 17. CHANGE HISTORY + 23. CHANGE HISTORY Sep 28, 1998 Initial Draft based on [White] and [Kaler]. Oct 24, 1998 Incorporate feedback from October 01-02 working group meeting. + + Jan 20, 1999 + + Incorporate feedback from December 1998 working group meeting.