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