The fork and merge features we've just seen allow multiple users to work on files, but they don't allow multiple users to check out files simultaneously. With all the features described up to this point, Bob can create a fork by checking out a version that already has a successor. However, Bob can't check out his version while Alice has her version already checked out he has to wait for Alice to check in first. In multiuser versioning systems, this isn't always acceptable. If Alice already has the document checked out and is editing it in place, Bob needs to be able to check out his file to a different location and edit the file there. DeltaV provides the working resource feature to allow this functionality. The working resource has its own URL, so Bob can PUT and PROPPATCH in that location, separate from Alice's changes to the VCR location. 11.8.1 Creating Working ResourcesA working resource is created with a CHECKOUT request. To create a working resource based on the target version, the client can send a CHECKOUT request to the VCR with an XML request body. The XML contains the apply-to-version element inside a checkout root element. This request creates a working resource with the auto-update property pointing to the VCR. This means that when the working resource is checked in and a new version is created, the server will automatically update the VCR's checked-in property to point to the new version (see Listing 11-9). Listing 11-9 CHECKOUT of a VCR to create a working resource.CHECKOUT /docs/index.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:checkout xmlns:D="DAV:"> <D:apply-to-version/> </D:checkout> HTTP/1.1 201 Created Location: http://www.example.com/wr/docs/index1.html In response to the CHECKOUT request, the working resource is created with a URL chosen by the server. Working resources could theoretically appear in some regular collection in the repository, but they are more likely to appear in some reserved namespace. There is no way to browse for working resources. Whenever a VCR is checked out with apply-to-version, the server must perform these steps:
Although Figure 11-10 suggests that the working resource exists off in space, that's not necessarily true. A DeltaV server could even put the working resource inside the same collection as the VCR through which it was created. Figure 11-10. Working resource relationships.A working resource does not have a new resourcetype value. It's not a new kind of resource, it's just a resource that happens to be checked out. If the client has a URL to some resource and needs to know if it's a working resource, the client must examine other properties. A working resource is required to have all the same properties as a regular checked-out resource. The auto-update property is unique to a working resource, but it doesn't always exist, so that's not a reliable property to look for. Instead, a client can try to look at the supported-method-set property. If the resource supports UNCHECKOUT, it can't be a working resource, because only a checked-out VCR supports UNCHECKOUT.
11.8.2 Editing a Working ResourceWhen a client checks out to a working resource, write operations are sent to the working resource, rather than the VCR that is not checked out. While the working resource exists, it is a complete stand-alone resource. For example, it may be locked or unlocked independently of the VCR it was created from.
DeltaV does not specify whether other users can view or edit working resources. Certainly the user creating the working resource ought to have permission to view and edit it. Perhaps the working resource should be limited so that only that user can view and edit it, or perhaps the working resource should inherit its permissions from the permissions of some other appropriate resource such as the VHR. If the server supports the WebDAV Access Control specification, it may even be possible to change permissions on the working resource and explicitly allow new principals to edit it.
11.8.3 CHECKIN a Working ResourceWhen a working resource is checked in, the state of the working resource is used to create a new version and the working resource is deleted. Since the working resource is deleted when it is checked in, a working resource never exists in the checked-in state. For interest's sake, we'll assume that the predecessor-set of the working resource names a version that already has a successor, so this checkin will create a fork. The client has checked the value of checkin-fork on the version that was checked out, and its value is discouraged. However, the user has confirmed that creating a fork is the intended outcome of this checkin, so the client includes fork-ok in the CHECKIN body (see Listing 11-10). Listing 11-10 CHECKIN working resource.CHECKIN /wr/docs/index1.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:checkin xmlns:D="DAV:"> <D:fork-ok/> </D:checkin> HTTP/1.1 201 Created Location: http://www.example.com/his/vers1/35.html GET /wr/docs/index1.html HTTP.1.1 Host: www.example.com HTTP/1.1 404 Not Found This interaction shows a checkin to a working resource, which creates a new version, and the new version's URL is returned. The checkin was intended to create a fork, and it may have; the server does not specify whether a fork has been created in the response. The GET request and 404 Not Found response are shown to illustrate that the server has cleaned up the working resource. When the working resource is checked in, the server performs the following steps:
The client may not use UNCHECKOUT with a working resource but may DELETE a working resource. This operation cancels the changes and deletes the working resource. The server cleans up the version that was checked out, to reset to its previous state (no checked-out property). If the working resource is never checked in and never deleted, the working resource exists indefinitely. DeltaV has no provision for a working resource to expire. The version would also remain checked out, which may prevent other checkouts if checkout-fork prevents forks. 11.8.4 Working Resources Create ForksWorking resources make it very easy to create forks, accidentally or intentionally. Here are some of the ways forks can be created:
11.8.5 Checking Out Other VersionsOther versions, not just the current target version, can be checked out too. A CHECKOUT request addressed to a version URL also creates a working resource (however, the auto-update property must start out empty). This can be a useful shortcut if a user wants to work from the content of a specific version other than the target version. The working resource is initialized with the requested version's content, not the target version's content (see Listing 11-11). Listing 11-11 CHECKOUT of a version creates a working resource.CHECKOUT /his/vers1/32.html HTTP/1.1 Host: www.example.com HTTP/1.1 201 Created Location: http://www.example.com/wr/docs/index2.html Listing 11-11 shows a CHECKOUT of a specific version and the server's response indicating that a working resource was created. The server must perform these steps:
Note that the auto-update property is not added to the working resource, although it was in the steps outlined in Section 11.8.1. The server must perform the same steps on checkin outlined in Section 11.8.3, except that if the auto-update property is still absent, there is no need to update any VCR's checked-in property. |