|
INTERNET-DRAFT draft-ietf-deltav-scenarios-00.1 Expires August 10, 2000 |
Tim Ellison, Object Technology International, Inc. February 10, 2000 |
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.
Scenarios are a useful mechanism for introducing readers to the new protocol of WebDAV versioning. This document provides an illustration of the versioning extensions to WebDAV through concrete examples. The scenarios are progressive, starting with the simplest operations that do not involve version control and building up to optional features of a WebDAV compliant server. All of the examples show the actual protocol used to communicate requests to the server and the resulting effects on the server’s resources.
This document is a companion to draft-ietf-deltav-versioning-01.2.
1.2. Relationship to protocol document
2. Simple Resource Manipulation
2.3. Put a resource under version control
2.4. Check out a versioned resource to permit updates.
2.5. Modify a working resource
2.6. Check-in the working resource to create a new revision
3. Working with Workspaces and Labels
3.2. Checkout a revision in a workspace
3.3. Checkout a revision in a second workspace
3.4. Check-in using a current label
3.5. Check-in the second working resource using a current label
3.6. Get an old revision by using a revision label
4.3. Check-in and create a new revision in that activity
5. Configurations of Revisions
5.1. Create a "labeled configuration"
5.4. Add the configuration to a workspace RSR
5.5. Select a revision from the configuration using the updated
workspace
6.1. Put a collection under version control
6.3. Add/remove members from the working collection
6.5. Access a revision of a member of a version of a collection
using a workspace
6.6. Access a specific revision
7.2. Use the baseline in a workspace RSR
8. International Considerations
This
document is aimed at readers who have read the WebDAV protocol specification,
and the Delta-V additions to the specification and would like to see the
protocol in action. In particular, these
scenarios provide a feedback loop to the Delta-V working group in order that
members can see how operations are represented in the versioning protocol and
where, if necessary, changes could be made.
Scenarios
build upon one another – both in terms of understanding the specification and
by using resources created in earlier scenarios. They are logically read in the sequence they are presented. However, the state of the repository is
shown after each scenario, so scenarios can be read in any order by looking at
the previous state of the server.
It is
important to understand that the scenarios reflect the protocol at a given
point in time, and are therefore subject to frequent revision based upon
changes to the protocol. When there is
discrepancy between the operations depicted in the scenarios and the equivalent
operations described in the protocol document THE PROTOCOL DOCUMENT IS ALWAYS
CONSIDERED TO BE THE MORE AUTHORITATIVE SOURCE.
See the
protocol specification for complete details of options and variations. The scenarios does not attempt to cover the
entire specification and all it’s options but rather illustrate common
operations and give the reader a feel for how they would use Delta-V.
To make
the scenarios useful and the document readable it is assumed that the root
collection (written “/”) and the default workspace (in this instance
“/default.wsp”) have been created in the repository and are known to the server
a priori. In addition, it is
assumed that no other clients are creating things on the server. When a new workspace is created it’s RSR is
“latest” by default.
The
starting state for the repository is a single root collection that contains
only the default workspace.
Scenarios
are written using the following section headings:
Objective: What is the scenario
trying to achieve?
Illustrates : The point(s) that
the scenario is drawing attention to in the protocol.
Overview : A high level
description of how the objective is being accomplished.
Protocol : The actual requests
and responses sent and received to accomplish the objectives.
Resource State: The state of the
repository after the scenario operations.
The
resource state is depicted as follows:
When
unversioned the resource is written as “URI <type>”.
When
versioned the resource is shown as “URI <versioned resource identifier
(VRID), type>”. Entries indented
below the versioned resource show the revisions and working resources, one per
line. A revision is written
“<revision identifier (RID), predecessors, successors>” and a working
resource is written as “<working resource in a workspace URI,
predecessors>”
For all
resources properties and state are shown as “name=value” or “name=(value1,
value2, … valueN)” for property collections.
Create a
new resource on a versioning server.
Before a
resource is brought under version control, it behaves much the same way as a
resource on a non-versioning server.
Resources are
created on a versioning server in the same way that they are created on a
non-versioning server. New resources
can be created by PUT, MKCOL, or MKRESOURCE.
This
scenario creates a new resource called foo.html in the root collection.
>>
Request
PUT /foo.html HTTP/1.1
Host: www.acme.com
Content-Type: text/plain
Content-Length: xxx
Hello world.
>>
Response
HTTP/1.1
201 Created
Target-Selector: http://www.acme.com/default.wsp
Content-Length: 0
/
<collection>
/default.wsp <workspace>
/foo.html <ordinary>
Update the
contents of a non-versioned resource on a versioning server.
Before a
resource is brought under version control, it is manipulated in much the same
way as a resource on a non-versioning server.
The
resource foo.html has its contents updated by the PUT method.
>>
Request
PUT
/foo.html HTTP/1.1
Host: www.acme.com
Content-Type: text/plain
Content-Length: xxx
This is the new content.
>>
Response
HTTP/1.1
200 OK
Target-Selector: http://www.acme.com/default.wsp
Content-Length: 0
/
<collection>
/default.wsp <workspace>
/foo.html <ordinary>
Indicate
to the server that the resource is to be version controlled.
Bringing a
resource under version control is an explicit action on the versioning server.
To put a
resource under version control use the VERSION method.
>>
Request
VERSION
/foo.html HTTP/1.1
Host: www.acme.com
Content-Type: text/plain
Content-Length: 0
>>
Response
HTTP/1.1
200 OK
Target-Selector: http://www.acme.com/default.wsp
Content-Length: 0
/
<collection>
/default.wsp <workspace>
/foo.html <VRID:9, ordinary>
<RID:0, pred.=null, succ.=null>
Note: The
server assigns the versioned resource identifier and revision identifier. In this example, the versioned resource
identifier of foo.html is “VRID:9”, and the revision identifier of the initial
revision is “RID:0”.
Update the
contents or properties of a versioned resource.
Once a
resource is under version control, it must be checked out before it can be
modified. A checked out resource is
called a working resource and is associated with a particular workspace. When no workspace is explicitly mentioned,
the server uses the resource’s default workspace
Check out
the versioned resource using the CHECKOUT method.
Omitting a
Target-Selector header in the request instructs the server uses the default
workspace. The server always includes
in the response the URL of the workspace containing the new working
resource. This permits clients to check
that the correct workspace was used and that an explicit Target-Selector was
not lost. In this example, the default
workspace for this versioned resource is called
http://www.acme.com/default.wsp.
>>
Request
CHECKOUT
/foo.html HTTP/1.1
Host: www.acme.com
Content-Length: 0
>>
Response
HTTP/1.1
201 Created
Target-Selector: http://www.acme.com/default.wsp
Content-Length: xxx
<?xml version=”1.0” encoding=”utf-8” ?>
<D:response xmlns:D=”DAV:”>
<D:href>http://www.acme.com/foo.html</D:href>
<D:propstat>
<D:prop>
<D:workspaces>
<D:href>http://www.acme.com/default.wsp</D:href>
</D:workspaces>
<D:status>HTTP/1.1
200 OK</D:status>
</D:prop>
</D:propstat>
<D:responsedescription>OK</D:responsedescription>
</D:response>
/
<collection>
/default.wsp <workspace>
/foo.html <VRID:9, ordinary>
<RID:0, pred.=null, succ.=null>
<working resource in /default.wsp,
pred.=RID:0>
Update the
contents of the resource that was checked out.
Updating a
working resource is like updating a non-versioned resource. You can use modify the working resource any
number of times. The previous state of
the working resource is overwritten by subsequent updates. The state of the resource is not preserved by the server in version history
until the working resource is checked in.
To refer
to the working resource pass in the URL of the versioned resource, and the URL
of the workspace in which the working resource resides. In this scenario, we continue to use the
default workspace.
Update the
resource contents using PUT method.
>>
Request
PUT
/foo.html HTTP/1.1
Host: www.acme.com
Content-Type: text/plain
Content-Length: xxx
updated contents
>>
Response
HTTP/1.1
200 OK
Target-Selector: http://www.acme.com/default.wsp
Content-Length: 0
/
<collection>
/default.wsp <workspace>
/foo.html <VRID:9, ordinary>
&l