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