12.1 Workspaces

Chapter 11, Versioning, introduced the concept of a working resource (Section 11.8). A working resource is a server-provided location or "sandbox" for editing content from a single VCR such that the changes are not automatically seen by users downloading the VCR.

It's possible for a developer in the multifile scenario to use working resources. The developer asks the server for a working resource for Employee.java and a working resource for Department.java. Now the developer can upload changes to each of these files. If the developer needs to work on a new machine, the software on the new machine can download each working resource and compile them. However, there's no way for the system to indicate that these two working resources belong together, so the developer would have to manually configure the software to make sure everything compiles together.

To make this process easier, server-side workspaces provide a location where VCRs being edited, VCRs not being edited, and even regular resources can exist in the same place. When they are all available in the same place, it's easier to make sure that cross-references work and that they all compile together before checking in changes.

A workspace can contain collections, regular resources, and VCRs. Within the workspace, resources can be changed, renamed, moved, deleted, or created. None of these changes is visible outside the workspace until the client checks in part or all of the work in progress.

A user may have a workspace that belongs to him for his development use. Alternatively, a user could have multiple workspaces to use or could share a workspace with other users. New files can be added to a workspace before being checked into the main repository. This provides a handy way to make sure the new file is integrated correctly and imported or referenced in all the other files that need to link to it, before making changes that could affect all other users.

12.1.1 Workspace Model

The main purpose of a workspace is to contain a number of VCRs, each of which points to a VHR. Many other workspaces may point to the same VHR. A VCR may be created from scratch (using PUT and VERSION-CONTROL) in the workspace, in which case the server creates a new VHR to manage versions. Alternatively, the user can choose to create a VCR that links a pre-existing VHR into the workspace.

The Meaning of Version History Resources

Now it becomes clearer how crucial VHRs are to the DeltaV data model. The VHR is the official location and URL for the content reflected in its versions. Any operation that adds a version can affect any VCR that points to those versions. VCRs may be moved, renamed, or deleted, but VHRs last forever with the same name. Any version that was ever saved on a repository can be found in a single VHR.

Regardless of whether the VCR was created from scratch or based on an existing VHR, what appears in the workspace is a real VCR. The user can check out the VCR in place to make changes within the workspace, independently of any editing going on in other VCRs. When the VCR inside the workspace is checked in, a new version is created in the version history.

Figure 12-2 shows two VCRs linked to the same VHR. One VCR is in the shared /docs/ repository, and the other is in Alice's workspace. While the VCR in Alice's workspace is checked out, Alice can edit the resource without affecting the main repository. The VCR in /docs/ could even be checked out independently.

Figure 12-2. Workspaces.

Even when Alice checks in the document, creating v3, the other VCR is not directly affected. The content at /docs/index.html continues to reflect the content in the first version. Only an UPDATE request will make the VCR in the main repository show the latest version. It's the same thing with any other workspace: For Bob to see the latest versions in his workspace, his client must send an UPDATE request for each VCR that has new versions.

When a server supports workspaces, every WebDAV resource has a workspace property containing an href element to indicate what workspace it is in. The main repository is a workspace, too. The data model is very consistent in treating workspaces exactly alike, with no difference in treatment of the main repository or primary namespace.

The value of the workspace property on a nonworkspace resource must be the same as the value of the property on the resource's parent. A collection can be identified as a workspace if its workspace property points to itself. DeltaV does not specify whether it's legal for the workspace property to be empty. Since every collection is a workspace or inside of one, it's pretty safe to assume that this property should never be empty.

Once the conceptual model for workspaces is understood, the mechanics are fairly easy. Clients can find or create workspaces, link in resources, and change resources within the workspace.

12.1.2 Finding or Creating a Workspace

First, the user needs a workspace to work in. The user can select a workspace to use in a couple of ways:

• The client may simply be configured by the user with the URL of the workspace to use.

• The client can browse workspaces and allow the user to select one.

• The client may create a new workspace for the user.

To browse workspaces, the client sends a special OPTIONS request to any resource supporting DeltaV. The body of the OPTIONS request contains an XML element workspace-collection-set. The server returns a set of collection URLs such as http://www.example.com/wksp/. Now the client can browse these collections to see what workspaces exist, and the user selects one.

To allow clients to create new workspaces, DeltaV defines a new method MKWORKSPACE. It works much like MKCOL. No body is required on the request. The workspace-collection-set OPTIONS request must be used again to figure out where to put the new workspace.

12.1.3 Linking Resources into Workspaces

The first step in editing a resource in a workspace is often to link the resource into the workspace. In this case, the client is simply creating a VCR based on a pre-existing VHR, so the method is the same as that used to create a VCR from a nonversioned resource: the VERSION-CONTROL method, this time with a body. The Request-URI identifies the workspace and VCR to create, and the body of the request identifies the VHR that will be linked to. The server creates a new modifiable VCR with the Request-URI, linked to the VHR if it exists.

The user might select existing VCRs in the main repository and tell the client to work on those files in the workspace. To do this, for each existing VCR the client must:

• Find out the VHR of the existing VCR with PROPFIND to the existing VCR.

• Decide what to call the new VCR. It must be inside the workspace or a subdirectory of the workspace, so the URL must contain the workspace name. The client must choose a final segment or file name. This might be the same as the name of the existing VCR.

• Send a VERSION-CONTROL request to the URL just constructed, where the body of the request specifies the URL of the VHR. This creates a new VCR linking to an existing VHR. This is Step 2 illustrated in Figure 12-3.

  Figure 12-3. Linking existing VHR into a workspace.

  

12.1.4 Working in Workspaces

Now the workspace is set up to begin working on files. From here, the set of steps is the same as modifying a regular VCR. For example, if the client wants to send explicit CHECKOUT and CHECKIN requests:

• Send a CHECKOUT request to /wksp/bob/index.htm to check it out to edit in place.

• Send PUT and PROPFIND requests to /wksp/bob/index.htm to update it.

• Send a CHECKIN request to /wksp/bob/index.htm to create new version /vers/index.html.3 for the VHR /vhrs/index.htm.

Ordinary resources can be created with PUT, MOVE, COPY, or MKCOL. Nonversioned resources can be replaced with VCRs using the VERSION-CONTROL method as described in Section 11.2.6. In general, resources behave the same way they do inside the main repository.