NUCM-2.0 Documentation Concepts

This section introduces the concepts that NUCM is based on. Below, each of the concepts is defined and illustrated with an example. The following concepts are present in NUCM:

• Artifact
• Version
• Attribute
• Garbage Collection
• Physical Repository
• Logical Repository
• Workspace
• CM Client
• Naming

Artifact

An artifact is anything that is visible to NUCM as a versionable object. In NUCM, two types of artifacts are defined: atoms and collections. An atom is a monolithic entity that has no substructure visible to NUCM. It is the smallest artifact that NUCM can store and version. A collection on the other hand is a set of artifacts grouped together into a single logical entity. The artifacts contained in a collection do not necessarily need to be atoms, they can be collections as well. Figure 1 illustrates the concept of atoms and collections. Shown in the figure are a collection that contains two atoms and one collection, which in turn contains two other atoms.

Figure 1: Atoms and Collections

The semantics of the atoms and collections is not determined by NUCM, but instead given by the user. For example, a hierarchy built out of collections and atoms could be source code for some project in which the collections represent subprojects, and the atoms the actual source code files. Alternatively, the hierarchy could represent for example some paper. Figure 2 illustrates the latter case. In this example, we now have given names to the collections and atoms. Presented here is a paper "Paper", that consists of a section called "Intro", a section called "Example", and a section called "End". The section called "End" in turn is divided into two subsections "Future" and "Conclusion".

Figure 2: Names of Atoms and Collections

It is important to note that NUCM, as illustrated in Figure 2, maintains the names of artifacts in their parent collection, not in the artifact itself. Combined with the capability that a single artifact can be contained in more than one collection, this results in a graph-based artifact model. This is illustrated in Figure 3, where another paper (named "Other Paper") is being written and stored in NUCM. This paper reuses the "Conclusion" section from the first paper, but instead names it "Abstract".

Figure 3: Multiple Names of an Artifact

Version

NUCM can not only store artifacts and relate them to each other using collections, but NUCM can also version the artifacts that it stores. Multiple instances of a single artifact can exist that each have different content. Looking at Figure 4, multiple versions of the atoms "Intro" and "Conclusion", as well as the collection "End" are present in the NUCM model. We note that different versions of the collection "End" reference different versions of the contained artifact "Conclusion".

Figure 4: Multiple Versions of an Artifact

To identify individual versions of an artifact, NUCM assigns a version number to each version of an artifact. NUCM numbers versions in a linear fashion: the first version is version 1, the second version is version 2, etcetera. As each version of an artifact therefore has a unique name (its name combined with its version number), we also note that a collection has individual versions of artifacts as its members. For example, as Figure 5 illustrates, version 3 of the "Conclusion" is a member of version 2 of the collection "End".

Figure 5: Naming Multiple Versions of an Artifact

The concepts introduced above make for a very flexible and powerful model to store and version artifacts; a CM system implementor using NUCM should carefully design the way the NUCM model is going to be used in the CM system as very complex networks can be constructed and stored by NUCM using the above model.

Attribute

Besides storing the contents of artifacts, NUCM allows for attributes to be attached to individual versions of an artifact. Attributes are name-value pairs: each attribute of a version of an artifact has to have a unique name. Figure 6 illustrates the concept of attributes in NUCM. Version 1 of the depicted artifact has three attributes attached to it, whereas version 3 also has three attributes attached to it, of which two are the same attribute but with a different value.

Figure 6: Attributes of Versions of an Artifact

Garbage Collection

Besides allowing for explicit removal of individual versions of artifacts, NUCM also employs the concept of garbage collection. Artifacts of which no version is referenced, will automatically be reclaimed by NUCM. If, for example, version 2 of the "Intro" is removed from the "Paper" as depicted in Figure 5, no references remain to the "Intro", and the artifact will be reclaimed (see Figure 7 for the remaining model).

Figure 7: Automatic Garbage Collection

If subsequently both version 1 and 3 of the "Conclusion" are removed from respectively version 1 and version 2 of the "End" of the "Paper", the "Conclusion" artifact will not be garbage collected as version 3 is still referenced as "Abstract" in "Other Paper" (the result of these removals is illustrated in Figure 8).

Figure 8: No Automatic Garbage Collection

Physical Repository

A physical repository is the place where NUCM stores the various versions of the artifacts as well as the associated attributes. Each physical repository has a root artifact, called nucm_root, which is the logical entrypoint to all the other artifacts in the repository. The root artifact can be versioned and manipulated just like all other artifacts, however, at least one version of it is guaranteed to exist at all times. Figure 9 illustrates a physical repository containing our "Paper" and "Other Paper" artifacts; which logically are members of the nucm_root collection.

Figure 9: Physical Repository

Access to each physical repository is maintained by an access server. An access server handles the requests made by CM clients to obtain, store, and version artifacts in the physical repository that it maintains. One access server maintains one physical repository (see Figure 10). An access server is identified by name of the machine it is running on combined with the port that it listens to. For example, an access server running on the machine serl.cs.colorado.edu that listens to port 1234, or an access server running on the machine anchor.cs.colorado.edu that listens to port 9876.

Figure 10: Access Server

Logical Repository

A logical repository implements a single distributed CM repository on top of multiple physical repositories. It allows for references across physical repositories. Figure 11 illustrates this capability. Our "Other Paper" is now located in a separate physical repository, contained in the nucm_root artifact of that repository. However, "Other Paper" still has "Abstract" as a member, even though it is located in the original repository (thus, the reference across the dashed line is a reference across physical repository boundaries). It should be noted that it is possible for a collection in one physical repository to contain the nucm_root of another physical repository (not illustrated).

Figure 11: Logical Repository

Workspace

Now that we have described how and where artifacts are stored, i.e., as artifact graphs in a logical repository that is maintained by one or more access servers, it is time to turn our attention to the client side of the versioning model of NUCM. Not only does NUCM maintain a repository with artifacts, NUCM also provides the concept of a workspace. A workspace is a location in the file system where artifacts from the repository are cached so that they can be manipulated with editors, compilers, code analysers, etcetera. In the workspace, collections are mapped to directories in the file system, and atoms are mapped to files. For example, our "Paper" from Figure 4 would be mapped into a workspace in the file system as follows:

   .../Paper/Intro
	     Example
	     End/Future
	        /Conclusion

   .../End/Future
          /Conclusion

CM Client

Tying together a workspace and a logical repository is the last part of the NUCM architecture: the CM client. The CM client consists of two parts: the standard NUCM client and a CM policy. The standard NUCM client implements the NUCM interface functions to obtain, store, and version artifacts in a logical repository. It is the same for each CM client.

Using the standard NUCM interface, a CM policy is constructed by a CM system implementor. Many different CM policies exist, however, they are all implemented on top of the standard NUCM interface. A CM policy implements the mechanism through which a user of a NUCM-based CM system will interact with the versioned artifacts.

It should be noted that, as illustrated in Figure 12, CM clients interact with a logical repository as opposed to a physical one. Distribution is hidden from CM clients, who only should worry about implementing a particular CM policy.

Figure 12: NUCM Architecture

Naming

The last concept of NUCM that needs to be introduced is its naming scheme. Given the graph-based artifact model, NUCM employs a naturally fitting hierarchical naming scheme. Similar to a file system, the nucm_root artifact is the logical "slash" or root-directory and at least one version of the nucm_root is guaranteed to exist at any given time in a physical repository. The name of an artifact is then the traversal of the graph from the nucm_root artifact to the node in the graph that represents the requested artifact. For example, the following is the name of the "Future" section of our paper (see Figure 11):

   nucm_root/Paper/End/Future

   nucm_root/Other Paper/Abstract

To distinguish between the various nucm_root artifacts, the physical repository where a nucm_root artifact is located is prepended to a names. For example, if our original physical repository is accessible through an access server running at machine serl.cs.colorado.edu and listening to port 1234, then the "Future" section is addressed as follows:

   //serl.cs.colorado.edu:1234/nucm_root/Paper/End/Future

   //anchor.cs.colorado.edu:9876/nucm_root/Other Paper/Abstract

To select one or more different versions while traversing the graph in constructing an artifact name, a colon can be used to separate the artifact name and version. For example, suppose we want version 2 of the "Abstract", its name is:

   //anchor.cs.colorado.edu:9876/nucm_root/Other Paper/Abstract:2

   //serl.cs.colorado.edu:1234/nucm_root:6/Paper/End:9/Future:10

What we have illustrated above is what is called a path in NUCM. A path is formally defined as follows:

   //host:port/nucm_root[:version][</name[:version]>....]

Paths directly address artifacts in a repository, however, artifacts are also cached in workspaces. To address an artifact in a workspace, existing file system pathnames can be used. For example, if the workspace is like (assuming ... is some absolute file system path):

   .../Paper/Intro
	     Example
	     End/Future
	        /Conclusion

   .../Paper

   ./Intro
   .../Paper/Intro
   ../Paper/End/Future

NUCM extends the file system path syntax with versions in a similar way NUCM pathnames are defined: colon-separated versions are allowed in the path. For example:

   ./Intro:2
   .:5/Intro:2
   .../Paper:3/Intro:4

We now have the full definition of a path: the definition given previsouly plus any versioned file system path. A path can thus point to either an artifact in a workspace or an artifact in a repository. In particular, a path can "jump" from workspace to repository when the first part is interpreted in a workspace, but the workspace does not contain enough information to fully interpret the path. What will happen is that NUCM will continue interpretation and location of the artifact in the repository.

Besides a path, NUCM uses two more ways to identify artifacts. Firstly, a target is defined as being a path that has to exist in a workspace. The given path can not point to an artifact in a repository. Secondly, a prefix-target is a path that points to a directory in which an artifact will be placed. This implies that the artifact does not exist yet as a NUCM-maintained artifact in that directory.

One final note needs to be made about NUCM naming. The interface functions accept names in two parts: a working directory and a path (or target). The name of the artifact is the path (target) that results from the concatenation of the working directory and the path. This two-stage interpretation allows for easy use of a "base" directory without a CM client having to do the path manipulation. Of course, a path into a repository does not need a working directory. Some examples:

   path                                 working directory
   ====================================================================
   //serl.cs.colorado.edu/nucm_root     (empty)
   ./nucm_root                          (empty)
   nucm_root                            .
   nucm_root:3                          /home/bigtime/andre
   project                              /home/bigtime/andre/nucm_root:3