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