001/* 002 * file ControllableResource.java 003 * 004 * Licensed Materials - Property of IBM 005 * Restricted Materials of IBM 006 * 007 * (c) Copyright IBM Corporation 2004, 2008. All Rights Reserved. 008 * Note to U.S. Government Users Restricted Rights: Use, duplication or 009 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp. 010 */ 011package javax.wvcm; 012 013import javax.wvcm.PropertyNameList.PropertyName; 014import javax.wvcm.Workspace.MergeFlag; 015import javax.wvcm.WvcmException.ReasonCode; 016 017/** 018 * A proxy for a controllable resource. 019 * 020 * A controllable resource is always the member of 021 * a special type of controllable folder called a "workspace". 022 * A controllable resource is either a version-controllable resource, 023 * a baseline-controllable resource, or both. 024 * <p> 025 * A version-controlled resource is a resource that is under control 026 * of a Checkout/Checkin protocol. 027 * The controlled state (content, controlled properties, and bindings to version-controlled members) 028 * of a version-controlled resource cannot be modified by a client 029 * unless that version-controlled resource is checked out. 030 * <p> 031 * When a version-controlled resource is checked in, 032 * a new version of that resource is created. 033 * The controlled state of the version-controlled resource is captured immutably in the new version. 034 * <p> 035 * The persistent state for a version-controlled resource may be 036 * stored on the client, on the server, or both. 037 * Storing the state on the server allows it to be shared 038 * by multiple clients. Storing the state on the client 039 * provides access to that state even when the client is 040 * disconnected from the server, and often provides more 041 * efficient access to that state. 042 * Note that the choice of what part of the state of a 043 * version-controlled resource is stored on the client 044 * is completely up to the implementation. In particular, 045 * although most implementations will cache some state on the client, 046 * an implementation may chose to store no local state. 047 * 048 * @since 1.0 049 */ 050public interface ControllableResource extends Resource { 051 052 // Basic Methods 053 054 /** 055 * Get the workspace provider of this resource. 056 * 057 * @return the {@link WorkspaceProvider} for this Resource. 058 */ 059 public WorkspaceProvider workspaceProvider(); 060 061 /** 062 * Create a new persistent resource at the location identified by this ControllableResource. 063 * The request will fail if a resource already exists at that location. 064 * 065 * <p> 066 * Postconditions: 067 * <li>(initialize-resource): A new resource of the specified type 068 * exists at the location of this Resource. 069 * 070 * @param feedback Specifies optional feedback to the caller. 071 * @return A proxy for this new resource, whose properties are specified by feedback. 072 * @throws WvcmException ReasonCode: 073 * <li>{@link ReasonCode#RESOURCE_ALREADY_EXISTS_AT_LOCATION}: 074 * A resource MUST NOT exist at the location of this Resource. 075 * <li>{@link ReasonCode#CANNOT_CREATE_AT_THIS_LOCATION}: 076 * The location of this Resource MUST identify a valid location to create this Resource. 077 * For a workspace, a client can determine locations where workspaces can be created 078 * from the {@link Resource#WORKSPACE_FOLDER_LIST} property. 079 */ 080 public ControllableResource doCreateResource(Feedback feedback) throws WvcmException; 081 082 /** 083 * Place this resource under version-control. 084 * When under version-control, the resource must be checked out to be modified 085 * and checked in to commit the modifications as a new version 086 * in the version history of the resource. 087 * <p> 088 * Postconditions: 089 * <li>(put-under-version-control): If this ControllableResource identified 090 * a resource that was not under version-control at the time of the request, 091 * the request MUST have created a new version history 092 * and MUST have created a new version resource in that version history. 093 * The {@link #IS_VERSION_CONTROLLED} property of this ControllableResource MUST be true. 094 * The {@link #IS_CHECKED_OUT} property of this ControllableResource MUST be false. 095 * The resource MUST have a {@link #CHECKED_IN} property that identifies the new version. 096 * The content and controlled properties of the new version MUST be the same as that of the resource. 097 * Note that an implementation can choose to locate the version history 098 * and version resources anywhere that it wishes. In particular, it could locate them 099 * on the same host and server as the version-controlled resource, 100 * on a different virtual host maintained by the same server, 101 * on the same host maintained by a different server, 102 * or on a different host maintained by a different server. 103 * <li>(must-not-change-existing-checked-in-out): If this ControllableResource 104 * identified a resource already under version-control at the time of the request, 105 * the request MUST NOT change the {@link #CHECKED_IN} 106 * or {@link #CHECKED_OUT} property of that version-controlled resource. 107 * <li>(new-version-history): If the request created a new version history, 108 * the request MUST have allocated a new server-defined location for that version history 109 * that MUST NOT have previously identified any other resource, 110 * and MUST NOT ever identify a resource other than this version history. 111 * <li>(update-stream): If the {@link Workspace#STREAM} property of the workspace 112 * of this controllable resource is non-null, the {@link Stream#VERSION_LIST} of the stream 113 * is updated to contain the new version resource. 114 * <li>(auto-checkout-parent): If the parent of this ControllableResource 115 * was a checked-in version-controlled folder and this ControllableResource 116 * is not already under version-control, the request MAY have checked out 117 * the parent folder. 118 * 119 * @param feedback Specifies optional feedback to the caller. 120 * @return A new proxy for this resource, whose properties are specified by feedback. 121 * @throws WvcmException ReasonCode: 122 * <li>{@link ReasonCode#FORBIDDEN} 123 * If the {@link #IS_VERSION_CONTROLLABLE} property of this resource is false, the request MUST fail. 124 * 125 */ 126 public ControllableResource doVersionControl(Feedback feedback) throws WvcmException; 127 128 // Basic Properties 129 130 /** 131 * The workspace of which this ControllableResource is a member. 132 * By definition, the workspace property of a workspace 133 * identifies itself, and the workspace property of any other 134 * type of resource must identify the same workspace as its parent. 135 */ 136 public static final PropertyName<Workspace> WORKSPACE = 137 new PropertyName<Workspace>("workspace"); //$NON-NLS-1$ 138 139 /** 140 * Get the {@link #WORKSPACE} property. 141 * 142 * @return the {@link #WORKSPACE} property. 143 * @throws WvcmException if this ControllableResource was not created with 144 * {@link #WORKSPACE} as a wanted property. 145 */ 146 public Workspace getWorkspace() throws WvcmException; 147 148 /** true if the resource is version-controlled, false otherwise. */ 149 public static final PropertyName<Boolean> IS_VERSION_CONTROLLED = 150 new PropertyName<Boolean>("is-version-controlled"); //$NON-NLS-1$ 151 152 /** 153 * Get the {@link #IS_VERSION_CONTROLLED} property. 154 * 155 * @return the {@link #IS_VERSION_CONTROLLED} property. 156 * @throws WvcmException if this ControllableResource was not created with 157 * {@link #IS_VERSION_CONTROLLED} as a wanted property. 158 */ 159 public boolean getIsVersionControlled() throws WvcmException; 160 161 /** true if the resource is checked out, false otherwise. */ 162 public static final PropertyName<Boolean> IS_CHECKED_OUT = 163 new PropertyName<Boolean>("is-checked-out"); //$NON-NLS-1$ 164 165 /** 166 * Get the {@link #IS_CHECKED_OUT} property. 167 * 168 * @return the {@link #IS_CHECKED_OUT} property. 169 * @throws WvcmException if this ControllableResource was not created with 170 * {@link #IS_CHECKED_OUT} as a wanted property. 171 */ 172 public boolean getIsCheckedOut() throws WvcmException; 173 174 175 /** 176 * Create a new version-controlled resource at the location identified by the proxy. 177 * The resource is associated with an existing version history, 178 * and if possible, is initialized with a specified version from that version history. 179 * If the specified version must be restored at a specific location, 180 * the new version-controlled resource is created at that specific location 181 * instead of the location of this ControllableResource. 182 * The request will fail if a resource already exists at that location. 183 * <p> 184 * Postconditions: 185 * <li>(new-version-controlled-resource): A new version-controlled resource is created 186 * for the version history of the specified version. If possible, the initial 187 * {@link ControllableResource#CHECKED_IN} property of the new version-controlled 188 * resource is set to be the specified version; if not, the version is implementation dependent. 189 * Otherwise, same semantics as the {@link Workspace#doUpdate}. 190 * <li>(new-version-controlled-folder): Same semantics as the update of a 191 * folder target in {@link Workspace#doUpdate}. 192 * <li>(auto-checkout-parent): If the parent of this ControllableResource 193 * was a checked-in version-controlled folder, the request MAY automatically check out 194 * the parent folder. 195 * 196 * @param version the version used to initialize the version-controlled 197 * resource. 198 * @param feedback Specifies optional feedback to the caller. 199 * @return A proxy for this new resource, whose properties are specified by feedback. 200 * @throws WvcmException ReasonCode: 201 * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}: 202 * The resource identified by the <code>version</code> argument must be a version. 203 * <li>{@link ReasonCode#CANNOT_CREATE_AT_THIS_LOCATION}: 204 * The location for the new version-controlled resource is not a valid location for a version-controlled resource. 205 * <li>{@link ReasonCode#RESOURCE_ALREADY_EXISTS_AT_LOCATION}: 206 * The location for the new version-controlled resource MUST NOT identify an existing resource. 207 * <li>{@link ReasonCode#ONE_CONTROLLED_RESOURCE_PER_HISTORY_PER_WORKSPACE}: 208 * The workspace of this ControllableResource MUST NOT have a member 209 * whose {@link #VERSION_HISTORY} property identifies the version history 210 * of the version specified in the request. 211 */ 212 public ControllableResource doCreateVersionControlledResource(Version version, Feedback feedback) 213 throws WvcmException; 214 215 /** Boolean flags for the doCheckin method */ 216 public static class CheckinFlag 217 { 218 private CheckinFlag(String flagName) { _flagName = flagName; } 219 220 /** 221 * Returns a string representation of this flag suitable for diagnostics. 222 */ 223 @Override 224 public String toString() { return _flagName; } 225 226 /** 227 * A string representation of this flag. 228 */ 229 private final String _flagName; 230 231 /** 232 * Indicates whether to fork even if forking is discouraged. 233 */ 234 public static final CheckinFlag FORK_OK = new CheckinFlag("fork-ok"); //$NON-NLS-1$ 235 236 /** 237 * Indicates whether to checkout the resource again immediately after checking it in. 238 */ 239 public static final CheckinFlag KEEP_CHECKED_OUT = new CheckinFlag("keep-checked-out"); //$NON-NLS-1$ 240 241 /** 242 * Indicates whether a checkin will be performed if the persistent state 243 * of the new version would be identical to that of the previous 244 * version. If this flag is not set, a checkin operation on an unchanged 245 * controllable resource will uncheckout that resource. 246 */ 247 public static final CheckinFlag CHECKIN_IDENTICAL = new CheckinFlag("checkin-identical"); //$NON-NLS-1$ 248 } 249 250 251 /** Boolean flags for the doCheckout method */ 252 public static class CheckoutFlag 253 { 254 private CheckoutFlag(String flagName) { _flagName = flagName; } 255 256 /** 257 * Returns a string representation of this flag suitable for diagnostics. 258 */ 259 @Override 260 public String toString() { return _flagName; } 261 262 /** 263 * The string form of this flag. 264 */ 265 private final String _flagName; 266 267 /** 268 * Indicates whether to fork even if forking is discouraged. 269 */ 270 public static final CheckoutFlag FORK_OK = new CheckoutFlag("fork-ok"); //$NON-NLS-1$ 271 272 /** 273 * Indicates whether to fail the checkout if there already is a reserved checkout 274 * from the currently selected version in the checkout activity. 275 */ 276 @SuppressWarnings("hiding") //$NON-NLS-1$ 277 public static final CheckoutFlag RESERVED = new CheckoutFlag("reserved"); //$NON-NLS-1$ 278 } 279 280 281 /** 282 * Changes the state of the resource identified by this ControllableResource 283 * to be checked-in, and synchronizes the persistent state 284 * of the resource to be that of the persistent state 285 * on the client. The current content and controlled properties of the resource are captured 286 * in a new version resource at a server-defined location. 287 * A doCheckin request can be applied to a checked-out configuration 288 * to produce a new baseline whose {@link Baseline#VERSION_LIST} captures the 289 * current state of the version-controlled members of the {@link Configuration#ROOT_FOLDER} 290 * of the configuration. 291 * <p> 292 * Postconditions: 293 * <li>(uncheckout-identical): If the controlled state of this resource is the same as its CHECKED_OUT version, 294 * and if the PREDECESSOR_LIST only contains the CHECKED_OUT version, 295 * and if the flag {@link CheckinFlag#CHECKIN_IDENTICAL} has not been passed in, 296 * an uncheckout on this resource will be automatically performed. 297 * <li>(complete-merge): If the {@link #MERGE_LIST} or the {@link #AUTO_MERGE_LIST} are non-empty, 298 * the versions within them are first moved to {@link #PREDECESSOR_LIST}. 299 * <li>(create-version): The request MUST have created a new version in the version history 300 * of the {@link #CHECKED_OUT} version. The request MUST have allocated a distinct new location 301 * for the new version, and that location MUST NOT ever identify any resource other than that version. 302 * <li>(initialize-version-content-and-properties): The content and controlled properties 303 * of the new version MUST be copied from the checked-out resource. 304 * The {@link Version#VERSION_NAME} of the new version MUST be set to a server-defined value 305 * distinct from all other {@link Version#VERSION_NAME} values of other versions in the same 306 * version history. 307 * The {@link #COMMENT} and {@link #PREDECESSOR_LIST} of the version-controlled resource 308 * MUST have been set to <code>null</code> after it was copied to the new version. 309 * <li>(checked-in): If keepCheckedOut is not specified in the request, 310 * the {@link #CHECKED_OUT} property of the version-controlled resource MUST have been removed 311 * and a {@link #CHECKED_IN} property that identifies the new version MUST have been added. 312 * <li>(keep-checked-out): If keepCheckedOut is specified in the request, 313 * the {@link #CHECKED_OUT} property of the checked-out resource MUST have been updated 314 * to identify the new version. 315 * <li>(add-to-history): The new version resource MUST have been added as a new bound member 316 * of the version history of the {@link #CHECKED_OUT} version. 317 * <li>(initialize-activity): The {@link Version#ACTIVITY} of the new version 318 * MUST have been initialized to be the same as the {@link #ACTIVITY} of the checked-out resource. 319 * The {@link #ACTIVITY} of the version-controlled resource MUST have been set to NULL 320 * after it was copied to the new version. 321 * <li>(initialize-folder-version-bindings): If this ControllableResource identifies 322 * a version-controlled folder, then for each version-controlled bound member of this 323 * ControllableResource, the new folder version MUST contain a bound member which 324 * is the version history of that version-controlled bound member, and whose binding 325 * name is the binding name of the version-controlled bound member. 326 * <li>(create-baseline-version-list): If this ControllableResource identifies a configuration, 327 * the {@link Baseline#VERSION_LIST} of the new baseline identifies a 328 * list of the {@link #CHECKED_IN} versions of each version-controlled member 329 * of the {@link Configuration#ROOT_FOLDER} of the configuration at the time of the request. 330 * <li>(update-stream): The {@link Stream#VERSION_LIST} of the {@link Workspace#STREAM} 331 * is updated to contain the new version resource. 332 * If the {@link Stream#VERSION_LIST} had previously contained a different version from the version history of the new version, 333 * that different version is removed. 334 * 335 * @param flags Array of boolean flags (may be null): 336 * <li>{@link CheckinFlag#KEEP_CHECKED_OUT} indicates whether to checkout the 337 * resource again immediately after checking it in. 338 * If <code>true</code>, the {@link #ACTIVITY} 339 * and {@link #RESERVED} properties should not be changed by the checkout. 340 * <li>{@link CheckinFlag#FORK_OK} indicates whether to fork even if forking is discouraged. 341 * <li>{@link CheckinFlag#CHECKIN_IDENTICAL} will force a checkin even if the controlled 342 * state is the same as its CHECKED_IN version. Otherwise, an uncheckout will be performed if 343 * the controlled state of this resource is the same as its CHECKED_IN version, 344 * and if the PREDECESSOR_LIST only contains the CHECKED_OUT version. 345 * @param feedback Specifies optional feedback to the caller. 346 * @return A new proxy for this resource, whose properties are specified by feedback. 347 * @throws WvcmException ReasonCode: 348 * <li>{@link ReasonCode#MUST_BE_CHECKED_OUT}: 349 * This ControllableResource MUST identify a resource whose {@link #IS_CHECKED_OUT} property is true. 350 * <li>{@link ReasonCode#VERSION_HISTORY_MUST_BE_A_TREE}: 351 * The versions identified by the {@link #PREDECESSOR_LIST}, {@link #MERGE_LIST} 352 * and {@link #AUTO_MERGE_LIST} of the checked-out resource MUST be descendants of 353 * the root version of the version history for the {@link #CHECKED_OUT} version. 354 * <li>{@link ReasonCode#CANNOT_FORK}: 355 * A doCheckin request MUST fail if it would cause a version 356 * whose {@link Version#CHECKIN_FORK} is {@link Version.Fork#FORBIDDEN} to 357 * appear in the {@link Version#PREDECESSOR_LIST} of more than one version. 358 * <li>{@link ReasonCode#CANNOT_CHECKIN_FORK_DISCOURAGED}: 359 * A doCheckin request MUST fail if it would cause a version 360 * whose {@link Version#CHECKIN_FORK} is {@link Version.Fork#DISCOURAGED} to 361 * appear in the {@link Version#PREDECESSOR_LIST} of more than one version, 362 * unless forkOk is specified in the request. 363 * <li>{@link ReasonCode#CANNOT_CREATE_BRANCH_IN_ACTIVITY}: 364 * Any version which is in the version history of the checked-out resource 365 * and whose {@link Version#ACTIVITY} identifies the {@link #ACTIVITY} 366 * of the checked-out resource MUST be an ancestor of the 367 * checked-out resource. 368 * <li>@{@link ReasonCode#CANNOT_CHECKIN_TO_RESERVED_ACTIVITY} 369 * If in another workspace there is a version-controlled resource 370 * whose {@link #CHECKED_OUT} property identifies a version in the version history 371 * of this resource, then the {@link #RESERVED} property of that version-controlled 372 * resource MUST be true. 373 * <li>{@link ReasonCode#NO_CHECKED_OUT_BASELINE_CONTROLLED_FOLDER_MEMBERS}: 374 * If this ControllableResource 375 * identifies a configuration, all version-controlled members 376 * of the {@link Configuration#ROOT_FOLDER} of the configuration MUST be checked-in. 377 * <li>{@link ReasonCode#CANNOT_CREATE_BRANCH_IN_STREAM}: 378 * If the {@link Stream#VERSION_LIST} of the {@link Workspace#STREAM} of this ControllableResource 379 * contains a version from the version history of this controllable resource, 380 * then the {@link Stream#VERSION_LIST} 381 * MUST contain one of the versions in the {@link #PREDECESSOR_LIST} of this controllable resource. 382 * 383 */ 384 public ControllableResource doCheckin(CheckinFlag[] flags, Feedback feedback) 385 throws WvcmException; 386 387 /** 388 * Checkout this ControllableResource so that its controlled state can be modified. 389 * <p> 390 * Postconditions: 391 * <li>(is-checked-out): The resource identified by this ControllableResource 392 * MUST have an {@link #IS_CHECKED_OUT} property whose value is true. 393 * <li>(has-checked-out-version): The checked-out resource MUST have a {@link #CHECKED_OUT} property 394 * that identifies the {@link #CHECKED_IN} version preceding the checkout. 395 * The version-controlled resource MUST NOT have a {@link #CHECKED_IN} property. 396 * <li>(initialize-predecessor-list): The {@link #PREDECESSOR_LIST} property of the checked-out resource 397 * MUST be initialized to be the {@link #CHECKED_OUT} version. 398 * <li>(initialize-activity): The {@link #ACTIVITY} of the checked-out resource is set as follows: 399 * - If the resource is a configuration, then the activity is the {@link Workspace#STREAM} of 400 * the workspace (possibly null). 401 * - Otherwise, if the resource is not a configuration, the {@link Workspace#CURRENT_ACTIVITY} 402 * of the workspace is used. If the {@link Workspace#CURRENT_ACTIVITY} is <code>null</code>, 403 * the server MAY automatically set the {@link Workspace#CURRENT_ACTIVITY} to be a newly created activity. 404 * <li>(initialize-reserved): If reserved was specified in the request, 405 * then the {@link #RESERVED} property of the checked-out resource MUST be true. 406 * @param flags Array of boolean flags (may be null): 407 * @param feedback Specifies optional feedback to the caller. 408 * @return A new proxy for this resource, whose properties are specified by feedback. 409 * @throws WvcmException ReasonCode: 410 * <li>{@link ReasonCode#MUST_BE_CHECKED_IN}: 411 * The {@link #IS_CHECKED_OUT} property of this ControllableResource MUST be false. 412 * <li>{@link ReasonCode#CANNOT_CHECKOUT_FORKING_IS_FORBIDDEN}: 413 * If the {@link Version#CHECKOUT_FORK} property 414 * of the version being checked out is {@link Version.Fork#FORBIDDEN}, the request MUST fail 415 * if the checked-out version has a non-empty list of successors. 416 * <li>{@link ReasonCode#CANNOT_CHECKOUT_FORKING_IS_DISCOURAGED}: 417 * If the {@link Version#CHECKOUT_FORK} property 418 * of the version being checked out is {@link Version.Fork#DISCOURAGED}, the request MUST fail 419 * if the checked-out version has a non-empty list of successors unless forkOk is specified 420 * in the request. 421 * <li>{@link ReasonCode#CANNOT_CHECKOUT_MULTI_CHECKOUT_IS_DISCOURAGED}: 422 * If the {@link Version#CHECKOUT_FORK} property 423 * of the version being checked out is {@link Version.Fork#DISCOURAGED}, the request MUST fail 424 * if a checked-out resource identifies that version in its {@link #CHECKED_OUT} property 425 * unless forkOk is specified in the request. 426 * <li>{@link ReasonCode#CANNOT_CHECKOUT_MULTI_CHECKOUT_IS_FORBIDDEN}: 427 * If the {@link Version#CHECKOUT_FORK} property 428 * of the version being checked out is {@link Version.Fork#FORBIDDEN}, the request MUST fail 429 * if a checked-out resource identifies that version in its {@link #CHECKED_OUT} property. 430 * <li>{@link ReasonCode#ONE_CHECKOUT_PER_ACTIVITY_PER_HISTORY}: 431 * If there is a request activity set, 432 * and if Reserved is specified, an existing reserved checkout from a version 433 * of that version history MUST NOT select an activity in that activity set. 434 * <li>{@link ReasonCode#CANNOT_CREATE_BRANCH_IN_ACTIVITY}: 435 * If there is a request activity set, and if Reserved is specified, 436 * the selected version MUST be a descendant of all other versions of that version history 437 * that select that activity. 438 * <li>{@link ReasonCode#CANNOT_CREATE_BRANCH_IN_STREAM}: 439 * If the {@link Workspace#STREAM} property of the workspace of this controllable resource 440 * is non-null, one of the following MUST be true: 441 * <br> - the {@link Stream#VERSION_LIST} of the stream contains no version from the version history 442 * of the {@link #CHECKED_IN} version. 443 * <br> - the {@link Stream#VERSION_LIST} of the stream contains the {@link #CHECKED_IN} version, 444 * <br> - the {@link CheckoutFlag#RESERVED} was not specified in the flags argument. 445 * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}: 446 * If the controllable resource is a configuration, and there is a request activity set, 447 * the <code>activity</code> argument MUST identify a stream; otherwise, the <code>activity</code> 448 * MUST identify an activity. 449 */ 450 public ControllableResource doCheckout( 451 CheckoutFlag[] flags, 452 Feedback feedback) 453 throws WvcmException; 454 455 /** 456 * Cancels the checkout of a version-controlled resource, 457 * and restores its controlled state to the state of its {@link #CHECKED_OUT} version. 458 * <p> 459 * Postconditions: 460 * <li>(cancel-checked-out): The value of the {@link #CHECKED_IN} property is that of the 461 * {@link #CHECKED_OUT} property prior to the request, and the {@link #CHECKED_OUT} property has been removed. 462 * <li>(restore-content): The controlled state of the version-controlled resource 463 * corresponds to that of its {@link #CHECKED_IN} version. 464 * 465 * @param feedback Specifies optional feedback to the caller. 466 * @return A new proxy for this resource, whose properties are specified by feedback. 467 * @throws WvcmException ReasonCode: 468 * <li>{@link ReasonCode#MUST_BE_CHECKED_OUT}: 469 * This ControllableResource 470 * MUST identify a version-controlled resource with a {@link #CHECKED_OUT} property. 471 */ 472 public ControllableResource doUncheckout(Feedback feedback) throws WvcmException; 473 474 /** 475 * Add the specified label to the checked-in version of this controllable resource. 476 * @see Version#doAddLabel 477 */ 478 public ControllableResource doAddLabel(String label, Feedback feedback) throws WvcmException; 479 480 /** 481 * Remove the specified lable from the {@link #CHECKED_IN} version of this controllable resource. 482 * @see Version#doRemoveLabel 483 */ 484 public ControllableResource doRemoveLabel(String label, Feedback feedback) throws WvcmException; 485 486 /** 487 * Set the specified label on the checked-in version of this controllable resource. 488 * @see Version#doSetLabel 489 */ 490 public ControllableResource doSetLabel(String label, Feedback feedback) throws WvcmException; 491 492 /** 493 * Apply {@link Resource#doReadProperties} 494 * to the version selected by <code>label</code> from the version history 495 * of this ControllableResource. 496 * 497 * @param label the label identifying the version to be selected 498 * @param feedback the list of properties that will be available on 499 * the returned version. 500 * @return a proxy for the selected version, with the wanted properties. 501 * @throws WvcmException ReasonCode: 502 * <li>{@link ReasonCode#MUST_BE_CHECKED_IN}: 503 * The {@link #CHECKED_IN} property of this ControllableResource MUST identify a version. 504 * <li>{@link ReasonCode#NOT_FOUND}: 505 * The label was not found. 506 */ 507 public Version doReadLabelledVersionProperties( 508 String label, 509 Feedback feedback) 510 throws WvcmException; 511 512 // Versioning Properties 513 514 /** 515 * A boolean value indicating whether this resource can be placed under version-control. 516 * @see #doVersionControl doVersionControl 517 */ 518 public static final PropertyName<Boolean> IS_VERSION_CONTROLLABLE = 519 new PropertyName<Boolean>("is-version-controllable"); //$NON-NLS-1$ 520 521 /** 522 * Get the {@link #IS_VERSION_CONTROLLABLE} property. 523 * 524 * @return the {@link #IS_VERSION_CONTROLLABLE} property. 525 * @throws WvcmException if this ControllableResource was not created with 526 * {@link #IS_VERSION_CONTROLLABLE} as a wanted property. 527 */ 528 public boolean getIsVersionControllable() throws WvcmException; 529 530 /** 531 * The version history of a version-controlled resource. 532 * This is the version history of the {@link #CHECKED_IN} or {@link #CHECKED_OUT} version. 533 */ 534 public static final PropertyName<VersionHistory> VERSION_HISTORY = 535 new PropertyName<VersionHistory>("version-history"); //$NON-NLS-1$ 536 537 /** 538 * Get the {@link #VERSION_HISTORY} property. 539 * 540 * @return the {@link #VERSION_HISTORY} property. 541 * @throws WvcmException if this ControllableResource was not created with 542 * {@link #VERSION_HISTORY} as a wanted property. 543 */ 544 public VersionHistory getVersionHistory() throws WvcmException; 545 546 /** 547 * The configuration to which this resource belongs. 548 */ 549 public static final PropertyName<Configuration> CONFIGURATION = 550 new PropertyName<Configuration>("configuration"); //$NON-NLS-1$ 551 552 /** 553 * Get the {@link #CONFIGURATION} property. 554 * 555 * @return the {@link #CONFIGURATION} property. 556 * @throws WvcmException if this property was not set and 557 * this ControllableResource was not created with 558 * {@link #CONFIGURATION} as a wanted property. 559 */ 560 public Configuration getConfiguration() 561 throws WvcmException; 562 563 /** 564 * The checked-in {@link Version} of this version-controlled resource. 565 * If this ControllableResource is checked-in, 566 * this is the version whose content and controlled properties 567 * are identical to those of this ControllableResource; 568 * otherwise, this is <code>null</code>. 569 */ 570 public static final PropertyName<Version> CHECKED_IN = 571 new PropertyName<Version>("checked-in"); //$NON-NLS-1$ 572 573 /** 574 * Get the {@link #CHECKED_IN} property. 575 * 576 * @return the {@link #CHECKED_IN} property. 577 * @throws WvcmException if this ControllableResource was not created with 578 * {@link #CHECKED_IN} as a wanted property. 579 */ 580 public Version getCheckedIn() throws WvcmException; 581 582 /** 583 * The checked-out version of a version-controlled resource. 584 * if this ControllableResource is checked-out, 585 * this is the checked-in version at the time 586 * the checkout was performed; otherwise, this is <code>null</code>. 587 */ 588 public static final PropertyName<Version> CHECKED_OUT = 589 new PropertyName<Version>("checked-out"); //$NON-NLS-1$ 590 591 /** 592 * Get the {@link #CHECKED_OUT} property. 593 * 594 * @return the {@link #CHECKED_OUT} property. 595 * @throws WvcmException if this ControllableResource was not created with 596 * {@link #CHECKED_OUT} as a wanted property. 597 */ 598 public Version getCheckedOut() throws WvcmException; 599 600 /** 601 * If this ControllableResource is checked-out, 602 * this is a list of the versions that 603 * will become the predecessors of the version created 604 * when this ControllableResource is checked in; 605 * otherwise, this is <code>null</code>. 606 * @see #getPredecessorList 607 * @see #setPredecessorList 608 */ 609 public static final PropertyName<ResourceList<Version>> PREDECESSOR_LIST = 610 new PropertyName<ResourceList<Version>>("predecessor-list"); //$NON-NLS-1$ 611 612 /** 613 * Get the {@link #PREDECESSOR_LIST} property. 614 * 615 * @return the {@link #PREDECESSOR_LIST} property. 616 * @throws WvcmException if this property was not set and 617 * this ControllableResource was not created with 618 * {@link #PREDECESSOR_LIST} as a wanted property. 619 * @see #setPredecessorList 620 */ 621 public ResourceList<Version> getPredecessorList() throws WvcmException; 622 623 /** 624 * Set the {@link #PREDECESSOR_LIST} property. 625 * 626 * @param versionList a list of versions that will 627 * be the predecessors of the version created when this ControllableResource 628 * is checked in. 629 * @see #getPredecessorList 630 */ 631 public void setPredecessorList(ResourceList<Version> versionList); 632 633 /** 634 * If the controllable resource is checked-out, this identifies the activity 635 * that will become the {@link Version#ACTIVITY} of the version created 636 * when the controllable resource is checked in; otherwise, this is <code>null</code>. 637 * If the controllable resource is not checked-out, an attempt to modify this 638 * property MUST fail. 639 * If the controllable resource is a Configuration, and the {@link #ACTIVITY} is not <code>null</code>, 640 * the activity must be a {@link Stream}. 641 * @see #setActivity 642 * @see #getActivity 643 */ 644 public static final PropertyName<Activity> ACTIVITY = 645 new PropertyName<Activity>("activity"); //$NON-NLS-1$ 646 647 /** 648 * Get the {@link #ACTIVITY} property. 649 * 650 * @return the {@link #ACTIVITY} property. 651 * @throws WvcmException if this property was not set and 652 * this ControllableResource was not created with 653 * {@link #ACTIVITY} as a wanted property. 654 * @see #setActivity 655 */ 656 public Activity getActivity() throws WvcmException; 657 658 /** 659 * Set the {@link #ACTIVITY} property. 660 * 661 * @param activity a list of {@link Activity} objects that identify 662 * the new value for the {@link #ACTIVITY} property. 663 * @see #getActivity 664 */ 665 public void setActivity(Activity activity); 666 667 /** 668 * A Boolean that indicates whether the checked-out version 669 * of this checked-out version-controlled resource can 670 * concurrently be checked-out to the same activity in 671 * another version-controlled resource. 672 * <p>In particular, this indicates whether the {@link #ACTIVITY} 673 * of another checked-out resource associated with the 674 * version history of this version-controlled resource 675 * can have be the activity that is also identified by the 676 * {@link #ACTIVITY} property of this checked-out resource. 677 * Since an activity must form a single line of descent through 678 * a given version history, a <code>doCheckin</code> may fail 679 * when a checkout is not reserved, because another version-controlled 680 * resource may have checked-in a parallel version into the 681 * activity. In this case, the user will first have 682 * to merge into this checked-out resource the latest 683 * version selected by that activity from that version history, 684 * and then modify the {@link #PREDECESSOR_LIST} of this checked-out resource 685 * to identify that version. 686 * @see #setReserved 687 * @see #getReserved 688 */ 689 public static final PropertyName<Boolean> RESERVED = 690 new PropertyName<Boolean>("reserved"); //$NON-NLS-1$ 691 692 /** 693 * Get the {@link #RESERVED} property. 694 * 695 * @return the {@link #RESERVED} property. 696 * @throws WvcmException if this property was not set and 697 * this ControllableResource was not created with 698 * {@link #RESERVED} as a wanted property. 699 * @see #setReserved 700 */ 701 public boolean getReserved() throws WvcmException; 702 703 /** 704 * Set the {@link #RESERVED} property. 705 * 706 * @param val the new value for the {@link #RESERVED} property of this ControllableResource. 707 * @see #getReserved 708 */ 709 public void setReserved(boolean val); 710 711 /** 712 * A list of {@link Version} objects that identify the versions whose 713 * content and controlled properties must be merged by the client into this 714 * checked-out ControllableResource. 715 * <p> 716 * After a merge operation, the merge list of each merge target contains a 717 * list of merge source versions, indicating the versions whose content or 718 * controlled properties are yet to be merged. For each entry in the merge 719 * list, it is the client's responsibility to update the controlled state of 720 * the checked-out merge target so that it reflects the logical merge of the 721 * merge source into the current controlled state of the merge target. The 722 * client indicates that it has completed the update of the merge target by 723 * deleting the merge source from the merge list of the checked-out merge 724 * target, and adding it to the predecessor list. 725 * <p> 726 * As an error check for a client forgetting to complete a merge, the server 727 * MUST fail an attempt to <code>doCheckin()</code> a version-controlled 728 * resource with a non-empty merge list. 729 * 730 * @see #setMergeList 731 * @see #getMergeList 732 */ 733 public static final PropertyName<ResourceList<Version>> MERGE_LIST = 734 new PropertyName<ResourceList<Version>>("merge-list"); //$NON-NLS-1$ 735 736 /** 737 * Get the {@link #MERGE_LIST} property. 738 * 739 * @return the {@link #MERGE_LIST} property. 740 * @throws WvcmException if this property was not set and 741 * this ControllableResource was not created with 742 * {@link #MERGE_LIST} as a wanted property. 743 * @see #setMergeList 744 */ 745 public ResourceList<Version> getMergeList() throws WvcmException; 746 747 /** 748 * Set the {@link #MERGE_LIST} property. 749 * 750 * @param versionList a list of {@link Version} objects that will be 751 * the value of the {@link #MERGE_LIST} property. 752 * @see #getMergeList 753 */ 754 public void setMergeList(ResourceList<Version> versionList); 755 756 /** 757 * A list of {@link Version} objects that identify each version whose 758 * controlled state has been merged by the server into this checked-out 759 * ControllableResource. 760 * <p> 761 * When a server has the ability to automatically update the controlled 762 * state of the merge target to reflect the logical merge of the merge 763 * source, it may do so unless {@link MergeFlag#NO_AUTO_MERGE} is specified 764 * in the {@link Workspace#doMerge} request. 765 * <p> 766 * After a merge operation, the auto-merge list of each merge target 767 * contains a list of merge source versions whose controlled state was 768 * automatically merged into that merge target. Automatically merged source 769 * versions appear only in the auto-merge list, and not the merge list. 770 * <p> 771 * The client is responsible for deleting entries from the 772 * {@link #AUTO_MERGE_LIST} and adding them to the {@link #PREDECESSOR_LIST} 773 * after the user has verified that the automatic merge was performed 774 * correctly by the server. 775 * 776 * @see #setAutoMergeList 777 * @see #getAutoMergeList 778 */ 779 public static final PropertyName<ResourceList<Version>> AUTO_MERGE_LIST = 780 new PropertyName<ResourceList<Version>>("auto-merge-list"); //$NON-NLS-1$ 781 782 /** 783 * Get the {@link #AUTO_MERGE_LIST} property. 784 * 785 * @return the {@link #AUTO_MERGE_LIST} property. 786 * @throws WvcmException if this property was not set and 787 * this ControllableResource was not created with 788 * {@link #AUTO_MERGE_LIST} as a wanted property. 789 * @see #setAutoMergeList 790 */ 791 public ResourceList<Version> getAutoMergeList() throws WvcmException; 792 793 /** 794 * Set the {@link #AUTO_MERGE_LIST} property. 795 * 796 * @param versionList a list of {@link Version} objects that identify 797 * the new value for the {@link #AUTO_MERGE_LIST} property. 798 * @see #getAutoMergeList 799 */ 800 public void setAutoMergeList(ResourceList<Version> versionList); 801 802}