001 /* 002 * Licensed Materials - Property of IBM 003 * Restricted Materials of IBM 004 * 005 * com.ibm.rational.wvcm.stp.cc.CcFile 006 * 007 * (C) Copyright IBM Corporation 2004, 2014. 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 */ 011 package com.ibm.rational.wvcm.stp.cc; 012 013 import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE; 014 015 import java.io.File; 016 import java.io.OutputStream; 017 import java.util.List; 018 019 import javax.wvcm.ControllableResource; 020 import javax.wvcm.Feedback; 021 import javax.wvcm.PropertyNameList.PropertyName; 022 import javax.wvcm.Resource; 023 import javax.wvcm.WvcmException; 024 025 import com.ibm.rational.wvcm.stp.cc.CcVersion.CcMergeFlag; 026 import com.ibm.rational.wvcm.stpex.StpExEnumeration; 027 028 /** 029 * A proxy for a file, directory, or symbolic link resource in a ClearCase view. 030 * This resource is either under version control or could potentially be 031 * put under version control. 032 */ 033 public interface CcFile 034 extends CcResource, ControllableResource 035 { 036 /** Flags for the doApplyAttribute and doRemoveAttribute methods */ 037 enum AttributeOpFlag implements StpExEnumeration { 038 039 /** 040 * Replace existing attribute instance. 041 * (Only applies to doApplyAttribute) 042 */ 043 REPLACE("replace"), 044 045 /** 046 * Apply/remove attribute recursively over sub-tree. 047 */ 048 RECURSE("recurse"), 049 050 /** 051 * If the attribute type was created with a default value, uses 052 * that value for the attribute instead of the value specified in 053 * the call. An error occurs if the attribute type was not created 054 * with a default value. 055 * (Only applies to doApplyAttribute) 056 */ 057 DEFAULT("default"); 058 059 private String m_name; 060 061 private AttributeOpFlag(String name) { m_name = name; } 062 063 /* (non-Javadoc) 064 * @see java.lang.Object#toString() 065 */ 066 public String toString() { return m_name; } 067 } 068 069 070 /** Flags for the doApplyLabel method */ 071 enum ApplyLabelFlag implements StpExEnumeration { 072 073 /** 074 * Replace existing label instance. 075 */ 076 REPLACE("replace"), 077 078 /** 079 * Apply label recursively over sub-tree. 080 */ 081 RECURSE("recurse"), 082 083 /** 084 * Follow symbolic links 085 */ 086 FOLLOW_SYMLINKS("follow-symlinks"); 087 088 private String m_name; 089 090 private ApplyLabelFlag(String name) { m_name = name; } 091 092 /* (non-Javadoc) 093 * @see java.lang.Object#toString() 094 */ 095 public String toString() { return m_name; } 096 } 097 098 /** Flags for the doRemoveLabel method */ 099 enum RemoveLabelFlag implements StpExEnumeration { 100 101 /** 102 * Remove label recursively over sub-tree. 103 */ 104 RECURSE("recurse"), 105 106 /** 107 * Follow symbolic links 108 */ 109 FOLLOW_SYMLINKS("follow-symlinks"); 110 111 private String m_name; 112 113 private RemoveLabelFlag(String name) { m_name = name; } 114 115 /* (non-Javadoc) 116 * @see java.lang.Object#toString() 117 */ 118 public String toString() { return m_name; } 119 } 120 121 /** Flags for the doApplyRolemap method */ 122 enum ApplyRolemapFlag { 123 /** 124 * Apply rolemap recursively over sub-tree, if one exists. 125 */ 126 RECURSE("recurse"), 127 128 /** 129 * Restricts the command to changing file elements only. 130 * (Mutually exclusive with DIRECTORY.) 131 */ 132 FILE("file"), 133 134 /** 135 * Restricts the command to changing directory elements only. 136 * (Mutually exclusive with FILE.) 137 */ 138 DIRECTORY("directory"); 139 140 private final String m_flag; 141 142 ApplyRolemapFlag(String flag) { 143 m_flag = flag; 144 } 145 146 public String toString() { 147 return m_flag; 148 } 149 } 150 151 /** Flags for the doUncheckout method */ 152 enum UncheckoutFlag implements StpExEnumeration { 153 /** 154 * Preserve changes in checked out version in a ".keep" file. 155 */ 156 KEEP("keep"); 157 158 private String m_name; 159 160 private UncheckoutFlag(String name) { m_name = name; } 161 162 /* (non-Javadoc) 163 * @see java.lang.Object#toString() 164 */ 165 public String toString() { return m_name; } 166 } 167 168 /** Flags for the doUnhijack method */ 169 enum UnhijackFlag implements StpExEnumeration { 170 171 /** 172 * Preserve changes in hijacked version in a ".keep" file. 173 */ 174 KEEP("keep"); 175 176 private UnhijackFlag(String name) { m_name = name; } 177 178 /* (non-Javadoc) 179 * @see java.lang.Object#toString() 180 */ 181 public String toString() { return m_name; } 182 183 private String m_name; 184 } 185 186 /** 187 * Flags for the <code>doRefresh</code> and <code>doRestore</code> methods. 188 */ 189 enum RefreshFlag implements StpExEnumeration { 190 191 /** 192 * Do <i>not</i> refresh hijacked files. 193 * Leave hijacked files in the hijacked state, and do not alter 194 * their contents. 195 * <p> 196 * Note: a deleted file or directory is considered to be hijacked. 197 * In order to refresh or restore a deleted file or directory, 198 * you must specify <code>OVERWRITE_HIJACKS</code> or 199 * <code>RENAME_HIJACKS</code>. 200 * </p> 201 * This is the default hijack behavior for both <code>doRefresh</code> 202 * and <code>doRestore</code>. 203 */ 204 KEEP_HIJACKS("keep-hijacks"), 205 206 /** 207 * If a file being refreshed is hijacked in this view, 208 * overwrite the hijacked contents with the new version's contents. 209 * Do not preserve the hijacked contents. 210 */ 211 OVERWRITE_HIJACKS("overwrite-hijacks"), 212 213 /** 214 * If a file being refreshed is hijacked in this view, 215 * preserve the hijacked contents by moving the hijacked file to 216 * <code><file-name>.keep</code>. 217 */ 218 RENAME_HIJACKS("rename-hijacks"), 219 220 /** 221 * When refreshing a file to a different version, set the file's 222 * "last modified" time to be the time when the version was created. 223 * <br /> 224 * Web View: 225 * By default, a refreshed file's "last modified" time will simply be 226 * the time when the <code>doRefresh</code> is performed. 227 * <br /> 228 * Snapshot View: 229 * If <code>PRESERVE_CREATION_TIME</code> or 230 * <code>USE_CURRENT_TIME</code> is not set then the file's 231 * "last modified" time will be set based on 232 * <code>CcView.PRESERVE_VOB_MODIFIED_TIME</code>. 233 */ 234 PRESERVE_CREATION_TIME("preserve-creation-time"), 235 236 /** 237 * When refreshing a file to a different version, set the file's 238 * "last modified" time to be the time when 239 * <code>doRefresh</code> is performed on the Snapshot view resource. 240 * Not applicable for other view types. 241 * <br /> 242 * If <code>PRESERVE_CREATION_TIME</code> or 243 * <code>USE_CURRENT_TIME</code> is not set then the file's 244 * "last modified" time will be set based on 245 * <code>CcView.PRESERVE_VOB_MODIFIED_TIME</code>. 246 */ 247 USE_CURRENT_TIME("use-current-time"), 248 249 /** 250 * Preview the refresh operation, but don't actually perform it. 251 * Invoke the caller's feedback methods to inform them what the 252 * refresh would do if it were performed right now. 253 */ 254 PREVIEW_ONLY("preview-only"), 255 256 /** 257 * Force the refresh/update of load-once rules in automatic views. 258 */ 259 FORCE_LOAD_ONCE("force-load-once"), 260 261 /** 262 * Resume a suspended update... 263 */ 264 RESUME_UPDATE("resume-update"); 265 266 private String m_name; 267 268 private RefreshFlag(String name) { m_name = name; } 269 270 /* (non-Javadoc) 271 * @see java.lang.Object#toString() 272 */ 273 public String toString() { return m_name; } 274 } 275 276 /** Flags for the <code>doCheckout</code> method. */ 277 enum CcCheckoutFlag implements StpExEnumeration { 278 279 /** 280 * Indicates whether to checkout this file reserved. 281 */ 282 RESERVED("reserved"), 283 284 /** 285 * Fall back to unreserved if a reservation can not be obtained. 286 */ 287 FALLBACK_TO_UNRESERVED("fallback-to-unreserved"), 288 289 /** 290 * Checkout the version of the file that is currently loaded in the 291 * view, even if that version is not the version selected by the 292 * view's config spec. 293 * 294 * <p>If the loaded version is not the version selected by the view's 295 * config spec, and neither {@link #LOADED_NOT_LATEST} nor 296 * {@link #LATEST_NOT_LOADED} flags are set, the checkout operation 297 * will throw an exception with reason code <code>CHECKOUT_NOT_LATEST</code>. 298 */ 299 LOADED_NOT_LATEST("checkout-loaded-not-latest"), 300 301 /** 302 * Checkout the version of the file that is selected by the view's 303 * config spec. If this version is not loaded at checkout time, then 304 * load it prior to performing the checkout. 305 * 306 * <p>If the loaded version is not the version selected by the view's 307 * config spec, and neither {@link #LOADED_NOT_LATEST} nor 308 * {@link #LATEST_NOT_LOADED} flags are set, the checkout operation 309 * will throw an exception with reason code <code>CHECKOUT_NOT_LATEST</code>. 310 */ 311 LATEST_NOT_LOADED("checkout-latest-not-loaded"), 312 313 /** 314 * Indicates whether to checkout this file even if the currently 315 * selected branch is mastered by another replica. The 316 * <code>RESERVED</code> flag must NOT be set with this flag. 317 * 318 * <p>If the file is mastered by this replica, setting this 319 * flag has no effect. 320 */ 321 NON_MASTERED_OK("non-mastered-ok"), 322 323 /** 324 * If the file is hijacked, keep the hijacked contents upon checkout. 325 */ 326 PRESERVE_HIJACK_CONTENTS("preserve-hijack-contents"), 327 328 /** 329 * After a file is 'checkedout', set the file's "last modified" 330 * time to be the time when the version was first created. 331 * <p>This applies only to dynamic views. 332 */ 333 PRESERVE_MODIFICATION_TIME("preserve-modification-time"); 334 335 private String m_name; 336 337 private CcCheckoutFlag(String name) { m_name = name; } 338 339 /* (non-Javadoc) 340 * @see java.lang.Object#toString() 341 */ 342 public String toString() { return m_name; } 343 } 344 345 /** Flags for the <code>doCcVersionControl</code> method. */ 346 enum CcVersionControlFlag implements StpExEnumeration { 347 348 /** 349 * Indicates whether to checkin this file after it is added to version control. 350 * The default is to leave it checked out.<p> 351 * This flag is mutually exclusive with {@link CcVersionControlFlag#NO_CHECKOUT}. 352 */ 353 CHECKIN("checkin"), 354 355 /** 356 * Do not checkout the file after adding to version control.<p> 357 * This flag is mutually exclusive with {@link CcVersionControlFlag#CHECKIN}. 358 */ 359 NO_CHECKOUT("no-checkout"), 360 361 /** 362 * Assigns mastership of the <b>main</b> branch of the newly version controlled 363 * file to the VOB replica in which you execute operation. By default 364 * mastership of the file's <b>main</b> branch is assigned to the VOB replica 365 * that masters the <b>main</b> branch type. <p> 366 * This flag is mutually exclusive with {@link CcVersionControlFlag#MAKE_PATH}. 367 */ 368 MASTER_LOCALLY("master-locally"), 369 370 /** 371 * Automatically checkout the version controlled parent directory and 372 * check back in after new file has been added to version control. 373 * Any view private parent directories below the version controlled parent 374 * and the desired file, will also be version controlled.<p> 375 * This flag is mutually exclusive with {@link CcVersionControlFlag#MASTER_LOCALLY}. 376 */ 377 MAKE_PATH("mkpath"); 378 379 private String m_name; 380 381 private CcVersionControlFlag(String name) { m_name = name; } 382 383 /* (non-Javadoc) 384 * @see java.lang.Object#toString() 385 */ 386 public String toString() { return m_name; } 387 } 388 389 /** Values for file or directory load state */ 390 enum LoadState implements StpExEnumeration { 391 392 /** 393 * This file or directory is loaded in its file area. 394 */ 395 LOADED, 396 397 /** 398 * This directory is partially loaded in its file area, i.e., 399 * some but not all of its children are loaded. 400 */ 401 PARTIALLY_LOADED, 402 403 /** 404 * This file or directory is not loaded in its file area. 405 */ 406 NOT_LOADED; 407 } 408 409 /** 410 * Create a new view-private file at the location specified by this resource. 411 * The request will fail if a resource already exists at that location. 412 * @param feedback 413 * @return a CcFile proxy for the new file 414 * @see javax.wvcm.ControllableResource#doCreateResource(Feedback) 415 */ 416 public CcFile createCcFile(Feedback feedback) throws WvcmException; 417 418 /** 419 * Apply the specified attribute to the checked-in version of this controllable resource. 420 * @param flags array of flags which specify the behavior of the operation 421 * @param comment Comment (if any) to be used for operation. Empty string if none. 422 * @param attributeName Name of an existing attribute type to be used to create 423 * an instance will to be applied to this resource. 424 * @param attributeValue Value of attribute instance. If the vtype of the attribute type is 425 * a string, it must be enclosed in additional quotes <em>within the string</em>. For example, if 426 * specified as a constant it would appear as <code>"\"string value\""</code>. If the 427 * vtype is not a string, this should be a string representation of the given value 428 * (e.g. <code>"3.1415"</code>, <code>"0xa413"</code>, etc.). 429 * @param versionId Applies the attribute to the explicitly specified version, 430 * overriding the version selected by the view. 431 * This string must only represent the version suffix (e.g. /main/314). 432 * @param feedback 433 * @return A new proxy for this resource, whose properties are specified by feedback. 434 * @throws WvcmException 435 */ 436 ControllableResource doApplyAttribute(AttributeOpFlag[] flags, String comment, 437 String attributeName, String attributeValue, String versionId, Feedback feedback) 438 throws WvcmException; 439 440 /** 441 * Remove the specified attribute from the checked-in version of this controllable resource. 442 * @param flags array of flags which specify the behavior of the operation 443 * @param comment Comment (if any) to be used for operation. Empty string if none. 444 * @param attributeName Name of the attribute to be removed from this resource 445 * @param versionId Removes the attribute from the explicitly specified version, 446 * overriding the version selected by the view. 447 * @param feedback 448 * @return A new proxy for this resource, whose properties are specified by feedback. 449 * @throws WvcmException 450 */ 451 ControllableResource doRemoveAttribute(AttributeOpFlag[] flags, String comment, 452 String attributeName, String versionId, Feedback feedback) 453 throws WvcmException; 454 455 /** 456 * Apply the specified label to the checked-in version of this controllable resource. 457 * @param flags array of flags which specify the behavior of the operation 458 * @param label the label to be added to this version 459 * @param feedback 460 * @return A new proxy for this resource, whose properties are specified by feedback. 461 * @throws WvcmException 462 */ 463 ControllableResource doApplyLabel(ApplyLabelFlag[] flags, 464 String label, Feedback feedback) 465 throws WvcmException; 466 467 /** 468 * Apply the specified label to the checked-in version of this controllable resource. 469 * @param flags array of flags which specify the behavior of the operation 470 * @param comment The comment for this operation, or null for no comment 471 * @param label the label to be added to this version 472 * @param feedback 473 * @return A new proxy for this resource, whose properties are specified by feedback. 474 * @throws WvcmException 475 */ 476 ControllableResource doApplyLabel(ApplyLabelFlag[] flags, String comment, 477 String label, Feedback feedback) 478 throws WvcmException; 479 480 /** 481 * Remove the specified label from the checked-in version of this controllable resource. 482 * @param flags array of flags which specify the behavior of the operation 483 * @param label the label to be removed from this version 484 * @param feedback 485 * @return A new proxy for this resource, whose properties are specified by feedback. 486 * @throws WvcmException 487 */ 488 ControllableResource doRemoveLabel(RemoveLabelFlag[] flags, 489 String label, Feedback feedback) 490 throws WvcmException; 491 492 /** 493 * Apply the specified rolemap to the element represented by this file/directory. 494 * @param flags array of flags which specify the behavior of the operation 495 * @param comment Comment (if any) to be used for operation. Empty string if none. 496 * @param rolemap The name of the rolemap to be applied. 497 * @throws WvcmException 498 */ 499 void doApplyRolemap(ApplyRolemapFlag[] flags, String comment, String rolemap) 500 throws WvcmException; 501 502 /** 503 * <p>Check out this version-controlled file or directory resource. 504 * The resource is checked out to the ClearCase view implied by its location. 505 * </p> 506 * <p>If the view is a UCM view, the caller must insure there is a 507 * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation. 508 * The checked out file will be added to the current activity's change set. 509 * The caller may explicitly specify an activity using this resource's 510 * {@link javax.wvcm.ControllableResource#setActivity} method. In that case, 511 * the specified activity will become the new current activity. 512 * Otherwise, the existing current activity will be used. 513 * If the view is a UCM view and there is no current activity, the operation 514 * will fail. 515 * </p> 516 * <p>The caller may optionally specify a checkout comment using this 517 * resource's {@link javax.wvcm.Resource#setComment} method. 518 * </p> 519 * @param flags array of flags which specify the behavior of the operation 520 * @param feedback 521 * @return new CcFile proxy representing the checked out file. 522 * @throws WvcmException 523 */ 524 CcFile doCcCheckout(CcCheckoutFlag[] flags, Feedback feedback) 525 throws WvcmException; 526 527 /** 528 * Cancel the checkout of this version-controlled resource, 529 * and restore its content to the state of its CHECKED_IN version. 530 * @param flags array of flags which specify the behavior of the operation 531 * @param feedback 532 * @return new CcFile proxy representing the file whose checkout has been canceled 533 * @throws WvcmException 534 * @see javax.wvcm.ControllableResource#doUncheckout 535 */ 536 CcFile doUncheckout(UncheckoutFlag[] flags, Feedback feedback) 537 throws WvcmException; 538 539 /** 540 * <p>Check in this checked out file or directory resource. 541 * </p> 542 * <p>If this resource is in a UCM view, it was added to an activity's 543 * change set at checkout time. The caller may specify an alternate 544 * change set using this resource's 545 * {@link javax.wvcm.ControllableResource#setActivity} method just before 546 * calling <code>doCheckin</code>. 547 * </p> 548 * <p>The caller may also specify a checkin comment using this 549 * resource's {@link javax.wvcm.Resource#setComment} method. 550 * This will override the comment specified at checkout time, if any. 551 * </p> 552 * @param flags array of flags which specify the behavior of the operation 553 * @param feedback 554 * @return new ControllableResource proxy representing the checked in file. 555 * @throws WvcmException 556 * @see javax.wvcm.ControllableResource#doCheckin 557 * @see com.ibm.rational.wvcm.stp.cc.CcFile#doCheckout 558 */ 559 ControllableResource doCheckin(CheckinFlag[] flags, Feedback feedback) 560 throws WvcmException; 561 562 /** 563 * Merges the contents of two or more versions, representing files or 564 * directories, into this file. Versions must be of the same element as this 565 * file. 566 * 567 * @param baseVersion Base contributor. Can be null. 568 * @param contribList One or more contributing versions. 569 * @param flags Specify options for the merge. Can be null. 570 * @param listener Callback notifier for the merge. 571 * @param feedback 572 * @return new CcFile proxy representing the merged file. 573 * @throws WvcmException if there is an error during the merge. 574 */ 575 CcFile doMerge(CcVersion baseVersion, 576 List<CcVersion> contribList, 577 CcMergeFlag[] flags, 578 CcListener listener, 579 Feedback feedback) throws WvcmException; 580 581 /** 582 * Places the view-private file specified by this proxy under version control. 583 * <p>If the view is a UCM view, the caller must insure there is a 584 * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation. 585 * The newly version controlled file will be added to the current activity's change set 586 * and left in a checked-in state. 587 * The caller may explicitly specify an activity using this resource's 588 * {@link javax.wvcm.ControllableResource#setActivity} method. In that case, 589 * the specified activity will become the new current activity. 590 * Otherwise, the existing current activity will be used. 591 * If the view is a UCM view and there is no current activity, the operation 592 * will fail. 593 * </p> 594 * <p>The caller may optionally specify a creation comment using this 595 * resource's {@link javax.wvcm.Resource#setComment} method. 596 * </p> 597 * <p>The caller may optionally specify the type of element to be created using 598 * this resource's {@link com.ibm.rational.wvcm.stp.cc.CcFile#setElementType} method. 599 * </p> 600 * @param feedback 601 * @return new ControllableResource proxy representing the version controlled file. 602 * @throws WvcmException 603 * @see javax.wvcm.ControllableResource#doVersionControl(javax.wvcm.Feedback) 604 */ 605 ControllableResource 606 doVersionControl(Feedback feedback) 607 throws WvcmException; 608 609 /** 610 * Enhanced variant of the doVersionControl that provides additional flags 611 * which modify the behaviour.<p> 612 * This method has two main difference from <code>doVersionControl</code>: 613 * <ol> 614 * <li>It does <b>not</b> automatically checkout the version controlled 615 * parent directory. The caller must do this explicitly unless the 616 * {@link com.ibm.rational.wvcm.stp.cc.CcFile.CcVersionControlFlag#MAKE_PATH} 617 * flag is specified. 618 * <li>The newly version controlled file will be left in a checked-out state. 619 * To have the resulting file checked-in, specify the 620 * {@link com.ibm.rational.wvcm.stp.cc.CcFile.CcVersionControlFlag#CHECKIN} flag. 621 * </ol> 622 * @param flags array of flags which specify the behavior of the operation 623 * @param feedback 624 * @return A new proxy for this resource, whose properties are specified by feedback. 625 * @throws WvcmException 626 * @see com.ibm.rational.wvcm.stp.cc.CcFile#doVersionControl(javax.wvcm.Feedback) 627 */ 628 ControllableResource 629 doCcVersionControl(CcVersionControlFlag flags[], Feedback feedback) 630 throws WvcmException; 631 632 /** 633 * <p> 634 * Refresh this file or directory. Re-evaluate the 635 * view's config spec and update resources on the client to be whatever 636 * is currently selected by the config spec. If this is a directory, 637 * recursively refresh its contents. 638 * </p> 639 * <p> 640 * Example: The config spec says "element * /main/LATEST", and you 641 * have version "/main/7" of this resource loaded. Someone else checks 642 * in a new version, thus creating a "/main/8". In that case, 643 * doRefresh() will cause version "/main/8" of this resource to 644 * be loaded into your view. 645 * </p> 646 * <p> 647 * Preconditions: This resource must be a version-controlled file 648 * or directory. 649 * </p> 650 * <p> 651 * Postconditions: This resource (and its descendants if this is a 652 * directory) are updated to be what is currently selected by the view's 653 * config spec. 654 * </p> 655 * @param flags array of flags which specify the behavior of the operation 656 * @param feedback (optional) a list of properties to fetch on the 657 * updated resources or a DetailedFeedback. If properties are provided, 658 * the returned resources will have them filled in. If a DetailedFeedback 659 * is provided, the appropriate notification methods will be called for each 660 * resource which is refreshed as part of the operation. 661 * by doRefresh will have these properties filled in. 662 * @return a new CcFile proxy representing the refreshed file 663 * @throws WvcmException if the precondition is not met or if an error 664 */ 665 CcFile doRefresh(RefreshFlag[] flags, Feedback feedback) 666 throws WvcmException; 667 668 /** 669 * <p> 670 * Refresh this file or directory. Re-evaluate the 671 * view's config spec and update resources on the client to be whatever 672 * is currently selected by the config spec. If this is a directory, 673 * recursively refresh its contents. 674 * </p> 675 * <p> 676 * Example: The config spec says "element * /main/LATEST", and you 677 * have version "/main/7" of this resource loaded. Someone else checks 678 * in a new version, thus creating a "/main/8". In that case, 679 * doRefresh() will cause version "/main/8" of this resource to 680 * be loaded into your view. 681 * </p> 682 * <p> 683 * Preconditions: This resource must be a version-controlled file 684 * or directory. 685 * </p> 686 * <p> 687 * Postconditions: This resource (and its descendants if this is a 688 * directory) are updated to be what is currently selected by the view's 689 * config spec. 690 * </p> 691 * @param flags array of flags which specify the behavior of the operation 692 * @param listener Callback notifier for the merge. 693 * @param feedback (optional) a list of properties to fetch on the 694 * updated resources or a DetailedFeedback. If properties are provided, 695 * the returned resources will have them filled in. If a DetailedFeedback 696 * is provided, the appropriate notification methods will be called for each 697 * resource which is refreshed as part of the operation. 698 * by doRefresh will have these properties filled in. 699 * @return a new CcFile proxy representing the refreshed file 700 * @throws WvcmException if the precondition is not met or if an error 701 */ 702 CcFile doCcRefresh(RefreshFlag[] flags, CcListener listener, Feedback feedback) 703 throws WvcmException; 704 705 /** 706 * <p> 707 * Restore this file or directory. If this is a directory, recursively 708 * restore its contents. This repairs any damage to the portion of the file 709 * area database specified by this resource. 710 * </p> 711 * 712 * @param flags array of flags which specify the behavior of the operation 713 * @param feedback 714 * @return a new CcFile proxy representing the restored file 715 * @throws WvcmException 716 */ 717 CcFile doRestore(RefreshFlag[] flags, Feedback feedback) 718 throws WvcmException; 719 720 /** 721 * <p> 722 * Load this controllable resource into a web or snapshot view's local 723 * file area, or load the controllable resource into the automatic view. 724 * If this is a controllable folder, loads the tree of controllable 725 * resources under this folder. 726 * Also updates the view's load rules if necessary 727 * to include this file or folder. 728 * </p> 729 * <p> 730 * If this resource was already loaded, doLoad is a no-op. 731 * </p> 732 * <p> 733 * Preconditions: This must be a version-controlled file or folder 734 * in a web, snapshot or automatic view. 735 * </p> 736 * <p> 737 * Postconditions: 738 * </p> 739 * <p> 740 * This file, or the tree of files under this folder, 741 * is loaded into the view. Thus, the file(s) appear, and the view's 742 * load rules are updated to include this file or folder. 743 * </p> 744 * <p> 745 * Snapshot view: <br /> 746 * This file, or the tree of files under this folder, 747 * is loaded into the view. Thus, the file(s) appear, and the view's 748 * load rules are updated to include this file or folder. 749 * </p> 750 * <p> 751 * Note that automatic views do not support load of individual 752 * resources. Addition of a load rule for a controllable resource in an 753 * automatic view must be done directly in the config spec. 754 * </p> 755 * <p> 756 * Note that automatic views do not support load of individual 757 * resources. Addition of a load rule for a controllable resource in an 758 * automatic view must be done directly in the config spec. 759 * </p> 760 * @param feedback (optional) feedback's notifyIsModified() method will be 761 * called for each file or directory as it is loaded 762 * @return a new CcFile proxy for the file that has been loaded 763 * @throws WvcmException 764 */ 765 CcFile doLoad(Feedback feedback) throws WvcmException; 766 767 /** 768 * Hijack this web, automatic or snapshot view controllable resource. 769 * Make the resource writable and set its "last modified" time to the 770 * current time. This operation does <i>not</i> contact the server. 771 * @param feedback 772 * @return a new CcFile proxy for the hijacked file 773 * @throws WvcmException 774 */ 775 CcFile hijack(Feedback feedback) 776 throws WvcmException; 777 778 /** 779 * Undo a hijack on this hijacked controllable resource. Reload the file's 780 * contents from the appropriate version on the server. 781 * @param flags Specify <code>KEEP</code> to save a copy of the hijacked 782 * file's contents in a ".keep" file before undoing the hijack. 783 * @param feedback 784 * @return a new CcFile proxy for the unhijacked file 785 * @throws WvcmException 786 */ 787 CcFile doUnhijack(UnhijackFlag[] flags, Feedback feedback) 788 throws WvcmException; 789 790 /** 791 * For client resources, identifies the file system path to the local file 792 * representing this controllable resource. 793 */ 794 PropertyName<File> CLIENT_PATH = 795 new PropertyName<File>(PROPERTY_NAMESPACE, "client-path"); 796 797 /** 798 * Returns the value of this proxy's {@link #CLIENT_PATH} property. 799 * @return The path to this ControllableResource in the local file area. 800 * Will never be <code>null</code>. 801 * @throws WvcmException if requested of a ControllableResource without client state 802 */ 803 File getClientPath() throws WvcmException; 804 805 /** 806 * For version-controlled resources, this resource's element type. 807 */ 808 PropertyName<CcElementType> ELEMENT_TYPE = 809 new PropertyName<CcElementType>(PROPERTY_NAMESPACE, "element-type"); 810 811 /** 812 * Returns the value of this proxy's {@link #ELEMENT_TYPE} property. 813 * @return This resource's element type. Will be <code>null</code> 814 * if resource is not version-controlled. 815 * @throws WvcmException if this proxy doesn't define a value for this property. 816 */ 817 CcElementType getElementType() throws WvcmException; 818 819 /** 820 * Set the value of this file or directory's {@link #ELEMENT_TYPE} property. 821 * This property can only be set just prior to calling doVersionControl() 822 * on the resource. 823 * @param eltype resource's desired element type 824 */ 825 void setElementType(CcElementType eltype); 826 827 /** 828 * Is this file a web view file area database file? File area DB files require 829 * special treatment. For instance, they cannot be source controlled. 830 * For this reason, applications may choose to hide these files from 831 * the end user. 832 */ 833 PropertyName<Boolean> IS_DB_FILE = 834 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-db-file"); 835 836 /** 837 * Get the value of this files {@link #IS_DB_FILE} property. 838 * @return true if this file is a file area database file, else false 839 * @throws WvcmException 840 * if this proxy doesn't define a value for this property. 841 */ 842 public boolean getIsDbFile() throws WvcmException; 843 844 /** 845 * Property which is true/false depending on whether this version-controlled 846 * resource has been hijacked. 847 */ 848 PropertyName<Boolean> IS_HIJACKED = 849 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-hijacked"); 850 851 /** 852 * Get the value of this file's {@link #IS_HIJACKED} property. 853 * @return true if the file is hijacked, false otherwise 854 * @throws WvcmException 855 * if this proxy doesn't define a value for this property. 856 */ 857 public boolean getIsHijacked() throws WvcmException; 858 859 /** 860 * Is this file actually a symbolic link? 861 */ 862 PropertyName<Boolean> IS_SYMLINK = 863 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-symlink"); 864 865 /** 866 * Get the value of the {@link #IS_SYMLINK} property. 867 * @return true if this resource is a symbolic link, false otherwise. 868 * @throws WvcmException 869 * if this proxy doesn't define a value for this property. 870 */ 871 public boolean getIsSymlink() throws WvcmException; 872 873 /** 874 * Returns the direct parent of this file. The value will 875 * be <code>null</code> if the file has no parent (e.g. VOB root). 876 * Does not find parents of hard-linked names for the file. 877 */ 878 public static final PropertyName<CcFile> PARENT = 879 new PropertyName<CcFile>(PROPERTY_NAMESPACE, "cc-parent"); 880 881 /** 882 * Get the value of the {@link #PARENT} property. 883 * @return A CcFile proxy for the parent, null if no parent 884 * @throws WvcmException 885 */ 886 public CcFile getParent() throws WvcmException; 887 888 /** 889 * <p>If this file is actually a symbolic link, the path to its target file 890 * or directory. The path is interpreted relative to this file's parent 891 * directory.</p> 892 * 893 * <p>If this file is not a symbolic link, this value will be 894 * <code>null</code>.</p> 895 */ 896 PropertyName<String> SYMLINK_TARGET_PATH = 897 new PropertyName<String>(PROPERTY_NAMESPACE, "symlink-target-path"); 898 899 /** 900 * Get the value of this resource's {@link #SYMLINK_TARGET_PATH} property. 901 * @return path to symlink's target file or directory, or <code>null</code> 902 * if this file is not a symbolic link. 903 * @throws WvcmException if property was not requested 904 */ 905 public String getSymlinkTargetPath() throws WvcmException; 906 907 /** 908 * The view-relative path for this resource. 909 */ 910 PropertyName<String> VIEW_RELATIVE_PATH = 911 new PropertyName<String>(PROPERTY_NAMESPACE, "cr-view-relative-path"); 912 913 /** 914 * Get the value of this resource's {@link #VIEW_RELATIVE_PATH} property. 915 * @return view-relative path 916 * @throws WvcmException if property was not requested 917 */ 918 public String getViewRelativePath() throws WvcmException; 919 920 /** 921 * The CC version resource associated with this file. 922 * The value of this property will be null if this is not a version- 923 * controlled resource. 924 * @see javax.wvcm.ControllableResource#CHECKED_IN and 925 * javax.wvcm.ControllableResource#CHECKED_OUT 926 */ 927 PropertyName<CcVersion> VERSION = 928 new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "version"); 929 930 /** 931 * Get the value of this resource's {@link #VERSION} property. 932 * @return this file's version, or <code>null</code> if this file is 933 * not version controlled 934 * @throws WvcmException if property was not requested 935 */ 936 public CcVersion getVersion() throws WvcmException; 937 938 /** 939 * The OID of the CC version resource associated with this file. 940 * The value of this property will be null if this is not a version- 941 * controlled resource. 942 */ 943 PropertyName<String> VERSION_OID = 944 new PropertyName<String>(PROPERTY_NAMESPACE, "version-oid"); 945 946 /** 947 * Get the value of this resource's {@link #VERSION_OID} property. 948 * @return this file's version oid, or <code>null</code> if this file is 949 * not version controlled 950 * @throws WvcmException if property was not requested 951 */ 952 public String getVersionOid() throws WvcmException; 953 954 /** 955 * The tag of the VOB in which this file resides. 956 */ 957 PropertyName<CcVobTag> VOB_TAG = 958 new PropertyName<CcVobTag>(PROPERTY_NAMESPACE, "file-vob-tag"); 959 960 /** 961 * Get the value of this resource's {@link #VOB_TAG} property. 962 * @return the VOB tag for this file's VOB as a CcVobTag proxy, 963 * or <code>null</code> if this file is not version controlled 964 * @throws WvcmException if property was not requested 965 */ 966 public CcVobTag getVobTag() throws WvcmException; 967 968 /** 969 * The CC element resource associated with this file. 970 * The value of this property will be null if this is not a version- 971 * controlled resource. 972 * @see javax.wvcm.ControllableResource#VERSION_HISTORY 973 */ 974 PropertyName<CcElement> ELEMENT = 975 new PropertyName<CcElement>(PROPERTY_NAMESPACE, "element"); 976 977 /** 978 * Get the value of this resource's {@link #ELEMENT} property. 979 * @return this file's element, or <code>null</code> if this file is 980 * not version controlled 981 * @throws WvcmException if property was not requested 982 */ 983 public CcElement getElement() throws WvcmException; 984 985 /** 986 * Returns a {@link java.io.File File} representing the location of this 987 * client-side resource in the local file system, else <code>null</code> if 988 * this resource is a server-side resource only, e.g., if it is a proxy 989 * to an unloaded file in a web view. 990 * @return The location of this resource in the local file system, else 991 * <code>null</code> if this is a proxy to a server-side resource only. 992 * 993 * @throws WvcmException Thrown if there was an error in determining the 994 * path for this client-side Resource. 995 */ 996 File clientResourceFile() throws WvcmException; 997 998 /** 999 * Reads the file's properties, if they are available locally on the client machine. 1000 * @param feedback the properties to be available in the returned proxy, 1001 * and any other feedback desired, such as progress indications. 1002 * @return a {@link CcFile} containing the wanted properties 1003 * that are available locally on the client machine 1004 * without communicating with the server. 1005 * @see Resource#doReadProperties(Feedback) doReadProperties. 1006 * @throws WvcmException ReasonCode: 1007 * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}: 1008 * The file MUST be available locally on the client machine. 1009 */ 1010 CcFile readProperties(Feedback feedback) throws WvcmException; 1011 1012 /** 1013 * Reads the file's content, if it is available locally on the client machine. 1014 * @see Resource#doReadContent(OutputStream,Feedback) doReadContent 1015 * @param feedback the properties to be available in the returned proxy, 1016 * and any other feedback desired, such as progress indications. 1017 * @param content the file's content, if available, is written to this 1018 * byte stream. The stream is then closed. 1019 * @return a CcFile proxy containing the wanted properties 1020 * that are available on the client host without communicating with the server. 1021 * @throws WvcmException ReasonCode: 1022 * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}: 1023 * The file MUST be available locally on the client machine. 1024 */ 1025 CcFile readContent(OutputStream content, Feedback feedback) throws WvcmException; 1026 1027 /** 1028 * Resolve this file resource, but do not consult the ClearCase server. 1029 * Unlike {@link CcResource#doResolve()}, use only information currently 1030 * available information on the local client machine. 1031 * @see CcResource#doResolve() 1032 * @return a new file proxy of the correct, most specific resource type 1033 * @throws WvcmException with NOT_FOUND reason code if this file does not 1034 * exist on the local machine. 1035 */ 1036 CcFile resolve() throws WvcmException; 1037 1038 /** 1039 * Whether this file is loaded, partially loaded, or not loaded in 1040 * the file area in which it resides. 1041 */ 1042 PropertyName<LoadState> LOAD_STATE = 1043 new PropertyName<LoadState>(PROPERTY_NAMESPACE, "load-state"); 1044 1045 /** 1046 * Get the value of this resource's {@link #LOAD_STATE} property. 1047 * @return LoadState.LOADED, LoadState.PARTIALLY_LOADED or LoadState.NOT_LOADED 1048 * @throws WvcmException 1049 * if this proxy doesn't define a value for this property. 1050 */ 1051 LoadState getLoadState() throws WvcmException; 1052 1053 /** 1054 * <p>Version controlled files and directories in a web view 1055 * may have both client state - 1056 * state maintained in a local file area - and server state. When the 1057 * client state and server state get out of sync, we call this <i>skew</i>. 1058 * </p> 1059 * <p>By definition, skew cannot occur in a dynamic view. 1060 * </p> 1061 * <p>The caller can detect skew by including the {@link #SKEWED_PROPERTY_LIST} 1062 * property in property requests to <code>doReadProperties()</code> and 1063 * other <code>do</code> methods that accept property requests. 1064 * 1065 * The resulting value of this property is the list of property names 1066 * in the request that differed between the client and the server for this 1067 * particular file or directory. 1068 * </p> 1069 * <p>Note that only certain properties are checked for skew - properties 1070 * where skew can cause significant problems. For example, 1071 * {@link #IS_CHECKED_OUT}, {@link #IS_VERSION_CONTROLLED}, and 1072 * {@link #VERSION_OID}. 1073 * 1074 * Note that skew can also be caused by elementness skew (file vs dir) and 1075 * loadness skew (loaded vs unloaded). 1076 * </p> 1077 * <p>Note also that <i>only</i> properties in the current property request 1078 * are checked for skew. 1079 * </p> 1080 * <p>NOTE: This should be used only as a trigger to do a real discordance 1081 * scan of the directory. These values are not reliable enough to use for 1082 * icon decoration or user messages. This is a quick and easy way to 1083 * automatically detect skew, but it does not cover all edge cases 1084 * (symlinks, aliases, and others) or discordance types. 1085 * </p> 1086 */ 1087 PropertyName<List<PropertyName>> SKEWED_PROPERTY_LIST = 1088 new PropertyName<List<PropertyName>>(PROPERTY_NAMESPACE, "skewed-property-list"); 1089 1090 /** 1091 * Get the value of this file's {@link #SKEWED_PROPERTY_LIST} property. 1092 * 1093 * NOTE: This should be used only as a trigger to do a real discordance 1094 * scan of the directory. These values are not reliable enough to use for 1095 * icon decoration or user messages. This is a quick and easy way to 1096 * automatically detect skew, but it does not cover all edge cases 1097 * (symlinks, aliases, and others) or discordance types. 1098 * 1099 * @return a list of property names in the current property request whose 1100 * values differed between the client and the server for this file 1101 * or directory. 1102 * @throws WvcmException 1103 * if this proxy doesn't define a value for this property. 1104 */ 1105 List<PropertyName> getSkewedPropertyList() throws WvcmException; 1106 1107 /** 1108 * The config spec rule that selects this file. 1109 */ 1110 PropertyName<String> SELECTION_RULE = 1111 new PropertyName<String>(PROPERTY_NAMESPACE, "selection-rule"); 1112 1113 /** 1114 * Get the value of this resource's {@link #SELECTION_RULE} property. 1115 * @return this file's config spec rule, as a string. 1116 * @throws WvcmException 1117 * if this proxy doesn't define a value for this property. 1118 */ 1119 String getSelectionRule() throws WvcmException; 1120 1121 /** 1122 * The version of this file that is currently the latest on the same branch. 1123 */ 1124 PropertyName<CcVersion> LATEST_VERSION_ON_BRANCH = 1125 new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "latest-version-on-branch"); 1126 1127 /** 1128 * Get the value of this resource's {@link #LATEST_VERSION_ON_BRANCH} property. 1129 * @return the version of this file that is the latest on the same branch as the 1130 * version in the view. 1131 * @throws WvcmException 1132 * if this proxy doesn't define a value for this property. 1133 */ 1134 CcVersion getLatestVersionOnBranch() throws WvcmException; 1135 }