Versioning

The information in this document is organized under the following headings:


DeltaV Overview

The web versioning and configuration management protocol DeltaV has been developed as an open standards-based infrastructure that supports collaborative development scenarios and includes:

  • explicit versioning

  • automatic versioning for versioning-unaware clients

  • version history management

  • workspace management

  • baseline management

  • activity management

  • URL namespace versioning

The DeltaV protocol is an extension to the WebDAV (Web Distributed Authoring and Versioning) protocol, which itself extends the Hypertext Transfer Protocol (HTTP), the core network protocol that carries web traffic between a web server and a web browser.

Despite its name, the WebDAV protocol only provides facilities for remote collaborative authoring of documents and does not provide any versioning capabilities.

DeltaV itself is a network protocol (IETF RFC 3253 http://www.ietf.org/rfc/rfc3253.txt) that allows remote versioning and configuration management of documents that are stored in a web server. It defines four implementation levels, implementing 11 features.

graphics/deltavpack.png

Versioning in Tamino WebDAV

Tamino WebDAV provides a URL space in which all versions of an object are located.

For the default context of WebDAV the URL is as follows:

http://<host:port>/tamino/<dbname>/ino:dav/ino:davHistory/<historyID>/<versionID>

All objects are dealt with primarily as non-XML objects.

In the case of resources that are stored outside of the WebDAV context in a collection of the Tamino namespace (ino:<collection>), for instance in order to follow a schema, the convention enforced here is that for an object named for example myCollection a Tamino collection v.myCollection is expected. Should this dedicated location bearing the prefix "v." not exist then the creation of versions will fail.

Subversion Overview

Subversion is an open source version control system. For more details about Subversion, refer to http://subversion.tigris.org/.

Tamino's WebDAV versioning functionality can also be used via the Subversion protocol. This feature can be used to connect a Subversion client to a Tamino repository. After you have set up a Tamino Subversion repository, you can use a Subversion client to check files into and out of this repository.

We recommend the Eclipse Subversion client "Subclipse". For details, refer to http://subclipse.tigris.org/.

Start of instruction setTo set up a Tamino Subversion repository

Choose a name that is not the same as the name of any existing WebDAV collection or Subversion repository in the referenced Tamino database.

  • Issue the following command:

    http://<host>/tamino/<dbname>/ino:collection?_admin=ino:CreateSvnRepository("<name>")

    Example: Database name: "mydb"; repository name: "myrepos":

    http://localhost/tamino/mydb/ino:collection?_admin=ino:CreateSvnRepository("myrepos")

Start of instruction setTo access a Tamino Subversion repository from a Subversion client

  • Issue a command of the following form:

    http://localhost/tamino/mydb/ino:dav/ino:dav/myrepos

Start of instruction setTo remove a Tamino Subversion repository

  • When the Tamino Subversion repository is no longer needed, it can be removed by issuing the following command.

    Warning:
    The entire contents of the repository will be deleted.
    http://<host>/tamino/<dbname>/ino:collection?_admin=ino:RemoveSvnRepository("<name>")

Basic Versioning Functions

Tamino WebDAV supports the following HTTP methods as defined in RFC 3253:

VERSION-CONTROL

The Version-Control feature provides support for putting a resource under version control, creating an associated version-controlled resource and version history resource. A server indicates that it supports the version-control feature by including the string "version-control" as a field in the DAV header in the response to an OPTIONS request.

The version-control feature must be supported if any other versioning feature is supported.

Putting a resource under version control

In order to track the history of the content and dead properties of a versionable resource, an author can put the resource under version control with a VERSION-CONTROL request. A VERSION-CONTROL request performs three distinct operations:

  1. It creates a new version history resource (VHR). Each version history resource is assigned a new distinct and unique server-defined URL.

  2. It creates a new version resource (VR) and adds it to the new version history resource. The body and dead properties of the new version resource are a copy of those of the versionable resource. The server assigns the new version resource a new distinct and unique URL.

  3. It converts the versionable resource into a version-controlled resource (VCR). The version-controlled resource continues to be identified by the same URL that identified it as a versionable resource. As part of this conversion, it adds a DAV:checked-in property, whose value contains the URL of the new version resource.

It is often useful to have access to a version history even after all version-controlled resources for that version history have been deleted. A server can provide this functionality by supporting version history resources. A version history resource is a resource that exists in a server defined namespace and therefore is unaffected by any deletion or movement of version-controlled resources. A version history resource is an appropriate place to add a property that logically applies to all states of a resource. The DAV:expand-property report can be applied to the DAV:version-set of a version history resource to provide a variety of useful reports on all versions in that version history.

CHECKIN

A CHECKIN request can be applied to a checked-out version-controlled resource to produce a new version whose content and dead properties are copied from the checked-out resource.

If a CHECKIN request fails, the server state preceding the request MUST be restored.

(Quoted from RFC 3253 - Versioning Extensions to WebDAV - http://www.ietf.org/rfc/rfc3253.txt.)

CHECKOUT

A CHECKOUT request can be applied to a checked-in version-controlled resource to allow modifications to the content and dead properties of that version-controlled resource.

If a CHECKOUT request fails, the server state preceding the request MUST be restored.

(Quoted from RFC 3253 - Versioning Extensions to WebDAV - http://www.ietf.org/rfc/rfc3253.txt.)

UNCHECKOUT

An UNCHECKOUT request can be applied to a checked-out version-controlled resource to cancel the CHECKOUT and restore the pre-CHECKOUT state of the version-controlled resource.

If an UNCHECKOUT request fails, the server MUST undo any partial effects of the UNCHECKOUT request.

(Quoted from RFC 3253 - Versioning Extensions to WebDAV - http://www.ietf.org/rfc/rfc3253.txt.)

REPORT

A REPORT request is an extensible mechanism for obtaining information about a resource. Unlike a resource property, which has a single value, the value of a report can depend on additional information specified in the REPORT request body and in the REPORT request headers.

(Quoted from RFC 3253 - Versioning Extensions to WebDAV - http://www.ietf.org/rfc/rfc3253.txt.)

Auto-Versioning

Additionally, in order to support access by simple clients such as an HTTP 1.1 client, auto-versioning is supported.

Ideally, as a document is edited using a WebDAV-capable client, the DeltaV server will automatically version its contents. DeltaV provides this capability, using a feature known as auto-versioning

There are two styles of auto-versioning, depending on whether a new version is created every time the resource is updated, or only when the resource is unlocked. In the first case, a PUT/PROPPATCH (this means a request to modify the state) is preceded by a CHECKOUT, and is followed by a CHECKIN. That is, a PUT/PROPPATCH is expanded to CHECKOUT > PUT/PROPPATCH > CHECKIN. This auto-versioning approach is ideally suited for HTTP clients.

Note:
This auto-versioning behavior can be used with tools like XML Spy from Altova.

In the second auto-versioning style, a LOCK request also results in a CHECKOUT, and an UNLOCK additionally results in a CHECKIN. This works well for authoring clients that using locking, since they typically take out a lock at the start of an editing session, and remove the lock at the end, and hence auto-versioning based on locks causes the authoring session to automatically be bracketed by CHECKOUT and CHECKIN operations.

Note:
This behavior is implemented for example with Microsoft Office 2000 products: LOCK with open und UNLOCK with close.

This auto-versioning approach is ideally suited for WebDAV clients using the WebDAV lock feature.

All resources have a live property called DAV:auto-version assigned. When a "non-DeltaV" client performs a PUT or PROPPATCH on a resource, the value of the DAV:auto-version property determines the behavior:

Property Behavior
<checkout-checkin/> Perform an implicit (auto-) CHECKOUT and CHECKIN.
<checkout-unlocked-checkin/> auto-CHECKOUT, and wait for a lock to vanish before auto-CHECKIN.
<checkout/> auto-CHECKOUT, and wait for a lock to vanish before auto-CHECKIN but wait for an explicit CHECKIN.
<locked-checkout/> Require a lock. LOCK causes auto-CHECKOUT, UNLOCK causes auto-CHECKIN.

Advanced Versioning Functions

In addition to the basic versioning functions, Tamino WebDAV supports the following methods:

UPDATE

The Update feature provides a mechanism for changing the state of a checked-in version-controlled resource to be that of another version from the version history of that resource.

The UPDATE method modifies the content and dead properties of a checked-in version-controlled resource (the "update target") to be those of a specified version (the "update source") from the version history of that version-controlled resource.

The response to an UPDATE request identifies the resources modified by the request, so that a client can efficiently update any cached state it is maintaining. Extensions to the UPDATE method allow multiple resources to be modified from a single UPDATE request

LABEL

In order to identify various sources that belong to a certain version, labels can be issued.

Labels offer the ability to associate a name with a specific version of various resources stored. By issuing a meaningful symbolic name to a snapshot of the various resources it is possible to later recreate the end-result of these combined resources and thereby to create a version history.

A label can automatically be assigned by a server, or it can be assigned by a client in order to provide a meaningful name for that version. A given version label can be assigned to at most one version of a given version history, but client assigned labels can be reassigned to another version at any time. Note that although a given label can be applied to at most one version from the same version history, the same label can be applied to versions from different version histories.

For certain methods, if the request-URL identifies a version-controlled resource, a label can be specified in a Label request header to cause the method to be applied to the version selected by that label from the version history of that version-controlled resource.

A LABEL request can be applied to a version to modify the labels that select that version. The case of a label name is preserved when it is stored and retrieved. When comparing two label names to decide if they match or not, a server uses a case-sensitive URL-escaped UTF-8 encoded comparison. If a LABEL request is applied to a checked in version-controlled resource, the operation is applied to the DAV:checked-in version of that version-controlled resource.

MKWORKSPACE

A MKWORKSPACE request creates a new workspace resource. A server may restrict workspace creation to particular collections, but a client can determine the location of these collections from a DAV:workspace-collection-set OPTIONS request.

If a MKWORKSPACE request fails, the server state preceding the request must be restored.

(Quoted from RFC 3253 - Versioning Extensions to WebDAV - http://www.ietf.org/rfc/rfc3253.txt.)

Workspaces

When working with version-controlled resources it is convenient for the user to have a workspace where he can create and modify copies of such resources without the need to do a check-out-in-place. For this reason a dedicated location is provided:

http://<host:port>/tamino/<dbname>/ino:dav/ino:davWork/<myWorkSpace>

All objects stored in this location are treated as non-XML objects.