============================================================================ Type: Resource Method: Resource doReadProperties(PropertyNameList w) Method: void doWriteProperties() Method: Resource doReadContent(PropertyNameList w, OutputStream content) Method: void doWriteContent(InputStream content, String contentIdentifier) Method: void doDelete() Postconditions: (resource-deleted): There is no resource at the location identified by this Resource. Method: 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. Method: 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. ========================================================================== Type: ControllableResource Method: 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. Postconditions: (initialize-resource): A new resource of the specified type exists at the location of this Resource. Method: doWriteContent() Preconditions: (cannot-modify-controlled-content): If this ControllableResource identifies a resource whose IsCheckedOut property is false, the request MUST fail. Method: doDelete() 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. Method: doMove() 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. 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. Method: 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. (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. Method: 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 of the version history MUST have been applied to the location of that bound member. Method: 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. Method: void doCheckout(boolean forkOK, List activityList, boolean newActivity, boolean unreserved) 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.- 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. Method: 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. Method: 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. (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. Method: 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. Method: void doUncheckout() Preconditions: (must-be-checked-out-version-controlled-resource): This ControllableResource MUST identify a version-controlled resource with a CheckedOut property. 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. Method: 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 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. Method: ControllableResource doMerge( Version source, boolean noAutoMerge, boolean noCheckout, boolean forkOK, boolean unreserved, List activityList, boolean newActivity, PropertyNameList wantedPropertyList) 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-checkout-preconditions**): 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). Method: MergePreviewReport doMergePreviewReport(Version source) ================================================================================= Type: Folder Method: 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. Method: 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. Method: 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. ================================================================================= Type: Workspace Method: doCreateResource() 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. (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. Method: doMove() 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. (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. Method: 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. 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). Method: Iterator doMergePreviewReport(List sourceList) Method: Iterator doLocateByHistoryReport(List versionHistoryList, PropertyNameList wantedPropertyList) ====================================================================================== Type: VersionHistory Method: doCopy() 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. Method: doMove() Preconditions: (cannot-rename-history): This proxy MUST NOT identify a version history. Method: doDelete() 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. ============================================================================== Type: Version Method: doWriteContent() Preconditions: (cannot-modify-version): If this proxy identifies a version, the request MUST fail. Method: doCopy() 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. Method: doMove() Preconditions: (cannot-rename-version): If this proxy identifies a version, the request MUST fail. Method: doDelete() 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. (delete-version-reference): If a version is deleted, any reference to that version in a MergeList or AutoMergeList property MUST be removed. Method: 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. Method: 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. Method: 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. =============================================================================== Type: Folder Version Method: doCopy() Preconditions: (cannot-copy-folder-version): This proxy MUST NOT identify a folder version. ============================================================================== Type: Baseline Method: Iterator doCompareBaselineReport(Baseline baseline) Preconditions: (baselines-from-same-history): A server MAY require that the baselines being compared be from the same baseline history. ============================================================================= Type: Configuration Method: doCheckin() 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 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. Method: doUpdate() 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 version-controlled configuration of that baseline-controlled member MUST have been updated to be that sub-baseline. =========================================================================== Type: Activity Method: doCreateResource() 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. Method: doMove() 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. Method: doDelete() Postconditions: (delete-activity-reference): If an activity is deleted, any reference to that activity in an ActivityList, SubactivityList, or CurrentActivityList MUST be removed. Method: doCheckin() 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.