11.4 Labels

The DeltaV label feature allows versions to be tagged with human-readable strings indicating their purpose, relevance, or identity. Consider the process of preparing documents for general publication. As the document is successively reviewed and edited, increasingly minor changes are made. The document authors might want to keep track of several important versions for each document: the latest version sent out for review, which version was approved, or which version was finally published. The labels "reviewed," "approved," and "published" will be applied to up to one version for each document.

11.4.1 Managing Many Versions with Labeling

Even though CHECKIN helps users create new versions only when needed, some documents will eventually have too many versions to keep track of without help. It's very useful to be able to label versions to keep track of them more effectively, and DeltaV does specify how to label versions. Although labels could simply be stored as a dead property of a version, a number of requirements led to the development of a special mechanism for labeling.

The label should be a property so that it can be retrieved with other metadata without requiring extra roundtrips. It's particularly useful to be able to retrieve the labels for every resource in a collection or for all versions in a version history. Both of these operations are automatically possible if the label is defined as a property. The client issues PROPFIND depth 1 to get labels for all resources in a collection and asks for the version-tree report to get labels for all versions in a version history.

The property has some extra syntactic and semantic rules that the server must enforce. The semantic rules help clients manage labels.

• Two versions in the same version history cannot have the same label. Only one version can be the "published" version. The server must check and enforce this restriction whenever label values are changed.

• A version may have more than one role or relevance, so it may have more than one label. If the label is a property, it must be capable of taking multiple values. There isn't a standard mechanism for multiple values, so DeltaV defines how to do that.

DeltaV defines the label-name-set property with these two rules. The property value can contain any number of (including zero) label-name elements, and each element contains a label string (see Listing 11-6).

Listing 11-6 Label-name-set property value.

 <D:prop xmlns:D="DAV:">    <D:label-name-set>       <D:label-name>published</D:label-name>       <D:label-name>reviewed</D:label-name>    </D:label-name-set> </D:prop> 

11.4.2 Modifying Label Values

Although label-name-set is a property, it cannot be modified with PROPPATCH (it is a protected property). There are a few reasons for this choice.

• Most version properties cannot be modified after the version has been created, because the property values are part of the version history. Servers might forbid PROPPATCH on versions in order to enforce that. However, it's not always clear at first what label to apply to a version. (Imagine labeling a version "approved," only to find a mistake later.) Labels must be modifiable even after the version has been created.

• Multiple users may add and remove labels from versions. It must be possible to add a new label without accidentally removing a label just added by another user. However, we can't use locks to protect labels from this special-case lost update problem, because a server might not allow versions to be locked.

How to Select a Label String

DeltaV is silent on what label strings mean. The published and reviewed values used here are simply the kinds of strings that humans might apply to labels. In a software repository, the label strings might contain version and build numbers, like 3.3.0.10.

Labels can be defined and used by rich client software as well as by humans. For example, a workflow software package may follow rules involving labels: Whenever a certain label is applied, the software automatically notifies the resource owner. When labels are defined and used by software, care should be taken to ensure that the label is unique, so that human-defined labels don't interfere. A simple way to accomplish this is to prefix a meaningful string with an XML namespace. For example, if the meaningful string is to be workflow-publish, then a unique label name would probably be http://www.example.com/workflow-publish.

Instead of PROPPATCH, DeltaV defines a new method, LABEL, to change a label. The LABEL method allows a user to add a label to the label name set without knowing the entire set. The LABEL method also provides a way to remove a label or move it from one version to another. The LABEL method is complicated and it is a single-purpose solution, but it does solve the problem (see Listing 11-7).

Listing 11-7 LABEL request.

 LABEL /his/vers1/32.html HTTP/1.1 Host: www.example.com Content-Type: text/xml; charset="utf-8" Content-Length: 1234  <?xml version="1.0" encoding="utf-8" ?> <D:label xmlns:D="DAV:">    <D:add><D:label-name>approved</D:label-name></D:add> </D:label> 

The LABEL request takes an XML body. The root element must be the label element. Inside the label element, there may be at most an add element, a set element, or a remove element. Each of these three must contain one and only one label-name element. This means that only one label can be altered on a version per request.

The add element is used to add a label that didn't exist before. The set element is used to add the label to the version identified in the Request-URI and remove it from whatever version previously had that label. If no other version previously had that same label, then it is treated like an add request.

When handling the LABEL request, the server must enforce the rule that every label must be unique for all versions in the same version history. That's because the label is used to uniquely identify a version from that set. However, not every version must have a label a version may have an empty label-name-set if that version isn't particularly notable or important.

11.4.3 The Label Header

To use labels, the client can retrieve all the label values for a set of versions (using the version-tree report), search for the appropriate label, and then do operations on the version that has that label. There's also a shortcut: DeltaV defines a header that requests the server to apply the operation to whatever version has the specified label. This header can cut out expensive queries and processing. For example, the user could download the "published" version of a resource in a single request to that resource. The Label header takes a single label as its value (see Listing 11-8).

Listing 11-8 LABEL header on a request.

 GET /docs/index.html HTTP/1.1 Label: published ... 

In this case, the server should select the version labelled published from index.html and return the body of that version. If the target resource is not version-controlled, the server must handle the method as if the Label header were not there and just return the resource's body.

Unfortunately, the Label header isn't very useful, because there is a serious problem in the way it is specified. The header can't be used on nonversioned collections, because the RFC says in Section 8.3 that if the requested resource (the collection) is not version-controlled, then the Label header must be ignored. In other words, it's useless to send a Label header on a request to a regular collection the server will ignore it. That's a shame, because the designers of labeling originally intended to allow a client to select related versions from multiple files using labels. For example, the client might want to view the last modifed date of all the file versions labeled with the 3.3.0.10 release label. To do this, the client might want to send a PROPFIND request to the root collection with the Label header, but the server will ignore the header if the root collection isn't versioned. Instead, the client must make the PROPFIND request separately for each child of the collection.

There are more complicated problems with the Label header and version-controlled collections. Given the known problems, the authors of the DeltaV specification have discussed removing the Label header and possibly replacing it with a report, even though the Label header is already in the RFC. In the meantime, clients should not rely on the Label header, even if support for the LABEL method is present.

Difficulties Comparing Natural-Language Strings

The mechanism for comparing the value of a label is clearly specified for a programmer to implement but may be unsatisfactory for users. This is a general unsolved problem, not unique to labels, but it happens to crop up here because the server is asked to compare strings that may be natural-language string values.

Because the server compares case-sensitive URL-escaped UTF-8 strings, many labels that humans consider matches will not be considered matches by the server. For example, accented characters will never match unaccented characters. There are even characters that look the same to the human eye but have different UTF-8 encodings and thus fail in equality tests.