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, 2016. 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 * Applies only to automatic views 264 */ 265 RESUME_UPDATE("resume-update"), 266 267 /** 268 * Reset local view db - used to restore a view 269 * Applies only to automatic views 270 */ 271 DO_RESET("do_reset"), 272 273 /** 274 * Master DB is on server - used to restore a view 275 * Applies only to automatic views 276 */ 277 RESTORE_FROM_SERVER("server"), 278 279 /** 280 * Master DB is on client - used to restore a view 281 * Applies only to automatic views 282 */ 283 RESTORE_FROM_CLIENT("client"); 284 285 private String m_name; 286 287 private RefreshFlag(String name) { m_name = name; } 288 289 /* (non-Javadoc) 290 * @see java.lang.Object#toString() 291 */ 292 public String toString() { return m_name; } 293 } 294 295 /** Flags for the <code>doCheckout</code> method. */ 296 enum CcCheckoutFlag implements StpExEnumeration { 297 298 /** 299 * Indicates whether to checkout this file reserved. 300 */ 301 RESERVED("reserved"), 302 303 /** 304 * Fall back to unreserved if a reservation can not be obtained. 305 */ 306 FALLBACK_TO_UNRESERVED("fallback-to-unreserved"), 307 308 /** 309 * Checkout the version of the file that is currently loaded in the 310 * view, even if that version is not the version selected by the 311 * view's config spec. 312 * 313 * <p>If the loaded version is not the version selected by the view's 314 * config spec, and neither {@link #LOADED_NOT_LATEST} nor 315 * {@link #LATEST_NOT_LOADED} flags are set, the checkout operation 316 * will throw an exception with reason code <code>CHECKOUT_NOT_LATEST</code>. 317 */ 318 LOADED_NOT_LATEST("checkout-loaded-not-latest"), 319 320 /** 321 * Checkout the version of the file that is selected by the view's 322 * config spec. If this version is not loaded at checkout time, then 323 * load it prior to performing the checkout. 324 * 325 * <p>If the loaded version is not the version selected by the view's 326 * config spec, and neither {@link #LOADED_NOT_LATEST} nor 327 * {@link #LATEST_NOT_LOADED} flags are set, the checkout operation 328 * will throw an exception with reason code <code>CHECKOUT_NOT_LATEST</code>. 329 */ 330 LATEST_NOT_LOADED("checkout-latest-not-loaded"), 331 332 /** 333 * For dynamic views only. 334 * 335 * <p>Checkout the version of the file that is the latest on the branch 336 * even if that version is not currently selected by the view. 337 * 338 * <p>If the version selected by the view's config spec is not the latest 339 * on the branch and neither {@link #LATEST_ON_BRANCH} nor 340 * {@link #VIEW_SELECTED_VERSION} flags are specified, the checkout 341 * operation will will throw an exception with reason code 342 * <code>CHECKOUT_NOT_LATEST</code>. 343 */ 344 LATEST_ON_BRANCH("latest-on-branch"), 345 346 /** 347 * Indicates whether to checkout this file even if the currently 348 * selected branch is mastered by another replica. The 349 * <code>RESERVED</code> flag must NOT be set with this flag. 350 * 351 * <p>If the file is mastered by this replica, setting this 352 * flag has no effect. 353 */ 354 NON_MASTERED_OK("non-mastered-ok"), 355 356 /** 357 * If the file is hijacked, keep the hijacked contents upon checkout. 358 */ 359 PRESERVE_HIJACK_CONTENTS("preserve-hijack-contents"), 360 361 /** 362 * After a file is 'checkedout', set the file's "last modified" 363 * time to be the time when the version was first created. 364 * <p>This applies only to automatic, dynamic and snapshot views. 365 */ 366 PRESERVE_MODIFICATION_TIME("preserve-modification-time"), 367 368 /** 369 * For dynamic views only. 370 * 371 * <p>Checkout the version of the file that is currently selected by 372 * the view, even if that version is not the latest on the branch. 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 VIEW_SELECTED_VERSION("view-selected-version"); 381 382 private String m_name; 383 384 private CcCheckoutFlag(String name) { m_name = name; } 385 386 /* (non-Javadoc) 387 * @see java.lang.Object#toString() 388 */ 389 public String toString() { return m_name; } 390 } 391 392 /** Flags for the <code>doCcVersionControl</code> method. */ 393 enum CcVersionControlFlag implements StpExEnumeration { 394 395 /** 396 * Indicates whether to checkin this file after it is added to version control. 397 * The default is to leave it checked out.<p> 398 * This flag is mutually exclusive with {@link CcVersionControlFlag#NO_CHECKOUT}. 399 */ 400 CHECKIN("checkin"), 401 402 /** 403 * Do not checkout the file after adding to version control.<p> 404 * This flag is mutually exclusive with {@link CcVersionControlFlag#CHECKIN}. 405 */ 406 NO_CHECKOUT("no-checkout"), 407 408 /** 409 * Assigns mastership of the <b>main</b> branch of the newly version controlled 410 * file to the VOB replica in which you execute operation. By default 411 * mastership of the file's <b>main</b> branch is assigned to the VOB replica 412 * that masters the <b>main</b> branch type. <p> 413 * This flag is mutually exclusive with {@link CcVersionControlFlag#MAKE_PATH}. 414 */ 415 MASTER_LOCALLY("master-locally"), 416 417 /** 418 * Automatically checkout the version controlled parent directory and 419 * check back in after new file has been added to version control. 420 * Any view private parent directories below the version controlled parent 421 * and the desired file, will also be version controlled.<p> 422 * This flag is mutually exclusive with {@link CcVersionControlFlag#MASTER_LOCALLY}. 423 */ 424 MAKE_PATH("mkpath"); 425 426 private String m_name; 427 428 private CcVersionControlFlag(String name) { m_name = name; } 429 430 /* (non-Javadoc) 431 * @see java.lang.Object#toString() 432 */ 433 public String toString() { return m_name; } 434 } 435 436 /** Values for file or directory load state */ 437 enum LoadState implements StpExEnumeration { 438 439 /** 440 * This file or directory is loaded in its file area. 441 */ 442 LOADED, 443 444 /** 445 * This directory is partially loaded in its file area, i.e., 446 * some but not all of its children are loaded. 447 */ 448 PARTIALLY_LOADED, 449 450 /** 451 * This file or directory is not loaded in its file area. 452 */ 453 NOT_LOADED; 454 } 455 456 /** 457 * Create a new view-private file at the location specified by this resource. 458 * The request will fail if a resource already exists at that location. 459 * @param feedback 460 * @return a CcFile proxy for the new file 461 * @see javax.wvcm.ControllableResource#doCreateResource(Feedback) 462 */ 463 public CcFile createCcFile(Feedback feedback) throws WvcmException; 464 465 /** 466 * Apply the specified attribute to the checked-in version of this controllable resource. 467 * @param flags array of flags which specify the behavior of the operation 468 * @param comment Comment (if any) to be used for operation. Empty string if none. 469 * @param attributeName Name of an existing attribute type to be used to create 470 * an instance will to be applied to this resource. 471 * @param attributeValue Value of attribute instance. If the vtype of the attribute type is 472 * a string, it must be enclosed in additional quotes <em>within the string</em>. For example, if 473 * specified as a constant it would appear as <code>"\"string value\""</code>. If the 474 * vtype is not a string, this should be a string representation of the given value 475 * (e.g. <code>"3.1415"</code>, <code>"0xa413"</code>, etc.). 476 * @param versionId Applies the attribute to the explicitly specified version, 477 * overriding the version selected by the view. 478 * This string must only represent the version suffix (e.g. /main/314). 479 * @param feedback 480 * @return A new proxy for this resource, whose properties are specified by feedback. 481 * @throws WvcmException 482 */ 483 ControllableResource doApplyAttribute(AttributeOpFlag[] flags, String comment, 484 String attributeName, String attributeValue, String versionId, Feedback feedback) 485 throws WvcmException; 486 487 /** 488 * Remove the specified attribute from the checked-in version of this controllable resource. 489 * @param flags array of flags which specify the behavior of the operation 490 * @param comment Comment (if any) to be used for operation. Empty string if none. 491 * @param attributeName Name of the attribute to be removed from this resource 492 * @param versionId Removes the attribute from the explicitly specified version, 493 * overriding the version selected by the view. 494 * @param feedback 495 * @return A new proxy for this resource, whose properties are specified by feedback. 496 * @throws WvcmException 497 */ 498 ControllableResource doRemoveAttribute(AttributeOpFlag[] flags, String comment, 499 String attributeName, String versionId, Feedback feedback) 500 throws WvcmException; 501 502 /** 503 * Apply the specified label to the checked-in version of this controllable resource. 504 * @param flags array of flags which specify the behavior of the operation 505 * @param label the label to be added to this version 506 * @param feedback 507 * @return A new proxy for this resource, whose properties are specified by feedback. 508 * @throws WvcmException 509 */ 510 ControllableResource doApplyLabel(ApplyLabelFlag[] flags, 511 String label, Feedback feedback) 512 throws WvcmException; 513 514 /** 515 * Apply the specified label to the checked-in version of this controllable resource. 516 * @param flags array of flags which specify the behavior of the operation 517 * @param comment The comment for this operation, or null for no comment 518 * @param label the label to be added to this version 519 * @param feedback 520 * @return A new proxy for this resource, whose properties are specified by feedback. 521 * @throws WvcmException 522 */ 523 ControllableResource doApplyLabel(ApplyLabelFlag[] flags, String comment, 524 String label, Feedback feedback) 525 throws WvcmException; 526 527 /** 528 * Remove the specified label from the checked-in version of this controllable resource. 529 * @param flags array of flags which specify the behavior of the operation 530 * @param label the label to be removed from this version 531 * @param feedback 532 * @return A new proxy for this resource, whose properties are specified by feedback. 533 * @throws WvcmException 534 */ 535 ControllableResource doRemoveLabel(RemoveLabelFlag[] flags, 536 String label, Feedback feedback) 537 throws WvcmException; 538 539 /** 540 * Apply the specified rolemap to the element represented by this file/directory. 541 * @param flags array of flags which specify the behavior of the operation 542 * @param comment Comment (if any) to be used for operation. Empty string if none. 543 * @param rolemap The name of the rolemap to be applied. 544 * @throws WvcmException 545 */ 546 void doApplyRolemap(ApplyRolemapFlag[] flags, String comment, String rolemap) 547 throws WvcmException; 548 549 /** 550 * <p>Check out this version-controlled file or directory resource. 551 * The resource is checked out to the ClearCase view implied by its location. 552 * </p> 553 * <p>If the view is a UCM view, the caller must insure there is a 554 * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation. 555 * The checked out file will be added to the current activity's change set. 556 * The caller may explicitly specify an activity using this resource's 557 * {@link javax.wvcm.ControllableResource#setActivity} method. In that case, 558 * the specified activity will become the new current activity. 559 * Otherwise, the existing current activity will be used. 560 * If the view is a UCM view and there is no current activity, the operation 561 * will fail. 562 * </p> 563 * <p>The caller may optionally specify a checkout comment using this 564 * resource's {@link javax.wvcm.Resource#setComment} method. 565 * </p> 566 * @param flags array of flags which specify the behavior of the operation 567 * @param feedback 568 * @return new CcFile proxy representing the checked out file. 569 * @throws WvcmException 570 */ 571 CcFile doCcCheckout(CcCheckoutFlag[] flags, Feedback feedback) 572 throws WvcmException; 573 574 /** 575 * Cancel the checkout of this version-controlled resource, 576 * and restore its content to the state of its CHECKED_IN version. 577 * @param flags array of flags which specify the behavior of the operation 578 * @param feedback 579 * @return new CcFile proxy representing the file whose checkout has been canceled 580 * @throws WvcmException 581 * @see javax.wvcm.ControllableResource#doUncheckout 582 */ 583 CcFile doUncheckout(UncheckoutFlag[] flags, Feedback feedback) 584 throws WvcmException; 585 586 /** 587 * <p>Check in this checked out file or directory resource. 588 * </p> 589 * <p>If this resource is in a UCM view, it was added to an activity's 590 * change set at checkout time. The caller may specify an alternate 591 * change set using this resource's 592 * {@link javax.wvcm.ControllableResource#setActivity} method just before 593 * calling <code>doCheckin</code>. 594 * </p> 595 * <p>The caller may also specify a checkin comment using this 596 * resource's {@link javax.wvcm.Resource#setComment} method. 597 * This will override the comment specified at checkout time, if any. 598 * </p> 599 * @param flags array of flags which specify the behavior of the operation 600 * @param feedback 601 * @return new ControllableResource proxy representing the checked in file. 602 * @throws WvcmException 603 * @see javax.wvcm.ControllableResource#doCheckin 604 * @see com.ibm.rational.wvcm.stp.cc.CcFile#doCheckout 605 */ 606 ControllableResource doCheckin(CheckinFlag[] flags, Feedback feedback) 607 throws WvcmException; 608 609 /** 610 * Merges the contents of two or more versions, representing files or 611 * directories, into this file. Versions must be of the same element as this 612 * file. 613 * 614 * @param baseVersion Base contributor. Can be null. 615 * @param contribList One or more contributing versions. 616 * @param flags Specify options for the merge. Can be null. 617 * @param listener Callback notifier for the merge. 618 * @param feedback 619 * @return new CcFile proxy representing the merged file. 620 * @throws WvcmException if there is an error during the merge. 621 */ 622 CcFile doMerge(CcVersion baseVersion, 623 List<CcVersion> contribList, 624 CcMergeFlag[] flags, 625 CcListener listener, 626 Feedback feedback) throws WvcmException; 627 628 /** 629 * Places the view-private file specified by this proxy under version control. 630 * <p>If the view is a UCM view, the caller must insure there is a 631 * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation. 632 * The newly version controlled file will be added to the current activity's change set 633 * and left in a checked-in state. 634 * The caller may explicitly specify an activity using this resource's 635 * {@link javax.wvcm.ControllableResource#setActivity} method. In that case, 636 * the specified activity will become the new current activity. 637 * Otherwise, the existing current activity will be used. 638 * If the view is a UCM view and there is no current activity, the operation 639 * will fail. 640 * </p> 641 * <p>The caller may optionally specify a creation comment using this 642 * resource's {@link javax.wvcm.Resource#setComment} method. 643 * </p> 644 * <p>The caller may optionally specify the type of element to be created using 645 * this resource's {@link com.ibm.rational.wvcm.stp.cc.CcFile#setElementType} method. 646 * </p> 647 * @param feedback 648 * @return new ControllableResource proxy representing the version controlled file. 649 * @throws WvcmException 650 * @see javax.wvcm.ControllableResource#doVersionControl(javax.wvcm.Feedback) 651 */ 652 ControllableResource 653 doVersionControl(Feedback feedback) 654 throws WvcmException; 655 656 /** 657 * Enhanced variant of the doVersionControl that provides additional flags 658 * which modify the behaviour.<p> 659 * This method has two main difference from <code>doVersionControl</code>: 660 * <ol> 661 * <li>It does <b>not</b> automatically checkout the version controlled 662 * parent directory. The caller must do this explicitly unless the 663 * {@link com.ibm.rational.wvcm.stp.cc.CcFile.CcVersionControlFlag#MAKE_PATH} 664 * flag is specified. 665 * <li>The newly version controlled file will be left in a checked-out state. 666 * To have the resulting file checked-in, specify the 667 * {@link com.ibm.rational.wvcm.stp.cc.CcFile.CcVersionControlFlag#CHECKIN} flag. 668 * </ol> 669 * @param flags array of flags which specify the behavior of the operation 670 * @param feedback 671 * @return A new proxy for this resource, whose properties are specified by feedback. 672 * @throws WvcmException 673 * @see com.ibm.rational.wvcm.stp.cc.CcFile#doVersionControl(javax.wvcm.Feedback) 674 */ 675 ControllableResource 676 doCcVersionControl(CcVersionControlFlag flags[], Feedback feedback) 677 throws WvcmException; 678 679 /** 680 * <p> 681 * Refresh this file or directory. Re-evaluate the 682 * view's config spec and update resources on the client to be whatever 683 * is currently selected by the config spec. If this is a directory, 684 * recursively refresh its contents. 685 * </p> 686 * <p> 687 * Example: The config spec says "element * /main/LATEST", and you 688 * have version "/main/7" of this resource loaded. Someone else checks 689 * in a new version, thus creating a "/main/8". In that case, 690 * doRefresh() will cause version "/main/8" of this resource to 691 * be loaded into your view. 692 * </p> 693 * <p> 694 * Preconditions: This resource must be a version-controlled file 695 * or directory. 696 * </p> 697 * <p> 698 * Postconditions: This resource (and its descendants if this is a 699 * directory) are updated to be what is currently selected by the view's 700 * config spec. 701 * </p> 702 * @param flags array of flags which specify the behavior of the operation 703 * @param feedback (optional) a list of properties to fetch on the 704 * updated resources or a DetailedFeedback. If properties are provided, 705 * the returned resources will have them filled in. If a DetailedFeedback 706 * is provided, the appropriate notification methods will be called for each 707 * resource which is refreshed as part of the operation. 708 * by doRefresh will have these properties filled in. 709 * @return a new CcFile proxy representing the refreshed file 710 * @throws WvcmException if the precondition is not met or if an error 711 */ 712 CcFile doRefresh(RefreshFlag[] flags, Feedback feedback) 713 throws WvcmException; 714 715 /** 716 * <p> 717 * Refresh this file or directory. Re-evaluate the 718 * view's config spec and update resources on the client to be whatever 719 * is currently selected by the config spec. If this is a directory, 720 * recursively refresh its contents. 721 * </p> 722 * <p> 723 * Example: The config spec says "element * /main/LATEST", and you 724 * have version "/main/7" of this resource loaded. Someone else checks 725 * in a new version, thus creating a "/main/8". In that case, 726 * doRefresh() will cause version "/main/8" of this resource to 727 * be loaded into your view. 728 * </p> 729 * <p> 730 * Preconditions: This resource must be a version-controlled file 731 * or directory. 732 * </p> 733 * <p> 734 * Postconditions: This resource (and its descendants if this is a 735 * directory) are updated to be what is currently selected by the view's 736 * config spec. 737 * </p> 738 * @param flags array of flags which specify the behavior of the operation 739 * @param listener Callback notifier for the merge. 740 * @param feedback (optional) a list of properties to fetch on the 741 * updated resources or a DetailedFeedback. If properties are provided, 742 * the returned resources will have them filled in. If a DetailedFeedback 743 * is provided, the appropriate notification methods will be called for each 744 * resource which is refreshed as part of the operation. 745 * by doRefresh will have these properties filled in. 746 * @return a new CcFile proxy representing the refreshed file 747 * @throws WvcmException if the precondition is not met or if an error 748 */ 749 CcFile doCcRefresh(RefreshFlag[] flags, CcListener listener, Feedback feedback) 750 throws WvcmException; 751 752 /** 753 * <p> 754 * Restore this file or directory. If this is a directory, recursively 755 * restore its contents. This repairs any damage to the portion of the file 756 * area database specified by this resource. 757 * </p> 758 * 759 * @param flags array of flags which specify the behavior of the operation 760 * @param feedback 761 * @return a new CcFile proxy representing the restored file 762 * @throws WvcmException 763 */ 764 CcFile doRestore(RefreshFlag[] flags, Feedback feedback) 765 throws WvcmException; 766 767 /** 768 * <p> 769 * Load this controllable resource into a web or snapshot view's local 770 * file area, or load the controllable resource into the automatic view. 771 * If this is a controllable folder, loads the tree of controllable 772 * resources under this folder. 773 * Also updates the view's load rules if necessary 774 * to include this file or folder. 775 * </p> 776 * <p> 777 * If this resource was already loaded, doLoad is a no-op. 778 * </p> 779 * <p> 780 * Preconditions: This must be a version-controlled file or folder 781 * in a web, snapshot or automatic view. 782 * </p> 783 * <p> 784 * Postconditions: 785 * </p> 786 * <p> 787 * This file, or the tree of files under this folder, 788 * is loaded into the view. Thus, the file(s) appear, and the view's 789 * load rules are updated to include this file or folder. 790 * </p> 791 * <p> 792 * Snapshot view: <br /> 793 * This file, or the tree of files under this folder, 794 * is loaded into the view. Thus, the file(s) appear, and the view's 795 * load rules are updated to include this file or folder. 796 * </p> 797 * <p> 798 * Note that automatic views do not support load of individual 799 * resources. Addition of a load rule for a controllable resource in an 800 * automatic view must be done directly in the config spec. 801 * </p> 802 * <p> 803 * Note that automatic views do not support load of individual 804 * resources. Addition of a load rule for a controllable resource in an 805 * automatic view must be done directly in the config spec. 806 * </p> 807 * @param feedback (optional) feedback's notifyIsModified() method will be 808 * called for each file or directory as it is loaded 809 * @return a new CcFile proxy for the file that has been loaded 810 * @throws WvcmException 811 */ 812 CcFile doLoad(Feedback feedback) throws WvcmException; 813 814 /** 815 * Hijack this web, automatic or snapshot view controllable resource. 816 * Make the resource writable and set its "last modified" time to the 817 * current time. This operation does <i>not</i> contact the server. 818 * @param feedback 819 * @return a new CcFile proxy for the hijacked file 820 * @throws WvcmException 821 */ 822 CcFile hijack(Feedback feedback) 823 throws WvcmException; 824 825 /** 826 * Undo a hijack on this hijacked controllable resource. Reload the file's 827 * contents from the appropriate version on the server. 828 * @param flags Specify <code>KEEP</code> to save a copy of the hijacked 829 * file's contents in a ".keep" file before undoing the hijack. 830 * @param feedback 831 * @return a new CcFile proxy for the unhijacked file 832 * @throws WvcmException 833 */ 834 CcFile doUnhijack(UnhijackFlag[] flags, Feedback feedback) 835 throws WvcmException; 836 837 /** 838 * For client resources, identifies the file system path to the local file 839 * representing this controllable resource. 840 */ 841 PropertyName<File> CLIENT_PATH = 842 new PropertyName<File>(PROPERTY_NAMESPACE, "client-path"); 843 844 /** 845 * Returns the value of this proxy's {@link #CLIENT_PATH} property. 846 * @return The path to this ControllableResource in the local file area. 847 * Will never be <code>null</code>. 848 * @throws WvcmException if requested of a ControllableResource without client state 849 */ 850 File getClientPath() throws WvcmException; 851 852 /** 853 * For version-controlled resources, this resource's element type. 854 */ 855 PropertyName<CcElementType> ELEMENT_TYPE = 856 new PropertyName<CcElementType>(PROPERTY_NAMESPACE, "element-type"); 857 858 /** 859 * Returns the value of this proxy's {@link #ELEMENT_TYPE} property. 860 * @return This resource's element type. Will be <code>null</code> 861 * if resource is not version-controlled. 862 * @throws WvcmException if this proxy doesn't define a value for this property. 863 */ 864 CcElementType getElementType() throws WvcmException; 865 866 /** 867 * Set the value of this file or directory's {@link #ELEMENT_TYPE} property. 868 * This property can only be set just prior to calling doVersionControl() 869 * on the resource. 870 * @param eltype resource's desired element type 871 */ 872 void setElementType(CcElementType eltype); 873 874 /** 875 * Is this file a web view file area database file? File area DB files require 876 * special treatment. For instance, they cannot be source controlled. 877 * For this reason, applications may choose to hide these files from 878 * the end user. 879 */ 880 PropertyName<Boolean> IS_DB_FILE = 881 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-db-file"); 882 883 /** 884 * Get the value of this files {@link #IS_DB_FILE} property. 885 * @return true if this file is a file area database file, else false 886 * @throws WvcmException 887 * if this proxy doesn't define a value for this property. 888 */ 889 public boolean getIsDbFile() throws WvcmException; 890 891 /** 892 * Is this a view-private file that is eclipsing a VOB file with 893 * the same name? 894 */ 895 PropertyName<Boolean> IS_ECLIPSING = 896 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-eclipsing"); 897 898 /** 899 * Get the value of this files {@link #IS_ECLIPSING} property. 900 * @return {@code true} if this is a view-private file that eclipses a VOB file 901 * with the same name, else {@code false} 902 * @throws WvcmException 903 * if this proxy doesn't define a value for this property. 904 */ 905 public boolean getIsEclipsing() throws WvcmException; 906 907 /** 908 * Property which is true/false depending on whether this version-controlled 909 * resource has been hijacked. 910 */ 911 PropertyName<Boolean> IS_HIJACKED = 912 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-hijacked"); 913 914 /** 915 * Get the value of this file's {@link #IS_HIJACKED} property. 916 * @return true if the file is hijacked, false otherwise 917 * @throws WvcmException 918 * if this proxy doesn't define a value for this property. 919 */ 920 public boolean getIsHijacked() throws WvcmException; 921 922 /** 923 * Is this file actually a symbolic link? 924 */ 925 PropertyName<Boolean> IS_SYMLINK = 926 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-symlink"); 927 928 /** 929 * Get the value of the {@link #IS_SYMLINK} property. 930 * @return true if this resource is a symbolic link, false otherwise. 931 * @throws WvcmException 932 * if this proxy doesn't define a value for this property. 933 */ 934 public boolean getIsSymlink() throws WvcmException; 935 936 /** 937 * Returns the direct parent of this file. The value will 938 * be <code>null</code> if the file has no parent (e.g. VOB root). 939 * Does not find parents of hard-linked names for the file. 940 */ 941 public static final PropertyName<CcFile> PARENT = 942 new PropertyName<CcFile>(PROPERTY_NAMESPACE, "cc-parent"); 943 944 /** 945 * Get the value of the {@link #PARENT} property. 946 * @return A CcFile proxy for the parent, null if no parent 947 * @throws WvcmException 948 */ 949 public CcFile getParent() throws WvcmException; 950 951 /** 952 * <p>If this file is actually a symbolic link, the path to its target file 953 * or directory. The path is interpreted relative to this file's parent 954 * directory.</p> 955 * 956 * <p>If this file is not a symbolic link, this value will be 957 * <code>null</code>.</p> 958 */ 959 PropertyName<String> SYMLINK_TARGET_PATH = 960 new PropertyName<String>(PROPERTY_NAMESPACE, "symlink-target-path"); 961 962 /** 963 * Get the value of this resource's {@link #SYMLINK_TARGET_PATH} property. 964 * @return path to symlink's target file or directory, or <code>null</code> 965 * if this file is not a symbolic link. 966 * @throws WvcmException if property was not requested 967 */ 968 public String getSymlinkTargetPath() throws WvcmException; 969 970 /** 971 * The view-relative path for this resource. 972 */ 973 PropertyName<String> VIEW_RELATIVE_PATH = 974 new PropertyName<String>(PROPERTY_NAMESPACE, "cr-view-relative-path"); 975 976 /** 977 * Get the value of this resource's {@link #VIEW_RELATIVE_PATH} property. 978 * @return view-relative path 979 * @throws WvcmException if property was not requested 980 */ 981 public String getViewRelativePath() throws WvcmException; 982 983 /** 984 * The CC version resource associated with this file. 985 * The value of this property will be null if this is not a version- 986 * controlled resource. 987 * @see javax.wvcm.ControllableResource#CHECKED_IN and 988 * javax.wvcm.ControllableResource#CHECKED_OUT 989 */ 990 PropertyName<CcVersion> VERSION = 991 new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "version"); 992 993 /** 994 * Get the value of this resource's {@link #VERSION} property. 995 * @return this file's version, or <code>null</code> if this file is 996 * not version controlled 997 * @throws WvcmException if property was not requested 998 */ 999 public CcVersion getVersion() throws WvcmException; 1000 1001 /** 1002 * The OID of the CC version resource associated with this file. 1003 * The value of this property will be null if this is not a version- 1004 * controlled resource. 1005 */ 1006 PropertyName<String> VERSION_OID = 1007 new PropertyName<String>(PROPERTY_NAMESPACE, "version-oid"); 1008 1009 /** 1010 * Get the value of this resource's {@link #VERSION_OID} property. 1011 * @return this file's version oid, or <code>null</code> if this file is 1012 * not version controlled 1013 * @throws WvcmException if property was not requested 1014 */ 1015 public String getVersionOid() throws WvcmException; 1016 1017 /** 1018 * The tag of the VOB in which this file resides. 1019 */ 1020 PropertyName<CcVobTag> VOB_TAG = 1021 new PropertyName<CcVobTag>(PROPERTY_NAMESPACE, "file-vob-tag"); 1022 1023 /** 1024 * Get the value of this resource's {@link #VOB_TAG} property. 1025 * @return the VOB tag for this file's VOB as a CcVobTag proxy, 1026 * or <code>null</code> if this file is not version controlled 1027 * @throws WvcmException if property was not requested 1028 */ 1029 public CcVobTag getVobTag() throws WvcmException; 1030 1031 /** 1032 * The CC element resource associated with this file. 1033 * The value of this property will be null if this is not a version- 1034 * controlled resource. 1035 * @see javax.wvcm.ControllableResource#VERSION_HISTORY 1036 */ 1037 PropertyName<CcElement> ELEMENT = 1038 new PropertyName<CcElement>(PROPERTY_NAMESPACE, "element"); 1039 1040 /** 1041 * Get the value of this resource's {@link #ELEMENT} property. 1042 * @return this file's element, or <code>null</code> if this file is 1043 * not version controlled 1044 * @throws WvcmException if property was not requested 1045 */ 1046 public CcElement getElement() throws WvcmException; 1047 1048 /** 1049 * Returns a {@link java.io.File File} representing the location of this 1050 * client-side resource in the local file system, else <code>null</code> if 1051 * this resource is a server-side resource only, e.g., if it is a proxy 1052 * to an unloaded file in a web view. 1053 * @return The location of this resource in the local file system, else 1054 * <code>null</code> if this is a proxy to a server-side resource only. 1055 * 1056 * @throws WvcmException Thrown if there was an error in determining the 1057 * path for this client-side Resource. 1058 */ 1059 File clientResourceFile() throws WvcmException; 1060 1061 /** 1062 * Reads the file's properties, if they are available locally on the client machine. 1063 * @param feedback the properties to be available in the returned proxy, 1064 * and any other feedback desired, such as progress indications. 1065 * @return a {@link CcFile} containing the wanted properties 1066 * that are available locally on the client machine 1067 * without communicating with the server. 1068 * Note that there is an exception to this for automatic views, where a request to 1069 * a connected automatic view may result in server communication to update local 1070 * cached data. 1071 * @see Resource#doReadProperties(Feedback) doReadProperties. 1072 * @throws WvcmException ReasonCode: 1073 * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}: 1074 * The file MUST be available locally on the client machine. 1075 */ 1076 CcFile readProperties(Feedback feedback) throws WvcmException; 1077 1078 /** 1079 * Reads the file's content, if it is available locally on the client machine. 1080 * @see Resource#doReadContent(OutputStream,Feedback) doReadContent 1081 * @param feedback the properties to be available in the returned proxy, 1082 * and any other feedback desired, such as progress indications. 1083 * @param content the file's content, if available, is written to this 1084 * byte stream. The stream is then closed. 1085 * @return a CcFile proxy containing the wanted properties 1086 * that are available on the client host without communicating with the server. 1087 * Note that there is an exception to this for automatic views, where a request to 1088 * a connected automatic view may result in server communication to update local 1089 * cached data. 1090 * @throws WvcmException ReasonCode: 1091 * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}: 1092 * The file MUST be available locally on the client machine. 1093 */ 1094 CcFile readContent(OutputStream content, Feedback feedback) throws WvcmException; 1095 1096 /** 1097 * Resolve this file resource, but do not consult the ClearCase server. 1098 * Unlike {@link CcResource#doResolve()}, use only information currently 1099 * available information on the local client machine. 1100 * @see CcResource#doResolve() 1101 * @return a new file proxy of the correct, most specific resource type 1102 * @throws WvcmException with NOT_FOUND reason code if this file does not 1103 * exist on the local machine. 1104 */ 1105 CcFile resolve() throws WvcmException; 1106 1107 /** 1108 * Whether this file is loaded, partially loaded, or not loaded in 1109 * the file area in which it resides. 1110 */ 1111 PropertyName<LoadState> LOAD_STATE = 1112 new PropertyName<LoadState>(PROPERTY_NAMESPACE, "load-state"); 1113 1114 /** 1115 * Get the value of this resource's {@link #LOAD_STATE} property. 1116 * @return LoadState.LOADED, LoadState.PARTIALLY_LOADED or LoadState.NOT_LOADED 1117 * @throws WvcmException 1118 * if this proxy doesn't define a value for this property. 1119 */ 1120 LoadState getLoadState() throws WvcmException; 1121 1122 /** 1123 * <p>Version controlled files and directories in a web view 1124 * may have both client state - 1125 * state maintained in a local file area - and server state. When the 1126 * client state and server state get out of sync, we call this <i>skew</i>. 1127 * </p> 1128 * <p>By definition, skew cannot occur in a dynamic or snapshot view. 1129 * </p> 1130 * <p>The caller can detect skew by including the {@link #SKEWED_PROPERTY_LIST} 1131 * property in property requests to <code>doReadProperties()</code> and 1132 * other <code>do</code> methods that accept property requests. 1133 * 1134 * The resulting value of this property is the list of property names 1135 * in the request that differed between the client and the server for this 1136 * particular file or directory. 1137 * </p> 1138 * <p>Note that only certain properties are checked for skew - properties 1139 * where skew can cause significant problems. For example, 1140 * {@link #IS_CHECKED_OUT}, {@link #IS_VERSION_CONTROLLED}, and 1141 * {@link #VERSION_OID}. 1142 * 1143 * Note that skew can also be caused by elementness skew (file vs dir) and 1144 * loadness skew (loaded vs unloaded). 1145 * </p> 1146 * <p>Note also that <i>only</i> properties in the current property request 1147 * are checked for skew. 1148 * </p> 1149 * <p>NOTE: This should be used only as a trigger to do a real discordance 1150 * scan of the directory. These values are not reliable enough to use for 1151 * icon decoration or user messages. This is a quick and easy way to 1152 * automatically detect skew, but it does not cover all edge cases 1153 * (symlinks, aliases, and others) or discordance types. 1154 * </p> 1155 */ 1156 PropertyName<List<PropertyName>> SKEWED_PROPERTY_LIST = 1157 new PropertyName<List<PropertyName>>(PROPERTY_NAMESPACE, "skewed-property-list"); 1158 1159 /** 1160 * Get the value of this file's {@link #SKEWED_PROPERTY_LIST} property. 1161 * 1162 * NOTE: This should be used only as a trigger to do a real discordance 1163 * scan of the directory. These values are not reliable enough to use for 1164 * icon decoration or user messages. This is a quick and easy way to 1165 * automatically detect skew, but it does not cover all edge cases 1166 * (symlinks, aliases, and others) or discordance types. 1167 * 1168 * @return a list of property names in the current property request whose 1169 * values differed between the client and the server for this file 1170 * or directory. 1171 * @throws WvcmException 1172 * if this proxy doesn't define a value for this property. 1173 */ 1174 List<PropertyName> getSkewedPropertyList() throws WvcmException; 1175 1176 /** 1177 * The config spec rule that selects this file. 1178 */ 1179 PropertyName<String> SELECTION_RULE = 1180 new PropertyName<String>(PROPERTY_NAMESPACE, "selection-rule"); 1181 1182 /** 1183 * Get the value of this resource's {@link #SELECTION_RULE} property. 1184 * @return this file's config spec rule, as a string. 1185 * @throws WvcmException 1186 * if this proxy doesn't define a value for this property. 1187 */ 1188 String getSelectionRule() throws WvcmException; 1189 1190 /** 1191 * The version of this file that is currently the latest on the same branch. 1192 */ 1193 PropertyName<CcVersion> LATEST_VERSION_ON_BRANCH = 1194 new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "latest-version-on-branch"); 1195 1196 /** 1197 * Get the value of this resource's {@link #LATEST_VERSION_ON_BRANCH} property. 1198 * @return the version of this file that is the latest on the same branch as the 1199 * version in the view. 1200 * @throws WvcmException 1201 * if this proxy doesn't define a value for this property. 1202 */ 1203 CcVersion getLatestVersionOnBranch() throws WvcmException; 1204 }