|
INTERNET-DRAFT draft-ietf-deltav-versioning-05
Expires November 20, 2000 |
Geoffrey Clemm, Rational Software Chris Kaler, Microsoft
|
Versioning Extensions to WebDAV
Status of this Memo
This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
Abstract
This document specifies a set of methods, headers, and resource-types that define the WebDAV Versioning extensions to the HTTP/1.1 protocol. WebDAV Versioning will minimize the complexity of clients so as to facilitate widespread deployment of applications capable of utilizing the WebDAV Versioning services. WebDAV Versioning includes:
- Basic versioning with automatic versioning for versioning-unaware clients,
- Activity and workspace management,
- URL namespace versioning.
Table of Contents
2.1 Creating
and Modifying a Versioned Resource
2.2 Accessing
a Versioned Resource
2.2.1 Selecting
a Working Resource: Working Resource Id
2.2.2 Selecting
a Revision: Stable URL, Revision Id, and Revision Label
3 Versioning
Properties by Resource Type
3.3 Versioned
Resource Properties
3.3.1 DAV:revision-set
(protected)
3.3.2 DAV:working-resource-id-set
(protected)
3.3.3 DAV:initial-revision
(protected)
3.4.1 DAV:revision
(protected)
3.4.2 DAV:revision-id
(protected)
3.4.3 DAV:predecessor-set
(protected)
3.4.4 DAV:successor-set
(protected)
3.4.5 DAV:label-set
(protected)
3.4.6 DAV:checkin-date
(protected)
3.4.7 DAV:working-resource-id-set
(protected)
3.5 Working
Resource Properties
3.5.1 DAV:working-resource-id
(protected)
3.5.2 DAV:predecessor-set
(protected)
5 Versioning
and Existing Methods
5.1 Automatic
Versioning for Versioning Unaware Clients
5.6 New
Status Codes for Existing Methods
6.5.1 Example
- SET-LABEL-TARGET
8 Advanced
Versioning Semantics
8.1 Target
Selection and Workspaces
8.3 Parallel
Development and Merging
9 Advanced
Versioning Properties by Resource Type. 23
9.2 Working
Resource Properties
9.3.1 DAV:working-resource-set
(protected)
9.3.4 DAV:predecessor-set
(protected)
9.4.1 DAV:predecessor-set
(protected)
9.4.2 DAV:successor-set
(protected)
9.5.1 DAV:revision-set
(protected)
9.5.3 DAV:workspace-set
(protected)
10 Advanced
Versioning Headers
11 Advanced
Versioning and Existing Methods
11.2.1 Example
- Advanced SET-TARGET
11.3.1 Example
- Advanced CHECKOUT
12 Advanced
Versioning Methods
13 Advanced
Versioning Reports
13.1 DAV:request-workspace-report
13.1.1 Example
- DAV:request-workspace-report
13.2 DAV:versioned-resource-url-report
13.2.1 Example
- DAV:versioned-resource-url-report
13.3.1 Example
- DAV:conflict-report
13.4.1 Example
- DAV:compare-report
13.5.1 Example
- DAV:repository-report
14 Internationalization
Considerations
24 Open
Issues and Pending Changes
This document defines WebDAV Versioning extensions, an application of HTTP/1.1 for handling resource versioning in a WebDAV environment. [Goals] describes the motivation and requirements for these extensions. WebDAV Versioning defines two levels of versioning functionality: basic versioning and advanced versioning.
Basic versioning provides versioning of largely independent resources. It allows authors to concurrently create, label, and access distinct revisions of a resource, and provides automatic versioning for versioning-unaware clients. All basic versioning functionality MUST be provided by a resource that supports versioning.
Advanced versioning provides more sophisticated capabilities such as logical change tracking, workspace management, and versioning the URL namespace. A particular versioned resource may support only a subset of the advanced versioning capabilities. The advanced versioning capabilities provided by a particular versioned resource may be discovered with an OPTIONS request.
This document will first define the terminology, semantics, properties, methods, and headers for basic versioning, and then define the additional terminology, semantics, properties, and methods for advanced versioning.
This draft uses the terms defined in [RFC2068] and [RFC2518]. In addition, the following terms are defined:
Versionable Resource
A "versionable
resource" is a resource that
can remember previous states of the contents and properties of that resource with a
CHECKIN request.
Versioned Resource
A "versioned
resource" is a versionable resource that has remembered at least one previous
state of that resource. To
update the state of a versioned resource, it must be checked out with a
CHECKOUT request and then subsequently checked in with a CHECKIN requestcreating
a new revision.
Working Resource
A "working resource" is a writeable resource created by applying a CHECKOUT request to a versioned resource.
Working Resource Id
A "working resource id" is a string chosen by the server to identify a particular working resource of a versioned resource. A working resource could be considered a tentative new revision that can be updated in a workspace. We should attempt to normalize the user of working resource id’s and revision id’s so they play nearly the same role.
Revision
A "revision" of a versioned resource is a write-protected resource created by applying a CHECKIN request to a working resource.
A "revision id" is a string chosen by the server to identify a particular revision of a versioned resource.
Revision Label
A "revision label" is a string chosen by a client to identify a particular revision of a versioned resource.
Initial Revision
An "initial revision" is the first revision of a versioned resource.
Predecessor, Successor
A "predecessor" of a revision is a previous revision that was checked out or merged to create the revision. A "successor" of a revision is a later revision that has the revision as one of its predecessors. Each revision except for the initial revision has at least one predecessor.
A revision that is related to another revision by one or more predecessor relations is called an "ancestor" of that revision, while a revision that is related to another revision by one or more successor relations is called a "descendent" of that revision.
The following diagram illustrates several of the previous definitions.
Versioned -------> Foo.html
Resource
+----+ \
Initial Revision ---> | V1 | |
+----+ |
| |
| |
+----+ |
Label ------> "beta1" | V2 | |
+----+ |
/ \ |
/ \ |
+----+ +----+ |
Revision Id ------> V3 | | V4 | | History
+----+ +----+ | of
^ | | | Foo.html
Predecessor | | | |
| +----+ +----+ |
| V5 | | V6 | |
+----+ +----+ |
| \ / |
Successor | \ / |
v +----+ |
| V7 | |
+----+ /
Target
Whenever a server encounters a versioned resource while it is processing an HTTP request, it acts on the "target" of the versioned resource, rather than on the versioned resource itself. This allows a client to largely ignore the fact that a resource has been placed under version control. The Target-Selector header is used to control the target selection for a versioned resource. The "default target" of a versioned resource is the target selected when no target selector header is specified.
RevisionStable URL
When a revision is created, it is given a server assigned "stable URL". Unlike a URL that identifies a versioned resource, a stable URL always identifies a particular revision and is not affected by a target selector header. Are there constraints on what the server can do with these stable URLs? That is, can the server ever change them? Assume the server is free to change them but in a semantics preserving way.
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 this document are to be interpreted as described in [RFC2119].
The term "protected" is placed in parentheses following the definition of a property that cannot be updated with a PROPPATCH request.
An unversioned resource that can be put under version control is called a versionable resource. A versionable resource that is put under version control is called a versioned resource. Once a resource is put under version control, the history of the body and properties of the resource is tracked as a sequence of revisions. The properties of the versioned resource itself provide access to this history (e.g. the revision set, the initial revision in this set, whether new revisions can be added).
In order to create a new revision, a versioned resource must first be checked out. This produces a new resource, called a working resource. A working resource is a modifiable copy of an existing revision of the versioned resource, and is identical to an unversioned resource in all respects other than that it is associated with a particular revision of a particular versioned resource. It may be edited by setting its properties or contents any number of times. When the author is satisfied that the working resource is in a state that should be retained in the versioned resource history, the author checks in the working resource to create a new revision of the versioned resource.<big> The revision that was checked out is the predecessor of the new revision.</big>
The following diagram illustrates the checkout/checkin process.
===CHECKOUT==> ===CHECKIN==>
Foo.html | Foo.html | Foo.html
| |
+----+ | +----+ | +----+
| V1 | | | V1 | | | V1 |
+----+ | +----+ | +----+
| | | | |
v | v | v
+----+ | +----+ | +----+
| V2 | | | V2 | | | V2 |
+----+ | +----+ | +----+
| | | |
| v | v
| +----+ | +----+
| | WR | | | V3 |
| +----+ | +----+
A server MAY support mutable revisions. Normally, a revision cannot be changed and provides a reliable environment for history management and state recovery. If a server supports mutable revisions, the client may request that a checkin should overwrite the revision that was checked out, instead of creating a new revision. Servers may choose not to support mutable revisions, since mutable revisions are unsuitable for many advanced versioning features, such as stable workspaces, change tracking, and merging.
When a method is applied to a versioned resource, it is
applied to the target of that versioned resource. The target can be a working resource of the versioned resource, a
revision of the versioned resource, or the versioned resource itself. The Target-Selector header of a request
determines the target of the request-URL.
If no Target-Selector header is specified, a revision of the versioned
resource called the default target is selected. The default target is also selected for any
versioned resource other than the one identified by the request-URL (such as
those identified by server side includes). That is, all relative
URLs are evaluated using the same Target-Selector as used in the method
request? Actually I just noticed I read this wrong. My expectation was that
Target-Selector behaved like URL context for relative URLs. If you don’t
specify something, and the URL is evaluated in the context of the request-URL, then the revision selection
should be evaluated in the context of the request Target-Selector.
Working resource ids are used to distinguish a working resource of a versioned resource from other working resources of that versioned resource. A working resource of a versioned resource is given a server assigned working resource id when it is created. A working resource id does not distinguish working resources from different versioned resources, since the same working resource id can be assigned to a working resource of any versioned resource.
When a revision is created, it is given a server assigned "stable URL". Unlike a URL that identifies a versioned resource, a stable URL always identifies a particular revision and is not affected by a target selector header.
When a revision is created, it is also given a server
assigned "revision id". The revision id acts as a persistent, immutable identifier
distinguishing this revision from all others of the same versioned resource.
The revision id cannot be changed or assigned to another revision.
At any time, a revision can be given a client assigned "label" in order to provide a more meaningful name for that revision. A given revision label can be assigned to at most one revision of a given versioned resource, but may be reassigned to another revision at any time.
Revision ids and revision labels
are unique only across a single versioned resource. That is, a revision id or revision label does not distinguish
revisions from different versioned resources, since the same revision id or
revision label can be applied to a revision of any other versioned resource.
This section defines the new resource types and properties introduced by WebDAV versioning. When a property cannot be updated by a PROPPATCH request, it is identified in this document as a "protected" property.
Some properties take a Boolean value.
boolean = "F" | "T"
Some properties take a value that is intended to identify the resource. An id is a sequence of characters. When an id is marshaled in the header of an HTTP request, the characters are encoded using the UTF-8 encoding scheme.
Some properties take a date or time value. The syntax of date-time is defined in section 23.2 of [RFC2518].
The href XML element is defined in section 12.3 of [RFC2518].
WebDAV versioning introduces the following properties for a resource. These properties are "dead" properties that can be placed on any resource, and are defined here only to provide a standard name for a property containing this type of information about a resource.
This property is used to track the author of a resource. Each revision of a versioned resource can have a different DAV:author values, indicating who authored that revision.
<!ELEMENT author (#PCDATA)>
This property is used to track a brief comment about a resource. Each revision of a versioned resource has its own set of properties, so each revision can be given a DAV:comment appropriate to that revision.
<!ELEMENT comment (#PCDATA)>
The DAV:resourcetype of a versioned resource MUST be DAV:versioned-resource. The DAV:versioned-resource element MAY contain an element defining the resource type of the revisions of the versioned resource. For example, the resource type for a versioned resource whose revisions are collections would be:
<DAV:versioned-resource> <DAV:collection/> </DAV:versioned-resource>
Since an HTTP method by default applies to the target of a versioned resource, a Target-Selector request header whose value is "versioned-resource" is required to apply an HTTP method to the versioned resource itself. This should be a separate property, or obtained from one of the revisions as it is redundant. Otherwise client and server software dealing with DAV:getresourcetype will have to have a special case for this structured resource type. Can’t change the resource type of a resource, so don’t need this.
WebDAV versioning introduces the following properties for a versioned resource:
This property contains a stable URL for each revision of this versioned resource.
<!ELEMENT revision-set (href+)>
This property identifies the working resource ids for the working resources currently checked out from some revision of this versioned resource.
<!ELEMENT working-resource-id-set (working-resource-id*)>
<!ELEMENT working-resource-id (#PCDATA)>
PCDATA value: id
This property contains a stable URL for the initial revision of this versioned resource.
<!ELEMENT initial-revision (href)>
When the DAV:linear property of a versioned resource is true, only one working resource can be checked out from that versioned resource at any time, and only the revision that has no successors can be checked out. The default value of DAV:linear is false (F). An attempt to set DAV:linear to true (T) MUST fail if more than one revision of that versioned resource has no successor (i.e. if the history is not linear).
<!ELEMENT linear (#PCDATA)>
PCDATA value: boolean
When the DAV:auto-version property of a versioned resource is set, a request without a target selector header that attempts to modify a versioned resource whose target is a revision (such as PUT/PROPPATCH for a basic resource or a DELETE /MOVE for a collection) is automatically preceded by a CHECKOUT and automatically followed by a CHECKIN. This allows a versioning-unaware client to modify a version-controlled resource.
<!ELEMENT auto-version (boolean)>
WebDAV versioning introduces the following properties for a revision of a versioned resource. Unless a server supports mutable revisions, all revision properties except for DAV:successor-set, DAV:working-resource-id-set, and DAV:label-set cannot be modified.
This property contains a stable URL for this revision.
<!ELEMENT revision (href)>
The DAV:revision-id is an identifier assigned to a revision by the server. A revision cannot be given a DAV:revision-id that has been given to any other revision of that versioned resource, even a revision that has been deleted.
<!ELEMENT revision-id (#PCDATA)>
PCDATA value: id
Since a revision id can be specified in a target selector header, the length of a revision id should be compatible with common header length constraints.
The DAV:predecessor-set of a revision contains a stable URL for each revision that is a predecessor as specified in section 1.2. Except for the initial revision, which does not have any predecessor, each revision either has a single predecessor that was checked out to create this revision, or it has multiple predecessors that it was merged from.
<!ELEMENT predecessor-set (href*)>
This property contains a stable URL for each of the revisions whose DAV:predecessor-set identifies this revision. Unlike most revision properties, the DAV:successor-set of a revision can change.
<!ELEMENT successor-set (href*)>
This property is used to identify labels that are associated with a specific revision. The value of DAV:label-set is updated with the SET-LABEL-TARGET method. Unlike most revision properties, the DAV:label-set of a revision can change.
<!ELEMENT label-set (label*)>
<!ELEMENT label (#PCDATA)>
PCDATA value: id
Since a revision label can be specified in a target selector header, clients should limit the length of a revision label to be compatible with common header length constraints. For security reasons, a PROPFIND request MAY report only a subset of the labels that select this revision.
This optional property contains the date when the revision was checked in.
<!ELEMENT checkin-date (#PCDATA)>
PCDATA value: date-time
This property identifies the working-resource-ids for the working resources currently checked out from this revision. This property is updated with the CHECKOUT, CHECKIN, and UNCHECKOUT methods. Unlike most revision properties, the DAV:working-resource-id-set of a revision can change.
<!ELEMENT working-resource-id-set (working-resource-id*)>
<!ELEMENT working-resource-id (#PCDATA)
PCDATA value: id
WebDAV versioning introduces the following properties for a working resource:
This property identifies the working-resource-id for this working resource.
<!ELEMENT working-resource-id (#PCDATA)
PCDATA value: id
This property contains a stable URL for the revision that was checked out to create this working resource. The DAV:predecessor-set property can contain multiple revisions if the advanced versioning MERGE method is supported.
<!ELEMENT predecessor-set (href*)>
The following defines the BNF for the Target-Selector header:
Target-Selector
:= "Target-Selector" ":" *LWS "revision-id" 1*LWS id
| "Target-Selector" ":" *LWS "working-resource-id" 1*LWS id
| "Target-Selector" ":" *LWS "label" 1*LWS id
| "Target-Selector" ":" *LWS "versioned-resource"
Examples of a Target-Selector header are:
Target-Selector: revision-id Rev178AE8
Target-Selector: working-resource-id WR854
Target-Selector: label released
Target-Selector: versioned-resource
When a request-URL identifies a versioned resource, and the Target-Selector value is "revision-id", "label", or "working-resource-id", the specified revision or working resource is the target of the request-URL. When the Target-Selector value is "versioned-resource", the versioned resource itself is the target of the request-URL.
A Target-Selector header has no affect on a request-URL that does not identify a versioned resource. In particular, it has no affect on a stable URL, since a stable URL identifies a particular revision and not a versioned resource.
A server MUST return a Vary header containing Target-Selector in a response to a cacheable request (e.g. GET, PROPFIND) that includes a Target-Selector header.
For most existing HTTP and WebDAV methods, the only change introduced by versioning is that instead of applying a method to a versioned resource, the method is applied to the target of that versioned resource. If the target is a revision or a working resource, the effect is the same as applying that method to an unversioned resource of that type.
Note that if a method modifies only a binding to a resource and not the resource itself (e.g. DELETE, MOVE, BIND, UNBIND), the method is being applied to the collection containing that binding, so the method is not affected by versioning unless that collection is under version control.
For methods that update a resource (e.g. PUT, PROPPATCH), when that method is applied to a revision of a versioned resource, the method MUST fail unless the versioned resource has a DAV:auto-version property and no target selector header has been specified. In this case, the revision is checked out, the update is applied to the resulting working resource, and the working resource is checked in. This functionality allows a versioning unaware client to update a versioned resource. If any part of the checkout-update-checkin sequence fails, the server state preceding the request MUST be restored.
When a resource supports core versioning, the DAV response header for an OPTIONS request MUST contain "core-versioning".
>>REQUEST
OPTIONS /file HTTP/1.1
Host: www.webdav.org
>>RESPONSE
HTTP/1.1 200 OK
DAV: 1, 2, core-versioning
Public: OPTIONS, GET, PUT, PROPFIND, PROPPATCH, CHECKIN
The binding protocol introduces the DAV:urn property [Binding]. When PROPFIND is applied to a versioned resource whose target is a revision or working resource, the DAV:urn property value returned by PROPFIND MUST be the DAV:urn of the versioned resource, and not that of the revision or working resource. This ensures that the versioned resource appears to be the "same" resource when different revisions or working resources of that versioned resource are selected as targets. When PROPFIND is applied to a stable URL for a revision, the DAV:urn for the revision will be returned.
A COPY request MUST fail when it is applied to a versioned resource itself (as opposed to a revision or working resource of the versioned resource). In order to create another versioned resource with a similar history, the appropriate sequence of PUT, CHECKIN, and CHECKOUT requests must be made.
When a client successfully
applies a write-lock to a request-URL, it has two effects: it ensures that the
state of the resource cannot be changed without the lock token, and it ensures
that the association between the request-URL and the resource identified by
that URL cannot be changed without the lock token.
When a LOCK request successfully
applies a write-lock to a request-URL that identifies a versioned resource, the
first effect of the write-lock is to ensure that the state of the target of that
versioned resource cannot be modified without the lock token. If the target is a revision, this is
redundant since the state of a revision cannot be modified in any case. Attempt to update a
mutable revision would fail. The second effect of the write-lock
is to ensure that the target that will be selected by the Target-Selector of
the LOCK request cannot be changed without the lock token. This means both that the request-URL cannot
be associated with a different versioned resource (e.g. with a MOVE request),
and that the specified Target-Selector cannot select a different target of that
versioned resource (e.g. with a SET-TARGET or CHECKIN request).
4xx (No Such Target): The target selector for the request selects no revision or working resource for this versioned resource.
A CHECKIN request can be applied to a versionable resource to produce a new revision that is a copy of the current state of that resource. If the request-URL identifies a versioned resource, that target of that versioned resource must be a working resource. Unless a DAV:private checkin policy is specified, the new revision then becomes the target for that versioned resource, as if a SET-DEFAULT-TARGET request had been performed.
If the target of the request-URL is a working resource, a CHECKIN request by default will delete the working resource after creating the new revision. If the request body of the CHECKIN request contains a DAV:keep-checked-out element, then instead of deleting the working resource, CHECKIN will modify the DAV:predecessor-set of the working resource to contain a stable URL for the newly created revision. If the request body of the CHECKIN request contains a DAV:overwrite element, and if the server supports mutable revisions, and if there is a single predecessor revision, then instead of creating a new revision, CHECKIN will overwrite the value of the predecessor revision.
A CHECKIN response MUST NOT be cached. If a CHECKIN request fails, the server state preceding the request MUST be restored.
Marshalling:
The request body MUST be a DAV:checkin XML element.
<!ELEMENT checkin (keep-checked-out|private|overwrite)* >
<!ELEMENT keep-checked-out EMPTY>
<!ELEMENT private EMPTY>
<!ELEMENT overwrite EMPTY>
The response MUST
contain a Location header.
Preconditions:
If the request-URL identifies a versioned resource, the target of that versioned resource MUST be a working resource.
If the request-URL identifies a versioned resource whose target is a write-locked working resource and DAV:keep-checked-out is not specified, then the appropriate lock token MUST be included in the request.
If DAV:private is not specified and the default target of
the request-URL is write-locked, then the appropriate lock token MUST be
included in the request.
Response Status Codes:
201 (Created): The revision was successfully created.
404 (Not Found): The request-URL did not identify a resource.
405 (Method Not Allowed): The request-URL did not identify a versionable resource.
409 (Conflict): A precondition was violated.
Postconditions:
A new revision of the versioned resource is created.
A stable URL for
the new revision is returned in a Location response header.
The new revision is added to the DAV:successor-set property of each of the predecessor revisions.
If DAV:keep-checked-out is specified, the working resource is not deleted, but the DAV:predecessor-set property of the working resource is modified to contain just the new revision. Otherwise, the working resource is deleted, and the working resource id of the working resource is deleted from the DAV:working-resource-id-set property of the versioned resource and from the DAV:working-resource-id-set property of each of the predecessors of the working resource.
Unless DAV:private is specified in the request body, the new revision becomes the default target for the versioned resource.
The DAV:checkin-date property of the new revision is set.
DAV:successor-set is empty
for immutable or unmodified for mutable.
DAV:label-set is
unmodified.
DAV:revision-set of versioned resource must be updated with the new revision.
>>REQUEST
CHECKIN /file HTTP/1.1
Host: www.webdav.org
Target-Selector: working-resource-id WR-18734
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0"
encoding="utf-8" ?>
<D:checkin xmlns:D="DAV:"> <D:private/> </D:checkin>
>>RESPONSE
HTTP/1.1 201 Created
Location: /repo/vr/id12/rev/id32
A CHECKOUT request can be applied to a versioned resource whose target is a revision to produce a working resource that is a modifiable copy of that revision. The CHECKOUT response body will contain a working resource id that can be specified in a Target-Selector header in subsequent requests on that URL to identify that working resource.
A CHECKOUT request does not require a lock token, since it does not modify an existing target.
A CHECKOUT response MUST NOT be cached. If a CHECKOUT request fails, the server state preceding the request MUST be restored.
Marshalling:
The request body MUST be a DAV:checkout XML element.
<!ELEMENT checkout (ANY) >
The request body of a CHECKOUT request is not used in core versioning.
Preconditions:
The request-URL MUST identify a versioned resource whose target is a revision
If the DAV:linear property of the versioned resource is set, the versioned resource DAV:working-resource-id-set MUST be empty and the target revision MUST NOT have any successors.
Response Status
Codes:
201 (Created): The working resource was successfully created.
404 (Not Found): The request-URL did not identify a resource.
405 (Method Not Allowed): The request-URL did not identify a versioned resource whose target is a revision.
409 (Conflict): Any other violated precondition.
Postconditions:
A new working resource is created that is a copy of the revision.
The DAV:predecessor-set of the new working resource is set to the revision.
The DAV:working-resource-id of the new working resource is set to a value selected by the server. This working resource id is added to the DAV:working-resource-id-set property of the versioned resource and the DAV:working-resource-id-set property of the revision.
>>REQUEST
CHECKOUT /file HTTP/1.1
Host: www.webdav.org
>>RESPONSE
HTTP/1.1 201
Created
Content-Type: text/xml;
charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:working-resource-id xmlns:D="DAV:">
WR-157F2
</D:working-resource-id>
An UNCHECKOUT request can be applied to a versioned resource whose target is a working resource to cancel the CHECKOUT and delete the working resource.
If the request-URL is write-locked for the specified working resource id, the UNCHECKOUT request MUST include the appropriate lock token.
An UNCHECKOUT response MUST NOT be cached. If an UNCHECKOUT request fails, the server state preceding the request MUST be restored.
Preconditions:
The request-URL MUST identify a versioned resource whose target is a working resource.
Response Status Codes:
200 (OK): The working resource was successfully deleted.
404 (Not Found): The request-URL did not identify a resource.
405 (Method Not Allowed): The URL did not identify a versioned resource whose target is a working resource.
Postconditions:
The working resource id of the working resource is removed from the DAV:working-resource-id-set of the versioned resource and from the DAV:working-resource-id-set of each predecessor of the working resource.
The working resource is deleted.
>>REQUEST
UNCHECKOUT /file HTTP/1.1
Host: www.webdav.org
Target-Selector: working-resource-id WR-13458
>>RESPONSE
HTTP/1.1 200 OK
A SET-TARGET request can be applied to a versioned resource to specify the revision that is to be the default target of that versioned resource.
A SET-TARGET response MUST NOT be cached.
Marshalling:
The SET-TARGET request body MUST be a DAV:set-target XML element.
<!ELEMENT set-target (revision-id | label | href | none))
<!ELEMENT none EMPTY>
Preconditions:
The request-URL MUST identify a versioned resource.
The DAV:set-target value MUST be DAV:none or select a revision of the versioned resource identified by the request-URL. What does target DAV:none mean? How can a versioned resource not have a default revision. Explain what all these things mean.
If the request-URL is write-locked, the SET-TARGET request MUST include the appropriate lock token.
Response Status Codes:
200 (OK): The target was set.
400 (Bad Request): The request body was invalid.
404 (Not Found): The request-URL did not identify a resource.
405 (Method Not Allowed): The request-URL did not identify a versioned resource.
Postconditions:
The specified revision of the versioned resource is the default target of that versioned resource.
>>REQUEST
SET-TARGET /file HTTP/1.1
Host: www.webdav.org
<?xml version="1.0" encoding="utf-8" ?>
<D:set-target xmlns:D="DAV:">
<D:revision-id> id23 </D:revision-id>
</D:set-target>
>>RESPONSE
HTTP/1.1 200 OK
A SET-LABEL-TARGET request can be applied to a versioned resource to specify the revision that is to be the target of that versioned resource when the request Target-Selector specifies the given label. This should be simple LABEL. It should add or remove a label on a revision. We should not confuse setting a label with setting a default target for a versioned resource. LABEL should use the Target-Selector header to specify the revision to label. The entity request body should add or remove the label.
A SET-LABEL-TARGET response MUST NOT be cached.
Marshalling:
The request body MUST be a DAV:set-label-target XML element.
<!ELEMENT set-label-target (label (revision-id|label|href|none))
Preconditions:
The request-URL MUST identify a versioned resource.
The DAV:set-label-target value must be DAV:none or select a revision of the versioned resource identified by the request-URL.
If the request-URL is write-locked for the given label, the SET-LABEL-TARGET request MUST include the appropriate lock token.
Response Status Codes:
200 (OK): The target was set.
400 (Bad Request): The DAV:set-label-target value was invalid.
404 (Not Found): The request-URL did not identify a resource.
405 (Method Not Allowed): The request-URL did not identify a versioned resource.
Postconditions:
The specified revision of the versioned resource is the target of that versioned resource when the request Target-Selector header specifies that label.
The label appears in the DAV:label-set of the specified revision.
If DAV:none was specified in the SET-LABEL-TARGET request body, no revision of the versioned resource is selected by the label and the label does not appear in the DAV:label-set of any revision of the versioned resource.
>>REQUEST
SET-LABEL-TARGET /file HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0"
encoding="utf-8" ?>
<D:set-label-target xmlns:D="DAV:">
<D:label> released </D:label>
<D:revision-id> id23 </D:revision-id>
</D:set-label-target>
>>RESPONSE
HTTP/1.1 200 OK
A REPORT request is an extensible mechanism for obtaining information about resources. Unlike a resource property, a report depends on more than the state of the resource identified by the request-URL. The REPORT method MUST NOT change the state of any resource managed by the server.
The request body of a REPORT request specifies which report is being requested.
Every resource must support the DAV:available-report, which lists the reports supported at the request-URL.
<!ELEMENT available-report EMPTY>
The response body of an available REPORT is a DAV:report-set element containing empty XML elements identifying the reports available at that request URL.
<!ELEMENT report-set (ANY*)>
Following is an example of a DAV:available-report:
>>REQUEST
REPORT /myCollection HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<DAV:available-report/>
>>RESPONSE
HTTP/1.1 200 OK
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:report-set xmlns:D="DAV:">
<D:available-report/>
<D:property-report/>
</D:report-set>
Many properties consist of a set of one or more href elements. The DAV:property-report provides a mechanism for retrieving in one request the properties from the resources identified by those href elements. This looks more like a PROPFIND with a Follow-Hrefs header then it does a report.
<!ELEMENT property-report (ANY*)>
The elements of a DAV:property-report identify which properties of a resource are to be reported. If a property element is empty, then just the value of that property is returned. If a property element contains a list of properties, then the specified properties of each resource identified by an href in the specified property is returned as well. The property elements in the nested property lists can in turn contain property lists, so that multiple levels of href expansion can be requested. This needs to be motivated by examples and use cases that return interesting results. As written, it is very confusing and it is difficult to visualize what is being returned.
The response body of a DAV:property-request is a DAV:multistatus element as returned by a PROPFIND request. If the DAV:property-report indicates that each href in a particular property value is to be expanded, the href element that normally would be returned by PROPFIND is replaced by a DAV:response element that contains those properties.
This example describes how to query a versioned resource to determine the revision-id and author of every revision of that versioned resource. This effectively provides a "history" report for a versioned resource.
>>REQUEST
REPORT /file HTTP/1.1
Host: www.webdav.org
Target-Selector: versioned-resource
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:property-report xmlns:D="DAV:">
<D:revision-set>
<D:revision-id/>
<D:author/>
</D:revision-set>
</D:property-report>
>>RESPONSE
HTTP/1.1 207 Multi-Status
Target-Selector: versioned-resource
Vary: Target-Selector
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.webdav.org/file</D:href>
<D:propstat>
<D:prop>
<D:revision-set>
<D:response>
<D:href>http://repo/rev/id182<D:href>
<D:propstat>
<D:prop>
<D:revision>id182</D:revision>
<D:author>Fred</D:author> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
<D:response>
<D:href>http://repo/rev/id263<D:href>
<D:propstat>
<D:prop>
<D:revision>id263</D:revision>
<D:author>Sally</D:author> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
</D:revision-set> </D:prop>
</D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
</D:multistatus>
Workspace
A workspace is a resource that can be used to select a revision (like a label) or identify a working resource (like a working resource id) for one or more versioned resources. A workspace URL can be used anywhere a label or a working resource id can appear. A workspace can also be used in a Workspace request header to specify target selection for versioned resources encountered in that request. If a workspace both identifies a working resource for a versioned resource and selects a revision of that versioned resource, the working resource is the target of that versioned resource.
Request Workspace
When a server supports workspaces, it associates a "request workspace" with each request. The request workspace either is specified explicitly in a Workspace header or is determined by the server based on the request-URL. How? The request workspace determines target selection for every versioned resource encountered in that request. A Target-Selector header can be used to override the request workspace target selection for the versioned resource identified by the request-URL.
Baseline
A baseline captures the set of revisions currently selected by a workspace. Like a revision of a versioned resource, a baseline is immutable. The following diagram illustrates a baseline.
Foo.html Bar.html Bing.html
+----+
| V1 |
+----+
|
|
+-----------------|-------------------------------+
| | |
| +----+ +----+ +----+ Baseline |
| | V1 | | V2 | | V1 | V1.1 |
| +----+ +----+ +----+ |
| | | |
+-----------------|------------|------------------+
| |
v v
+----+ +----+
| V3 | | V2 |
+----+ +----+
Merging
"Merging" is a mechanism for combining two revisions of a versioned resource. If one revision is a descendent of the other, the descendent is the result of the merge. If neither is a descendent of the other, a new working resource is created that has both revisions as its predecessors. This new working resource is the result of the merge. The client is then responsible for updating the working resource so that it contains the logical combination of those predecessors, and then checking in the working resource.
Activity
An activity is an unversionable resource that selects a set of revisions that correspond to some unit of work or conceptual change. An activity can contain revisions of multiple versioned resources, and multiple revisions of the same versioned resource. If an activity contains multiple revisions of the same versioned resource, every revision must be on a single "line of descent" in that versioned resource, where a line of descent is a sequence of revisions connected by successor relationships.
The following diagram illustrates activities. Revision V3 is the latest revision of Foo.html selected by activity 2, and revision V7 is the latest revision of Bar.html selected by activity 2.
Foo.html | Bar.html
|
+----+ | +----+
| V1 | | | V5 |
+----+ | +----+
| Activity | | Activity
v 1 | v 2
+----+ | +----+
| V2 | | | V6 |
+----+ | +----+
| Activity | | Activity
v 2 | v 2
+----+ | +----+
| V3 | | | V7 |
+----+ | +----+
| | Activity
| v 3
| +----+
| | V8 |
| +----+
Versioned Collection
A versioned collection is a type of versioned resource that results from placing a collection under version control. The members of a versioned collection revision must be versioned resources. The working resource that results from checking out a versioned collection is called a working collection.
Core
versioning provides a labels as a
target selectors that can be used to select a
consistent set of revisions, but provides no mechanism for selecting a
consistent set of working resources. In
addition, core versioning provides no mechanism for a client to determine whether
a given label is already in use for some other purpose. The purpose of a
workspace is to provide a controlled set of
resources that a user can expect to remain stable unless explicitly changed.
These sets of resources can play any role including providing a private area in
which users can make changes, or integration areas where changes can be
integrated together. In order to address these issues, advanced
versioning introduces the concept of a "workspace" resource.
Unlike
a label, a new workspace is registered with a MKWORKSPACE request, thus
ensuring that a client will not mistakenly use a target selector already in use
by another client. Unlike a working
resource id, which is allocated by the server for a single versioned resource,
a workspace can identify a working resources for
multiple versioned resources. This
significantly simplifies a client implementation by allowing the use of a
single URL to identify a consistent set of revisions and working resources.
A workspace is initially populated with MERGE requests that cause it to select a particular set of revisions. A CHECKOUT request that specifies that workspace in a Workspace header creates a new working resource identified by that workspace. A subsequent CHECKIN request creates a new revision that is selected by the workspace. A SET-TARGET request can be used to cause a workspace to select an earlier revision or a revision on a different line of descent than the one it is currently selecting.
When
a server supports workspaces, it associates a "request workspace"
with every request. The request workspace is used to determine the target of
every versioned resource encountered in that request. A request workspace can be specified explicitly in a Workspace
request header. If no Workspace header
is specified, a server defined default workspace is the request workspace. A server can associate different default
workspaces with different URL's, and thereby expose multiple workspaces to
versioning unaware clients. How are these multiple default workspaces
specified? If the Workspace header is not specified, and neither is the
Target-Selector, then the default target for the versioned resource must be
used (to be consistent with core versioning. So I don’t see
how we know to use the default workspace unless it is set as the default target
for the versioned resource. I need to understand
how this works with core versioning.
A workspace selects a volatile set of revisions. A baseline can be created to capture the set of revisions selected by the workspace at a particular moment. This can be useful for a variety of purposes such as publishing consistent revisions of resources to deploy an application, or for recovering a specific state for legal or maintenance reasons. I liked using a version of a workspace for this role once I got used to it. What was the reason for introducing baselines? Is a baseline a versionable resource? Seems like it should be in order to capture many different states of a set of related revisions. Versioned workspaces make this simpler. Baselines create another namespace entry for a revision of a workspace. One VERY IMPORTANT missing feature is that a baseline needs to be able to appear in a Workspace header. This is a strong indication that a baseline is a revision of a workspace. We can call a revision or a workspace a baseline or configuration to indicate its role, but I don’t think it needs to be a new resource type.
When all clients are using the same workspace, a change made by one client is immediately visible to all other clients. In situations where the work of one client would be disrupted by changes made by other clients, it is desirable to allocate a separate workspace for that client. When that client is ready to see changes made by clients in another workspace, it can "merge" that other workspace into its workspace. Since the revisions selected by a workspace could change in the middle of the merge operation, it is common to merge a baseline created by that other workspace, rather than just the revisions currently selected by that other workspace.
In case the other workspace selects a revision of a versioned resource that is on a different line of descent than the one selected by the workspace (neither revision is an ancestor of the other), the contents of those revisions must be merged. For each versioned resource with such a conflict, the merge request will create a new working resource with the appropriate revisions as the predecessors. The client is responsible for modifying the contents of the working resource so that it represents the logical merge of the two revisions, and then checking in the working resource.
Normally, the "merge state" of a working resource created by a merge request is "initial", indicating that the contents of the working resource is just a copy of the revision originally selected by the workspace. In case the server is capable of performing part of the merge automatically, it indicates that it has done so by setting the merge state of the working resource to be "intermediate". If the server believes it has correctly merged the revisions, it indicates that it has done so by setting the merge state to be "final". Even if the merge state is final, it is still the responsibility of the client to verify that the merge is correct, and then to checkin the working resource.
Another reason a client may choose to use a separate workspace is to allow concurrent modification of the same versioned resource. Each workspace has its own working resource for that versioned resource, and the merge operation ensures that these concurrent changes will be merged instead of one overwriting the other.
In some advanced versioning scenarios, several different logical changes are performed in a single workspace, but another workspace only wants a subset of those changes. An "activity" resource provides the mechanism for addressing this problem. Each activity represents a single logical change, although many resources might need to be modified to effect that single logical change. When a working resource is created, the client specifies which activity that working resource will contribute towards. When a working resource is checked in to create a new revision, the association between the working resource and an activity is inherited by the newly created revision. The results of an activity can then be merged into another workspace with a MERGE request.
Another
use for an activity is to avoid merges.
Since normally (when is this not the case?) only one
working resource of a versioned resource can be checked out in the context of a
given activity, two clients can avoid merging with each other by selecting the
same activity as the current activity of their workspaces. If one client attempts to check out a
versioned resource already checked out by the other client, the checkout
request will fail. The client would
then have to either checkout the versioned resource in a different activity, or
wait until the other client checked in its working resource for that versioned
resource. Alternatively, a client can
request an "shared" checkout against
an activity, but then only the first checkin of the resulting working resources
will succeed without merging. What’s the use case here? What happens on
subsequent checkins? Is a merge done at this
time automatically? I think this should be removed. Clients shouldn’t use
activities if they want this flexibility.
A collection contains a set of named bindings to other resources that are the members of that collection. For a versioned collection, the bindings are to versioned resources, not to particular revisions and not to unversioned resources. Disallowing members to be particular revisions ensures that a new revision of that member can be selected by a workspace without having to create a new revision of the versioned collection. Disallowing members to be an unversioned resource ensures that collection revisions will never contain mutable resources shared with other collection revisions (a constraint required to allow efficient implementation of versioned collections). I don’t see why this is a problem, and the protocol shouldn’t be constrained by perceived implementation efficiencies in most cases. Some servers may be able to provide the function efficiently.
To modify the state of a versioned collection (e.g. add or remove a binding), the versioned collection must be checked out. Requests that modify the state of a member of a collection (e.g. check it out or check it in) have no effect on the state of the collection, and therefore a member of a collection revision can be checked out and checked in without checking out the collection itself. Conversely, requests that modify the state of a working collection, such as adding or deleting a binding to a versioned resource, have no effect on the state of the versioned resource being bound or unbound.
If a URL identifies a sequence of nested versioned collections, revision selection is performed for each versioned collection in the sequence, to select the versioned collection revision that will be used to map the next segment of the URL to the appropriate versioned resource.
This section defines the new resource types and properties introduced by WebDAV advanced versioning.
WebDAV advanced versioning introduces the following properties for a revision:
This property contains a URL for the activity that represents the logical change to which this revision contributes.
<!ELEMENT activity (href)>
WebDAV advanced versioning introduces the following properties for a working resource:
This property contains a URL for the activity that represents the logical change to which this working resource contributes.
<!ELEMENT activity (href)>
This property contains a URL for the activity that represents the logical change to which this working resource contributes. Don’t know what this is. The description is the same as DAV:activity.
<!ELEMENT activity (href)>
This property contains the state of a working resource that has multiple predecessors due to a MERGE request. DAV:initial indicates that the server has made no attempt to automate the merge, and the working resource has the same contents as the revision or working resource selected by the workspace before the merge. DAV:intermediate indicates that the server has automatically performed a merge, but that the results of the merge MUST be modified before it could represent a merge of the specified predecessors. DAV:final indicates that the server believes that the automatic merge is likely to be a correct merge of the specified predecessors. Note that a user might need to modify a working resource even if its DAV:merge-state is DAV:final, since there is no guarantee that the automatic merge is what the user actually wanted. A working resource cannot be checked in if its DAV:merge-state is DAV:initial or DAV:intermediate. I think we should remove this. Clients have to do the work anyway, regardless of what the server may or may not do. It just adds unnecessary complexity to the protocol for something the server usually can’t do very well.
<!ELEMENT merge-state (initial | intermediate | final)>
<!ELEMENT initial EMPTY>
<!ELEMENT intermediate EMPTY>
<!ELEMENT final EMPTY>
The DAV:resourcetype of a workspace MUST be DAV:workspace. WebDAV advanced versioning introduces the following properties for a workspace:
The DAV:working-resource-set of a workspace contains URL's that can be used to identify the working resources in that workspace. In order to use one of these URL's to identify a working resource, the workspace must be specified in a Workspace request header.
<!ELEMENT working-resource-set (href*)>
This property indicates that no new working resources can be created in this workspace. Could this be handled with a lock on the workspace?
<!ELEMENT no-checkout (#PCDATA)>
PCDATA value: boolean
This property identifies the activity that is currently being performed in this workspace. A new working resource in a workspace will automatically have its DAV:current-activity property set to this activity. This allows an activity-unaware client to update a workspace in which activity tracking is required. Checkout needs to have an activity argument to override this default.
<!ELEMENT current-activity (href)>
This property contains a URL for each baseline that was merged into this workspace. The DAV:predecessor-set is updated by the MERGE method. Another indication that a baseline is a revision of a Workspace.
<!ELEMENT predecessor-set (href*)>
This property contains a URL for each activity that is being tracked by this workspace. This property has no effect on the revisions selected by the workspace, but is just a list of likely arguments for a MERGE request for that workspace.
<!ELEMENT activity-set (href*)>
This property contains a URL for each workspace that is being tracked by this workspace. This property has no effect on the revisions selected by the workspace, but is just a list of likely arguments for a MERGE or SET-TARGET request for that workspace. What does it mean for a workspace to track a workspace?
<!ELEMENT activity-set (href*)>
The DAV:resourcetype of a baseline MUST be DAV:baseline. WebDAV advanced versioning introduces the following properties for a baseline.
The DAV:predecessor-set of a baseline contains a copy of the DAV:predecessor-set of the request workspace. So it is a versioned resource. Is it ever unversioned? Another indication that a baseline is a revision of a workspace. Is that your intent?
<!ELEMENT predecessor-set (href*)>
This property contains a URL for each of the baselines whose DAV:predecessor-set identifies this baseline. Not clear how this would ever be created. Automatically on baselining a workspace? Which revision of which baseline would be updated? Can baselines be checked out? If so, what could you do with them? This is starting to look like a mess.
<!ELEMENT successor-set (href*)>
The DAV:resourcetype of an activity MUST be DAV:activity. WebDAV advanced versioning introduces the following properties for an activity:
This property contains a stable URL for each revision whose DAV:activity property identifies this activity.
<!ELEMENT revision-set (href*)>
This property contains a URL for each of the other activities that form a part of the logical change being captured by this activity. The DAV:needed-activity-set of an activity contribute to the revision selection behavior of that activity when it is used in a MERGE request. The purpose of this property is to identify other activities that are a prerequisite to this activity.
<!ELEMENT needed-activity-set (href*)>
This property identifies the workspaces whose DAV:current-activity property identifies this activity.
<!ELEMENT workspace-set (href*)>
The following defines the BNF for the Workspace header:
Workspace := "Workspace" ":" *LWS URL
Examples of a workspace header are:
Workspace: http://www.webdav.org/workspace/mywksp
Whenever a server encounters a versioned resource while it is processing an HTTP request, it is required to act on the target of the versioned resource. If a Workspace header is specified in a request, the revision selected by the specified workspace is the target of the versioned resource.
A Workspace header only has an effect on a versioned resource. In particular, it has no effect on a stable URL, since a stable URL identifies a particular revision and not a versioned resource.
If both Workspace and Target-Selector headers are specified in a request, the Target-Selector applies to the versioned resource identified by the request-URL, and the Workspace applies to all other versioned resources encountered while processing that request. For example, in the request:
GET /x/y/foo.html
HTTP/1.1
Workspace: http://www.webdav.org/workspace/mywksp
Target-Selector: label released
the Workspace header determines the target of "/x" and "/x/y", while the Target-Selector header determines the target of "/x/y/foo.html".
A server MUST return a Vary header containing "Workspace" in a response to a cacheable request (e.g. GET, PROPFIND) that includes a Workspace header.
Each binding in a working collection MUST be to a versioned resource (see section 8.5). Therefore, when a request (e.g. PUT, MKCOL) attempts to create a new resource in a working collection:
- A new versioned resource is created.
- An empty initial revision is created and checked out.
- The request is used to initialize the state of the new working resource.
- A binding to the new versioned resource is added to the working collection.
When a request attempts to add or remove a binding to a revision of a versioned collection, if the versioned collection has a DAV:auto-version property, the versioned collection is checked out, the request is applied to the resulting working collection, and the working collection is checked in.
When a resource supports advanced versioning, the DAV response header for an OPTIONS request MUST indicate which advanced versioning extensions are supported. The possible extensions are: "workspace", "baseline", "merge", "activity", "versioned-collection", and "versioning". The "versioning" extension indicates that all advanced versioning extensions are supported.
>>REQUEST
OPTIONS /file HTTP/1.1
Host: www.webdav.org
>>RESPONSE
HTTP/1.1 200 OK
DAV: 1, 2, core-versioning, workspace, merge
Public: OPTIONS, GET, PUT, PROPFIND, PROPPATCH, CHECKIN, MERGE
Additional Marshalling:
The request MAY contain a Workspace header.
Additional Preconditions:
The versioned resource MUST NOT have a working resource whose working resource id is the URL of the request workspace.
Additional Postconditions:
If no Target-Selector header is specified, the specified revision of the versioned resource will be the target of that versioned resource when the specified workspace is the request workspace for a request. What if neither are specified. This is mentioned in the definitions, but not spelled out here.
>>REQUEST
SET-TARGET /file HTTP/1.1
Host: www.webdav.org
Workspace: http://www.webdav.org/workspace/mywksp
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0"
encoding="utf-8" ?>
<DAV:revision-id> id23 </DAV:revision-id>
>>RESPONSE
HTTP/1.1 200 OK
When workspaces are supported, a CHECKOUT request MAY specify a request workspace in a Workspace header.
When activities are supported, a CHECKOUT request MAY specify a request activity in the request body. If no activity is specified in the request body, the DAV:current-activity of the request workspace is the request activity.
Additional Marshalling:
A Workspace header MAY be used to specify the request workspace.
The request body MUST be a DAV:checkout XML element.
<!ELEMENT checkout (activity? shared?) >
<!ELEMENT shared EMPTY >
Additional Preconditions:
The versioned resource MUST NOT have a working resource whose working resource id is the request workspace.
If there is a request activity, the revision being checked out MUST be a descendent of all other revisions of that versioned resource that have that activity as their DAV:activity. Note the only time an activity is used as a revision selector is on merge into a workspace. Might be nice to allow an Activity to be a Target-Selector. A Target-Selector should be able to specify a Workspace too in which case it has the same effect as specifying a Workspace with no Target-Selector. This simplifies client implementations for the usual cases. In fact, I think the headers should be Target-Selector and Override-Target-Selector with each containing the same contents. This unifies target selection for core and advanced versioning, and clearly describes the roles of the two headers.
If DAV:shared is not specified, then there MUST NOT be any working resources of that versioned resource whose DAV:activity identifies the request activity. Remove this.
If DAV:shared is specified, all working resources of that versioned resource whose DAV:activity identifies the request activity MUST have a DAV:shared property whose value is "T". Remove this.
If the request-URL is write-locked for the request workspace, the CHECKOUT request MUST include the appropriate lock token.
Additional Postconditions:
The working resource id of the new working resource MUST be the request workspace URL.
The request-URL is added to the DAV:working-resource-set property of the request workspace.
The DAV:activity of the new working resource MUST identify the request activity.
If DAV:shared was specified in the CHECKOUT request body, then the new working resource MUST have a DAV:shared property whose value is "T".
>>REQUEST
CHECKOUT /file HTTP/1.1
Host: www.webdav.org
Workspace: http://www.webdav.org/workspace/mywksp
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:checkout xmlns:D="DAV:">
<D:activity>http://www.webdav.org/repo/activity/fix-bug-23</D:href>
</D:checkout>
>>RESPONSE
HTTP/1.1 201 Created
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:working-resource-id xmlns:D="DAV:">
<D:href>
http://www.webdav.org/workspace/mywksp
</D:href>
</D:working-resource-id>
Additional Preconditions:
The
working resource MUST be a descendent of all revisions of that versioned
resource that have the same DAV:activity value as the working resource.
If the DAV:merge-state of the working
resource MUST NOT be DAV:initial or DAV:intermediate.
Additional Postconditions:
The
new revision becomes the selected revision of that versioned resource for the
request workspace.
A stable URL for the new revision is added to
the DAV:revision-set property of the activity specified by the DAV:activity
property of the working resource.
A MKWORKSPACE request creates a new workspace resource. If the MKWORKSPACE request fails, no new resource is created at the request-URL, and any existing resource at the request-URL is unaffected. A server may restrict workspace creation to a particular collection, but a client can determine the location of this collection with a repository REPORT (see section 13.5).
A MKWORKSPACE response MUST NOT be cached. If a MKWORKSPACE request fails, the server state preceding the request MUST be restored.
Preconditions:
A resource MUST NOT exist at the Request-URL.
Return Status Codes:
201 (Created): The new workspace was successfully created.
403 (Forbidden): The server does not allow the creation of a workspace at the requested location.
409 (Conflict): A workspace cannot be created at the request-URL because the parent collection for the workspace does not exist, or because there is already a resource at that request-URL.
Postconditions:
A new workspace exists at the request-URL.
>>REQUEST
MKWORKSPACE /repo/workspace/public HTTP/1.1
Host: www.webdav.org
>>RESPONSE
HTTP/1.1 201 Created
Location: http://www.webdav.org/repo/workspace/public
A MKBASELINE request creates a new baseline resource. If the server cannot create a baseline at the request-URL (e.g. a baseline already exists at that URL), it may create the baseline at a server-defined URL instead. Remove this. The Location response header indicates where the baseline was created. No. To be consistent with HTTP and other WebDAV methods, the baseline should be created where the user said to create it or the method should fail. If a server restricts the creation of activities to a server-defined collection, a client can determine the location of this collection with a repository REPORT (see section 13.5).
A MKBASELINE response MUST NOT be cached. If a MKBASELINE request fails, the server state preceding the request MUST be restored.
Marshalling:
The response MUST contain a Location header.
Preconditions:
The DAV:working-resource-set of the request workspace MUST be empty.
Return Status Codes:
201 (Created): The new baseline was successfully created.
Postconditions:
A new baseline exists at the URL specified in the Location response header.
The
new baseline selects the set of revisions currently selected by the request
workspace.
>>REQUEST
MKBASELINE /alpha-23 HTTP/1.1
Workspace: /repo/workspace/public
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 201 Created
Location: /repo/baseline/alpha-23
A MKACTIVITY request creates a new activity resource. If the server cannot create the activity at the request-URL (e.g. an activity already exists at that URL), it may create the activity at a server-defined URL instead. The Location response header indicates where the activity was created. If a server restricts the creation of activities to a server-defined collection, a client can determine the location of this collection with a repository REPORT (see section 13.5).
A MKACTIVITY response MUST NOT be cached. If a MKACTIVITY request fails, the server state preceding the request MUST be restored.
Marshalling:
The response MUST contain a Location header.
Return Status Codes:
201 (Created): The new activity was successfully created.
Postconditions:
A new activity exists at the URL specified in the Location response header.
>>REQUEST
MKACTIVITY /repo/activity/test HTTP/1.1
Host: www.webdav.org
>>RESPONSE
HTTP/1.1 201 Created
Location: http://www.webdav.org/repo/activity/test-31
A MERGE request performs the logical merge of one or more revisions into the request workspace. The result of a merge depends on the relationship between the revision selected by the request workspace and the revision specified by the MERGE request-URL.
- If the workspace selects a revision or working resource that is a descendent of the request revision, the workspace continues to select the workspace revision or working resource following the merge.
- If the workspace selects no revision or selects a revision that is an ancestor of the request revision, the workspace selects the request revision following the merge. If the revision URL is write-locked for that workspace, the MERGE request MUST include the appropriate lock token.
- If the workspace selects a revision that is neither a descendent nor an ancestor of the request revision, the workspace revision is checked out in that workspace and the request revision is added to the DAV:predecessor-set of the resulting working resource. If the working resource URL is write-locked for that workspace, the MERGE request MUST include the appropriate lock token.
- If the workspace identifies a working resource that is not a descendent of the request revision, the request revision is added to the DAV:predecessor-set of that working resource, and the DAV:merge-state of that working resource is updated.
If the request URL identifies a baseline, all revisions selected by that baseline are merged into the request workspace. In addition, the baseline is added to the DAV:predecessor-set of the request workspace.
If the request URL identifies a workspace, all revisions selected by that workspace are merged into the request workspace. If that workspace identifies any working resources, the MERGE request MUST fail.
If
the request URL identifies an activity, then for each versioned resource
containing a revision selected by the activity, the latest revision selected by
that activity is merged into the request workspace. Each activity in the DAV:needed-activity-set property of the
activity is also merged, possibly resulting in multiple revisions being merged.
If the request URL identifies a resource or collection, the resource or collection is merged into the workspace.
A MERGE response MUST NOT be cached. If a MERGE request fails, the server state preceding the request MUST be restored.
Marshalling:
The response body MUST contain a DAV:update-set element.
<!ELEMENT update-set (href)* >
Preconditions:
The request-URL MUST identify a revision, a versioned resource whose target is a revision, an activity, a workspace, or a baseline.
Response Status Codes:
200 (OK): The merge was performed.
404 (Not Found): The request-URL did not identify a resource.
405 (Method Not Allowed): The resource identified by the request-URL is not a revision, an activity, a workspace, or a baseline.
Postconditions:
The specified revisions have been merged into the request workspace. The versioned resources whose targets have been modified by the MERGE are identified in the DAV:update-set. A URL in the DAV:update-set is the URL that identifies that versioned resource in the request workspace.
>>REQUEST
MERGE /repo/activity/fix-parser-bug HTTP/1.1
Host: www.webdav.org
Workspace: http://www.webdav.org/workspace/mywksp
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:update-set xmlns:D="DAV:">
<D:href>http://www.webdav.org/src/parse.c</D:href>
<D:href>http://www.webdav.org/src/inc/parse.h</D:href>
<D:href>http://www.webdav.org/doc/parse.html</D:href>
</D:update-set>
Advanced versioning introduces the following reports (the REPORT method is defined in section 6.4).
This report indicates the request workspace for a versioned resource at the request-URL. I couldn’t parse this.
<!ELEMENT request-workspace-report EMPTY>
A DAV:request-workspace-report response is a DAV:href element that contains a URL for the request workspace.
>>REQUEST
REPORT /myCollection HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<DAV:request-workspace-report/>
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:href xmlns:D="DAV:">
http://www.webdav.org/repo/workspace/default
</D:href>
The request URL of this report MUST be a stable URL for a revision of a versioned resource, and the result is a URL that can be used to locate this versioned resource in the request workspace. If the versioned resource specified in the request URL is not visible in the request workspace, a 4xx response status is returned.
<!ELEMENT versioned-resource-url-report EMPTY>
>>REQUEST
REPORT /repo/rev/id173 HTTP/1.1
Host: www.webdav.org
Workspace: http://www.webdav.org/repo/workspace/public
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<DAV:versioned-resource-url-report/>
>>RESPONSE
HTTP/1.1 200 OK
Host: www.webdav.org
Workspace: http://www.webdav.org/repo/workspace/public
Vary: Workspace
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:href xmlns:D="DAV:">
http://www.webdav.org/mycollection/test.html
</D:href>
A conflict report describes the conflicts that would result if the revisions specified by the request-URL were merged into the request workspace. A conflict occurs when the revision of a versioned resource specified by the request-URL is not on the same line of descent as the revision of that versioned resource selected by the request workspace. If the request-URL identifies a versioned resource, a Target-Selector header MUST be specified to indicate which revision of that versioned resource is to be tested for a conflict. If the request-URL identifies an activity, and that activity contains multiple revisions of a versioned resource, only the latest of those revisions is tested for a conflict. If the request-URL identifies a baseline, all revisions selected by that baseline are tested for a conflict.
<!ELEMENT conflict-report EMPTY>
A DAV:conflict-report response contains a DAV:conflict-set element, which contains the list of conflicts.
<!ELEMENT conflict-set (conflict*)>
<!ELEMENT conflict (href, common-ancestor, contributor, contributor+)>
<!ELEMENT common-ancestor (href)>
<!ELEMENT contributor(href)>
The DAV:conflict element contains the URL of a versioned resource for which there is a conflict. It also contains a DAV:common-ancestor for the conflict, and two or more DAV:contributor elements for the conflict.
The DAV:common-ancestor element contains a stable URL for a revision that is a common ancestor of all the DAV:contributor elements for a particular conflict.
The first DAV:contributor element contains a stable URL for the revision selected by the workspace. The remaining DAV:contributor elements identify the revisions selected by the request-URL.
>>REQUEST
REPORT /repo/activity/fix-it HTTP/1.1
Host: www.webdav.org
Workspace: http://www.webdav.org/repo/workspace/public
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<DAV:conflict-report/>
>>RESPONSE
HTTP/1.1 200 OK
Workspace: http://www.webdav.org/repo/workspace/public
Vary: Workspace
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:conflict-set xmlns:D="DAV:">
<D:conflict>
<D:href>http://www.webdav.org/file</D:href>
<D:common-ancestor>
<D:href>http://www.webdav.org/repo/rev/id23</D:href>
</D:common-ancestor>
<D:contributor>
<D:href>http://www.webdav.org/repo/rev/id42</D:href>
</D:contributor>
<D:contributor>
<D:href>http://www.webdav.org/repo/rev/id56</D:href>
</D:contributor>
</D:conflict>
</D:conflict-set>
A DAV:compare-report identifies the differences between the resource identified by the request-URL (base) and the resources specified in the body of the request (contributors). The comparison is carried out transitively on any children of the resources according to the value of the Depth header. If the Depth header is not specified, the value infinity is assumed. Resources appearing in a contributor but not in the base are described by DAV:added elements, resources appearing in the base but not a contributor are described by DAV:deleted elements, and resources appearing in both base and contributor but having different states are described by DAV:changed elements. Resource content comparison is not specified, though servers MAY provide it.
A DAV:compare-report contains the URL's of the resources to be compared with the resource identified by the request URL.
<!ELEMENT compare-report (href+)>
The body of DAV:compare-report response is a DAV:comparison element, which contains DAV:added, DAV:deleted, and DAV:changed elements. For example, if a DAV:compare-report is applied to two baselines, the DAV:compare-report response may contain the revisions that are selected by one baseline but not the other.
<!ELEMENT comparison (added, deleted, changed)*>
<!ELEMENT added (href, ANY*)>
<!ELEMENT deleted (href, ANY*)>
<!ELEMENT changed (href, ANY*)>
A DAV:added element identifies something that appears in a particular contributor resource but not in the base.
A DAV:deleted element identifies something that appears in the base resource but not in a particular contributor.
A DAV:changed element identifies information that is in both the base and the contributor but that has changed in some way. For example, when two baselines are being compared, a DAV:changed element can identify a versioned resource if the baselines select different revisions of that versioned resource.
>>REQUEST
REPORT /myCollection HTTP/1.1
Host: www.foo.com
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Depth: 1
<?xml version="1.0" encoding="utf-8" ?>
<D:compare-report xmlns:D="DAV:">
<href>http://www.foo.com/myOtherCollection</href>
</D:compare-report>
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:comparison xmlns:D="DAV:">
<D:added>
<href>http://www.foo.com/myOtherCollection</href>
</D:added>
<D:added>
<href>http://www.foo.com/myOtherCollection/foo.html</href>
</D:added>
<D:deleted>
<href>http://www.foo.com/myCollection/bar.html</href>
</D:deleted>
</D:comparison>
Often a versioning implementation requires that versioning metadata (such as workspaces and activities) be created in a server specified collection. When such a constraint exists, the DAV:repository-report can be used to determine the URL of this collection.
The DAV:repository-report MUST contain a resource type, such as DAV:workspace, or DAV:activity.
<!ELEMENT repository-report (ANY)>
A DAV:repository-report response is a DAV:href element that contains a server-defined URL for a collection in which the specified type of resource can be created. Since different parts of the URL namespace can be controlled by different servers, the value of a DAV:repository response will depend on the request-URL.
>>REQUEST
REPORT /myCollection HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:repository-report xmlns:D="DAV:">
<D:activity/>
</D:repository-report>
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:href xmlns:D="DAV:">
http://www.webdav.org/repo/activity
</D:href>
To be supplied.
To
be supplied.
Authentication mechanisms defined in WebDAV will also apply to WebDAV Versioning.
This document uses the namespace defined by [RFC2518] for XML elements. All other IANA considerations mentioned in [RFC2518] are also applicable to WebDAV Versioning.
The following notice is copied from RFC 2026, section 10.4, and describes the position of the IETF concerning intellectual property claims made against this document.
The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use other technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF Secretariat.
The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director.
This protocol is the collaborative product of the Delta-V design team: Jim Amsden (IBM, DeltaV Chair), Geoffrey Clemm (Rational), Bruce Cragun (Novell), David Durand (INSO), Chris Kaler (Microsoft), Jeff McAffer (OTI), Bradley Sergeant (Merant), and Jim Whitehead (UC Irvine). We would like to acknowledge the foundation laid for us by the authors of the WebDAV and HTTP protocols upon which this protocol is layered, and the invaluable feedback from the WebDAV and DeltaV working groups.
To be supplied.
[RFC2026] S.Bradner, "The Internet Standards Process", Harvard, 1996, <http://www.ietf.org/rfc/rfc2026.txt>.
[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, 1997, <http://www.ietf.org/rfc/rfc2068.txt >.
[RFC2119] S.Bradner, "Key words for use in RFCs to Indicate Requirement Levels", Harvard, 1997, <http://www.ietf.org/rfc/rfc2119.txt >.
[RFC2396] T.Berners-Lee, R.Fielding, L.Masinter, “Uniform Resource Identifiers (URI): Generic Syntax”, MIT/LCS, U.C. Irvine, Xerox, 1998, <http://www.ietf.org/rfc/rfc2396.txt>.
[RFC2518] Y. Goland, E.Whitehead, A.Faizi, S.R.Carter, D.Jensen, "HTTP Extensions for Distributed Authoring - WEBDAV", Microsoft, U.C.Irvine, Netscape, Novell, 1999 <http://www.ietf.org/rfc/rfc2518.txt>.
[Binding] J.Slein, E.Whitehead, J.Davis, G.Clemm, C.Fay, J.Crawford, T.Chihaya, "WebDAV Bindings", Xerox, U.C.Irvine, CourseNet, Rational, FileNet, DataChannel, 1999, <http://www.ietf.org/internet-drafts/draft-ietf-webdav-binding-protocol-01.txt>
[Goals] J.Amsden, C.Kaler, J.Stracke, "Goals for Web Versioning", IBM, Microsoft, Netscape, 1999, <http://www.ietf.org/internet-drafts/draft-ietf-webdav-version-goals-01.txt>
Geoffrey
Clemm
Rational
Software
20
Maguire Road
Lexington,
MA
Email:
geoffrey.clemm@rational.com
Christopher Kaler
Microsoft
One Microsoft Way
Redmond WA, 9085-6933
Email: ckaler@microsoft.com
The following list identifies open issues and pending changes against this document:
¨ Move the Response-Status information into the Precondition clauses (i.e. associate a status with each precondition indicating the status returned when that precondition is violated). Do a consistency pass making the use of status returns uniform.
¨ Mention somewhere that the If-Modified-Since header cannot be used to reliably cache versioned resource information since the modification date can decrease.
¨ Allow Depth:Infinity header on SET-TARGET, SET-LABEL-TARGET, CHECKIN ?
¨ Mention that "the method XXX is applied to a yyy" is a shorthand for "the method XXX is applied to a URL that identifies a resource of type yyy".
¨ Mention that "the target of a versioned resource" is a shorthand for "the target of a versioned resource, based on the request workspace and the Target-Selector header".