Internet DRAFT - draft-clemm-wvcm
draft-clemm-wvcm
INTERNET-DRAFT G. Clemm
draft-clemm-wvcm-00 Rational Software
Expires January 21, 2003 July 21, 2002
WVCM: The Workspace Versioning and Configuration Management API
Status of this Memo
This document is an Internet-Draft and is in full conformance with all
provisions of RFC 2026, Section 10.
Internet-Drafts are working documents of the Internet Engineering Task
Force (IETF), its areas, and its working groups. Note that other groups
may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference material
or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
Abstract
This document specifies the classes and interfaces that define the
Workspace Versioning and Configuration Management API. The WVCM API
will minimize the complexity of clients that are capable of
interoperating with a variety of versioning repositories. The WVCM API
includes: workspace management, version history management, baseline
management, activity management, and namespace versioning.
Clemm [Page 1]
INTERNET-DRAFT WVCM API May 8, 2002
Table of Contents
1 INTRODUCTION...........................................6
1.1 Relationship to the DeltaV/WebDAV/HTTP Protocols......7
1.2 Notational Conventions................................7
1.3 Workspace Terms.......................................7
1.4 Versioning Terms......................................8
1.5 Method Preconditions and Postconditions..............11
2 NON-VERSIONING WORKSPACE SEMANTICS....................11
3 NON-VERSIONING PROPERTIES.............................12
3.1 Resource Properties..................................12
3.1.1 DisplayName......................................12
3.1.2 Comment..........................................12
3.1.3 CreationDate.....................................12
3.1.4 CreatorDisplayName...............................13
3.1.5 LastModified.....................................13
3.1.6 ContentLanguage..................................13
3.1.7 ContentLength....................................13
3.1.8 ContentType......................................13
3.1.9 ContentCharacterSet..............................13
3.1.10 ContentIdentifier................................13
3.1.11 WorkspaceFolderList..............................14
3.2 ControllableResource Properties......................14
3.2.1 Workspace........................................14
3.2.2 IsCheckedOut.....................................14
3.2.3 ServerState......................................14
3.2.4 IsStale..........................................14
3.2.5 IsDirty..........................................15
3.3 Workspace Properties.................................15
3.3.1 WorkspaceCheckoutList............................15
3.3.2 WorkspaceServerLocation..........................15
4 NON-VERSIONING METHODS................................15
4.1 Resource Methods.....................................15
4.1.1 doCreateResource Method..........................15
4.1.2 doReadProperties Method..........................16
4.1.3 doWriteProperties Method.........................16
4.1.4 doReadContent Method.............................16
4.1.5 doWriteContent Method............................16
4.1.6 doDelete Method..................................17
4.1.7 doCopy Method....................................17
4.1.8 doMove Method....................................17
4.2 ControllableResource Methods.........................18
4.2.1 Additional doWriteContent Semantics..............18
4.2.2 Additional doDelete Semantics....................18
4.2.3 Additional doMove Semantics......................18
4.2.4 doControl Method.................................18
4.2.5 doCheckout Method................................19
4.2.6 doCheckin Method.................................19
4.2.7 doRefresh Method.................................19
4.3 Folder Methods.......................................20
Clemm [Page 2]
INTERNET-DRAFT WVCM API May 8, 2002
4.3.1 doReadMemberList Method..........................20
4.4 Workspace Methods....................................20
4.4.1 Additional doCreateResource Semantics............20
4.4.2 Additional doMove Semantics......................21
5 VERSIONING WORKSPACE SEMANTICS........................21
5.1 Creating a Version-Controlled Resource...............21
5.2 Modifying a Version-Controlled Resource..............22
5.3 Workspaces...........................................23
5.4 Folder Versions......................................24
5.5 Configurations and Baselines.........................26
5.6 Activities...........................................28
5.7 Merging..............................................29
5.8 Labels...............................................30
6 VERSIONING PROPERTIES.................................30
6.1 Additional Resource Properties.......................30
6.1.1 ActivityFolderList...............................30
6.1.2 VersionHistoryFolderList.........................30
6.2 Additional ControllableResource Properties...........31
6.2.1 VersionControllable..............................31
6.2.2 VersionHistory...................................31
6.2.3 CheckedIn........................................31
6.2.4 CheckedOut.......................................31
6.2.5 PredecessorList..................................31
6.2.6 ActivityList.....................................32
6.2.7 Unreserved.......................................32
6.2.8 MergeList........................................32
6.2.9 AutoMergeList....................................32
6.2.10 ControlledConfiguration..........................33
6.3 Folder Properties....................................33
6.3.1 BaselineControllable.............................33
6.3.2 EclipsedList.....................................33
6.4 Additional Workspace Properties......................33
6.4.1 BaselineControlledFolderList.....................33
6.4.2 CurrentActivityList..............................33
6.5 Version Properties...................................34
6.5.1 VersionHistory...................................34
6.5.2 PredecessorList..................................34
6.5.3 SuccessorList....................................34
6.5.4 CheckoutList.....................................34
6.5.5 ActivityList.....................................34
6.5.6 CheckoutFork.....................................34
6.5.7 CheckinFork......................................35
6.5.8 VersionName......................................35
6.5.9 LabelNameList....................................35
6.6 VersionHistory Properties............................35
6.6.1 RootVersion......................................35
6.6.2 VersionList......................................35
6.7 Folder Version Properties............................36
6.7.1 ControlledBindingList............................36
6.8 Baseline Properties..................................36
6.8.1 BaselineFolder...................................36
6.8.2 SubbaselineList..................................36
Clemm [Page 3]
INTERNET-DRAFT WVCM API May 8, 2002
6.9 Configuration Properties.............................36
6.9.1 RootFolder.......................................36
6.9.2 SubbaselineList..................................36
6.10 Activity Properties................................37
6.10.1 ActivityVersionList..............................37
6.10.2 ActivityCheckoutList.............................37
6.10.3 SubactivityList..................................37
6.10.4 CurrentWorkspaceList.............................37
7 VERSIONING METHODS....................................38
7.1 Additional ControllableResource Methods..............38
7.1.1 Additional doControl Semantics...................38
7.1.2 Additional doCheckout Semantics..................38
7.1.3 Additional doCheckin Semantics...................40
7.1.4 Additional doMove Semantics......................41
7.1.5 doUncheckout Method..............................41
7.1.6 doCreateControlledResource Method................42
7.1.7 doUpdate Method..................................43
7.1.8 doMerge Method...................................44
7.1.9 doMergePreview Method............................46
7.2 Additional Workspace Methods.........................46
7.2.1 Additional doMove Semantics......................46
7.2.2 Additional doDelete SemanticsError! Bookmark not defined.
7.2.3 doLocateByHistory Method.........................48
7.2.4 Additional doMerge Semantics.....................46
7.3 Additional Folder Methods............................48
7.3.1 doBaselineControl Method.........................49
7.3.2 doCreateBaselineControlledFolder Method..........49
7.4 Configuration Methods................................50
7.4.1 Additional doCheckin Semantics...................50
7.4.2 Additional doUpdate Semantics....................51
7.5 Version Methods......................................52
7.5.1 Additional doWriteContent Semantics..............52
7.5.2 Additional doCopy Semantics......................52
7.5.3 Additional doMove Semantics......................52
7.5.4 Additional doDelete Semantics....................52
7.5.5 doAddLabel Method................................53
7.5.6 doSetLabel Method................................53
7.5.7 doRemoveLabel Method.............................54
7.6 Version History Methods..............................54
7.6.1 Additional doCopy Semantics......................54
7.6.2 Additional doMove Semantics......................54
7.6.3 Additional doDelete Semantics....................54
7.7 Folder Version Methods...............................55
7.7.1 Additional doCopy Semantics......................55
7.8 Baseline Methods.....................................55
7.8.1 doCompareBaseline Method.........................55
7.9 Activity Methods.....................................56
7.9.1 Additional doCreateResource Semantics............56
7.9.2 Additional doMove Semantics......................56
7.9.3 Additional doDelete Semantics....................56
7.9.4 Additional doCheckin Semantics...................56
8 INTERNATIONALIZATION CONSIDERATIONS...................56
Clemm [Page 4]
INTERNET-DRAFT WVCM API May 8, 2002
9 SECURITY CONSIDERATIONS...............................57
10 IANA CONSIDERATIONS..................................57
11 INTELLECTUAL PROPERTY................................57
12 ACKNOWLEDGEMENTS.....................................57
13 REFERENCES...........................................57
14 AUTHOR'S ADDRESS.....................................58
Clemm [Page 5]
INTERNET-DRAFT WVCM API May 8, 2002
1 INTRODUCTION
This document specifies the classes and interfaces that define the
Workspace Versioning and Configuration Management (WVCM) API.
There are two key concepts in this API: "workspaces" and
"versioning".
The purpose of a workspace is to provide an environment within
which a user can make persistent modifications to a configuration
of resources without interfering or disrupting the work of other
users of those resources. This requires that the user be able to
persist changes to resources (both content changes and naming
changes) without those changes being immediately visible to other
users. To provide this functionality, the persistent changes saved
in one workspace (also known as a "sandbox" or a "view") are
visible in other workspaces only after the user of that workspace
explicitly exposes those changes for use by other workspaces, and
after a user of another workspace explicitly requests to see the
changes that have been exposed.
In some implementations, a workspace is stored primarily in local
persistent storage of the client, and changes are exposed to other
workspaces by uploading changed resource names and content to a
shared server. Changes are made visible in another workspace by
downloading those changes to that other workspace. In other
implementations, only the resources being changed are stored on the
client, while unmodified resources are stored only on the server.
These implementations are often preferable when there are large
numbers of resources (e.g. thousands, or hundreds of thousands),
since it would be prohibitively expensive to download all those
resources to each client. Finally, in some implementations, all
workspace state is stored on the server. These implementations
have the advantages that they can be used by clients with no local
persistent storage, and that the private workspace state can be
seen from multiple clients (this is important when a user needs to
be able to easily move from one host to another, or when several
users are working very closely together). These implementations
are also used when key resources (such as high-performance
databases) are required for effective workspace authoring, and
these resources are only available on the server. One of the key
challenges of the WVCM API is to hide these implementation choices
from a client.
The purpose of versioning is to provide an environment within which
previous states of resource (both content and naming) are easily
available. The term "configuration management" is used to
emphasize that it is not just isolated resource states that must be
easily available, but also consistent configurations of related
resources.
The benefits of versioning and configuration management include:
Clemm [Page 6]
INTERNET-DRAFT WVCM API May 8, 2002
- A resource has an explicit history and a persistent identity
across the various states it has had during the course of that
history. It allows browsing through past and alternative versions
of a resource. Frequently the modification and authorship history
of a resource is critical information in itself.
- Resource states (versions) are given stable names that can
support externally stored references for annotation and linking.
By providing stable states of resources, version control systems
allow not only stable pointers into those resources, but also well
defined methods to determine the relationships of those states of a
resource.
- Sets of resources can be developed in parallel. Each client has
its own configuration of the controlled resources, and can make
changes to its configuration without disturbing that of another
client. Consistent groups of changes can then be exposed for use
by other clients.
1.1 Relationship to the DeltaV/WebDAV/HTTP Protocols
To maximize interoperability and the use of existing protocol
functionality, the WVCM semantic model is designed to be compatible
with the DeltaV [RFC3253], WebDAV [RFC2518], and HTTP [RFC2616]
protocols.
1.2 Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", and "MAY " in this
document are to be interpreted as described in RFC 2119.
1.3 Workspace Terms
Resource
A "resource" is a locatable persistent object whose state consists
of content (a sequence of bytes) and properties (a set of
name/value pairs).
Controlled Resource, Check Out, Check In
A "controllable resource" is a resource whose state can be
"controlled". When a resource is controlled, it becomes a
"controlled resource". A controlled resource must be "checked out"
in order to modify its content, and then "checked in" to allow that
modification to be visible in another workspace. A controlled
resource is always either in a "checked-in" or "checked-out" state.
Clemm [Page 7]
INTERNET-DRAFT WVCM API May 8, 2002
Folder Resource, Binding, Member
A "folder resource", or simply "folder", is a controllable resource
whose state contains a set of named "bindings". Each folder
binding defines a mapping from a name to another resource, called a
"bound member" of the folder. A folder must be checked-out to add,
remove, or rename a controlled bound member of that folder, and
then checked in to commit that modification. The "members" of a
folder are the folder itself and all bound members of any member of
the folder. In mathematical terms, the member relationship is the
transitive closure of the bound-member relationship. Note that a
folder is a member of itself.
Configuration
A "configuration" is a set of resources associated with a
particular folder, called the "root folder" of the configuration.
In particular, a configuration consists of all members of the root
folder that are not members of another configuration. Note that a
folder (which is a single resource) is very different from a
configuration (which is a set of resources).
Workspace Resource
A "workspace resource", or simply "workspace", is a configuration
that can have both controllable and controlled members.
1.4 Versioning Terms
Version Control
When a resource is "version-controllable", a history of its
checked-in states is kept after it is controlled. When a version-
controllable resource is controlled, it becomes a "version-
controlled" resource.
Version Resource
A "version resource", or simply "version", is a resource that
contains a copy of a particular state of a version-controlled
resource. A new version is created whenever the version-controlled
resource is checked in. The server allocates a distinct new
location for each new version, and this location will never be
occupied by any resource other than that version. The content of a
version never changes.
Predecessor, Successor, Ancestor, Descendant
When a version-controlled resource is checked out and then
subsequently checked in, the version that was checked out becomes a
"predecessor" of the version created by the checkin. A client can
specify multiple predecessors for a new version if the new version
is logically a merge of those predecessors. When a version is
Clemm [Page 8]
INTERNET-DRAFT WVCM API May 8, 2002
connected to another version by traversing one or more predecessor
relations, it is called an "ancestor" of that version. The inverse
of the predecessor and ancestor relations are the "successor" and
"descendant" relations. Therefore, if X is a predecessor of Y,
then Y is a successor of X, and if X is an ancestor of Y, then Y is
a descendant of X.
Version History Resource
A "version history resource", or simply "version history", is a
resource that contains all the versions that are descendants of a
particular version, called the "root version" of that version
history. A version history is located in a server defined
namespace and therefore is unaffected by any deletion or movement
of version-controlled resources. A workspace contains at most one
version-controlled resource for a given version history.
Version Name
A "version name" is a string chosen by the server to distinguish
one version of a version history from the other versions of that
version history. Versions from different version histories may
have the same version name.
Label
A "label" is a string that can be used to select a version from a
version history. A label can be assigned by either a client or the
server. The same label can be used in different version histories.
Fork, Merge
When a second successor is added to a version, this creates a
"fork" in the version history. When a version is created with
multiple predecessors, this creates a "merge" in the version
history. A server may restrict the version history to be linear
(with no forks or merges), but an interoperable versioning client
should be prepared to deal with both forks and merges in the
version history.
Clemm [Page 9]
INTERNET-DRAFT WVCM API May 8, 2002
The following diagram illustrates several of the previous
definitions. Each box represents a version and each line between
two boxes represents a predecessor/successor relationship. For
example, it shows V3 is a predecessor of V5, V7 is a successor of
V5, V1 is an ancestor of V4, and V7 is a descendant of V4. It also
shows that there is a fork at version V2 and a merge at version V7.
History of foo.html
+---+
Root Version -------> | | V1
+---+ ^
| |
| |
+---+ |
Version Name ----> V2 | | | Ancestor
+---+ |
/ \ |
/ \ |
+---+ +---+
| | V3 | | V4
^ +---+ +---+
| | | |
Predecessor | | | |
+---+ +---+ |
| | V5 | | V6 | Descendant
+---+ +---+ |
Successor | \ / |
| \ / |
v +---+ v
| | V7
+---+
Folder Version Resource
A "folder version resource", or simply "folder version", captures
the names of its controlled bindings. A controlled binding is a
binding to a controlled resource. A folder version is created by
checking out and then checking in a controlled folder. The list of
controlled bindings of a folder version never changes.
Baseline Resource
A "baseline resource", or simply "baseline", of a folder is a
version of the configuration that is rooted at that folder. In
particular, a baseline captures the version identified by the
CheckedIn property of every version-controlled member of that
configuration. Note that a folder version (which captures the
state of a single resource) is very different from a folder
baseline (which captures the states of a set of resources).
Clemm [Page 10]
INTERNET-DRAFT WVCM API May 8, 2002
Baseline-Controlled Folder
A "baseline-controlled folder" is the root folder for a
configuration that is being baselined.
Controlled Configuration Resource
A " controlled configuration resource", or simply " controlled
configuration", is a special kind of version-controlled resource
that is associated with a baseline-controlled folder, and is used
to create and access baselines of that folder. When a folder is
both version-controlled and baseline-controlled, a client can
create a new version of the folder by checking out and checking in
that folder, and it can create a new baseline of that folder by
checking out and checking in the controlled configuration of that
folder.
Activity Resource
An "activity resource", or simply "activity", is a resource that
selects a set of versions that correspond to a single logical
change, where the versions selected from a given version history
are required to form a single line of descent through that version
history.
1.5 Method Preconditions and Postconditions
A "precondition" of a method describes the state on the server that
must be true for that method to be performed. A "postcondition" of
a method describes the state on the server that must be true after
that method has completed. If a method precondition or
postcondition for a request is not satisfied, a WvcmException will
be thrown, containing a string that identifies the exact condition
that was not satisfied.
2 NON-VERSIONING WORKSPACE SEMANTICS
Although the WVCM API is designed to supported workspace management
by a versioning server, a simple subset of the WVCM API can be used
to support workspace management by a non-versioning server. In
this simplified form, only Resource, ControllableResource, Folder,
and Workspace resources are supported. Each workspace has both
private client-side persistent state, as well as server-side
persistent state that it shares with other workspaces. In
particular, a copy of the resource state of each checked-in
controlled resource is stored persistently on the server.
In order to create a workspace, a client specifies the location in
the local client file system for the root folder of the workspace.
In addition, the client must specify the location on the server for
the checked-in controlled resource state that is shared with other
workspaces. A client can then create, browse, and update
Clemm [Page 11]
INTERNET-DRAFT WVCM API May 8, 2002
uncontrolled workspace members (files and folders) through WVCM API
calls, or alternatively, through native client file system
commands.
In order to share changes to a resource with other workspaces, the
client must first put that resource under control using the
doControl WVCM API call. In order to update a controlled resource,
a client must first check out that resource using the doCheckout
WVCM API call. A checked-out controlled resource can then be
updated in the same ways that an uncontrolled resource is updated,
i.e. using WVCM API calls or native client file system commands.
When a client is ready to expose the modified state of a controlled
resource to other workspaces, it must use the doCheckin WVCM API
call. If the state of that resource on the server has not changed
since the doCheckout call was performed, the local resource state
is copied to the server. If the state of that resource on the
server has changed (as a result of a doCheckin call from a client
in another workspace that shares that server state), the client
must merge its changes with the changes made to the server. In
particular, the client must save its changes to a temporary
location, use the doRefresh WVCM API call to retrieve the modified
server state, merge its changes with that new state retrieved from
the server, and attempt the doCheckin again. Note that a WVCM
implementation will commonly mark a checked-in controlled resource
as read-only, to prevent local file system commands from
incorrectly modifying a checked-in resource.
3 NON-VERSIONING PROPERTIES
3.1 Resource Properties
3.1.1DisplayName
This property contains a description of the resource that is
suitable for presentation to a user.
String getDisplayName()
setDisplayName(String s)
3.1.2Comment
This property is used to track a brief comment about a resource
that is suitable for presentation to a user.
String getComment()
setComment(String s);
3.1.3CreationDate
This property contains the resource creation date.
Clemm [Page 12]
INTERNET-DRAFT WVCM API May 8, 2002
java.util.Date getCreationDate()
setCreationDate(java.util.Date date);
3.1.4CreatorDisplayName
This property contains a description of the creator of the resource
that is suitable for presentation to a user. The
CreatorDisplayName of a version can be used to indicate who created
that version.
String getCreatorDisplayName()
setCreatorDisplayName(String s)
3.1.5LastModified
This property contains the date the content was last modified.
java.util.Date getLastModified()
3.1.6ContentLanguage
This property specifies the content language.
java.util.Locale getContentLanguage()
setContentLanguage(java.util.Locale contentLanguage);
3.1.7ContentLength
This property contains the content length in bytes.
long getContentLength()
3.1.8ContentType
This property specifies the content type.
String getContentType()
setContentType(String contentType);
3.1.9ContentCharacterSet
This property specifies the content character set.
String getContentCharacterSet()
setContentCharacterSet(String contentCharacterSet);
3.1.10 ContentIdentifier
This property contains a string that can be used to determine
whether the content of the resource has changed. In particular, if
the content identifier of a resource has not changed, the content
of the resource also has not changed.
String getContentIdentifier()
Clemm [Page 13]
INTERNET-DRAFT WVCM API May 8, 2002
3.1.11 WorkspaceFolderList
This property identifies folders that may contain workspaces. This
property allows a client that knows the location of one resource in
a workspace to find other workspaces. An identified folder MAY be
the root folder of a tree of folders, all of which may contain
workspaces. Since different servers can control different parts of
the resource namespace, different resources on the same host MAY
have different WorkspaceFolderList values. The identified folders
MAY be located on different hosts from the resource.
<Folder>List getWorkspaceFolderList()
3.2 ControllableResource Properties
3.2.1Workspace
The Workspace property of a workspace resource MUST identify
itself. The Workspace property of any other type of resource MUST
be the same as the Workspace property of its parent folder.
Workspace getWorkspace()
3.2.2IsCheckedOut
This property identifies whether the resource is checked-out or
checked-in.
Boolean getIsCheckedOut()
3.2.3ServerState
In some implementations, persistent copies of the content and some
of the properties of the resource are maintained on both the client
and the server. If this ControllableResource has persistent state
on both the client and the server, this property identifies the
server resource corresponding to the client resource. If this
ControllableResource only has persistent state on the client or
only has persistent state on the server, this property is null.
ControllableResource getServerState()
3.2.4IsStale
This property identifies whether the content on the server has
changed since it was last synchronized with the content on the
client. If the ServerState property of this ControllableResource
is null, this property is false.
Boolean getIsStale()
Clemm [Page 14]
INTERNET-DRAFT WVCM API May 8, 2002
3.2.5IsDirty
This property identifies whether the content on the client has
changed since it was last synchronized with the content on the
server. If the ServerState property of this ControllableResource
is null, this property is false.
Boolean getIsDirty()
3.3 Workspace Properties
A workspace is a folder that can have both controlled and
uncontrolled members.
3.3.1WorkspaceCheckoutList
This property identifies each member of this Workspace that is
currently checked out.
<ControlledResource>List getWorkspaceCheckoutList()
3.3.2WorkspaceServerLocation
When a workspace has persistent state on both the client and the
server, this property identifies the location of the server
persistent state.
String getWorkspaceServerLocation()
setWorkspaceServerLocation(String location)
4 NON-VERSIONING METHODS
4.1 Resource Methods
4.1.1doCreateResource Method
The doCreateResource method can be used to create new persistent
uncontrolled resources.
Marshalling:
void doCreateResource()
Preconditions:
(resource-must-be-null): A resource MUST NOT exist at the location
of this Resource.
(location-ok): The location of this Resource MUST identify a valid
location to create this Resource.
Clemm [Page 15]
INTERNET-DRAFT WVCM API May 8, 2002
Postconditions:
(initialize-resource): A new resource of the specified type exists
at the location of this Resource.
4.1.2doReadProperties Method
The doReadProperties method returns a Resource containing the
requested set of properties of the resource identified by this
Resource.
Many property values are defined as a list of references to other
resources. The PropertyNameList provides a mechanism for
retrieving in one request the properties from the resources
identified by those references. This not only decreases the number
of requests required, but also allows the server to minimize the
number of separate read transactions required on the underlying
persistent store.
Marshalling:
Resource doReadProperties(PropertyNameList w)
4.1.3doWriteProperties Method
The doWriteProperties method commits the property updates that have
been applied to this Resource.
Marshalling:
void doWriteProperties()
4.1.4doReadContent Method
The doReadContent method writes the current content of the resource
identified by this Resource to the OutputStream, and returns a
Resource containing a requested set of properties of this Resource.
Marshalling:
Resource doReadContent(PropertyNameList w, OutputStream content)
4.1.5doWriteContent Method
The doWriteContent method writes the content from the InputStream
to the resource identified by this Resource. If the content
identifier of the resource at the time of the request does not
match the content identifier specified in the doWriteContent
argument list, the request fails. This allows the client to ensure
it is not overwriting content written by another client.
Clemm [Page 16]
INTERNET-DRAFT WVCM API May 8, 2002
Marshalling:
void doWriteContent(InputStream content, String contentIdentifier)
4.1.6doDelete Method
Marshalling:
void doDelete()
Postconditions:
(resource-deleted): There is no resource at the location identified
by this Resource.
4.1.7doCopy Method
Marshalling:
void doCopy(Resource destination, boolean overwrite)
Postconditions:
(must-not-copy-property): A property defined by this document MUST
NOT have been copied to the new resource created by this request,
but instead that property of the new resource MUST have the default
initial value it would have had if the new resource had been
created by doCreateResource.
(copy-creates-new-resource): If the source of a doCopy is a
controlled resource, and if there is no resource at the destination
of the doCopy, then the doCopy creates a new uncontrolled resource
at the destination of the doCopy.
4.1.8doMove Method
Marshalling:
void doMove(String destinationLocation, Boolean overwrite)
Postconditions:
(preserve-properties): The property values of the resource
identified by this Resource MUST NOT have been modified by the
doMove request unless this specification states otherwise.
(workspace-member-moved): If this Resource did not identify a
workspace, the Workspace property MUST have been updated to have
the same value as the Workspace of its parent folder at the
destination location.
Clemm [Page 17]
INTERNET-DRAFT WVCM API May 8, 2002
4.2 ControllableResource Methods
4.2.1Additional doWriteContent Semantics
Preconditions:
(cannot-modify-version-controlled-content): If this
ControllableResource identifies a resource whose IsCheckedOut
property is false, the request MUST fail.
4.2.2Additional doDelete Semantics
Preconditions:
(cannot-modify-checked-in-parent): If this Resource identifies a
controlled resource, the doDelete MUST fail when the folder
containing the controlled resource is a checked-in controlled
folder.
4.2.3Additional doMove Semantics
Preconditions:
(cannot-modify-checked-in-parent): If this ControllableResource is
a controlled resource, the request MUST fail when the folder
containing this ControllableResource is a checked-in controlled
folder.
(cannot-modify-destination-checked-in-parent): If this
ControllableResource is a controlled resource, the request MUST
fail when the folder containing the destination location is a
checked-in controlled folder.
4.2.4doControl Method
Marshalling:
void doControl()
Preconditions:
(cannot-modify-checked-in-parent): If the parent of this
ControllableResource is a checked-in controlled folder and this
ControllableResource is not already under control, the request MUST
fail.
Postconditions:
(initialize-checked-out): The IsCheckedOut property of the resource
identified by this ControllableResource MUST be FALSE.
Clemm [Page 18]
INTERNET-DRAFT WVCM API May 8, 2002
4.2.5doCheckout Method
A doCheckout request can be applied to a checked-in resource to
allow modifications to the content of that controlled resource.
Marshalling:
void doCheckout()
Preconditions:
(must-be-checked-in): The IsCheckedOut property of this
ControllableResource MUST be FALSE.
(must-not-be-stale): If the content is being maintained on both the
client and server, the state on the server MUST NOT have changed
since it was last synchronized with the state on the client.
Postconditions:
(is-checked-out): The resource identified by this
ControllableResource MUST have an IsCheckedOut property whose value
is TRUE.
4.2.6doCheckin Method
A doCheckin request can be applied to a checked-out controlled
resource to allow its content to be visible in other workspaces.
Marshalling:
void doCheckin()
Preconditions:
(must-be-checked-out): This ControllableResource MUST identify a
resource whose IsCheckedOut property is TRUE.
(must-not-be-stale): If the content is being maintained on both the
client and server, the state on the server MUST NOT have changed
since it was last synchronized with the state on the client.
Postconditions:
(update-server-content): If the content is being maintained on both
the client and server, the content on the server MUST have been
updated to contain the content on the client.
4.2.7doRefresh Method
If content for a resource is being maintained on both the client
and the server, a doRefresh request can be used to update the local
Clemm [Page 19]
INTERNET-DRAFT WVCM API May 8, 2002
persistent copy of the content of a controlled resource to be the
same as the persistent content on the server.
Marshalling:
void doRefresh(Boolean IgnoreDirty)
Preconditions:
(must-not-be-dirty): If IgnoreDirty is false, then the state on the
client MUST NOT have changed since it was last synchronized with
the state on the server.
Postconditions:
(content-synchronized): The content on the client has been updated
to be the same as the content on the server.
4.3 Folder Methods
4.3.1doReadMemberList Method
The doReadMemberList method returns a list of proxies containing
the requested set of properties, where the list contains the folder
and other members of that folder.
Marshalling:
<Resource>Iterator doReadMemberList
(PropertyNameList wantedPropertyList, boolean deep)
Postconditions:
(read-bound-members): The result contains a proxy for the folder
identified by this Folder, as well as a proxy for each bound member
of the folder.
(read-all-members): If deep is true, the result contains a proxy
for every member of the folder identified by this Folder.
4.4 Workspace Methods
4.4.1Additional doCreateResource Semantics
Preconditions:
(workspace-location-allowed): A server MAY restrict workspace
creation to particular folders, but a client can determine the
location of these folders from the WorkspaceFolderList property.
Clemm [Page 20]
INTERNET-DRAFT WVCM API May 8, 2002
(workspace-server-location-specified): If persistent state of the
workspace is stored on both the client and the server, the
WorkspaceServerLocation property MUST identify the location of the
server state for this Workspace.
4.4.2Additional doMove Semantics
Postconditions:
(workspace-moved): If this proxy identified a workspace, any
reference to that workspace in a Workspace property MUST have been
updated to refer to the new location of that workspace.
5 VERSIONING WORKSPACE SEMANTICS
When a server supports versioning, the history of the content of a
controlled resource is captured in the form of a set of versions of
that resource. Unlike non-versioning servers, where work can only
be effectively shared between the client workspaces that are
associated with a common server location, a versioning server
allows work to be shared in a very flexible manner between
arbitrary workspaces, by merging consistent sets of versions
created in one workspace into the corresponding controlled
resources of another workspace.
5.1 Creating a Version-Controlled Resource
In order to track the history of the content of a version-
controllable resource, a user can put the resource under version
control with a doControl request. The doControl request on a
version-controllable resource performs three distinct operations:
1) It creates a new version history resource. Each version history
resource is assigned a new distinct and unique server-defined
location.
2) It creates a new version resource and adds it to the new version
history resource. The content of the new version resource is a
copy of that of the controllable resource. The server assigns the
new version resource a new distinct and unique location.
3) It converts the controllable resource into a version-controlled
resource. Note that the location of the resource remains
unchanged. As part of this conversion, it adds a CheckedIn
property that identifies the new version resource.
Clemm [Page 21]
INTERNET-DRAFT WVCM API May 8, 2002
In the following example, foo.html is a controllable resource that
is put under version control. After the doControl request
succeeds, there are two additional resources: a new version history
resource and a new version resource in that version history. The
controllable resource is converted into a version-controlled
resource, whose CheckedIn property identifies the new version
resource. The content of a resource is represented by the symbol
appearing inside the box for that resource (e.g. "S1" in the
following example).
===doControl==>
| +----+ version
| version- | | history
controllable | controlled +----+ resource
resource | resource |
/foo.html | /foo.html |
| v
+----+ | +----+ CheckedIn +----+ version
| S1 | | | S1 |----------->| S1 | resource
+----+ | +----+ +----+ /his/73/ver/1
Thus, whereas before the doControl request there was only one,
uncontrolled resource, after doControl there are three separate,
distinct resources, each containing its own state and properties:
the version-controlled resource, the version resource, and the
version history resource. Since the version-controlled resource
and the version resource are separate, distinct resources, when a
method is applied to a version-controlled resource, it is only
applied to that version-controlled resource, and is not applied to
the version resource that is currently identified by the CheckedIn
property of that version-controlled resource. Although the content
of a checked-in version-controlled resource is required to be the
same as that of the version identified by its current CheckedIn
property, its properties may differ. An implementation may
optimize storage by retrieving the content of a checked-in version-
controlled resource from the version identified by its current
CheckedIn property rather than storing it in the version-controlled
resource, but this is just an implementation optimization.
5.2 Modifying a Version-Controlled Resource
In order to modify the content of a version-controlled resource,
the version-controlled resource must first be checked out. When
the checked-out resource is checked in, a new version is created in
the version history of that version-controlled resource. The
version that was checked out is remembered as the predecessor of
the new version.
Clemm [Page 22]
INTERNET-DRAFT WVCM API May 8, 2002
The following diagram illustrates the effect of the
checkout/checkin process on a version-controlled resource and its
version history. The symbol inside a box (S1, S2, S3) represents
the current content of the resource represented by that box. The
symbol next to a box (V1, V2, V3) represents the location of that
resource.
==doCheckout=> ==doWriteContent=> ==doCheckin=>
/foo.html (version-controlled resource)
+----+ | +----+ | +----+ | +----+
| S2 | | | S2 | | | S3 | | | S3 |
+----+ | +----+ | +----+ | +----+
Checked-In=V2|Checked-Out=V2|Checked-Out=V2|Checked-In=V3
/his/73 (version history for /foo.html)
+----+ | +----+ | +----+ | +----+
| S1 | V1 | | S1 | V1 | | S1 | V1 | | S1 | V1
+----+ | +----+ | +----+ | +----+
| | | | | | |
| | | | | | |
+----+ | +----+ | +----+ | +----+
| S2 | V2 | | S2 | V2 | | S2 | V2 | | S2 | V2
+----+ | +----+ | +----+ | +----+
| | | |
| | | |
| | | +----+
| | | | S3 | V3
| | | +----+
Note that a version captures only a defined subset of the state of
a resource. In particular, a version of a basic resource captures
its content, but not its live properties.
5.3 Workspaces
Multiple workspaces may be used to expose different versions and
configurations of a set of version-controlled resources
concurrently. In order to make changes to a version-controlled
resource in one workspace visible in another workspace, that
version-controlled resource must be checked in, and then the
corresponding version-controlled resource in the other workspace
can be updated to display the content of the new version.
In order to ensure unambiguous baselining (see Section 5.5) and
merging (see Section 5.7) semantics, a workspace may contain at
most one version-controlled resource for a given version history.
This is required for unambiguous baselining because a baseline can
Clemm [Page 23]
INTERNET-DRAFT WVCM API May 8, 2002
only select one version for a given version-controlled resource.
This is required for unambiguous merging because the doMerge method
must identify which version-controlled resource is to be the merge
target of a given version.
Initially, an empty workspace can be created. New resources can
then be added to the workspace with methods such as
doCreateResource. Version-controlled resources for existing
version histories can be added to the workspace with
doCreateControlledResource requests. Folders in the workspace can
be placed under baseline control, and then initialized by existing
baselines.
5.4 Folder Versions
As with any version-controllable resource, when a version-
controllable folder is put under control, a version history
resource is created to contain its versions. In order to preserve
standard versioning semantics (a version of a folder should not be
modifiable), a folder version only records information about the
version-controlled bindings of that folder. In order to add,
remove, or rename a controlled bound member of a controlled folder,
the folder must first be checked out and then checked in to commit
the change.
In order to cleanly separate a modification to the namespace from a
modification to content, a version of a folder has no members, but
instead records in its ControlledBindingList property the binding
name and version history resource of each version-controlled bound
member of that folder. If, instead, a folder version contained
bindings to other versions, creating a new version of a resource
would require creating a new version of all the folder versions
that contain that resource, which would cause activities to become
entangled. For example, suppose a "feature-12" activity created a
new version of /x/y/a.html. If a folder version contained bindings
to versions of its members, a new version of /x/y would have to be
created to contain the new version of /x/y/a.html, and a new
version of /x would have to be created to contain the new version
of /x/y. Now suppose a "bugfix-47" activity created a new version
of /x/z/b.html. Again, a new version of /x/z and a new version of
/x would have to be created to contain the new version of
/x/y/b.html. But now it is impossible to merge just "bugfix-47"
into another workspace without "feature-12", because the version of
/x that contains the desired version of /x/z/b.html also contains
version of /x/y/a.html created for "feature-12". If, instead, a
folder version just records the binding name and version history
resource of each version-controlled bound member, changing the
version selected by a member of that folder would not require a new
version of the folder. The new version is still in the same
version history so no new folder version is required, and "feature-
12" and "bugfix-47" would not become entangled.
Clemm [Page 24]
INTERNET-DRAFT WVCM API May 8, 2002
In the following example, there are three version histories, named
VH14, VH19, and VH24, where VH14 contains versions of a folder.
The version-controlled folder /x has version V2 of version history
VH14 as its CheckedIn version. Since V2 has recorded two version
controlled bindings, one with binding name "a" to version history
VH19, and the other with binding name "b" to version history VH24,
/x MUST have two version-controlled bindings, one named "a" to a
version-controlled resource for history VH19, and the other named
"b" to a version-controlled resource for history VH24. The
version-controlled resource /x/a currently has V4 of VH19 as its
CheckedIn version, while /x/b has V8 of VH24 as its CheckedIn
version.
VH19
+---------+
| +---+ |
| | |V4 |
| +---+ |
| | |
| | |
| +---+ |
| | |V5 |
VH14 | +---+ |
+---------+ | | |
| +---+ | | | |
a +---+ | | |V1 | | +---+ |
---->| |CheckedIn=V4 | +---+ | a | | |V6 |
/ +---+ | | ------>| +---+ |
/ | | / | +---------+
+---+ | +---+ |
/x | |CheckedIn=V2 | | |V2 |
+---+ | +---+ | VH24
\ | | \ | b +---------+
\ b +---+ | | ------>| +---+ |
---->| |CheckedIn=V8 | +---+ | | | |V7 |
+---+ | | |V3 | | +---+ |
| +---+ | | | |
+---------+ | | |
| +---+ |
| | |V8 |
| +---+ |
| | |
| | |
| +---+ |
| | |V9 |
| +---+ |
+---------+
For any request (e.g. doControl, doDelete, doMove) that modifies a
version-controlled binding of a checked-in version-controlled
folder, the request MUST fail.
Clemm [Page 25]
INTERNET-DRAFT WVCM API May 8, 2002
Although a folder version only records the version-controlled bound
members of a folder, a version-controlled folder MAY have both
controlled and uncontrolled bound members. Uncontrolled bound
members are not under version control, and therefore can be added
or deleted without checking out the version-controlled folder.
Note that a folder version captures only a defined subset of the
state of a folder. In particular, a version of a folder captures
its bindings to version-controlled resources, but not its live
properties or bindings to uncontrolled members.
5.5 Configurations and Baselines
A configuration is a set of resources that consists of all members
of a root folder except those resources that are members of another
configuration. A configuration that contains a large number of
resources can consume a large amount of space on a server. This
can make it prohibitively expensive to capture the state of a
configuration by creating a copy of all resources in the
configuration.
A baseline is a version resource that captures the state of each
version-controlled member of a configuration. A baseline history
is a version history whose versions are baselines. New baselines
are created by checking out and then checking in a special kind of
version-controlled resource called a version-controlled
configuration.
A folder that is under baseline control is called a baseline-
controlled folder. In order to allow efficient baseline
implementation, the state of a baseline of a folder is limited to
be a set of versions and their names relative to the folder, and
the operations on a baseline are limited to the creation of a
baseline from a folder, and restoring or merging the baseline back
into a folder. A client can use the doBaselineControl method to
put a specified folder under baseline control.
As a configuration gets large, it is often useful to break it up
into a set of smaller configurations that form the logical
"components" of that configuration. In order to capture the fact
that a baseline of a configuration is logically extended by a
component configuration baseline, the component configuration
baseline is captured as a "sub-baseline" of the baseline.
The root folder of a configuration is unconstrained with respect to
its relationship to the root folder of any of its components. In
particular, the root folder of a configuration can have a member
that is the root folder of one of its components (e.g.
configuration /sys/x can have a component /sys/x/foo), can be a
member of the root folder of one of its components (e.g.
configuration /sys/y/z can have a component /sys/y), or neither
(e.g. configuration /sys/x can have a component /comp/bar).
Clemm [Page 26]
INTERNET-DRAFT WVCM API May 8, 2002
In the following example, the folder /src is placed under baseline
control, and is populated with members from an existing baseline.
A new version-controlled configuration (/repo/vcc/128) is created
and associated with /src, and /src is initialized with version-
controlled members whose CheckedIn versions are those selected by
the BaselineFolder (/repo/bc/15) of the specified baseline
(/repo/blh/13/ver/8). The following diagram illustrates the
resulting state on the server.
+----------------------------+
|Baseline-Controlled Folder |<------+
|/src | |
|----------------------------| |
|ControlledConfiguration +---+ |
+----------------------------+ | |
| |
| |
+----------------------------+ | |
|Controlled Configuration |<--+ |
|/repo/vcc/128 | |
|----------------------------| |
|RootFolder +-------+
|----------------------------|
|CheckedIn +-------+
|----------------------------+ |
|VersionHistory +---+ |
+----------------------------+ | |
| |
| |
+--------------------+ | |
|Baseline History |<----------+ |
|/repo/blh/13 | |
|--------------------+ |
|VersionList +-----------+ |
+--------------------+ | | | |
v | v |
| |
+--------------------+ | |
|Baseline |<-------+------+
|/repo/blh/13/ver/8 |
|--------------------+ +------------+
|BaselineFolder +-->|Folder |
+--------------------+ |/repo/bc/15 |
+------------+
In order to create new baselines of /src, /repo/vcc/128 can be
checked out, new versions can be created or selected by the
version-controlled members of /src, and then /repo/vcc/128 can be
checked in to capture the current state of those version-controlled
members.
Clemm [Page 27]
INTERNET-DRAFT WVCM API May 8, 2002
5.6 Activities
An activity is a resource that selects a set of versions that are
on a single "line of descent", where a line of descent is a
sequence of versions connected by successor relationships. If an
activity selects versions from multiple version histories, the
versions selected in each version history must be on a single line
of descent.
A common problem that motivates the use of activities is that it is
often desirable to perform several different logical changes in a
single workspace, and then selectively merge a subset of those
logical changes to other workspaces. An activity can be used to
represent a single logical change, where an activity tracks all the
resources that were modified to effect that single logical change.
When a version-controlled resource is checked out, the user
specifies which activity should be associated with a new version
that will be created when that version-controlled resource is
checked in. It is then possible to select a particular logical
change for merging into another workspace, by specifying the
appropriate activity in a doMerge request.
Another common problem is that although a version-controlled
resource may need to have multiple lines of descent, a particular
team may want all work done by members of that team to be on a
single line of descent (to avoid merging between team members). An
activity resource provides the mechanism for addressing this
problem. When a version-controlled resource is checked out, a
client can request that an existing activity be used or that a new
activity be created. Activity semantics then ensure that all
versions in a given version history that are associated with an
activity are on a single line of descent. If all members of a team
share a common activity (or sub-activities of a common activity),
then all changes made by members of that team will be on a single
line of descent.
Clemm [Page 28]
INTERNET-DRAFT WVCM API May 8, 2002
The following diagram illustrates activities. Version V5 is the
latest version of foo.html selected by activity Act-2, and version
V8 is the latest version of bar.html selected by activity Act-2.
foo.html History bar.html History
+---+ +---+
Act-1| |V1 Act-1| |V6
+---+ +---+
| |
| |
+---+ +---+
Act-1| |V2 Act-2| |V7
+---+ +---+
/ \ |
/ \ |
+---+ +---+ +---+
Act-1| |V3 Act-2| |V4 Act-2| |V8
+---+ +---+ +---+
| |
| |
+---+ +---+
Act-2| |V5 Act-3| |V9
+---+ +---+
Activities appear under a variety of names in existing versioning
systems. When an activity is used to capture a logical change, it
is commonly called a "change set". When an activity is used to
capture a line of descent, it is commonly called a "branch". When
a system supports both branches and change sets, it is often useful
to require that a particular change set occur on a particular
branch. This relationship can be captured by making the change set
activity be a "sub-activity" of the branch activity.
5.7 Merging
When a user wants to accept the changes (new versions) created by
someone else, it is important not just to update the version-
controlled resources in the user's workspace with those new
versions, since this could result in "backing out" changes the user
has made to those version-controlled resources. Instead, the
versions created in another workspace should be "merged" into the
user's version-controlled resources.
The version history of a version-controlled resource provides the
information needed to determine the result of the merge. In
particular, the merge should select whichever version is later in
the line of descent from the root version. In case the versions to
be merged are on different lines of descent (neither version is a
descendant of the other), neither version should be selected, but
instead, a new version should be created that contains the logical
merge of the content of those versions. The doMerge request can be
used to check out each version-controlled resource that requires
Clemm [Page 29]
INTERNET-DRAFT WVCM API May 8, 2002
such a merge, and set the MergeList property of each checked-out
resource to identify the version to be merged. The user is
responsible for modifying the content of the checked-out resource
so that it represents the logical merge of that version, and then
adding that version to the PredecessorList of the checked-out
resource.
If the server is capable of automatically performing the merge, it
MAY update the content and PredecessorList of the checked-out
resource itself. Before checking in the automatically merged
resource, the user is responsible for verifying that the automatic
merge is correct.
5.8 Labels
A version "label" is a string that distinguishes one version in a
version history from all other versions in that version history. A
label can automatically be assigned by a server, or it can be
assigned by a client in order to provide a meaningful name for that
version. A given version label can be assigned to at most one
version of a given version history, but client assigned labels can
be reassigned to another version at any time. Note that although a
given label can be applied to at most one version from the same
version history, the same label can be applied to versions from
different version histories.
6 VERSIONING PROPERTIES
6.1 Additional Resource Properties
6.1.1ActivityFolderList
This property identifies folders on the server implementing this
resource that may contain activities. This property allows a
client that knows the location of one resource on a server to find
activities on that server. An identified folder MAY be the root
folder of a tree of folders, all of which may contain activities.
Since different servers can control different parts of the resource
namespace, different resources on the same host MAY have different
ActivityFolderList values. The identified folders MAY be located
on different hosts from the resource.
<Folder>List getActivityFolderList()
6.1.2VersionHistoryFolderList
This property identifies folders on the server implementing this
resource that may contain version histories. This property allows
a client that knows the location of one resource on a server to
find version histories on that server. An identified folder MAY be
Clemm [Page 30]
INTERNET-DRAFT WVCM API May 8, 2002
the root folder of a tree of folders, all of which may contain
version histories. Since different servers can control different
parts of the resource namespace, different resources on the same
host MAY have different VersionHistoryFolderList values. The
identified folders MAY be located on different hosts from the
resource.
<Folder>List getVersionHistoryFolderList()
6.2 Additional ControllableResource Properties
6.2.1VersionControllable
This property identifies whether or not versions will be tracked
for the resource when it is controlled.
Boolean getVersionControllable()
6.2.2VersionHistory
This property identifies the version history resource for the
CheckedIn or CheckedOut version of this version-controlled
resource.
VersionHistory getVersionHistory()
6.2.3CheckedIn
This property appears on a checked-in version-controlled resource,
and identifies a version that has the same content as the version-
controlled resource. This property is removed when the resource is
checked out, and then added back (identifying a new version) when
the resource is checked back in.
Version getCheckedIn()
6.2.4CheckedOut
This property on a checked-out version-controlled resource
identifies the version that was identified by the CheckedIn
property at the time the resource was checked out. This property is
removed when the resource is checked in.
Version getCheckedOut()
6.2.5PredecessorList
This property on a checked-out version-controlled resource
determines the PredecessorList property of the version that results
from checking in this resource.
A server MAY reject attempts to modify the PredecessorList of a
version-controlled resource.
Clemm [Page 31]
INTERNET-DRAFT WVCM API May 8, 2002
<Version>List getPredecessorList()
setPredecessorList(<Version>List)
6.2.6ActivityList
This property on a checked-out version-controlled resource
determines the ActivityList property of the version that results
from checking in this resource.
<Activity>List getActivityList()
setActivityList(<Activity>List)
6.2.7Unreserved
This property on a checked-out version-controlled resource
indicates whether the ActivityList of another checked-out resource
associated with the version history of this version-controlled
resource can have an activity that is in the ActivityList property
of this checked-out resource.
A result of the requirement that an activity must form a single
line of descent through a given version history is that if multiple
checked-out resources for a given version history are checked out
unreserved into a single activity, only the first doCheckin will
succeed. Before another of these checked-out resources can be
checked in, the user will first have to merge into that checked-out
resource the latest version selected by that activity from that
version history, and then modify the PredecessorList of that
checked-out resource to identify that version.
boolean getUnreserved()
setUnreserved(boolean unreserved)
6.2.8MergeList
This property on a checked-out version-controlled resource
identifies each version that is to be merged into this checked-out
resource.
<Version>List getMergeList()
setMergeList(<Version>List)
6.2.9AutoMergeList
This property on a checked-out version-controlled resource
identifies each version that the server has merged into this
checked-out resource. The client should confirm that the merge has
been performed correctly before moving an entry from the
AutoMergeList to the PredecessorList of a checked-out resource.
<Version>List getAutoMergeList()
setAutoMergeList(<Version>List)
Clemm [Page 32]
INTERNET-DRAFT WVCM API May 8, 2002
6.2.10 ControlledConfiguration
If the resource is a member of a controlled configuration (i.e. the
resource is a member of a folder under baseline control), this
property identifies that controlled configuration.
Configuration getControlledConfiguration()
6.3 Folder Properties
6.3.1BaselineControllable
This property identifies whether or not the folder can be placed
under baseline control with a doBaselineControl request.
Boolean getBaselineControllable()
6.3.2EclipsedList
When a folder is version-controlled, this property identifies the
uncontrolled bound members of the folder that currently are
eclipsing a version-controlled bound member of the folder.
<String>List getEclipsedList()
A doUpdate or doMerge request can give a version-controlled folder
a version-controlled bound member that has the same name as an
existing uncontrolled bound member. In this case, the uncontrolled
bound member takes precedence and is said to "eclipse" the new
versioned-controlled bound member. If the uncontrolled bound
member is removed (e.g. by a doDelete or doMove), the version-
controlled bound member is exposed.
6.4 Additional Workspace Properties
6.4.1BaselineControlledFolderList
This property identifies each member of the workspace that is a
folder under baseline control.
<Folder>List getBaselineControlledFolderList()
6.4.2CurrentActivityList
This property identifies the activities that currently are being
performed in this workspace. When a member of this workspace is
checked out, if no activity is specified in the checkout request,
the CurrentActivityList will be used. This allows an activity-
unaware client to update a workspace in which activity tracking is
required. The CurrentActivityList MAY be restricted to identify at
most one activity.
Clemm [Page 33]
INTERNET-DRAFT WVCM API May 8, 2002
<Activity>List getCurrentActivityList()
setCurrentActivityList(<Activity>List)
6.5 Version Properties
6.5.1VersionHistory
This property identifies the version history that contains this
version.
VersionHistory getVersionHistory()
6.5.2PredecessorList
This property identifies each predecessor of this version. Except
for the root version, which has no predecessors, each version has
at least one predecessor.
<Version>List getPredecessorList()
6.5.3SuccessorList
This property identifies each version whose PredecessorList
identifies this version.
<Version>List getSuccessorList()
6.5.4CheckoutList
This property identifies each checked-out resource whose CheckedOut
property identifies this version.
<ControllableResource>List getCheckoutList()
6.5.5ActivityList
This property identifies the activities that determine to which
logical changes this version contributes, and on which lines of
descent this version appears. A server MAY restrict the
ActivityList to identify a single activity. A server MAY refuse to
allow the value of the ActivityList property of a version to be
modified.
<Activity>List ActivityList()
setActivityList(<Activity>List)
6.5.6CheckoutFork
This property controls the behavior of doCheckout when a version
already is checked out or has a successor. If the CheckoutFork of
a version is FORBIDDEN, a doCheckout request MUST fail if it would
result in that version appearing in the PredecessorList or
CheckedOut property of more than one version or checked-out
Clemm [Page 34]
INTERNET-DRAFT WVCM API May 8, 2002
resource. If CheckoutFork is DISCOURAGED, such a doCheckout
request MUST fail unless forkOk is specified in the doCheckout
request.
A server MAY reject attempts to modify the CheckoutFork of a
version.
int getCheckoutFork()
setCheckoutFork(int checkoutFork)
6.5.7CheckinFork
This property controls the behavior of doCheckin when a version
already has a successor. If the CheckinFork of a version is
FORBIDDEN, a doCheckin request MUST fail if it would result in that
version appearing in the PredecessorList of more than one version.
If CheckinFork is DISCOURAGED, such a doCheckin request MUST fail
unless forkOk is specified in the doCheckin request.
A server MAY reject attempts to modify the CheckinFork of a
version.
int getCheckinFork()
setCheckinFork(int checkinFork)
6.5.8VersionName
This property contains a server-defined string that is different
for each version in a given version history. This string is
intended for display to a user, unlike the location of a version,
which is normally only used by a client and not displayed to a
user.
String getVersionName()
6.5.9LabelNameList
This property contains the labels that currently select this
version.
<String>List getLabelNameList()
6.6 VersionHistory Properties
6.6.1RootVersion
This property identifies the root version of this version history.
Version getRootVersion()
6.6.2VersionList
This property identifies each version of this version history.
Clemm [Page 35]
INTERNET-DRAFT WVCM API May 8, 2002
<Version>List getVersionList()
6.7 Folder Version Properties
6.7.1ControlledBindingList
This property captures the name and version-history of each
version-controlled bound member of a folder.
<Binding>List getControlledBindingList()
Interface Binding {
String getBindingName();
VersionHistory getVersionHistory(); }
6.8 Baseline Properties
6.8.1BaselineFolder
This property identifies a folder at a server-defined location,
where each member of this folder MUST either be a version-
controlled resource with the same CheckedIn version and relative
name as a version-controlled member of the baseline-controlled
folder at the time the baseline was created, or be a folder needed
to provide the relative name for a version-controlled resource.
Folder getBaselineFolder()
6.8.2SubbaselineList
The sub-baselines of a baseline are the baselines identified by its
SubbaselineList and all sub-baselines of the baselines identified
by its SubbaselineList.
<Baseline>List getSubbaselineList()
6.9 Configuration Properties
6.9.1RootFolder
This property identifies the root folder of the configuration. The
ControlledConfiguration property of the root folder of a version-
controlled configuration MUST identify that version-controlled
configuration.
Folder getRootFolder()
6.9.2SubbaselineList
This property of a checked-out version-controlled configuration
determines the SubbaselineList property of the baseline that
results from checking it in.
Clemm [Page 36]
INTERNET-DRAFT WVCM API May 8, 2002
A server MAY reject attempts to modify the SubbaselineList of a
checked-out configuration.
<Baseline>List getSubbaselineList()
setSubbaselineList(<Baseline>List)
6.10Activity Properties
6.10.1 ActivityVersionList
This property identifies each version whose ActivityList property
identifies this activity. Multiple versions of a single version
history can be selected by an activity's ActivityVersionList
property, but all ActivityVersionList versions from a given version
history must be on a single line of descent from the root version
of that version history.
<Version>List getActivityVersionList()
6.10.2 ActivityCheckoutList
This property identifies each checked-out resource whose
ActivityList identifies this activity.
<ControllableResource>List getActivityCheckoutList()
6.10.3 SubactivityList
This property identifies each activity that forms a part of the
logical change being captured by this activity. An activity
behaves as if its ActivityVersionList is extended by the
ActivityVersionList of each activity identified in the
SubactivityList. In particular, the versions in this extended set
MUST be on a single line of descent, and when an activity selects a
version for merging, the latest version in this extended set is the
one that will be merged.
A server MAY reject attempts to modify the SubactivityList of an
activity.
<Activity>List getSubactivityList()
setSubactivityList(<Activity>List)
6.10.4 CurrentWorkspaceList
This property identifies each workspace whose CurrentActivityList
identifies this activity.
<Workspace>List getCurrentWorkspaceList()
Clemm [Page 37]
INTERNET-DRAFT WVCM API May 8, 2002
7 VERSIONING METHODS
7.1 Additional ControllableResource Methods
7.1.1Additional doControl Semantics
Postconditions:
(put-under-version-control): If this ControllableResource
identified a version-controllable resource at the time of the
request, the request MUST have created a new version history and
MUST have created a new version resource in that version history.
The resource MUST have a CheckedIn property that identifies the new
version. The content of the new version MUST be the same as that
of the resource. Note that an implementation can choose to locate
the version history and version resources anywhere that it wishes.
In particular, it could locate them on the same host and server as
the version-controlled resource, on a different virtual host
maintained by the same server, on the same host maintained by a
different server, or on a different host maintained by a different
server.
(must-not-change-existing-checked-in-out): If this
ControllableResource identified a resource already under version
control at the time of the request, the request MUST NOT change the
CheckedIn or CheckedOut property of that version-controlled
resource.
(new-version-history): If the request created a new version
history, the request MUST have allocated a new server-defined
location for that version history that MUST NOT have previously
identified any other resource, and MUST NOT ever identify a
resource other than this version history.
7.1.2Additional doCheckout Semantics
A doCheckout request can be applied to a checked-in version-
controlled resource to allow modifications to the content of that
version-controlled resource.
Marshalling:
void doCheckout(
boolean forkOK,
List activityList,
boolean newActivity,
boolean unreserved)
Clemm [Page 38]
INTERNET-DRAFT WVCM API May 8, 2002
Preconditions:
(checkout-of-version-with-descendant-is-forbidden): If the
CheckoutFork property of the version being checked out is
FORBIDDEN, the request MUST fail if a version identifies that
version in its PredecessorList.
(checkout-of-version-with-descendant-is-discouraged): If the
CheckoutFork property of the version being checked out is
DISCOURAGED, the request MUST fail if a version identifies that
version in its PredecessorList unless forkOk is specified in the
request.
(checkout-of-checked-out-version-is-forbidden): If the CheckoutFork
property of the version being checked out is FORBIDDEN, the request
MUST fail if a checked-out resource identifies that version in its
CheckedOut property.
(checkout-of-checked-out-version-is-discouraged): If the
CheckoutFork property of the version being checked out is
DISCOURAGED, the request MUST fail if a checked-out resource
identifies that version in its CheckedOut property unless forkOk is
specified in the request.
(must-not-update-baseline-folder): If this ControllableResource
identifies a member of the BaselineFolder of a baseline, the
request MUST fail.
(one-checkout-per-activity-per-history): If there is a request
activity set, unless Unreserved is specified, another checkout from
a version of that version history MUST NOT select an activity in
that activity set.
(linear-activity): If there is a request activity set, unless
Unreserved is specified, the selected version MUST be a descendant
of all other versions of that version history that select that
activity.
Postconditions:
(has-checked-out-version): The checked-out resource MUST have a
CheckedOut property that identifies the CheckedIn version preceding
the checkout. The version-controlled resource MUST NOT have a
CheckedIn property.
(initialize-predecessor-list): The PredecessorList property of the
checked-out resource MUST be initialized to be the CheckedOut
version.
(initialize-activity-list): The ActivityList of the checked-out
resource is set as follows:
- If newActivity is specified, then a new activity created by the
server is used.
Clemm [Page 39]
INTERNET-DRAFT WVCM API May 8, 2002
- Otherwise, if activityList is non-empty, then those activities
are used.
- Otherwise, if the version-controlled resource is a member of a
workspace and the CurrentActivityList of the workspace is set, then
those activities are used.
- Otherwise, the ActivityList of the CheckedOut version is used.
(initialize-unreserved): If unreserved was specified in the
request, then the Unreserved property of the checked-out resource
MUST be "true".
7.1.3Additional doCheckin Semantics
A doCheckin request can be applied to a checked-out version-
controlled resource to produce a new version whose content is
copied from the checked-out resource.
Marshalling:
void doCheckin(boolean keepCheckedOut, boolean forkOK)
Preconditions:
(version-history-is-tree) The versions identified by the
PredecessorList of the checked-out resource MUST be descendants of
the root version of the version history for the CheckedOut version.
(checkin-fork-forbidden): A doCheckin request MUST fail if it would
cause a version whose CheckinFork is FORBIDDEN to appear in the
PredecessorList of more than one version.
(checkin-fork-discouraged): A doCheckin request MUST fail if it
would cause a version whose CheckinFork is DISCOURAGED to appear in
the PredecessorList of more than one version, unless forkOk is
specified in the request.
(merge-must-be-complete): The MergeList and AutoMergeList of the
checked-out resource MUST be empty or not exist.
(linear-activity): Any version which is in the version history of
the checked-out resource and whose ActivityList identifies an
activity from the ActivityList of the checked-out resource MUST be
an ancestor of the checked-out resource.
Postconditions:
(create-version): The request MUST have created a new version in
the version history of the CheckedOut version. The request MUST
have allocated a distinct new location for the new version, and
that location MUST NOT ever identify any resource other than that
version.
Clemm [Page 40]
INTERNET-DRAFT WVCM API May 8, 2002
(initialize-version-content-and-properties): The content and
PredecessorList of the new version MUST be copied from the checked-
out resource. The VersionName of the new version MUST be set to a
server-defined value distinct from all other VersionName values of
other versions in the same version history.
(checked-in): If this ControllableResource identifies a version-
controlled resource and keepCheckedOut is not specified in the
request, the CheckedOut property of the version-controlled resource
MUST have been removed and a CheckedIn property that identifies the
new version MUST have been added.
(keep-checked-out): If keepCheckedOut is specified in the request,
the CheckedOut property of the checked-out resource MUST have been
updated to identify the new version.
(add-to-history): The new version resource MUST have been added to
the VersionList of the version history of the CheckedOut version.
(initialize-activity-list): The ActivityList of the new version
MUST have been initialized to be the same as the ActivityList of
the checked-out resource.
(initialize-version-controlled-bindings): If this
ControllableResource identified a version-controlled folder, then
the ControlledBindingList of the new folder version MUST contain a
Binding that identifies the binding name and version history for
each version-controlled binding of the version-controlled folder.
7.1.4Additional doMove Semantics
Postconditions:
(update-checked-out-reference): If a checked-out resource is moved,
any reference to that resource in a ActivityCheckoutList property
MUST be updated to refer to the new location of that resource.
7.1.5doUncheckout Method
A doUncheckout request can be applied to a checked-out version-
controlled resource to cancel the checkout and restore the pre-
checkout state of the version-controlled resource.
Marshalling:
void doUncheckout()
Preconditions:
(must-be-checked-out-version-controlled-resource): This
ControllableResource MUST identify a version-controlled resource
with a CheckedOut property.
Clemm [Page 41]
INTERNET-DRAFT WVCM API May 8, 2002
Postconditions:
(cancel-checked-out): The value of the CheckedIn property is that
of the CheckedOut property prior to the request, and the CheckedOut
property has been removed.
(restore-content): The content of the version-controlled resource
is a copy of that of its CheckedIn version.
7.1.6doCreateControlledResource Method
A doCreateControlledResource request can also be used to create a
new version-controlled resource for an existing version history.
This allows the creation of version-controlled resources for the
same version history in multiple workspaces.
Marshalling:
void doCreateControlledResource(Version v)
Preconditions:
(cannot-modify-checked-in-parent): If the parent of this
ControllableResource is a checked-in version-controlled folder, the
request MUST fail.
(cannot-add-to-existing-history): This ControllableResource MUST
NOT identify an existing resource.
(one-version-controlled-resource-per-history-per-workspace): There
MUST NOT already be a version-controlled member in the workspace of
this ControllableResource whose CheckedIn or CheckedOut property
identifies any version from the version history of the version
specified in the request.
Postconditions:
(new-version-controlled-resource): A new version-controlled
resource exists at the location of this ControllableResource whose
content is initialized by those of the version in the request, and
whose CheckedIn property identifies that version.
(new-version-controlled-folder): If the request identified a folder
version, the folder identified by this ControllableResource MUST
contain a version-controlled bound member for each Binding
specified in the ControlledBindingList of the folder version, where
the name and version history of the bound member MUST be the name
and version history specified by the Binding. If the bound member
is a member of a workspace, and there is another member of the
workspace for the same version history, those two members MUST
identify the same version-controlled resource; otherwise, a
doCreateControlledResource request with a server selected version
Clemm [Page 42]
INTERNET-DRAFT WVCM API May 8, 2002
of the version history MUST have been applied to the location of
that bound member.
7.1.7doUpdate Method
The doUpdate method modifies the content of a checked-in version-
controlled resource (the "update target") to be those of a
specified version (the "update source") from the version history of
that version-controlled resource. The response to a doUpdate
request identifies the resources modified by the request, so that a
client can efficiently update any cached state it is maintaining.
Marshalling:
Iterator doUpdate
(Version v, PropertyNameList wantedPropertyList)
Preconditions:
(version-in-version-history): The Version argument must identify a
version from the version history of this ControllableResource.
(must-not-update-baseline-folder): If this ControllableResource
identifies a member of the BaselineFolder of a baseline, the
request MUST fail.
Postconditions:
(update-content-and-properties): If the Version argument identified
a version that is in the same version history as the CheckedIn
version of a version-controlled resource identified by this
ControllableResource, then the content of that version-controlled
resource MUST be the same as those of the version specified by the
Version argument, and the CheckedIn property of the version-
controlled resource MUST identify that version.
(report-properties): The properties specified in the
wantedPropertyList argument MUST be reported in the result.
(update-version-controlled-folder-members): If the request modified
the CheckedIn version of a version-controlled folder, then the
version-controlled members of that version-controlled folder MUST
have been updated. In particular:
- A version-controlled bound member MUST have been deleted if its
version history is not identified by the ControlledBindingList of
the new CheckedIn version.
- A version-controlled bound member for a given version history
MUST have been renamed if its binding name differs from the Binding
name for that version history in the ControlledBindingList of the
new CheckedIn version.
- A new version-controlled bound member MUST have been created when
a version history is identified by the ControlledBindingList of the
Clemm [Page 43]
INTERNET-DRAFT WVCM API May 8, 2002
CheckedIn version, but there was no member of the version-
controlled folder for that version history.
If a new version-controlled member is in a workspace that already
has a version-controlled resource for that version history, then
the new version-controlled member MUST be just a binding (i.e.
another name for) that existing version-controlled resource.
Otherwise, the content of the new version-controlled member MUST
have been initialized to be those of the version specified for that
version history by the request. If no version is specified for
that version history by the request, the version selected is server
defined.
7.1.8doMerge Method
The doMerge method performs the logical merge of a specified
version (the "merge source") into the version-controlled resource
(the "merge target"). If the merge source is neither an ancestor
nor a descendant of the CheckedIn or CheckedOut version of the
merge target, the doMerge checks out the merge target (if it is not
already checked out) and adds the merge source to the MergeList of
the merge target. It is then the client's responsibility to update
the content of the checked-out merge target so that it reflects the
logical merge of the merge source into the current state of the
merge target. The client indicates that it has completed the
update of the merge target, by deleting the merge source from the
MergeList of the checked-out merge target, and adding it to the
PredecessorList. As an error check for a client forgetting to
complete a merge, the server MUST fail an attempt to doCheckin a
version-controlled resource with a non-empty MergeList.
When a server has the ability to automatically update the content
of the merge target to reflect the logical merge of the merge
source, it may do so unless noAutoMerge is specified in the doMerge
request. In order to notify the client that a merge source has
been automatically merged, the doMerge request MUST add the auto-
merged source to the AutoMergeList property of the merge target,
and not to the MergeList property. The client indicates that it
has verified that the auto-merge is valid, by deleting the merge
source from the AutoMergeList, and adding it to the
PredecessorList.
Marshalling:
ControllableResource doMerge(
Version source,
boolean noAutoMerge,
boolean noCheckout,
boolean forkOK,
boolean unreserved,
<Activity>List activityList,
boolean newActivity,
PropertyNameList wantedPropertyList)
Clemm [Page 44]
INTERNET-DRAFT WVCM API May 8, 2002
Preconditions:
(checkout-not-allowed): If noCheckout is specified in the request,
it MUST be possible to perform the merge without checking out the
merge target.
All preconditions of the doCheckout operation apply to any checkout
performed by the request.
(must-not-update-baseline-folder): Same semantics as doUpdate (see
Section 7.1.7).
Postconditions:
(ancestor-version): If the merge target is a version-controlled
resource whose CheckedIn version or CheckedOut version is the merge
source or is a descendant of the merge source, the merge target
MUST NOT have been modified by the doMerge.
(descendant-version): If the merge target was a checked-in version-
controlled resource whose CheckedIn version was an ancestor of the
merge source, a doUpdate operation MUST have been applied to the
merge target to set its content to be that of the merge source. If
the doUpdate method is not supported, the merge target MUST have
been checked out, the content of the merge target MUST have been
set to those of the merge source, and the merge source MUST have
been added to the AutoMergeList of the merge target.
(checked-out-for-merge): If the merge target was a checked-in
version-controlled resource whose CheckedIn version was neither a
descendant nor an ancestor of the merge source, a doCheckout MUST
have been applied to the merge target. All arguments that could
appear in a doCheckout request MUST have been used as arguments to
the doCheckout request.
(update-merge-list): If the CheckedOut version of the merge target
is not equal to or a descendant of the merge source, the merge
source MUST be added to either the MergeList or the AutoMergeList
of the merge target. The merge target MUST appear in the result.
If a merge source has been added to the AutoMergeList, the content
of the merge target MUST have been modified by the server to
reflect the result of a logical merge of the merge source and the
merge target. If a merge source has been added to the MergeList,
the content of the merge target MUST NOT have been modified by the
server. If noAutoMerge is specified in the request, the merge
source MUST NOT have been added to the AutoMergeList.
(report-properties): The properties of the merge target specified
in the wantedPropertyList argument MUST be reported in the result.
(update-version-controlled-folder-members): Same semantics as
doUpdate (see Section 7.1.7).
Clemm [Page 45]
INTERNET-DRAFT WVCM API May 8, 2002
7.1.9doMergePreview Method
The doMergePreview method returns a MergePreviewReport that
identifies the changes that would result if the version specified
by the source argument in the request were to be merged into the
resource identified by this ControllableResource.
Marshalling:
MergePreviewReport doMergePreviewReport(Version source)
interface MergePreviewReport { }
interface Update extends MergePreviewReport {
ControllableResource getTarget();
Version getVersion(); }
interface Conflict extends MergePreviewReport {
ControllableResource getTarget();
Version getCommonAncestor();
<Version>List getVersionList(); }
Interface Ignore extends MergePreviewReport {
Version GetVersion(); }
An Update identifies a merge target whose CheckedIn property would
change as a result of the doMerge, and identifies the merge source
for that merge target.
A Conflict identifies a merge target that requires a merge, where
the common ancestor identifies the version that is a common
ancestor of both the merge source and the CheckedIn or CheckedOut
version of the merge target.
An Ignore identifies a version that has no merge target and
therefore could not be merged.
7.2 Additional Workspace Methods
7.2.1Additional doMove Semantics
Postconditions:
(update-workspace-reference): If this proxy identifies a workspace,
any reference to that workspace in a CurrentWorkspaceList property
MUST be updated to refer to the new location of that workspace.
7.2.2Additional doMerge Semantics
When doMerge is applied to a workspace, multiple merge sources can
be specified in a single doMerge request. The set of merge sources
for a doMerge request is determined from the sourceList of the
doMerge request as follows:
Clemm [Page 46]
INTERNET-DRAFT WVCM API May 8, 2002
- If a sourceList member identifies a baseline, that baseline is a
merge source.
- If a sourceList member identifies a version-controlled resource,
the CheckedIn version of that version-controlled resource is a
merge source.
- If a sourceList member identifies a folder, the CheckedIn version
of each version-controlled resource that is a member of that folder
is a merge source.
- If a sourceList member identifies an activity, then for each
version history containing a version selected by that activity, the
latest version selected by that activity is a merge source. Note
that the versions selected by an activity are the versions in its
ActivityVersionList unioned with the versions selected by the
activities in its SubactivityList.
Any member of the workspace is a possible merge target. The merge
target of a particular merge source is the version-controlled
resource whose CheckedIn or CheckedOut version is from the same
version history as the merge source. If a merge source has no
merge target, that merge source is ignored.
If the merge source is a baseline, the merge target is a version-
controlled configuration for the baseline history of that baseline,
where the baseline-controlled folder of that version-controlled
configuration is a member of the workspace.
The response to a doMerge request identifies the resources that a
client must modify to complete the merge. It also identifies the
resources modified by the request, so that a client can efficiently
update any cached state it is maintaining.
Marshalling:
<ControllableResource>Iterator doMerge(
<Resource>List sourceList,
boolean noAutoMerge,
boolean noCheckout,
boolean checkinActivity,
boolean forkOK,
boolean unreserved,
<Activity>List activityList,
boolean newActivity,
PropertyNameList wantedPropertyList)
Preconditions:
(cannot-merge-checked-out-resource): The sourceList argument member
MUST NOT identify a checked-out resource. If the sourceList
argument member identifies a folder, the folder MUST NOT have a
member that is a checked-out resource.
Clemm [Page 47]
INTERNET-DRAFT WVCM API May 8, 2002
Postconditions:
(merge-baseline): If the merge target is a version-controlled
configuration whose CheckedOut baseline is not a descendant of the
merge baseline, then the merge baseline MUST have been added to the
AutoMergeList of a version-controlled configuration. The CheckedIn
version of each member of the BaselineFolder of that baseline MUST
have been merged into the RootFolder of that version-controlled
configuration.
(merge-sub-baselines): If the merge target is a version-controlled
configuration whose RootFolder contains a baseline-controlled
member for one of the sub-baselines of the merge baseline, then
that sub-baseline MUST have been merged into the version-controlled
configuration of that baseline-controlled member. If the merge
target is a version-controlled configuration whose RootFolder is a
member of a workspace that contains a baseline-controlled member
for one of the sub-baselines of the merge baseline, then that sub-
baseline MUST have been merged into the version-controlled
configuration of that baseline-controlled member.
(set-baseline-controlled-folder-members): Same semantics as
doUpdate (see Section 7.4.2).
7.2.3Additional doMergePreview Semantics
When the doMergePreview method is applied to a workspace, a list of
merge sources can be specified, and an iterator is returned of
MergePreviewReport objects that identify how the members of the
workspace identified by this Workspace would be modified by the
merge.
Marshalling:
<MergePreviewReport>Iterator doMergePreviewReport(List sourceList)
7.2.4doLocateByHistory Method
Many properties identify a version from some version history. It
is often useful to be able to efficiently locate a version-
controlled resource for that version history. The
doLocateByHistory method can be applied to a workspace to locate
the workspace member that is a version-controlled resource for one
of the specified version history resources.
Marshalling:
<ControllableResource>List doLocateByHistoryReport(
List versionHistoryList,
PropertyNameList wantedPropertyList)
Clemm [Page 48]
INTERNET-DRAFT WVCM API May 8, 2002
7.3 Additional Folder Methods
7.3.1doBaselineControl Method
A folder can be placed under baseline control with a
doBaselineControl request. When a folder is placed under baseline
control, the ControlledConfiguration property of the folder is set
to identify a new version-controlled configuration. This version-
controlled configuration can be checked out and then checked in to
create a new baseline for that folder. A new baseline history is
created containing a baseline that captures the state of the
version-controlled members of the folder, and the CheckedIn version
of the version-controlled configuration will be that baseline.
Marshalling:
void doBaselineControl()
Preconditions:
(controlled-configuration-must-not-exist): The
ControlledConfiguration property of the folder identified by this
Folder MUST not exist.
Postconditions:
(create-controlled-configuration): A new version-controlled
configuration is created, whose RootFolder property identifies the
folder.
(reference-controlled-configuration): The ControlledConfiguration
of the folder identifies the new version-controlled configuration.
(create-new-baseline): The request MUST have created a new baseline
history at a server-defined location, and MUST have created a new
baseline in that baseline history. The BaselineFolder of the new
baseline MUST identify a folder whose members have the same
relative name and CheckedIn version as the version-controlled
members of the request folder. The CheckedIn property of the new
version-controlled configuration MUST identify the new baseline.
7.3.2doCreateBaselineControlledFolder Method
A baseline-controlled folder for an existing baseline history can
be created with a doCreateBaselineControlledFolder request. When
the folder is created, the ControlledConfiguration property of the
folder is set to identify a new version-controlled configuration
whose CheckedIn version will be a specified baseline, and the
folder is initialized to contain version-controlled members whose
CheckedIn versions and relative names are determined by the
specified baseline.
Clemm [Page 49]
INTERNET-DRAFT WVCM API May 8, 2002
Marshalling:
void doCreateBaselineControlledFolder(Baseline baseline)
Preconditions:
(cannot-add-to-existing-history): This Folder MUST NOT identify an
existing resource.
(one-baseline-controlled-folder-per-history-per-workspace): There
MUST NOT be another folder in the workspace of this Folder whose
ControlledConfiguration property identifies a version-controlled
configuration for the baseline history of that baseline.
Postconditions:
(create-controlled-configuration): A new folder is created at the
location of this Folder, and a new version-controlled configuration
is created, whose RootFolder property identifies the new folder.
The ControlledConfiguration property of the new folder identifies
the new version-controlled configuration.
(select-existing-baseline): The CheckedIn property of the new
version-controlled configuration MUST have been set to identify the
specified baseline. A version-controlled member of the folder will
be created for each version in the baseline, where the version-
controlled member will have the content of that version, and will
have the same name relative to the folder as the corresponding
version-controlled resource had when the baseline was created. Any
nested folders that are needed to provide the appropriate name for
a version-controlled member will be created.
7.4 Configuration Methods
7.4.1Additional doCheckin Semantics
A doCheckin request can be applied to a checked-out version-
controlled configuration to produce a new baseline whose Baseline-
Folder captures the current state of the version-controlled members
of the RootFolder of the configuration.
Preconditions:
(no-checked-out-baseline-controlled-folder-members): If this
ControllableResource identifies a version-controlled configuration,
all version-controlled members of the RootFolder of the version-
controlled configuration MUST be checked-in.
(one-version-per-history-per-baseline): If this configuration
identifies a version-controlled configuration, the set of versions
selected by that version-controlled configuration MUST contain at
most one version from any version history, where a version is
Clemm [Page 50]
INTERNET-DRAFT WVCM API May 8, 2002
selected by a version-controlled configuration if the version is
identified by the CheckedIn property of any member of the baseline-
controlled folder of that version-controlled configuration, or is
identified by the CheckedIn property of any member of the
BaselineFolder of any sub-baseline of that version-controlled
configuration.
Postconditions:
(create-baseline-folder): If this ControllableResource identifies a
version-controlled configuration, the BaselineFolder of the new
baseline identifies a folder whose members have the same relative
name and CheckedIn version as the members of the RootFolder of the
version-controlled configuration at the time of the request.
7.4.2Additional doUpdate Semantics
Preconditions:
(baseline-controlled-members-must-be-checked-in): If this
Configuration identifies a version-controlled configuration, then
all version-controlled members of the RootFolder of that version-
controlled configuration MUST be checked-in.
Postconditions:
(set-baseline-controlled-folder-members): If the request updated
the CheckedIn property of a version-controlled configuration, then
the version-controlled members of the RootFolder of that version-
controlled configuration MUST have been updated so that they have
the same relative name, content, as the members of the
BaselineFolder of the baseline. In particular:
- A version-controlled member for a given version history MUST have
been deleted if there is no version-controlled member for that
version history in the BaselineFolder of the baseline.
- A version-controlled member for a given version history MUST have
been renamed if its name relative to the baseline-controlled folder
is different from that of the version-controlled member for that
version history in the BaselineFolder of the baseline.
- A new version-controlled member MUST have been created for each
member of the BaselineFolder of the baseline for which there is no
corresponding version-controlled member in the baseline-controlled
folder.
- A doUpdate request MUST have been applied to each version-
controlled member for a given version history whose CheckedIn
version is not the same as that of the version-controlled member
for that version history in the BaselineFolder of the baseline.
(update-sub-baselines): If the request updated a version-controlled
configuration whose RootFolder is a member of a workspace that
contains a baseline-controlled member for one of the sub-baselines
of the request baseline, then the CheckedIn property of the
Clemm [Page 51]
INTERNET-DRAFT WVCM API May 8, 2002
version-controlled configuration of that baseline-controlled member
MUST have been updated to be that sub-baseline.
7.5 Version Methods
7.5.1Additional doWriteContent Semantics
Preconditions:
(cannot-modify-version): If this proxy identifies a version, the
request MUST fail.
7.5.2Additional doCopy Semantics
Postconditions:
(copy-creates-new-resource): If this proxy identifies a version,
and if there is no resource at the destination of the doCopy, then
the doCopy creates a new uncontrolled resource at the destination
of the doCopy.
7.5.3Additional doMove Semantics
Preconditions:
(cannot-rename-version): If this proxy identifies a version, the
request MUST fail.
7.5.4Additional doDelete Semantics
Preconditions:
(no-version-delete): A server MAY fail an attempt to apply doDelete
to a version.
Postconditions:
(update-predecessor-list): If a version was deleted, the server
MUST have replaced any reference to that version in a
PredecessorList by a copy of the PredecessorList of the deleted
version.
(version-history-has-root): If the request deleted the root version
of a version history, the request MUST have updated the RootVersion
of the version history to refer to another version that is an
ancestor of all other remaining versions in that version history.
A result of this postcondition is that every version history will
have at least one version, and the only way to delete all versions
is to delete the version history resource.
Clemm [Page 52]
INTERNET-DRAFT WVCM API May 8, 2002
(delete-version-reference): If a version is deleted, any reference
to that version in a MergeList or AutoMergeList property MUST be
removed.
7.5.5doAddLabel Method
A doAddLabel request can be applied to a version to add a new label
to the LabelNameList property of that version. The case of a label
name MUST be preserved when it is stored and retrieved. When
comparing two label names to decide if they match or not, a server
SHOULD use a case-sensitive comparison of the two label names.
Marshalling:
void doAddLabel(String label)
Preconditions:
(add-must-be-new-label): The specified label MUST NOT appear in the
LabelNameList of any other version in the version history of that
version.
Postconditions:
(add-label): The specified label MUST appear in the LabelNameList
of the specified version, and MUST NOT appear in the LabelNameList
of any other version in the version history of that version.
7.5.6doSetLabel Method
A doSetLabel request can be applied to a version to remove that
label from the LabelNameList property of any other version in the
version history of that version, and to add that label to the
LabelNameList property of that version. The case of a label name
MUST be preserved when it is stored. When comparing two label
names to decide if they match or not, a server SHOULD use a case-
sensitive comparison of the two label names.
Marshalling:
void doSetLabel(String label)
Postconditions:
(set-label): The specified label MUST appear in the LabelNameList
of the specified version, and MUST NOT appear in the LabelNameList
of any other version in the version history of that version.
Clemm [Page 53]
INTERNET-DRAFT WVCM API May 8, 2002
7.5.7doRemoveLabel Method
A doRemoveLabel request can be applied to a version to remove that
label from the LabelNameList of that version. When comparing two
label names to decide if they match or not, a server SHOULD use a
case-sensitive comparison of the two label names.
Marshalling:
void doRemoveLabel(String label)
Preconditions:
(label-must-exist): The specified label MUST appear in the
LabelNameList of that version.
Postconditions:
(remove-label): The specified label MUST NOT appear in the
LabelNameList of any version in the version history of that
version.
7.6 Version History Methods
7.6.1Additional doCopy Semantics
Preconditions:
(cannot-copy-history): If this proxy identifies a version history,
the request MUST fail. In order to create another version history
whose versions have the same content, the appropriate sequence of
doControl, doCheckout, doWriteContent, and doCheckin requests must
be made.
7.6.2Additional doMove Semantics
Preconditions:
(cannot-rename-history): This proxy MUST NOT identify a version
history.
7.6.3Additional doDelete Semantics
Postconditions:
(delete-version-set): If the request deleted a version history, the
request MUST have deleted all versions in the VersionList of that
version history, and MUST have satisfied the postconditions for
version deletion.
Clemm [Page 54]
INTERNET-DRAFT WVCM API May 8, 2002
7.7 Folder Version Methods
7.7.1Additional doCopy Semantics
Preconditions:
(cannot-copy-folder-version): This proxy MUST NOT identify a folder
version.
7.8 Baseline Methods
7.8.1doCompareBaseline Method
A doCompareBaseline method reports the differences between the
baseline identified by this Baseline (the "request baseline") and
the baseline specified in the request (the "compare baseline").
Marshalling:
public interface AddedVersion {
public Version getVersion; }
public interface DeletedVersion {
public Version getVersion; }
public interface ChangedVersion {
public Version getOldVersion();
public Version getNewVersion(); }
public Iterator doCompareBaselineReport(Baseline baseline)
An AddedVersion object identifies a version that is the CheckedIn
version of a member of the BaselineFolder of the compare baseline,
but no version in the version history of that version is the
CheckedIn version of a member of the BaselineFolder of the request
baseline.
A DeletedVersion object identifies a version that is the CheckedIn
version of a member of the BaselineFolder of the request baseline,
but no version in the version history of that version is the
CheckedIn version of a member of the BaselineFolder of the compare
baseline.
A ChangedVersion object identifies two different versions from the
same version history that are the CheckedIn version of the
BaselineFolder of the request baseline and the compare baseline,
respectively.
Preconditions:
(baselines-from-same-history): A server MAY require that the
baselines being compared be from the same baseline history.
Clemm [Page 55]
INTERNET-DRAFT WVCM API May 8, 2002
7.9 Activity Methods
7.9.1Additional doCreateResource Semantics
Preconditions:
(activity-location-allowed): A server MAY restrict activity
creation to particular folders, but a client can determine the
location of these folders from the ActivityFolderList property.
7.9.2Additional doMove Semantics
Postconditions:
(update-activity-reference): If this proxy identifies an activity,
any reference to that activity in a ActivityList, SubactivityList,
or CurrentActivityList MUST be updated to refer to the new location
of that activity.
7.9.3Additional doDelete Semantics
Postconditions:
(delete-activity-reference): If an activity is deleted, any
reference to that activity in an ActivityList, SubactivityList, or
CurrentActivityList MUST be removed.
7.9.4Additional doCheckin Semantics
Preconditions:
(atomic-activity-checkin): If this proxy identifies an activity,
the server MAY fail the request if any of the checked-out resources
in the ActivityCheckoutList of either that activity or any sub-
activity of that activity cannot be checked in.
Postconditions:
(activity-checkin): If this proxy identified an activity, the
server MUST have applied the doCheckin request to each checked-out
resource in the ActivityCheckoutList of both that activity and any
sub-activity of that activity.
8 INTERNATIONALIZATION CONSIDERATIONS
All of the internationalization considerations of DeltaV discussed
in RFC 3253 also apply to the WVCM API.
Clemm [Page 56]
INTERNET-DRAFT WVCM API May 8, 2002
9 SECURITY CONSIDERATIONS
The security considerations of DeltaV discussed in RFC 3253 also
apply to the WVCM API.
10 IANA CONSIDERATIONS
No IANA considerations apply to the WVCM API.
11 INTELLECTUAL PROPERTY
The following notice is copied from RFC 2026, Section 10.4, and
describes the position of the IETF concerning intellectual property
claims made against this document.
The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to
pertain to the implementation or use other technology described in
this document or the extent to which any license under such rights
might or might not be available; neither does it represent that it
has made any effort to identify any such rights. Information on
the procedures of the IETF with respect to rights in standards-
track and standards-related documentation can be found in BCP-11.
Copies of claims of rights made available for publication and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use
of such proprietary rights by implementers or users of this
specification can be obtained from the IETF Secretariat.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to practice
this standard. Please address the information to the IETF
Executive Director.
12 ACKNOWLEDGEMENTS
This API is the collaborative product of the author and the members
of the JSR-147 expert team: Nick Crossley(Telelogic), John Dooley
(Broadvision), Tim Ellison (IBM), Peter Raymond (Merant), and Eric
Sedlar (Oracle). We would like to acknowledge the foundation laid
for us by the authors of the DeltaV protocol.
13 REFERENCES
[RFC2026] S.Bradner, "The Internet Standards Process", RFC 2026,
October 1996.
[RFC2119] S.Bradner, "Key words for use in RFCs to Indicate
Requirement Levels", RFC 2119, March 1997.
Clemm [Page 57]
INTERNET-DRAFT WVCM API May 8, 2002
[RFC2518] Y.Goland, E.Whitehead, A.Faizi, S.R.Carter, D.Jensen,
"HTTP Extensions for Distributed Authoring - WEBDAV", RFC 2518,
February 1999.
[RFC2616] R.Fielding, J.Gettys, J.C.Mogul, H.Frystyk, L.Masinter,
P.Leach, and T.Berners-Lee, "Hypertext Transfer Protocol --
HTTP/1.1", RFC 2616, June 1999.
14 AUTHOR'S ADDRESS
Geoffrey Clemm
Rational Software
20 Maguire Road, Lexington, MA 02421
Email: geoffrey.clemm@rational.com
Clemm [Page 58]
