11.3 Editing Version-Controlled Resources

Armed with information about the VCR and its versions and how they relate together, we can discuss how to modify them.

11.3.1 CHECKOUT and CHECKIN

In existing versioning systems, clients frequently check out files before they start editing them, and they check them in again when finished. DeltaV supports a checkin/checkout model because it's common and solves a number of subtle problems.

"Check out" and "check in" are widely used phrases that often have different meanings in different software systems. In some versioning systems, when a file is checked out by one user, it cannot be checked out by another user, but in other systems a file can be checked out twice. In some systems, checking out downloads the resource content to the client machine, but in other systems the content is downloaded in a separate operation. At least the order of operations is consistent across versioning systems using this terminology: The client checks out the file, edits it, and then checks it in again. Usually, the checkin operation creates the new version.

DeltaV introduces the CHECKOUT and CHECKIN methods. CHECKOUT sets the state of the VCR to checked out, and CHECKIN returns it to the checked-in state and creates a new version. A VCR can only be changed while it is checked out.

If the user checks out a resource and then decides not to make changes after all, there must be a way to make the resource checked-in again without creating a new version. This operation is called UNCHECKOUT. If any changes were made while the resource was checked out, these are thrown away as the UNCHECKOUT restores the VCR to the same contents and dead properties of the previous target version. The server returns the VCR to the checked-in state.

DeltaV is built on WebDAV, so DeltaV can use the GET, PUT, LOCK, and UNLOCK methods. There's no need to reinvent the functions those methods provide. Thus, CHECKOUT does not download the content of the resource, GET does. CHECKIN does not upload the content of the resource, PUT does. CHECKOUT does not prevent other users from changing a resource because locks already provide that functionality. So what do CHECKOUT and CHECKIN do on their own? There are several functions.

• There's no other way to edit a resource on the server and then back out changes. This provides a useful "rollback" functionality for versioned resources.

• It's often useful to combine a set of related changes into a single new version (e.g., new content and new property values). The client signals the beginning of a set of related changes with CHECKOUT and the end of the changes with CHECKIN. That's why no new version is created until CHECKIN. Multiple PUT and PROPPATCH operations can be done in between, and only one new version is created.

• Other users can see that a resource is being edited as long as it is checked out. CHECKOUT is often done long before the first PUT or PROPPATCH, so it corresponds to the intention to edit the resource. While the resource is checked out, other users see that the resource is being edited and may choose not to edit it.

CHECKOUT and CHECKIN are explicit methods that cause the server to perform the requested operation. There are also occasions when the server must perform the same operation automatically. Although we haven't yet discussed what causes an automatic CHECKOUT or CHECKIN operation, the behavior of the operation is identical.

Locks and Checkouts

Since locks have timeouts and checkouts do not, it may be difficult to tie locks and checkouts together. A client may prefer to lock a resource as long as it is checked out, but the server may not allow infinite length locks. If the lock expires while the checkout still exists, then other users may edit the resource while it remains checked out by the original user (and this may easily happen unintentionally, through non-DeltaV-aware clients).

Servers supporting CHECKOUT should support long-lived locks to minimize this problem.

The next sections fill in the details of checking out a resource, editing a checked-out resource, checking it in, and cancelling a checkout.

11.3.2 CHECKOUT and Checked-Out VCRs

A CHECKOUT operation changes the state of the VCR from checked-in to checked-out (see Listing 11-3). No new versions are created. When a resource is checked out, it is not locked or downloaded to the client. Those operations are already covered by LOCK and GET methods, and there's no need to overload checkout to include those operations. With this separation of concerns, the client has more flexibility to perform exactly the desired set of operations.

When a VCR is checked out, its target version gets a new live property: The checkout-set property of the target version must contain the URL of the VCR that was just checked out.

Listing 11-3 CHECKOUT example.

 CHECKOUT /docs/index.html HTTP/1.1 Host: www.example.com  HTTP/1.1 200 OK  

While a VCR is checked out, the resource may be edited. The contents of the VCR are now independent of any version already created. The changes made on a checked-out VCR do not create a new version; instead, changes are applied to the content and dead properties of the VCR as it currently appears. The VCR content and dead properties were initialized to those of the target version when it was checked out, but they diverge from that version as changes are made and saved. Compare Figure 11-3 with Figure 11-2; when the VCR is checked out, its body can be different from the body of any historical version.

Figure 11-3. Checked-out VCR has independent contents from any version.

Note that all clients, including other users, can view and modify a checked-out resource normally.

• When any client issues a GET request to a VCR, the server must respond with the results of the latest PUT to the VCR, not with the body of the latest version.

• When any client issues a PROPFIND, the server must return the properties of the VCR, not the properties of the latest version.

• Any client can issue a PUT or PROPPATCH to a checked-out resource, too. These are subject to access control and locks as usual.

• Any client may attempt to CHECKIN the checked-out resource if it is not locked.

The client that does the CHECKOUT must separately issue a LOCK request to prevent other clients from using PUT, PROPPATCH, or CHECKIN.

In the checked-out state, the VCR has different values for some live properties. For example, the getlastmodified property value changes every time a write operation is used. The checked-out property only exists in this state. Its value is an <href> element containing a link to the target version.

Who Checked Out This Resource?

DeltaV does not specify a way to find out who checked out a resource. DeltaV defines the creator-displayname property for any resource, but it indicates who originally created the resource; thus, its value never changes. After the checkin is completed, the client can look at the creator-displayname property to find out who created the version.

11.3.3 Editing a Checked-Out Resource

After a successful CHECKOUT operation on a VCR, the client software may issue write requests like PUT and PROPPATCH. The client software may also COPY content from somewhere else, in which case the checked-out VCR's URL is the destination of the COPY method. Listing 11-4 is an example of using PUT to update a checked-out VCR. This request does not create a new version, because the resource isn't checked in yet, but it does modify the VCR's contents and live properties, as if the VCR were a regular resource.

Listing 11-4 PUT request to a checked-out VCR and success response.

 PUT /docs/index.html HTTP/1.1 Host: www.example.com Content-type: text/html Content-length: 11  Hello world HTTP/1.1 204 No Content ETag: "12345-09876"  

Soon after the CHECKOUT, the client software should set the comment property on the VCR. DeltaV defined the comment property to contain a human-language description of the reason the version was created and perhaps how it is different from the previous version. Since DeltaV does not define a way to find out who checked out a VCR, I recommend using the comment property to say who checked out the VCR (and why it was checked out, if that is known). The property may be changed again just before CHECKIN, because in many existing versioning systems, users are prompted for a text description when they decide to check in, and this is the place to put such information.

Client application software can save a temporary copy of the content on the local file system while it is being edited. Every time the user chooses to save the work, the local copy is changed. Only when the user decides to check in does the client issue one PUT request with all the new content, one PROPPATCH request to set the comment property and any other new property values, and finally CHECKIN.

In an alternative model, the client may issue a number of PUT operations throughout the editing session. This alternative model can be used in a number of situations:

• The user's latest save should not be lost if the client machine crashes. This benefit may be outweighed by the cost of the PUT operation, depending on the size of the file and the bandwidth of the connection.

• If the client machine has no local storage, every save must PUT the content to the server.

• Editing can begin on one client machine and proceed on a different client machine, continuing the work done so far, if each save is PUT to the server.

• The user may want to see the results of the work in progress on the server before checking in. For example, the user may be editing a Web page and can use a Web browser to view the page in its current state and make sure all the links work before checking in.

• Other users may see the work in progress and perhaps help edit the new version.

One way of looking at the DeltaV model is that CHECKOUT and CHECKIN reflect user decisions to start and finish editing the file, whereas GET and PUT are performed whenever the software needs to.

When the client sends the CHECKIN request, the server will respond with the URL of the newly created version.

11.3.4 CHECKIN and Checked-In VCRs

When a checked-out VCR gets a CHECKIN request, it is returned to the checked-in state, and one new version is created (even if no changes were made). The server assigns a new URL for the new version. The body and dead properties of the new version are copied from the VCR at the instant of the CHECKIN, as shown by the large arrows in Figure 11-4.

Figure 11-4. State of a resource through checkout, write operation, and checkin.

At CHECKIN, the server must remove the checked-out property of the VCR and restore the checked-in property. It must also set the value of the checked-in property on the VCR to point to the newly created version, which makes it the new target version.

When the new version is created, the value of the predecessor-set property must be the URL of the version from which it was derived. With the functionality defined so far, the predecessor must be the previous target version. The successor-set property for a new version is empty (but the property should exist). The server assigns a value to the version-name property which is distinct from all other version names in the same version history.

CHECKIN also causes some changes to live properties on the previous target version. The URL of the VCR is removed from the checkout-set property, and the successor-set property has a new value added, which is the URL of the new version (Figure 11-5).

Figure 11-5. Version relationships.

In the response to a CHECKIN request, the server tells the client the location of the newly created version. A successful response status is 201 Created rather than 200 OK, because of the new version created (see Listing 11-5).

Listing 11-5 CHECKIN example.

 CHECKIN /docs/index.html HTTP/1.1 Host: www.example.com  HTTP/1.1 201 Created Location: http://www.example.com/his/vers1/32.html  

Now that the VCR is checked in again, the server must not allow it to be altered. It has the same contents and dead properties as its target version.

11.3.5 UNCHECKOUT

UNCHECKOUT takes the VCR from checked-out to checked-in state without creating a new version. The checked-in property is restored to the value it had before, and the checked-out property is removed. Any live properties that were altered on any version (like checkout-set) are restored to the way they were before. The resource content and dead properties are restored to those of the target version.

The resource's URL is not affected by UNCHECKOUT. That means if a MOVE operation is applied to a resource while it is checked out, the MOVE operation is not undone when the UNCHECKOUT operation is applied. The UNCHECKOUT operation still restores the original content and dead properties in the new location.