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. 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. 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: 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. 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. 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 List getPredecessorList() setPredecessorList(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. List getActivityList() setActivityList(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. List getMergeList() setMergeList(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. List getAutoMergeList() setAutoMergeList(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. 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. 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 List getCurrentActivityList() setCurrentActivityList(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. List getPredecessorList() 6.5.3SuccessorList This property identifies each version whose PredecessorList identifies this version. List getSuccessorList() 6.5.4CheckoutList This property identifies each checked-out resource whose CheckedOut property identifies this version. 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. List ActivityList() setActivityList(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. 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 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. 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. 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. List getSubbaselineList() setSubbaselineList(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. List getActivityVersionList() 6.10.2 ActivityCheckoutList This property identifies each checked-out resource whose ActivityList identifies this activity. 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. List getSubactivityList() setSubactivityList(List) 6.10.4 CurrentWorkspaceList This property identifies each workspace whose CurrentActivityList identifies this activity. 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, 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(); 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: Iterator doMerge( List sourceList, boolean noAutoMerge, boolean noCheckout, boolean checkinActivity, boolean forkOK, boolean unreserved, 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: 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: 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]