INTERNET-DRAFT

draft-ietf-deltav-scenarios-00.1

 

 

Expires August 10, 2000

Tim Ellison,

Object Technology International, Inc.

 

 

February 10, 2000

WebDAV Versioning Scenarios

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

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.

Table of Contents

WebDAV Versioning Scenarios. 1

Status of this Memo. 1

Abstract 1

Table of Contents. 2

1. Introduction. 4

1.1. Audience. 4

1.2. Relationship to protocol document 4

1.3. Assumptions. 4

1.4. Key. 4

2. Simple Resource Manipulation. 5

2.1. Create a resource. 5

2.2. Update a resource. 5

2.3. Put a resource under version control 6

2.4. Check out a versioned resource to permit updates. 7

2.5. Modify a working resource. 8

2.6. Check-in the working resource to create a new revision. 8

3. Working with Workspaces and Labels. 10

3.1. Create a basic workspace. 10

3.2. Checkout a revision in a workspace. 11

3.3. Checkout a revision in a second workspace. 11

3.4. Check-in using a current label 13

3.5. Check-in the second working resource using a current label 14

3.6. Get an old revision by using a revision label 16

3.7. Manipulate labels. 16

4. Introducing Activities. 19

4.1. Create an activity. 19

4.2. Checkout in an activity. 20

4.3. Check-in and create a new revision in that activity. 21

4.4. Merge activities. 23

4.5. Change the workspace RSR.. 28

5. Configurations of Revisions. 31

5.1. Create a "labeled configuration". 31

5.2. Create a configuration. 32

5.3. Add member revisions. 33

5.4. Add the configuration to a workspace RSR.. 34

5.5. Select a revision from the configuration using the updated workspace. 35

6. Operations on Collections. 37

6.1. Put a collection under version control 37

6.2. Checkout a collection. 37

6.3. Add/remove members from the working collection. 37

6.4. Check-in the collection. 37

6.5. Access a revision of a member of a version of a collection using a workspace. 37

6.6. Access a specific revision. 37

7. Baselines. 38

7.1. Create a baseline. 38

7.2. Use the baseline in a workspace RSR.. 38

7.3. Update a baseline. 38

8. International Considerations. 39

9. Security Considerations. 39

10. Scalability. 39

11. Authentication. 39

12. IANA Considerations. 39

13. Intellectual Property. 39

14. Acknowledgements. 39

15. Index. 39

16. References. 39

17. Authors’ Addresses. 40

 

1. Introduction

1.1. Audience

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.

1.2. Relationship to protocol document

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.

1.3. Assumptions

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.

1.4. Key

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.

2. Simple Resource Manipulation

2.1. Create a resource

2.1.1. Objective

Create a new resource on a versioning server.

2.1.2. Illustrates

Before a resource is brought under version control, it behaves much the same way as a resource on a non-versioning server.

2.1.3. Overview

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.

2.1.4. Protocol

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

2.1.5. Resource State

/ <collection>
/default.wsp <workspace>
/foo.html <ordinary>

2.2. Update a resource

2.2.1. Objective

Update the contents of a non-versioned resource on a versioning server.

2.2.2. Illustrates

Before a resource is brought under version control, it is manipulated in much the same way as a resource on a non-versioning server.

2.2.3. Overview

The resource foo.html has its contents updated by the PUT method.

2.2.4. Protocol

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

2.2.5. Resource State

/ <collection>
/default.wsp <workspace>
/foo.html <ordinary>

2.3. Put a resource under version control

2.3.1. Objective

Indicate to the server that the resource is to be version controlled.

2.3.2. Illustrates

Bringing a resource under version control is an explicit action on the versioning server.

2.3.3. Overview

To put a resource under version control use the VERSION method.

2.3.4. Protocol

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

2.3.5. Resource State

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

2.4. Check out a versioned resource to permit updates.

2.4.1. Objective

Update the contents or properties of a versioned resource.

2.4.2. Illustrates

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

2.4.3. Overview

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.

2.4.4. Protocol

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

2.4.5. Resource State

/ <collection>
/default.wsp <workspace>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=null>
   <working resource in /default.wsp, pred.=RID:0>

2.5. Modify a working resource

2.5.1. Objective

Update the contents of the resource that was checked out.

2.5.2. Illustrates

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.

2.5.3. Overview

Update the resource contents using PUT method.

2.5.4. Protocol

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

2.5.5. Resource State

/ <collection>
/default.wsp <workspace>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=null>
   <working resource in /default.wsp, pred.=RID:0>

2.6. Check-in the working resource to create a new revision

2.6.1. Objective

Preserve the contents and properties of the working resource as a new revision in version history.

2.6.2. Illustrates

After changes have been made to the working resource, the state of the resource may be made immutable by “checking it in” on the server.

In this scenario the working resource is in the default workspace so no explicit Target-Selector header is required in the request.

2.6.3. Overview

Check in the working resource using the CHECKIN method.  The successful response is a 201 (Created) to indicate that the revision was successfully created.

2.6.4. Protocol.

>> Request

CHECKIN /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: 0

2.6.5. Resource State

/ <collection>
/default.wsp <workspace>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=null>

3. Working with Workspaces and Labels

3.1. Create a basic workspace

3.1.1. Objective

Create a workspace as a named context for working resources.

3.1.2. Illustrates

Workspaces are simply resources within the server.  By creating a workspace resource we can subsequently use it to separate working resources from others in different workspaces.

3.1.3. Overview

Workspaces are created using the MKRESOURCE method where the type of the resource is <DAV:workspace-resourcetype/>.

This scenario creates a new workspace called /scenarios.wsp (note: the particular name is unimportant since it is the “resource type” property that denotes this as a workspace).

3.1.4. Protocol

>> Request

MKRESOURCE /scenarios.wsp HTTP/1.1
Host: www.acme.com
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8” ?>
<D:propertyupdate xmlns:D=”DAV:”>
   <D:set>
      <D:prop>
         <D:resourcetype><D:workspace-resourcetype/></D:resourcetype>
      </D:prop>
   </D:set>
</D:propertyupdate>

 

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/default.wsp
Content-Length: 0

3.1.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=null>

3.2. Checkout a revision in a workspace

3.2.1. Objective

Checkout a revision of a versioned resource in the context of a specific workspace.

3.2.2. Illustrates

A working resource is associated with a particular workspace.  To check out a revision into the context of a known workspace the URL of the workspace is passed in the Target-Selector: header of the request.

The server responds with the name of the workspace containing the new working resource so that the client can check that the header was not lost in message transfer.  (Some proxy servers strip out headers that they do not recognize.)

3.2.3. Overview

Checkout the resource using the CHECKOUT method specifying the workspace in the Target-Selector: header.

3.2.4. Protocol

>> Request

CHECKOUT /foo.html HTTP/1.1
Target-Selector: http://www.acme.com/scenarios.wsp
Host: www.acme.com
Content-Type: text/xml; charset=”utf8”
Content-Length: 0

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/scenarios.wsp
Content-Length: 0

3.2.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=null>
   <working resource in /scenarios.wsp, pred.=RID:1>

3.3. Checkout a revision in a second workspace

3.3.1. Objective

Another user will checkout the same revision of the versioned resource in a different workspace to perform parallel development.

3.3.2. Illustrates

Since the workspace is the context for working resources, it is possible for another user to create another workspace and checkout the same revision for change.  The changes will be maintained separately within the server, and can be independently addressed using the workspace name and resource name together.

3.3.3. Overview

Step 1: Create a workspace.

Use MKRESOURCE to create another workspace called /second.wsp.

Step 2: Checkout the revision.

Use the CHECKOUT method with the Target-Selector: header to check out the resource /foo.html into /second.wsp.

Note that the correct workspace name is returned as part of the response confirming that the header was successfully received.

3.3.4. Protocol

Step 1: Create a workspace.

>> Request

MKRESOURCE /second.wsp HTTP/1.1
Host: www.acme.com
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8” ?>
<D:propertyupdate xmlns:D=”DAV:”>
   <D:set>
      <D:prop>
         <D:resourcetype><D:workspace-resourcetype/></D:resourcetype>
      </D:prop>
   </D:set>
</D:propertyupdate>

 

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/default.wsp
Content-Length: 0

Step 2: Checkout the revision.

>> Request

CHECKOUT /foo.html HTTP/1.1
Target-Selector: http://www.acme.com/second.wsp
Host: www.acme.com
Content-Length: 0

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/second.wsp
Content-Length: 0

3.3.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace>
/second.wsp <workspace>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=null>
   <working resource in /scenarios.wsp, pred.=RID:1>
   <working resource in /second.wsp, pred.=RID:1>

3.4. Check-in using a current label

3.4.1. Objective

Check in a working resource that will have a label assigned by the “current label” property of a workspace.

3.4.2. Illustrates

Workspaces do not only identify sets of working resources.  Workspaces can be used to define a default label for revisions checked in through that workspace.  The label is stored in the <DAV:current-label> property of the workspace.

3.4.3. Overview

Step 1: Define the current label for the workspace.

Use the PROPPATCH method to set the <DAV:current-label> property of /scenarios.wsp to “Mercury”.  A label value must be a valid URI segment.

Step 2: Check in the working resource.

Now when the working resource is checked in it will become a revision labeled “Mercury”.  Check-in is performed using the CHECKIN method and specifying the working resource workspace in the Target-Selector: header.

3.4.4. Protocol

Step 1: Define the current label for the workspace.

>> Request

PROPPATCH /scenarios.wsp HTTP/1.1
Host: www.acme.com
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8” ?>
<D:propertyupdate xmlns:D=”DAV:”>
   <D:set>
      <D:prop>
         <D:current-label>Mercury</D:current-label>
      </D:prop>
   </D:set>
</D:propertyupdate>

>> Response

HTTP/1.1 207 Multi-Status
Target-Selector: http://www.acme.com/default.wsp
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8”>
<D:multistatus xmlns:D=”DAV:”>
   <D:response>
      <D:href>http://www.acme.com/scenarios.wsp</D:href>
      <D:propstat>
         <D:prop><D:current-label/></D:prop>
         <D:status>HTTP/1.1 200 OK</D:status>
      </D:propstat>
      <D:responsedescription>OK</D:responsedescription>
   </D:response>
</D:multistatus>

Step 2: Check in the working resource.

>> Request

CHECKIN /foo.html HTTP/1.1
Target-Selector: http://www.acme.com/scenarios.wsp
Host: www.acme.com
Content-Length: 0

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/scenarios.wsp
Content-Length: 0

3.4.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace, current-label=”Mercury”>
/second.wsp <workspace>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=RID:2>
   <RID:2, pred.=RID:1, succ.=null, labels=(”Mercury”)>
   <working resource in /second.wsp, pred.=RID:1>

3.5. Check-in the second working resource using a current label

3.5.1. Objective

The second user will also create a current label for their workspace and check in their working resource with that label.

3.5.2. Illustrates

Using independent workspaces and distinct labels, multiple users can make independent changes to the versioned resource and save their changes in the version history.

3.5.3. Overview

Step 1: Define the current label for the second workspace.

Use PROPPATCH method to set the “current label” of the workspace /second.wsp to “Venus”.

Step 2: Check in the working resource for that workspace.

CHECKIN the working resource to a revision labeled “Venus”.

3.5.4. Protocol

Step 1: Define the current label for the workspace.

>> Request

PROPPATCH /second.wsp HTTP/1.1
Host: www.acme.com
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8” ?>
<D:propertyupdate xmlns:D=”DAV:”>
   <D:set>
      <D:prop>
         <D:current-label>Venus</D:current-label>
      </D:prop>
   </D:set>
</D:propertyupdate>

>> Response

HTTP/1.1 207 Multi-Status
Target-Selector: http://www.acme.com/default.wsp
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8”>
<D:multistatus xmlns:D=”DAV:”>
   <D:response>
      <D:href>http://www.acme.com/second.wsp</D:href>
      <D:propstat>
         <D:prop><D:current-label/></D:prop>
         <D:status>HTTP/1.1 200 OK</D:status>
      </D:propstat>
      <D:responsedescription>OK</D:responsedescription>
   </D:response>
</D:multistatus>

Step 2: Check in the working resource.

>> Request

CHECKIN /foo.html HTTP/1.1
Target-Selector: http://www.acme.com/second.wsp
Host: www.acme.com
Content-Length: 0

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/second.wsp
Content-Length: 0

3.5.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace, current-label=”Mercury”>
/second.wsp <workspace, current-label=”Venus”>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=(RID:2, RID:3)>
   <RID:2, pred.=RID:1, succ.=null, labels=(”Mercury”)>
   <RID:3, pred.=RID:1, succ.=null, labels=(”Venus”)>

3.6. Get an old revision by using a revision label

3.6.1. Objective

Get a particular revision of the resource based upon its label.

3.6.2. Illustrates

Labels can be used to identify revisions in a versioned resource’s history.  By specifying a label in the Target-Selector: header clients can retrieve a labeled revision.

3.6.3. Overview

The GET method is simply annotated with a Target-Selector: header to get a particular labeled revision.

3.6.4. Protocol

>> Request

GET /foo.html HTTP/1.1
Target-Selector: label:Mercury
Host: www.acme.com
Content-Length: 0

>> Response

HTTP/1.1 200 OK
Target-Selector: label:Mercury
Content-Type: text/plain; charset=”ascii”
Content-Length: xxx

This is the new content.

 

3.6.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace, current-label=”Mercury”>
/second.wsp <workspace, current-label=”Venus”>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=(RID:2, RID:3)>
   <RID:2, pred.=RID:1, succ.=null, labels=(”Mercury”)>
   <RID:3, pred.=RID:1, succ.=null, labels=(”Venus”)>

3.7. Manipulate labels

3.7.1. Objective

To add, move, and remove a label from a revision.

3.7.2. Illustrates

Labels are a simple means of identifying revisions of a versioned resource.

A given label cannot be used for more than one revision of a given versioned resource.  If a label is set on a revision it will be removed from any revision that previously had that label (i.e., it moves).

3.7.3. Overview

Label operations are accomplished using the LABEL method on the versioned resource URL.  The body of the LABEL method describes the operation.

Step 1: Add a label.

Add the label “Earth” to the revision of the /foo.html resource that is currently labeled “Mercury”.  This requires the LABEL method with a Target-Selector of label:Mercury and a <set> directive in the body.

Step 2: Move a label.

Move the label “Earth” to the revision that is currently labeled “Venus”.  Moving a label is implicitly achieved by setting it to another revision.

Step 3: Remove a label.

Remove the label “Earth” from the revision.

3.7.4. Protocol

Step 1: Add a label.

>> Request

LABEL /foo.html HTTP/1.1
Target-Selector: label:Mercury
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<? xml version=”1.0” encoding=”utf-8” ?>
<D:label xmlns:D=”DAV:”>
   <D:set>Earth</D:set>
</D:label>

>> Response

HTTP/1.1 200 OK
Target-Selector: label:Mercury
Content-Length: 0

Step 2: Move a label.

>> Request

LABEL /foo.html HTTP/1.1
Target-Selector: label:Venus
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<? xml version=”1.0” encoding=”utf-8” ?>
<D:label xmlns:D=”DAV:”>
   <D:set>Earth</D:set>
</D:label>

>> Response

HTTP/1.1 200 OK
Target-Selector: label:Venus
Content-Length: 0

Step 3: Remove a label.

>> Request

LABEL /foo.html HTTP/1.1
Target-Selector: label:Earth
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<? xml version=”1.0” encoding=”utf-8” ?>
<D:label xmlns:D=”DAV:”>
   <D:remove>Earth</D:remove>
</D:label>

>> Response

HTTP/1.1 200 OK
Target-Selector: label:Earth
Content-Length: 0

3.7.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace, current-label=”Mercury”>
/second.wsp <workspace, current-label=”Venus”>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=(RID:2, RID:3)>
   <RID:2, pred.=RID:1, succ.=null, labels=(”Mercury”)>
   <RID:3, pred.=RID:1, succ.=null, labels=(”Venus”)>

4. Introducing Activities

4.1. Create an activity

4.1.1. Objective

Create an activity resource to represent the set of changes to one or more versioned resources.

4.1.2. Illustrates

An activity is simply a resource within the server.  Once created the activity can be used to represent a thread of development.

4.1.3. Overview

Activities are created using the MKRESOURCE method where the resource type is set to <DAV:activity-resourcetype>.

This scenario creates a new activity called /mainstream.

4.1.4. Protocol

>> Request

MKRESOURCE /mainstream HTTP/1.1
Host: www.acme.com
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8” ?>
<D:propertyupdate xmlns:D=”DAV:”>
   <D:set>
      <D:prop>
         <D:resourcetype><D:activity-resourcetype/></D:resourcetype>
      </D:prop>
   </D:set>
</D:propertyupdate>

 

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/default.wsp
Content-Length: 0

4.1.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace, current-label=”Mercury”>
/second.wsp <workspace, current-label=”Venus”>
/mainstream <activity>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.= RID:1>
   <RID:1, pred.=RID:0, succ.=(RID:2, RID:3)>
   <RID:2, pred.=RID:1, succ.=null, labels=(”Mercury”)>
   <RID:3, pred.=RID:1, succ.=null, labels=(”Venus”)>

4.2. Checkout in an activity

4.2.1. Objective

Check-out a revision within the context of a particular activity.

4.2.2. Illustrates

Activities group together sets of related changes.  This grouping allows conflict detection and merging of overlapping changes.  Activities also provide isolation from these conflicting changes to allow for parallel development.

A working resource gets its activity from the workspace in which it was checked out.  If the workspace has a current-activity defined, the working resource is added to that activity.  The resource remains in the activity until the activity is deleted.

4.2.3. Overview

Step 1: Define the current activity for the workspace.

The current activity for a workspace is set using PROPPATCH on the <DAV:current-activity> property.  The value is the URL of an activity resource.

Step 2: Check-out the revision into the workspace.

All subsequent check-outs in this workspace (until the current-activity is changed) will form part of the same activity.

After the revision has been checked out into a working resource, it will have its <DAV:activity> property set to http://www.acme.com/mainline.

4.2.4. Protocol

Step 1: Define the current activity for the workspace.

>> Request

PROPPATCH /scenarios.wsp HTTP/1.1
Host: www.acme.com
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8” ?>
<D:propertyupdate xmlns:D=”DAV:”>
   <D:set>
      <D:prop>
         <D:current-activity>
            <D:href>http://www.acme.com/mainstream</D:href>
         </D:current-activity>
      </D:prop>
   </D:set>
</D:propertyupdate>

>> Response

HTTP/1.1 207 Multi-Status
Target-Selector: http://www.acme.com/default.wsp
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8”>
<D:multistatus xmlns:D=”DAV:”>
   <D:response>
      <D:href>http://www.acme.com/scenarios.wsp</D:href>
      <D:propstat>
         <D:prop><D:current-activity/></D:prop>
         <D:status>HTTP/1.1 200 OK</D:status>
      </D:propstat>
      <D:responsedescription>OK</D:responsedescription>
   </D:response>
</D:multistatus>

Step 2: Check-out the revision into the workspace.

>> Request

CHECKOUT /foo.html HTTP/1.1
Target-Selector: http://www.acme.com/scenarios.wsp
Host: www.acme.com
Content-Length: 0

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/scenarios.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/scenarios.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>

4.2.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace, current-label=”Mercury”, current-activity=”/mainstream”>
/second.wsp <workspace, current-label=”Venus”>
/mainstream <activity>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=(RID:2, RID:3)>
   <RID:2, pred.=RID:1, succ.=null, labels=(”Mercury”)>
   <RID:3, pred.=RID:1, succ.=null, labels=(”Venus”)>
   <working resource in /scenarios.wsp, pred.=RID:3, succ.=null, activity=”/mainstream”>

4.3. Check-in and create a new revision in that activity

4.3.1. Objective

Check in the modified resource and have it associated with that activity.

4.3.2. Illustrates

Activities ‘remember’ the resources that were created in them, even when those resources migrate from working resources to revisions.

A single activity can have multiple revisions of a versioned resource, say if the same resource was checked-out and checked-in multiple times.  The activity continues to represent the unit of work associated with a logical change to the versioning store.

4.3.3. Overview

Step 1: Check-in the working resource.

Check-in the working resource using CHECKIN.  The resulting revision contains a <DAV:activity> property equivalent to the activity property of the working resource.

Step 2: Look at the activity property.

For the purposes of this scenario we will check the activity property of the resulting revision to see that it has the required activity URL.

4.3.4. Protocol

Step 1: Check-in the working resource.

>> Request

CHECKIN /foo.html HTTP/1.1
Target-Selector: http://www.acme.com/scenarios.wsp
Host: www.acme.com
Content-Length: 0

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/scenarios.wsp
Content-Length: 0

Step 2: Look at the activity property.

>> Request

PROPFIND /foo.html HTTP/1.1
Target-Selector: http://www.acme.com/scenarios.wsp
Host: www.acme.com
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8” ?>
<D:propfind xmlns:D=”DAV:”>
   <D:prop>
      <D:activity/>
   </D:prop>
</D:propfind>

>> Response

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

<?xml version=”1.0” encoding=”utf-8”>
<D:multistatus xmlns:D=”DAV:”>
   <D:response>
      <D:href>http://www.acme.com/foo.html</D:href>
      <D:propstat>
         <D:prop>
            <D:activity>http://www.acme.com/mainstream</D:activity>
         </D:prop>
         <D:status>HTTP/1.1 200 OK</D:status>
      </D:propstat>
   </D:response>
   <D:responsedescription>OK</D:responsedescription>
</D:multistatus>

4.3.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace, current-label=”Mercury”, current-activity=”/mainstream”>
/second.wsp <workspace, current-label=”Venus”>
/mainstream <activity>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=(RID:2, RID:3)>
   <RID:2, pred.=RID:1, succ.=null>
   <RID:3, pred.=RID:1, succ.=RID:4, labels=(”Venus”)>
   <RID:4, pred.=RID:3, succ.=null, labels=(”Mercury”), activity=”/mainstream”>

4.4. Merge activities

4.4.1. Objective

Make a change to the same versioned resource in another activity, then merge the two activities to illustrate the changes were integrated.

4.4.2. Illustrates

To support parallel development versioned resources can be checked out and tracked within distinct activities.  When the client chooses to merge the work done in separate activities they will produce a new working resource to accept the combined changes, then indicate a merge in the activities to show the work streams have been brought together.

4.4.3. Overview

Step 1: Create conflicting changes in a second activity.

Step 1.1: Create a second activity.

The second activity resource will be called /bugfix.  So do a MKRESOURCE to /bugfix where the <DAV:resource-type> is <DAV:activity-resourcetype>.

Step 1.2: Set the current activity of the workspace.

PROPPATCH the <DAV:current-activity> property on the /scenarios.wsp resource to be the /bugfix activity.

Step 1.3: Check-out the versioned resource.

To generate a detectable conflict, we must checkout/check-in an earlier revision of /foo.html such that there will be two revisions of /foo.html with the same predecessor.

Here we will assume that the client has previously retrieved the stable-href for foo.html RID:3 (say, by PROPFINDing on the revision labeled “Venus”) and has remembered that it is “/repo/vr/VRID:9/RID:3”.

A CHECKOUT of /foo.html revision (RID:3) will create a new working resource in /scenarios.wsp that is associated with the /bugfix activity. 

This scenario demonstrates two clients in their personal workspaces basing their differing changes upon the same version revision.

Step 1.4: Make some conflicting changes to the working resource.

Make some changes to the versioned resource in this activity.  Here we’ll assume that the changes are conflicting by just performing a PUT on the contents of the working resource.

Step 1.5: Check-in the conflicting changes.

Check the changes back in to make them part of the versioned resource’s history (RID:5).

By this point we have created RID:4 and RID:5 in different activities, both are successors of RID:3.  The versioning system considers these conflicts since there is no unified line of descent from RID:3.

Requesting a conflicts report will show that VRID:9 is in conflict.

Note that since the current label property is still set for the /scenarios workspace the label “Mercury” must move from RID:2 to RID:5.

Step 2: Create a working resource to be the merge successor.

A new working resource will be created to receive the merged changes from the conflicting revisions.  The new working resource can be created from any revision of the versioned resource.

In this scenario we checkout in the scenarios workspace which will select the latest revision (RID:5) into the activity /mainstream.

Step 3: Merge the resources.

The resource merge is handled by the client.  In general the merging semantics will be predicated upon the content type or the changes that were made to the resource properties.

Versioning protocol does not attempt to automate the merging of the resource, rather it allows the revision history to reflect the merging actions that were undertaken by the client.

In this scenario we assume that the client has retrieved and considered revision /repo/vr/VRID:9/RID:4 when resolving the conflict in the working resource.

Step 4: Indicate the merge on the working resource.

The merging is shown by sending the MERGE method to the working resource that is the target of the merge, and in the body of the request indicating the revisions that were merged.

The MERGE method allows clients to incrementally add and remove entries from the merge list.

Step 5: Check-in the merged resource.

Finally, the merged resource is checked back in to make the version history complete.

Notice that the predecessors of RID:6 show that this revision is a merge of RID:5 and RID:4.  This resolves the conflict for the versioning system.

4.4.4. Protocol

Step 1: Create conflicting changes in a second activity.

Step 1.1: Create a second activity.

>> Request

MKRESOURCE /bugfix HTTP/1.1
Host: www.acme.com
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8” ?>
<D:propertyupdate xmlns:D=”DAV:”>
   <D:set>
      <D:prop>
         <D:resourcetype><D:activity-resourcetype/></D:resourcetype>
      </D:prop>
   </D:set>
</D:propertyupdate>

 

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/default.wsp
Content-Length: 0

Step 1.2: Set the current activity of the workspace.

>> Request

PROPPATCH /scenarios.wsp HTTP/1.1
Host: www.acme.com
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8” ?>
<D:propertyupdate xmlns:D=”DAV:”>
   <D:set>
      <D:prop>
         <D:current-activity>
            <D:href>http://www.acme.com/bugfix</D:href>
         </D:current-activity>
      </D:prop>
   </D:set>
</D:propertyupdate>

>> Response

HTTP/1.1 207 Multi-Status
Target-Selector: http://www.acme.com/default.wsp
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8”>
<D:multistatus xmlns:D=”DAV:”>
   <D:response>
      <D:href>http://www.acme.com/scenarios.wsp</D:href>
      <D:propstat>
         <D:prop><D:current-activity/></D:prop>
         <D:status>HTTP/1.1 200 OK</D:status>
      </D:propstat>
      <D:responsedescription>OK</D:responsedescription>
   </D:response>
</D:multistatus>

Step 1.3: Check-out the versioned resource.

>> Request

CHECKOUT /repo/vr/VRID:9/RID:3 HTTP/1.1
Target-Selector: http://www.acme.com/scenarios.wsp
Host: www.acme.com
Content-Type: text/xml; charset=”utf-8”
Content-Length: 0

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/scenarios.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/scenarios.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>

Step 1.4: Make some conflicting changes to the working resource.

>> Request

PUT /foo.html HTTP/1.1
Target-Selector: http://www.acme.com/scenarios.wsp
Host: www.acme.com
Content-Type: text/plain
Content-Length: xxx

This is conflicting content.

>> Response

HTTP/1.1 200 OK
Target-Selector: http://www.acme.com/scenarios.wsp
Content-Length: 0

Step 1.5: Check-in the conflicting changes.

>> Request

CHECKIN /foo.html HTTP/1.1
Target-Selector: http://www.acme.com/scenarios.wsp
Host: www.acme.com
Content-Length: 0

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/scenarios.wsp
Content-Length: 0

Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace, current-label=”Mercury”, current-activity=”/bugfix”>
/second.wsp <workspace, current-label=”Venus”>
/mainstream <activity>
/bugfix <activity>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=(RID:2, RID:3)>
   <RID:2, pred.=RID:1, succ.=null>
   <RID:3, pred.=RID:1, succ.=(RID:4, RID:5), labels=(”Venus”)>
   <RID:4, pred.=RID:3, succ.=null, activity=”/mainstream”>
   <RID:5, pred.=RID:3, succ.=null, labels=(”Mercury”), activity=”/bugfix”>

Step 2: Create a working resource to be the merge successor.

>> Request

CHECKOUT /foo.html HTTP/1.1
Target-Selector: http://www.acme.com/scenarios.wsp
Host: www.acme.com
Content-Length: 0

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/scenarios.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/scenarios.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>

Step 3: Merge the resources.

>> Request

PUT /foo.html HTTP/1.1
Target-Selector: http://www.acme.com/scenarios.wsp
Host: www.acme.com
Content-Type: text/plain
Content-Length: xxx

This is the merged content.

>> Response

HTTP/1.1 200 OK
Target-Selector: http://www.acme.com/scenarios.wsp
Content-Length: 0

Step 4: Indicate the merge on the working resource.

>> Request

MERGE /foo.html HTTP/1.1
Target-Selector: http://www.acme.com/scenarios.wsp
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8” ?>
<D:request xmlns:D=”DAV:”>
   <D:add>http://www.acme.com/repo/vr/VRID:9/RID:4</D:add>
</D:request>

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/scenarios.wsp
Content-Type: text/xml; charset=”utf-8”
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:status>HTTP/1.1 200 OK</D:status>
</D:response>

4.4.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace, current-label=”Mercury”, current-activity=”/bugfix”>
/second.wsp <workspace, current-label=”Venus”>
/mainstream <activity>
/bugfix <activity>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=(RID:2, RID:3)>
   <RID:2, pred.=RID:1, succ.=null>
   <RID:3, pred.=RID:1, succ.=(RID:4, RID:5), labels=(”Venus”)>
   <RID:4, pred.=RID:3, succ.=RID:6, activity=”/mainstream”>
   <RID:5, pred.=RID:3, succ.=RID:6, activity=”/bugfix”>
   <RID:6, pred.=(RID:5, RID:4), succ.=null, labels=(”Mercury”), activity=”/bugfix”>

4.5. Change the workspace RSR

4.5.1. Objective

Change the selection rule of an extended workspace to select revisions from a named activity, or the revision with a specified labeled, or the chronologically latest.

4.5.2. Illustrates

So far the scenarios have all used workspaces in their basic form.  A basic workspace is used to “encapsulate” working resources.

An extended workspace adds the ability to specify which one of the versioned resource’s revisions is selected for operations on the versioned resource URL where no working resource exists.

The selection is based upon a “revision selection rule” (RSR) which is stored as a property of the workspace. RSRs can be used to specify complex searches through the revision selection history using combinations of primitive selection criteria.

4.5.3. Overview

The workspace RSR is changed using the PROPPATCH method.

The RSR is stored in the <DAV:revision-selection-rule> property.  The value of the property is an XML fragment that describes the selection rule.

In this scenario we will set the rule to select the revision that satisfies the following criteria:

1)       choose the revision in the activity /demo, or

2)       choose the revision labeled “working”, or

3)       choose the chronologically latest revision.

Note that if non of the selection rules are satisfied there is no revision selected.

4.5.4. Protocol

>> Request

PROPPATCH /scenarios.wsp HTTP/1.1
Host: www.acme.com
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8” ?>
<D:propertyupdate xmlns:D=”DAV:”>
   <D:set>
      <D:prop>
         <D:revision-selection-rule>
            <D:rsr-or>
               <D:href>http://www.acme.com/demo</D:href>
               <D:label>working</D:label>
               <D:rsr-latest/>
            </D:rsr-or>
         </D:revision-selection-rule>
      </D:prop>
   </D:set>
</D:propertyupdate>

>> Response

HTTP/1.1 207 Multi-Status
Target-Selector: http://www.acme.com/default.wsp
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8”>
<D:multistatus xmlns:D=”DAV:”>
   <D:response>
      <D:href>http://www.acme.com/scenarios.wsp</D:href>
      <D:propstat>
         <D:prop><D:revision-selection-rule/></D:prop>
         <D:status>HTTP/1.1 200 OK</D:status>
      </D:propstat>
      <D:responsedescription>OK</D:responsedescription>
   </D:response>
</D:multistatus>

4.5.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace, current-label=”Mercury”, current-activity=”/bugfix”, RSR=(/demo | “working” | latest)>
/second.wsp <workspace, current-label=”Venus”>
/mainstream <activity>
/bugfix <activity>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=(RID:2, RID:3)>
   <RID:2, pred.=RID:1, succ.=null>
   <RID:3, pred.=RID:1, succ.=(RID:4, RID:5), labels=(”Venus”)>
   <RID:4, pred.=RID:3, succ.=RID:6, activity=”/mainstream”>
   <RID:5, pred.=RID:3, succ.=RID:6, activity=”/bugfix”>
   <RID:6, pred.=(RID:5, RID:4), succ.=null, labels=(”Mercury”), activity=”/bugfix”>

5. Configurations of Revisions

5.1. Create a "labeled configuration"

5.1.1. Objective

Create a distinct set of revisions by labeling them with the same label.

5.1.2. Illustrates

Labels can be used as a simple mechanism for identifying a particular revision of a versioned resource.  By using a common label across multiple versioned resources, the user can create a simple “configuration” of versioned resource revisions.

Since a label can only be applied to a single revision of a versioned resource, a labeled configuration will never be ambiguous about the revision of a versioned resource it selects.

However, since labels can be moved labeled configurations are not a good mechanism for identifying a repeatable set of revisions.

5.1.3. Overview

Simply use the LABEL method to apply a label to the revision.  When selecting resources from the “configuration” the client requests the labeled revision.

In this scenario we are creating a “configuration” labeled “Published”.

5.1.4. Protocol

>> Request

LABEL /foo.html HTTP/1.1
Target-Selector: label:Mercury
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<? xml version=”1.0” encoding=”utf-8” ?>
<D:label xmlns:D=”DAV:”>
   <D:set>Published</D:set>
</D:label>

>> Response

HTTP/1.1 200 OK
Target-Selector: label:Mercury
Content-Length: 0

5.1.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace, current-label=”Mercury”, current-activity=”/bugfix”, RSR=(/demo | “working” | latest)>
/second.wsp <workspace, current-label=”Venus”>
/mainstream <activity>
/bugfix <activity>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=(RID:2, RID:3)>
   <RID:2, pred.=RID:1, succ.=null>
   <RID:3, pred.=RID:1, succ.=(RID:4, RID:5), labels=(”Venus”)>
   <RID:4, pred.=RID:3, succ.=RID:6, activity=”/mainstream”>
   <RID:5, pred.=RID:3, succ.=RID:6, activity=”/bugfix”>
   <RID:6, pred.=(RID:5, RID:4), succ.=null, labels=(”Mercury”, “Published”), activity=”/bugfix”>

5.2. Create a configuration

5.2.1. Objective

Create a configuration resource to identify a set of revisions.

5.2.2. Illustrates

A configuration resource is a set of resource revisions that can be versioned.  Configurations are created using MKRESOURCE and accessed in a similar way to collections.

5.2.3. Overview

Create an empty configuration called /deployed using the MKRESOURCE method.

5.2.4. Protocol

>> Request

MKRESOURCE /deployed HTTP/1.1
Host: www.acme.com
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8” ?>
<D:propertyupdate xmlns:D=”DAV:”>
   <D:set>
      <D:prop>
         <D:resourcetype><D:configuration-resourcetype/></D:resourcetype>
      </D:prop>
   </D:set>
</D:propertyupdate>

 

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/default.wsp
Content-Length: 0

5.2.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace, current-label=”Mercury”, current-activity=”/bugfix”, RSR=(/demo | “working” | latest)>
/second.wsp <workspace, current-label=”Venus”>
/mainstream <activity>
/bugfix <activity>
/deployed <configuration>
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=(RID:2, RID:3)>
   <RID:2, pred.=RID:1, succ.=null>
   <RID:3, pred.=RID:1, succ.=(RID:4, RID:5), labels=(”Venus”)>
   <RID:4, pred.=RID:3, succ.=RID:6, activity=”/mainstream”>
   <RID:5, pred.=RID:3, succ.=RID:6, activity=”/bugfix”>
   <RID:6, pred.=(RID:5, RID:4), succ.=null, labels=(”Mercury”, “Published”), activity=”/bugfix”>

5.3. Add member revisions

5.3.1. Objective

Add the latest revision of /foo.html that is currently in the activity /bugfix to the configuration /deployed.

5.3.2. Illustrates

A configuration provides a mapping from versioned resource to a particular revision of the versioned resource.

Adding a revision to a configuration is achieved using similar protocol to adding a resource to a collection.

5.3.3. Overview

The BIND method is used where the request URI is the version resource being added to the configuration, and the Destination is the configuration resource.

The Target-Selector: header dictates the particular revision of the versioned resource that is added.

5.3.4. Protocol

>> Request

BIND /foo.html HTTP/1.1
Target-Selector: http://www.acme.com/bugfix
Host: www.acme.com
Destination: http://www.acme.com/deployed
Content-Length: 0

>> Response

HTTP/1.1 201 Created
Target-Selector: http://www.acme.com/bugfix
Content-Length: 0

5.3.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace, current-label=”Mercury”, current-activity=”/bugfix”, RSR=(/demo | “working” | latest)>
/second.wsp <workspace, current-label=”Venus”>
/mainstream <activity>
/bugfix <activity>
/deployed <configuration>
   VRID:9 -> RID:6
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=(RID:2, RID:3)>
   <RID:2, pred.=RID:1, succ.=null>
   <RID:3, pred.=RID:1, succ.=(RID:4, RID:5), label=”Venus”>
   <RID:4, pred.=RID:3, succ.=RID:6, activity=”/mainstream”>
   <RID:5, pred.=RID:3, succ.=RID:6, activity=”/bugfix”>
   <RID:6, pred.=(RID:5, RID:4), succ.=null, label=(”Mercury”, “Published”), activity=”/bugfix”>

5.4. Add the configuration to a workspace RSR

5.4.1. Objective

Change the workspace revision selection rule to select the revisions named in the configuration in preference to the “latest” revision.

5.4.2. Illustrates

The configuration is a set of mappings from versioned resource identifier to revision identifier.  This mapping can be added to a revision selection rule to explicitly enumerate the revisions that are chosen for each versioned resource.

5.4.3. Overview

This scenario will change the revision selection rule (RSR) of the /second.wsp workspace to be:

1)                   the revision named in the configuration /deployed, or

2)                   the revision in the /mainstream activity.

Note that if none of the revision selection rules are satisfied for the versioned resource, no revision is selected.

The RSR is changed using the PROPPATCH method on the workspace’s <DAV:revision-selection-rule> property.

5.4.4. Protocol

>> Request

PROPPATCH /second.wsp HTTP/1.1
Host: www.acme.com
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8” ?>
<D:propertyupdate xmlns:D=”DAV:”>
   <D:set>
      <D:prop>
         <D:revision-selection-rule>
            <D:rsr-or>
               <D:href>http://www.acme.com/deployed</D:href>
               <D:href>http://www.acme.com/mainstream</D:href>
            </D:rsr-or>
         </D:revision-selection-rule>
      </D:prop>
   </D:set>
</D:propertyupdate>

>> Response

HTTP/1.1 207 Multi-Status
Target-Selector: http://www.acme.com/default.wsp
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8”>
<D:multistatus xmlns:D=”DAV:”>
   <D:response>
      <D:href>http://www.acme.com/second.wsp</D:href>
      <D:propstat>
         <D:prop><D:revision-selection-rule/></D:prop>
         <D:status>HTTP/1.1 200 OK</D:status>
      </D:propstat>
      <D:responsedescription>OK</D:responsedescription>
   </D:response>
</D:multistatus>

5.4.5. Resource State

/ <collection>
/default.wsp <workspace>
/scenarios.wsp <workspace, current-label=”Mercury”, current-activity=”/bugfix”, RSR=(/demo | “working” | latest)>
/second.wsp <workspace, current-label=”Venus”, RSR=(/deployed | /mainstream)>
/mainstream <activity>
/bugfix <activity>
/deployed <configuration>
   VRID:9 -> RID:6
/foo.html <VRID:9, ordinary>
   <RID:0, pred.=null, succ.=RID:1>
   <RID:1, pred.=RID:0, succ.=(RID:2, RID:3)>
   <RID:2, pred.=RID:1, succ.=null>
   <RID:3, pred.=RID:1, succ.=(RID:4, RID:5), labels=(”Venus”)>
   <RID:4, pred.=RID:3, succ.=RID:6, activity=”/mainstream”>
   <RID:5, pred.=RID:3, succ.=RID:6, activity=”/bugfix”>
   <RID:6, pred.=(RID:5, RID:4), succ.=null, labels=(”Mercury”, “Published”), activity=”/bugfix”>

5.5. Select a revision from the configuration using the updated workspace

5.5.1. Objective

Choose a revision of the resource /foo.html that is selected by a workspace through a configuration.

5.5.2. Illustrates

The configuration resource provides the mapping from versioned resource identifier to revision identifier.  When used as a revision selection rule, and the configuration contains a revision of the versioned resource, that revision is selected by the workspace or no revision is selected.

5.5.3. Overview

This scenario shows a PROPFIND request on the /foo.html selected by the /second.wsp workspace.  The property being requested is the revision identifier (<DAV:revision-id>) which is returned as RID:6 since that is the revision named for VRID:9 in the configuration /deployed which was the matching RSR clause.

5.5.4. Protocol

>> Request

PROPFIND /foo.html HTTP/1.1
Target-Selector: http://www.acme.com/second.wsp
Host: www.acme.com
Content-Type: text/xml; charset=”utf-8”
Content-Length: xxx

<?xml version=”1.0” encoding=”utf-8” ?>
<D:propfind xmlns:D=”DAV:”>
   <D:prop>
      <D:revision-id/>
   </D:prop>
</D:propfind>

>> Response

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

<?xml version=”1.0” encoding=”utf-8”>
<D:multistatus xmlns:D=”DAV:”>
   <D:response>
      <D:href>http://www.acme.com/foo.html</D:href>
      <D:propstat>
         <D:prop>
            <D:revision-id>RID:6</D:revision-id>
         </D:prop>
         <D:status>HTTP/1.1 200 OK</D:status>
      </D:propstat>
   </D:response>
   <D:responsedescription>OK</D:responsedescription>
</D:multistatus>

5.5.5. Resource State

No change

6. Operations on Collections

To be supplied.

6.1. Put a collection under version control

6.2. Checkout a collection

6.3. Add/remove members from the working collection

6.4. Check-in the 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. Baselines

To be supplied.

7.1. Create a baseline

7.2. Use the baseline in a workspace RSR

7.3. Update a baseline

8. International Considerations

This section is not applicable.

9. Security Considerations

This section is not applicable.

10. Scalability

This section is not applicable.

11. Authentication

This section is not applicable.

12. IANA Considerations

This document uses the namespace defined by [RFC2518] for XML elements.  All other IANA considerations mentioned in [RFC2518] also applicable to WebDAV Versioning.

13. Intellectual Property

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 which may cover technology that may be required to practice this standard.  Please address the information to the IETF Executive Director.

14. Acknowledgements

To be supplied.

15. Index

To be supplied.

16. References

[RFC2026] S.Bradner, "The Internet Standards Process", Harvard, 1996, <http://www.ietf.org/rfc/rfc2026.txt>.

 [RFC2119] S.Bradner, "Key words for use in RFCs to Indicate Requirement Levels", Harvard, 1997, <http://www.ietf.org/rfc/rfc2119.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>

[Protocol] G.Clemm, C.Kaler, "Versioning Extensions to WebDAV", Rational Software, Microsoft, 1999, <http://www.ietf.org/internet-drafts/draft-ietf-deltav-versioning-01.2.txt>

17. Authors’ Addresses

Tim Ellison
Object Technology International, Inc.
2670 Queensview Drive
Ottawa, Ontario
Canada
Email: tim_ellison@oti.com