11.2 Core Versioning

DeltaV has a core set of functionality that is required for implementation by any DeltaV compliant server. This section addresses the core versioning model, how to list and access versions, and how to turn on versioning for a resource.

There's a lot of conceptual material to cover in DeltaV, so I won't cover all the requirements or error messages. The DeltaV specification very clearly defines preconditions, or the state the resources must be in for the request to succeed, and the unique identifier that is returned for each failed precondition. It also defines postconditions, or the state the resources must be in after the request has succeeded, and the unique identifier that is returned for each failed postcondition. Thus, DeltaV uses precondition and postcondition identifiers not only for declaring requirements, but also as a way to provide extra information in the response to a failed request. See Section 11.10.2 for more information on how the precondition or postcondition identifiers are marshaled in a response body.

11.2.1 Version-Controlled Resources

When a regular WebDAV resource has versioning "turned on," it retains the same location and URL but is now a version-controlled resource (VCR). The VCR contents and properties change over time, like a regular WebDAV resource. WebDAV operations behave the same way they normally do a lot of the time. In fact, to ordinary WebDAV clients, the VCR appears to be an ordinary resource.

A VCR may be checked out, which means that it is being modified, or checked in. For now, assume that a VCR is checked in because a VCR begins in a checked in state when it is first created. These two states are defined more fully in Sections 11.3.2 and 11.3.4.

A VCR is related to a particular set of version resources. The set of versions constitutes the entire version history for the VCR. The target version is usually the most recently created version (the latest version), but it can be another version instead as shown in Section 11.6.1. The target version is identified by the checked-in^[1] property if the VCR is checked in. A checked-in VCR will always appear to have the same content and dead properties as its target version.

^[1] This property, along with every other property in this chapter, is in the regular DAV: namespace.

The live properties of a VCR may be different from the live properties of the target version. For example, the WebDAV property lockdiscovery exists on a VCR but not on any version. (Versions can't be locked, because they can't be updated.)

The creationdate property exists on both versions and VCRs, but on the latter, the property should contain the date the resource was created, which may precede the creation date of the target version. The getlastmodified property on a checked-in VCR should be the same as the creationdate of the latest version.

VCRs and unversioned resources may coexist inside ordinary WebDAV collections, and they have the same resourcetype property value. The resourcetype property value stays the same so that existing non-DeltaV clients can interoperate with DeltaV resources as if both versionable and unversioned resources were simple RFC2518 resources. In order to see if a resource is versioned, a DeltaV client must check to see if the resource has DeltaV properties like checked-in or checked-out.

11.2.2 Versions

A resource can have a number of versions corresponding to instances of that resource. Those versions themselves are resources, too. However, typically versions do not appear in the same collection as the resource, because a directory listing containing versions mixed with versioned resources might confuse clients or users. A DeltaV client takes special steps to discover the existence and location of versions and typically shows the list of versions only when the user is interested in that information.

A version has a body and properties and a URL, just like any regular WebDAV resource. The server automatically creates a new version when a VCR is changed, and the server decides where to put it and what URL to assign to it.

Versions are linked to other versions according to their derivation. When a new version is derived from an older version, the new version is called a successor of the older version, and the previous version is a predecessor of the new version. The predecessor of a given version isn't necessarily the most recent pre-existing version, although it often is. The first version is the root version and has no predecessor. The latest version is the one most recently created, and it has no successor.

The body and dead properties of a version must never change, whether it's an older version or the one just created.

Storing Versions

Versioning systems are frequently built on top of nonversioning file systems. The simplest approach to storing versions would be to store a full copy of the file every time a new version is created. However, it may be wasteful to store full copies when one version may differ from the next only slightly. Instead, many systems store a delta or a diff for each new version, where each delta is a precise description of the difference between the new version and the previous version.

Although versions may be stored as deltas, DeltaV requires full bodies to be sent. This choice does have costs for both network and software performance, but it would complicate the standard, and in this case optimization choices are best made at a lower level. General mechanisms for transferring deltas rather than full files have already been defined for HTTP [RFC3229].

Each version has its own live properties, which may have different values. For example, the creationdate property of each version should have the date the version was created (which is the same as the getlastmodifed property for the same version). Most live properties on versions won't change over time. However, some are designed to change, such as successor-set, which changes when a new successor version is created.

Some useful properties of versions:

• predecessor-set contains the list of versions from which this version was derived.

• successor-set contains the list of versions that were derived from this version.

• version-name is the name of the version, any value chosen by the server.

• creator-displayname is a server-calculated property with some user-readable description of who created the version.

• comment can be any text string, but it's usually some explanation of why the version was created or how it differs from the previous version (set by the version's creator).

11.2.3 Core Versioning Model

Figure 11-2 illustrates the basic components in a DeltaV-compliant repository. The client can look at the properties of each resource to find out the kind of resource it is.

Figure 11-2. Core versioning.

We already know the resources without any versioning properties: docs/ is a regular collection, and logo.gif is a regular resource.

The file letter.html has the same resource type as logo.gif (an empty resourcetype value), but it also has the checked-in property, so the client can tell that letter.html:

• Is a version-controlled resource.

• Is checked in, so may not be writable as is (shown shaded in Figure 11-2).

• Has a target version identified by the URL in the value of the checked-in property. (In figures in this chapter, properties with URL values like checked-in are shown with arrows pointing to the resource they refer to.)

• Has the same contents and dead properties as its target version.

If the client is handed a URL to a resource that it found to have the version-name property, the client can deduce that it is a version, that it is not writable, that it can't be checked out or checked in, and so on.

Note that a version must have the same resource type as the VCR it came from. A version is by definition not a new resource type but an existing regular resource that behaves differently. All of the resources represented in Figure 11-2 would have an empty resource type except one, and that's the docs/ collection.

11.2.4 Accessing Versions

Assume that a resource exists, and the user wants to find out if past versions exist and access one of them. How is this done? The first step is to find out if a resource is a VCR or not. If it is, it will have either the checked-out or the checked-in live property, depending on its current state. The checked-in property contains the URL to the target version, so the client can simply use that URL to find out more about the target version. The client could then query the target version's predecessor-set property to find the previous version's URL, and thus eventually discover every version in the version history.

Discovering version URLs one by one is slow. Thus, DeltaV requires every VCR to support the version-tree report to allow all versions to be discovered in one request. The version-tree report is a special kind of report available with the REPORT method defined in DeltaV, described in the next section.

To query the properties of a single version, the client issues a PROPFIND request directly to the version. Similarly, to download the body of a version, the client issues a GET request.

11.2.5 Viewing All Versions

DeltaV defines reports in order to streamline frequent but expensive information-finding processes. Usually, the information returned in a REPORT could be also found by querying live properties across a number of resources and collating the results. However, both client and server may find the processing and communication costs of that approach prohibitive.

In a REPORT request, the client asks for a specific report known to be supported by the server. The client may also provide some variables that affect the report output. For example, in the version-tree report, the client provides the names of the properties it wants to see for every version returned in the report results.

Functionally, the version-tree report is very similar to a depth 1 PROPFIND response. However, a depth 1 PROPFIND response could not be used to find all the versions in a version tree, because the versions may not be in the same collection and because there could be other resources in the same collections where versions appear. DeltaV makes no requirements about where versions must exist.

In Listing 11-1, only one property is requested (the version-name property), but any number of properties can be requested, as in a PROPFIND request. The response is a 207 Multi-Status response just like a PROPFIND response showing two versions.

Listing 11-1 REPORT request and response (version-tree report).

 REPORT /docs/index.html HTTP/1.1 Host: www.example.com Content-Type: text/xml; charset="utf-8" Content-Length: xxxx  <?xml version="1.0" encoding="utf-8" ?> <D:version-tree xmlns:D="DAV:">    <D:prop>       <D:version-name/>    </D:prop> </D:version-tree> HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx  <?xml version="1.0" encoding="utf-8" ?> <multistatus xmlns="DAV:">    <response>       <href>http://www.example.com/vers/index.html.1</href>       <propstat>          <prop>             <version-name>V1</version-name>          </prop>          <status>HTTP/1.1 200 OK</status>       </propstat>    </response>    <response>       <href>http://www.example.com/vers/index.html.2</href>       <propstat>          <prop>             <version-name>V2</version-name>          </prop>          <status>HTTP/1.1 200 OK</status>       </propstat>    </response> </multistatus> 

11.2.6 Turning on Versioning

If a resource does not have the checked-out or checked-in property, it is not a version-controlled resource. The client can ask the server to turn it into a VCR with the VERSION-CONTROL method. The VERSION-CONTROL method does not need a body in this case (see Listing 11-2).

Listing 11-2 VERSION-CONTROL.

 VERSION-CONTROL /docs/index.html HTTP/1.1 Host: www.example.com  

Some versioning servers require all files to be under version control. These servers automatically create VCRs whenever a new resource is created with PUT. Many source control systems have the policy that all noncollection resources must be version controlled. The client can tell if a new resource has been created as a VCR only by querying the resource after it has been created.

Note that DeltaV defines no way to undo a VERSION-CONTROL. In other words, there's no direct way to turn a VCR into a regular resource. A VCR's latest version can be copied to create a new nonversioned resource, but of course that's a new resource with new values for properties like creationdate.