11.5 Using Existing WebDAV Methods with Versioning

Some WebDAV methods behave differently on servers supporting Delta V.

11.5.1 DELETE

DELETE operations are special in versioning systems. Many systems do not allow versions or VCRs to be deleted, because it must always be possible to recover past state.

It must be possible to remove a resource from a collection, even if this action doesn't destroy the resource content. Thus, DeltaV allows the DELETE method to delete a checked-in VCR, but this does not destroy all the saved versions that are related to the resource.

Since DeltaV does not specify whether the client must check out the resource prior to deleting it, I recommend that servers accept DELETE both on checked-out and checked-in VCRs.

DeltaV needs a way to access versions of deleted resources. Recall that you can use the VCR URL to discover a set of versions by asking the server for a version-tree report. However, when the VCR is deleted, the versions still exist and there must be some way to be access them. A new kind of resource type was introduced to serve as a gateway: A version-history resource (VHR) is a permanent resource with a permanent link to a set of versions. The VHR is created as soon as a VCR is created, and it continues to exist after the VCR is deleted. VHRs exist in a special collection, with URLs chosen by the server. The server publishes the URLs to the VHR collections in the body of a special OPTIONS response (see Section 11.10.3), so the client can discover VHRs by using PROPFIND to browse those collections.

There are three ways to discover the URL of a VHR:

• While the VCR exists, its version-history property will give the URL of the VHR.

• If the URL of a version is known, the VHR that the version belongs to is named in the version's version-history property.

• If the VCR has already been deleted and no version URLs are known, the client can browse the collections that hold VHRs, looking for the right one.

VHRs don't quite allow a perfect historical reconstruction after a VCR has been deleted. There is no way to tell, for example, what version was the target version just before the resource was deleted. There is no way to tell what URL or URLs the VCR had before it was deleted. There is no standard way to recognize a VHR when browsing through the VHR collections, so presumably these collections can only contain VHRs. At least the content bodies and properties of versions are still available, so a human has a chance of recognizing a deleted resource by looking at that information. Human intervention is almost certainly necessary to restore a deleted resource based only on the functionality described in DeltaV.

VHR support is not mandatory. On systems that don't support VHRs, a DELETE (if permitted) is permanent and the versions are no longer available. Some systems may even allow individual versions to be deleted.

11.5.2 Version History Resources

VHRs were introduced in the previous section and are defined more completely here. VHRs have their own URLs, separate from all VCRs. These URLs all exist in VHR collections, and clients may be prevented from creating regular resources in those collections.

A VHR is created whenever an existing resource is put under version control. The server automatically assigns a URL to the new VHR. A VHR must exist for each VCR. The VHR is truly a new kind of resource its resource type is <DAV:version-history>.

A VHR has no body, but it has a number of properties that link to versions. In fact, much of the specification of VHRs involves how to find the URL to one kind of resource given another kind of resource.

1. If you have the URL to a VHR, you can:

   1. Use the version-set property to get the URLs for all versions.

   2. Use the root-version property to get the URL to the original version.

   3. Use the REPORT request to get the locate-by-history report for a collection, returning all the VCRs that relate to your VHR. There can be many VCRs sharing the same version history.

2. If you have the URL to a VCR, you can:

   1. Use the version-history property to get the URL for the VHR.

   2. Use the checked-in property to get the URL for the target version, or use the checked-out property to get the URL for the version on which this VCR is based.

   3. Use the version-tree report to get a list or tree of all the version URLs.

3. If you have the URL to a version, you can use the version-history property to get the URL for the VHR.

Note that DeltaV defines no way to go straight from the version URL to the VCR URL. That's because the core DeltaV model must be compatible with the advanced DeltaV model, including features like workspaces (Section 12.2). Workspaces introduce a way for multiple VCRs to share the same versions and version history, so DeltaV does not require the server to link each version back to all those VCRs (see Figure 11-6).

Figure 11-6. VHR and relationships to other resources.

11.5.3 COPY

The COPY method existed before DeltaV, but DeltaV adds some new concerns. First, we'll discuss what happens to the version history if the source or the destination is a VCR.

How should COPY work? The desired behavior for COPY is clearest when the source is a regular resource and the destination is a VCR with an associated version history. Clearly, the server should not overwrite the destination and its entire history with the single body of a regular resource. What if the source resource was just a template or a file in a contributions folder? The user probably intended the source content to overwrite only the latest version of the destination. Thus, the model for COPY behavior is that the result should be the same if the client did a GET and PROPFIND of dead properties, followed by PUT and PROPPATCH to the new location.

That model leads to the following behavior (see Table 11-1), with the caveat that if the Overwrite header on the request has the value F and the destination exists in any form, the request must be failed.

Because the destination is altered in a COPY operation, if the destination is a VCR it may have to be checked out first. A new version may be created immediately if the COPY destination is a VCR with auto-versioning (see Section 11.6.2). The new version may be created later if the destination is a checked-out VCR which is later checked in. The request will fail if the destination is checked in and auto-versioning is off.

Table 11-1. Use Cases for COPY

Scenario	COPY Behavior
Source is a VCR, destination does not exist.	Creates a regular resource at the destination URL, consisting only of the body and dead properties of the source.
Source is a VCR, destination is not versioned.	Overwrites the content at the destination but does not convert it to a VCR. The content copied is the target body and dead properties from the source.
Source and destination are both VCRs.	Copies the current body and dead properties from the source to the destination, which may create a new version. Leaves the destination version history in place.
Source is not versioned but destination is a VCR.	Copies the body and dead properties from the source to the destination, which may create a new version. Leaves the destination version history in place.

DeltaV doesn't specify what to do if the client sends the Overwrite: F header on a COPY request when the destination is a VCR. One could imagine two ways to interpret this:

• The destination is a VCR representing many versions, so it's not being overwritten, and the COPY should succeed.

• The client may not be a DeltaV client. As far as that client is concerned, the Overwrite: F header must consistently work such that if the destination exists, the request fails.

For the sake of the non-DeltaV client and for consistency with MOVE when the destination is a VCR, I recommend that servers use the second option and fail the request. However, since this isn't specified in the standard, there is no way for the client to rely on this behavior. Unfortunately, the client has no real workarounds here. There are no conditional headers that would allow the client to insist that if the destination exists already, the COPY must fail. Thus, the burden on the server to do the right thing is even heavier.

The source of a COPY request may be a version, but the destination may not be. A VHR may not be either the source or the destination of a COPY.

11.5.4 MOVE

MOVE is even more difficult than COPY because both the source and the destination are modified. The definition must include what happens to the version history at the source (if the source is a VCR) as well as the version history at the destination.

The rename scenario makes the desired behavior of MOVE most obvious. Clearly, if a client is using MOVE to rename a VCR (the source is a VCR and the destination does not exist), the result of the operation must be a VCR with the same version history, contents, and properties but a new URL. DeltaV specifies this by saying that a MOVE must be applied by doing a depth infinity DELETE operation on the destination first. To apply that definition to the case where the destination is a VCR as well, we can see that the destination is completely replaced by the source. The original destination version history may still be available (if the server supports VHRs), but the destination URL no longer links to it.

DeltaV does not require either the source or the destination to be checked out prior to a MOVE request, so the server should be able to handle each case. If the source of the MOVE is checked out prior to the MOVE, then it should remain in that state after the operation (see Table 11-2).

Table 11-2. Scenarios for MOVE

Scenario	MOVE Behavior
Source is a VCR, destination does not exist.	Moves the source resource and its version history. After the MOVE, the destination resource is a VCR with the same version history the source had before the MOVE. If it was checked out before the MOVE, it remains checked out.
Source is a VCR, destination is not versioned.	As above, but overwrites the destination with the source resource and the source's version history. After the MOVE, since the original destination resource wasn't a VCR, no record exists of its previous history.
Source and destination are both VCRs.	Overwrites the destination with the source resource and the source version history. After the MOVE, if VHRs are supported, the VHR previously associated with the destination must remain accessible in the version history collection. If the destination was checked out before the MOVE, changes made during the checkout would be completely lost, not having been checked into any permanent version.
Source is not versioned, but destination is a VCR.	Overwrites the destination VCR with an unversioned resource. Unless the server supports VHRs, all the versions that were at the destination are lost.

If the Overwrite header is false and any resource exists at the destination, the request is failed.

Because version histories at the destination can be lost if a destination VCR is overwritten, client implementors should be cautious in issuing MOVE operations of this kind. The client software could present a warning to the user or not allow the operation at all unless the user is willing to explicitly delete the destination first. The server could also reject MOVE requests when the destination has a version history, but there is no specific error code to use to indicate why the operation is forbidden.

Neither the source nor the destination of a MOVE request may be a version or a VHR.