001 /* 002 * file CcFile.java 003 * 004 * Licensed Materials - Property of IBM 005 * Restricted Materials of IBM 006 * 007 * com.ibm.rational.wvcm.stp.cc.CcFile 008 * 009 * © Copyright IBM Corporation 2004, 2008. All Rights Reserved. 010 * Note to U.S. Government Users Restricted Rights: Use, duplication or 011 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp. 012 */ 013 package com.ibm.rational.wvcm.stp.cc; 014 015 import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE; 016 import static com.ibm.rational.wvcm.stpex.StpExBase.STP_NAMESPACE; 017 018 import java.io.File; 019 import java.io.OutputStream; 020 import java.util.List; 021 022 import javax.wvcm.ControllableResource; 023 import javax.wvcm.Feedback; 024 import javax.wvcm.Resource; 025 import javax.wvcm.WvcmException; 026 import javax.wvcm.PropertyNameList.PropertyName; 027 028 import com.ibm.rational.wvcm.stpex.StpExBase; 029 import com.ibm.rational.wvcm.stpex.StpExEnumeration; 030 031 /** 032 * A proxy for a file, directory, or symbolic link resource in a ClearCase view. 033 * This resource is either under version control or could potentially be 034 * put under version control. 035 */ 036 public interface CcFile 037 extends CcResource, ControllableResource 038 { 039 /** Flags for the doApplyLabel method */ 040 enum ApplyLabelFlag implements StpExEnumeration { 041 042 /** 043 * Replace existing label instance. 044 */ 045 REPLACE("replace"), 046 047 /** 048 * Apply label recursively over sub-tree. 049 */ 050 RECURSE("recurse"), 051 052 /** 053 * Follow symbolic links 054 */ 055 FOLLOW_SYMLINKS("follow-symlinks"); 056 057 private String m_name; 058 059 private ApplyLabelFlag(String name) { m_name = name; } 060 061 /* (non-Javadoc) 062 * @see java.lang.Object#toString() 063 */ 064 public String toString() { return m_name; } 065 } 066 067 /** Flags for the doRemoveLabel method */ 068 enum RemoveLabelFlag implements StpExEnumeration { 069 070 /** 071 * Remove label recursively over sub-tree. 072 */ 073 RECURSE("recurse"), 074 075 /** 076 * Follow symbolic links 077 */ 078 FOLLOW_SYMLINKS("follow-symlinks"); 079 080 private String m_name; 081 082 private RemoveLabelFlag(String name) { m_name = name; } 083 084 /* (non-Javadoc) 085 * @see java.lang.Object#toString() 086 */ 087 public String toString() { return m_name; } 088 } 089 090 /** Flags for the doUncheckout method */ 091 enum UncheckoutFlag implements StpExEnumeration { 092 /** 093 * Preserve changes in checked out version in a ".keep" file. 094 */ 095 KEEP("keep"); 096 097 private String m_name; 098 099 private UncheckoutFlag(String name) { m_name = name; } 100 101 /* (non-Javadoc) 102 * @see java.lang.Object#toString() 103 */ 104 public String toString() { return m_name; } 105 } 106 107 /** Flags for the doUnhijack method */ 108 enum UnhijackFlag implements StpExEnumeration { 109 110 /** 111 * Preserve changes in hijacked version in a ".keep" file. 112 */ 113 KEEP("keep"); 114 115 private UnhijackFlag(String name) { m_name = name; } 116 117 /* (non-Javadoc) 118 * @see java.lang.Object#toString() 119 */ 120 public String toString() { return m_name; } 121 122 private String m_name; 123 } 124 125 /** 126 * Flags for the <code>doRefresh</code> and <code>doRestore</code> methods. 127 */ 128 enum RefreshFlag implements StpExEnumeration { 129 130 /** 131 * Do <i>not</i> refresh hijacked files. 132 * Leave hijacked files in the hijacked state, and do not alter 133 * their contents. 134 * <p> 135 * Note: a deleted file or directory is considered to be hijacked. 136 * In order to refresh or restore a deleted file or directory, 137 * you must specify <code>OVERWRITE_HIJACKS</code> or 138 * <code>RENAME_HIJACKS</code>. 139 * </p> 140 * This is the default hijack behavior for both <code>doRefresh</code> 141 * and <code>doRestore</code>. 142 */ 143 KEEP_HIJACKS("keep-hijacks"), 144 145 /** 146 * If a file being refreshed is hijacked in this view, 147 * overwrite the hijacked contents with the new version's contents. 148 * Do not preserve the hijacked contents. 149 */ 150 OVERWRITE_HIJACKS("overwrite-hijacks"), 151 152 /** 153 * If a file being refreshed is hijacked in this view, 154 * preserve the hijacked contents by moving the hijacked file to 155 * <code><file-name>.keep</code>. 156 */ 157 RENAME_HIJACKS("rename-hijacks"), 158 159 /** 160 * When refreshing a file to a different version, set the file's 161 * "last modified" time to be the time when the version was created. 162 * By default, a refreshed file's "last modified" time will simply be 163 * the time when the <code>doRefresh</code> was performed. 164 */ 165 PRESERVE_CREATION_TIME("preserve-creation-time"), 166 167 /** 168 * Preview the refresh operation, but don't actually perform it. 169 * Invoke the caller's feedback methods to inform them what the 170 * refresh would do if it were performed right now. 171 */ 172 PREVIEW_ONLY("preview-only"); 173 174 private String m_name; 175 176 private RefreshFlag(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 184 /** Flags for the <code>doCheckout</code> method. */ 185 enum CcCheckoutFlag implements StpExEnumeration { 186 187 /** 188 * Indicates whether to checkout this file reserved. 189 */ 190 RESERVED("reserved"), 191 192 /** 193 * Fall back to unreserved if a reservation can not be obtained. 194 */ 195 FALLBACK_TO_UNRESERVED("fallback-to-unreserved"), 196 197 /** 198 * Checkout the version of the file that is currently loaded in the 199 * view, even if that version is not the version selected by the 200 * view's config spec. 201 * 202 * <p>If the loaded version is not the version selected by the view's 203 * config spec, and neither {@link #LOADED_NOT_LATEST} nor 204 * {@link #LATEST_NOT_LOADED} flags are set, the checkout operation 205 * will throw an exception with reason code <code>CHECKOUT_NOT_LATEST</code>. 206 */ 207 LOADED_NOT_LATEST("checkout-loaded-not-latest"), 208 209 /** 210 * Checkout the version of the file that is selected by the view's 211 * config spec. If this version is not loaded at checkout time, then 212 * load it prior to performing the checkout. 213 * 214 * <p>If the loaded version is not the version selected by the view's 215 * config spec, and neither {@link #LOADED_NOT_LATEST} nor 216 * {@link #LATEST_NOT_LOADED} flags are set, the checkout operation 217 * will throw an exception with reason code <code>CHECKOUT_NOT_LATEST</code>. 218 */ 219 LATEST_NOT_LOADED("checkout-latest-not-loaded"), 220 221 /** 222 * Indicates whether to checkout this file even if the currently 223 * selected branch is mastered by another replica. The 224 * <code>RESERVED</code> flag must NOT be set with this flag. 225 * 226 * <p>If the file is mastered by this replica, setting this 227 * flag has no effect. 228 */ 229 NON_MASTERED_OK("non-mastered-ok"), 230 231 /** 232 * If the file is hijacked, keep the hijacked contents upon checkout. 233 */ 234 PRESERVE_HIJACK_CONTENTS("preserve-hijack-contents"); 235 236 private String m_name; 237 238 private CcCheckoutFlag(String name) { m_name = name; } 239 240 /* (non-Javadoc) 241 * @see java.lang.Object#toString() 242 */ 243 public String toString() { return m_name; } 244 } 245 246 /** Values for file or directory load state */ 247 enum LoadState implements StpExEnumeration { 248 249 /** 250 * This file or directory is loaded in its file area. 251 */ 252 LOADED, 253 254 /** 255 * This directory is partially loaded in its file area, i.e., 256 * some but not all of its children are loaded. 257 */ 258 PARTIALLY_LOADED, 259 260 /** 261 * This file or directory is not loaded in its file area. 262 */ 263 NOT_LOADED; 264 } 265 266 /** 267 * Create a new view-private file at the location specified by this resource. 268 * The request will fail if a resource already exists at that location. 269 * @param feedback 270 * @return a CcFile proxy for the new file 271 * @see javax.wvcm.ControllableResource#doCreateResource(Feedback) 272 */ 273 public CcFile createCcFile(Feedback feedback) throws WvcmException; 274 275 /** 276 * Apply the specified label to the checked-in version of this controllable resource. 277 * @param flags array of flags which specify the behavior of the operation 278 * @param label the label to be added to this version 279 * @param feedback 280 * @return A new proxy for this resource, whose properties are specified by feedback. 281 * @throws WvcmException 282 */ 283 ControllableResource doApplyLabel(ApplyLabelFlag[] flags, String label, Feedback feedback) 284 throws WvcmException; 285 286 /** 287 * Remove the specified label from the checked-in version of this controllable resource. 288 * @param flags array of flags which specify the behavior of the operation 289 * @param label the label to be removed from this version 290 * @param feedback 291 * @return A new proxy for this resource, whose properties are specified by feedback. 292 * @throws WvcmException 293 */ 294 ControllableResource doRemoveLabel(RemoveLabelFlag[] flags, String label, Feedback feedback) 295 throws WvcmException; 296 297 /** 298 * <p>Check out this version-controlled file or directory resource. 299 * The resource is checked out to the ClearCase view implied by its location. 300 * </p> 301 * <p>If the view is a UCM view, the caller must insure there is a 302 * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation. 303 * The checked out file will be added to the current activity's change set. 304 * The caller may explicitly specify an activity using this resource's 305 * {@link javax.wvcm.ControllableResource#setActivity} method. In that case, 306 * the specified activity will become the new current activity. 307 * Otherwise, the existing current activity will be used. 308 * If the view is a UCM view and there is no current activity, the operation 309 * will fail. 310 * </p> 311 * <p>The caller may optionally specify a checkout comment using this 312 * resource's {@link javax.wvcm.Resource#setComment} method. 313 * </p> 314 * @param flags array of flags which specify the behavior of the operation 315 * @param feedback 316 * @return new CcFile proxy representing the checked out file. 317 * @throws WvcmException 318 */ 319 CcFile doCcCheckout(CcCheckoutFlag[] flags, Feedback feedback) 320 throws WvcmException; 321 322 /** 323 * Cancel the checkout of this version-controlled resource, 324 * and restore its content to the state of its CHECKED_IN version. 325 * @param flags array of flags which specify the behavior of the operation 326 * @param feedback 327 * @return new CcFile proxy representing the file whose checkout has been canceled 328 * @throws WvcmException 329 * @see javax.wvcm.ControllableResource#doUncheckout 330 */ 331 CcFile doUncheckout(UncheckoutFlag[] flags, Feedback feedback) 332 throws WvcmException; 333 334 /** 335 * <p>Check in this checked out file or directory resource. 336 * </p> 337 * <p>If this resource is in a UCM view, it was added to an activity's 338 * change set at checkout time. The caller may specify an alternate 339 * change set using this resource's 340 * {@link javax.wvcm.ControllableResource#setActivity} method just before 341 * calling <code>doCheckin</code>. 342 * </p> 343 * <p>The caller may also specify a checkin comment using this 344 * resource's {@link javax.wvcm.Resource#setComment} method. 345 * This will override the comment specified at checkout time, if any. 346 * </p> 347 * @param flags array of flags which specify the behavior of the operation 348 * @param feedback 349 * @return new ControllableResource proxy representing the checked in file. 350 * @throws WvcmException 351 * @see javax.wvcm.ControllableResource#doCheckin 352 * @see com.ibm.rational.wvcm.stp.cc.CcFile#doCheckout 353 */ 354 ControllableResource doCheckin(CheckinFlag[] flags, Feedback feedback) 355 throws WvcmException; 356 357 /** 358 * Places the view-private file specified by this proxy under version control. 359 * <p>If the view is a UCM view, the caller must insure there is a 360 * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation. 361 * The newly version controlled file will be added to the current activity's change set. 362 * The caller may explicitly specify an activity using this resource's 363 * {@link javax.wvcm.ControllableResource#setActivity} method. In that case, 364 * the specified activity will become the new current activity. 365 * Otherwise, the existing current activity will be used. 366 * If the view is a UCM view and there is no current activity, the operation 367 * will fail. 368 * </p> 369 * <p>The caller may optionally specify a creation comment using this 370 * resource's {@link javax.wvcm.Resource#setComment} method. 371 * </p> 372 * @param feedback 373 * @return new ControllableResource proxy representing the version controlled file. 374 * @throws WvcmException 375 * @see javax.wvcm.ControllableResource#doVersionControl 376 */ 377 ControllableResource 378 doVersionControl(Feedback feedback) 379 throws WvcmException; 380 381 /** 382 * <p> 383 * Refresh this file or directory. Re-evaluate the 384 * view's config spec and update resources on the client to be whatever 385 * is currently selected by the config spec. If this is a directory, 386 * recursively refresh its contents. 387 * </p> 388 * <p> 389 * Example: The config spec says "element * /main/LATEST", and you 390 * have version "/main/7" of this resource loaded. Someone else checks 391 * in a new version, thus creating a "/main/8". In that case, 392 * doRefresh() will cause version "/main/8" of this resource to 393 * be loaded into your view. 394 * </p> 395 * <p> 396 * Preconditions: This resource must be a version-controlled file 397 * or directory. 398 * </p> 399 * <p> 400 * Postconditions: This resource (and its descendants if this is a 401 * directory) are updated to be what is currently selected by the view's 402 * config spec. 403 * </p> 404 * @param flags array of flags which specify the behavior of the operation 405 * @param feedback a list of properties to fetch on the 406 * updated resources. The resources returned by the iterator returned 407 * by doRefresh will have these properties filled in. 408 * @return a new CcFile proxy representing the refreshed file 409 * @throws WvcmException if the precondition is not met or if an error 410 */ 411 CcFile doRefresh(RefreshFlag[] flags, Feedback feedback) 412 throws WvcmException; 413 414 /** 415 * <p> 416 * Restore this file or directory. If this is a directory, recursively 417 * restore its contents. This repairs any damage to the portion of the file 418 * area database specified by this resource. 419 * </p> 420 * 421 * @param flags array of flags which specify the behavior of the operation 422 * @param feedback 423 * @return a new CcFile proxy representing the restored file 424 * @throws WvcmException 425 */ 426 CcFile doRestore(RefreshFlag[] flags, Feedback feedback) 427 throws WvcmException; 428 429 /** 430 * <p> 431 * Load this controllable resource into the view's local file area. 432 * If this is a controllable folder, loads the tree of controllable 433 * resources under this folder. 434 * Also updates the view's load rules if necessary 435 * to include this file or folder. 436 * </p> 437 * <p> 438 * If this resource was already loaded, doLoad is a no-op. 439 * </p> 440 * <p> 441 * Preconditions: This must be a version-controlled file or folder 442 * in a web view. 443 * </p> 444 * <p> 445 * Postconditions: This file, or the tree of files under this folder, 446 * is loaded into the web view. Thus, the file(s) appear, and the view's 447 * load rules are updated to include this file or folder. 448 * </p> 449 * @param feedback (optional) feedback's notifyIsModified() method will be 450 * called for each file or directory as it is loaded 451 * @return a new CcFile proxy for the file that has been loaded 452 * @throws WvcmException 453 */ 454 CcFile doLoad(Feedback feedback) throws WvcmException; 455 456 /** 457 * Hijack this controllable resource. 458 * Make the resource writable and set its "last modified" time to the 459 * current time. This operation does <i>not</i> contact the server. 460 * @param feedback 461 * @return a new CcFile proxy for the hijacked file 462 * @throws WvcmException 463 */ 464 CcFile hijack(Feedback feedback) 465 throws WvcmException; 466 467 /** 468 * Undo a hijack on this hijacked controllable resource. Reload the file's 469 * contents from the appropriate version on the server. 470 * @param flags Specify <code>KEEP</code> to save a copy of the hijacked 471 * file's contents in a ".keep" file before undoing the hijack. 472 * @param feedback 473 * @return a new CcFile proxy for the unhijacked file 474 * @throws WvcmException 475 */ 476 CcFile doUnhijack(UnhijackFlag[] flags, Feedback feedback) 477 throws WvcmException; 478 479 /** 480 * For client resources, identifies the file system path to the local file 481 * representing this controllable resource. 482 */ 483 PropertyName<File> CLIENT_PATH = 484 new PropertyName<File>(StpExBase.STP_NAMESPACE, "client-path"); 485 486 /** 487 * Returns the value of this proxy's {@link #CLIENT_PATH} property. 488 * @return The path to this ControllableResource in the local file area. 489 * Will never be <code>null</code>. 490 * @throws WvcmException if requested of a ControllableResource without client state 491 */ 492 File getClientPath() throws WvcmException; 493 494 /** 495 * For version-controlled resources, this resource's element type. 496 */ 497 PropertyName<CcElementType> ELEMENT_TYPE = 498 new PropertyName<CcElementType>(STP_NAMESPACE, "element-type"); 499 500 /** 501 * Returns the value of this proxy's {@link #ELEMENT_TYPE} property. 502 * @return This resource's element type. Will be <code>null</code> 503 * if resource is not version-controlled. 504 * @throws WvcmException if this proxy doesn't define a value for this property. 505 */ 506 CcElementType getElementType() throws WvcmException; 507 508 /** 509 * Set the value of this file or directory's {@link #ELEMENT_TYPE} property. 510 * This property can only be set just prior to calling doVersionControl() 511 * on the resource. 512 * @param eltype resource's desired element type 513 */ 514 void setElementType(CcElementType eltype); 515 516 /** 517 * Is this file a file area database file? File area DB files require 518 * special treatment. For instance, they cannot be source controlled. 519 * For this reason, applications may choose to hide these files from 520 * the end user. 521 */ 522 PropertyName<Boolean> IS_DB_FILE = 523 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-db-file"); 524 525 /** 526 * Get the value of this files {@link #IS_DB_FILE} property. 527 * @return true if this file is a file area database file, else false 528 * @throws WvcmException 529 * if this proxy doesn't define a value for this property. 530 */ 531 public boolean getIsDbFile() throws WvcmException; 532 533 /** 534 * Property which is true/false depending on whether this version-controlled 535 * resource has been hijacked. 536 */ 537 PropertyName<Boolean> IS_HIJACKED = 538 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-hijacked"); 539 540 /** 541 * Get the value of this file's {@link #IS_HIJACKED} property. 542 * @return true if the file is hijacked, false otherwise 543 * @throws WvcmException 544 * if this proxy doesn't define a value for this property. 545 */ 546 public boolean getIsHijacked() throws WvcmException; 547 548 /** 549 * Is this file actually a symbolic link? 550 */ 551 PropertyName<Boolean> IS_SYMLINK = 552 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-symlink"); 553 554 /** 555 * Get the value of the {@link #IS_SYMLINK} property. 556 * @return true if this resource is a symbolic link, false otherwise. 557 * @throws WvcmException 558 * if this proxy doesn't define a value for this property. 559 */ 560 public boolean getIsSymlink() throws WvcmException; 561 562 /** 563 * Returns the direct parent of this file. The value will 564 * be <code>null</code> if the file has no parent (e.g. VOB root). 565 * Does not find parents of hard-linked names for the file. 566 */ 567 public static final PropertyName<CcDirectory> PARENT = 568 new PropertyName<CcDirectory>(PROPERTY_NAMESPACE, "cc-parent"); 569 570 /** 571 * Get the value of the {@link #PARENT} property. 572 * @return A CcDirectory proxy for the parent, null if no parent 573 * @throws WvcmException 574 */ 575 public CcDirectory getParent() throws WvcmException; 576 577 /** 578 * <p>If this file is actually a symbolic link, the path to its target file 579 * or directory. The path is interpreted relative to this file's parent 580 * directory.</p> 581 * 582 * <p>If this file is not a symbolic link, this value will be 583 * <code>null</code>.</p> 584 */ 585 PropertyName<String> SYMLINK_TARGET_PATH = 586 new PropertyName<String>(PROPERTY_NAMESPACE, "symlink-target-path"); 587 588 /** 589 * Get the value of this resource's {@link #SYMLINK_TARGET_PATH} property. 590 * @return path to symlink's target file or directory, or <code>null</code> 591 * if this file is not a symbolic link. 592 * @throws WvcmException if property was not requested 593 */ 594 public String getSymlinkTargetPath() throws WvcmException; 595 596 /** 597 * The view-relative path for this resource. 598 */ 599 PropertyName<String> VIEW_RELATIVE_PATH = 600 new PropertyName<String>(PROPERTY_NAMESPACE, "cr-view-relative-path"); 601 602 /** 603 * Get the value of this resource's {@link #VIEW_RELATIVE_PATH} property. 604 * @return view-relative path 605 * @throws WvcmException if property was not requested 606 */ 607 public String getViewRelativePath() throws WvcmException; 608 609 /** 610 * The CC version resource associated with this file. 611 * The value of this property will be null if this is not a version- 612 * controlled resource. 613 * @see javax.wvcm.ControllableResource#CHECKED_IN and 614 * javax.wvcm.ControllableResource#CHECKED_OUT 615 */ 616 PropertyName<CcVersion> VERSION = 617 new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "version"); 618 619 /** 620 * Get the value of this resource's {@link #VERSION} property. 621 * @return this file's version, or <code>null</code> if this file is 622 * not version controlled 623 * @throws WvcmException if property was not requested 624 */ 625 public CcVersion getVersion() throws WvcmException; 626 627 /** 628 * The OID of the CC version resource associated with this file. 629 * The value of this property will be null if this is not a version- 630 * controlled resource. 631 */ 632 PropertyName<String> VERSION_OID = 633 new PropertyName<String>(PROPERTY_NAMESPACE, "version-oid"); 634 635 /** 636 * Get the value of this resource's {@link #VERSION_OID} property. 637 * @return this file's version oid, or <code>null</code> if this file is 638 * not version controlled 639 * @throws WvcmException if property was not requested 640 */ 641 public String getVersionOid() throws WvcmException; 642 643 /** 644 * The tag of the VOB in which this file resides. 645 */ 646 PropertyName<CcVobTag> VOB_TAG = 647 new PropertyName<CcVobTag>(PROPERTY_NAMESPACE, "file-vob-tag"); 648 649 /** 650 * Get the value of this resource's {@link #VOB_TAG} property. 651 * @return the VOB tag for this file's VOB as a CcVobTag proxy, 652 * or <code>null</code> if this file is not version controlled 653 * @throws WvcmException if property was not requested 654 */ 655 public CcVobTag getVobTag() throws WvcmException; 656 657 /** 658 * The CC element resource associated with this file. 659 * The value of this property will be null if this is not a version- 660 * controlled resource. 661 * @see javax.wvcm.ControllableResource#VERSION_HISTORY 662 */ 663 PropertyName<CcElement> ELEMENT = 664 new PropertyName<CcElement>(PROPERTY_NAMESPACE, "element"); 665 666 /** 667 * Get the value of this resource's {@link #ELEMENT} property. 668 * @return this file's element, or <code>null</code> if this file is 669 * not version controlled 670 * @throws WvcmException if property was not requested 671 */ 672 public CcElement getElement() throws WvcmException; 673 674 /** 675 * Returns a {@link java.io.File File} representing the location of this 676 * client-side Resource in the local file system, else <code>null</code> if 677 * this Resource is a server-side resource only. 678 * @return The location of this Resource in the local file system, else 679 * <code>null</code> if this is a proxy to a server-side resource only. 680 * 681 * @throws WvcmException Thrown if there was an error in determining the 682 * path for this client-side Resource. 683 */ 684 File clientResourceFile() throws WvcmException; 685 686 /** 687 * Reads the file's properties, if they are available locally on the client machine. 688 * @param feedback the properties to be available in the returned proxy, 689 * and any other feedback desired, such as progress indications. 690 * @return a {@link CcFile} containing the wanted properties 691 * that are available locally on the client machine 692 * without communicating with the server. 693 * @see Resource#doReadProperties(Feedback) doReadProperties. 694 * @throws WvcmException ReasonCode: 695 * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}: 696 * The file MUST be available locally on the client machine. 697 */ 698 CcFile readProperties(Feedback feedback) throws WvcmException; 699 700 /** 701 * Reads the file's content, if it is available locally on the client machine. 702 * @see Resource#doReadContent(OutputStream,Feedback) doReadContent 703 * @param feedback the properties to be available in the returned proxy, 704 * and any other feedback desired, such as progress indications. 705 * @param content the file's content, if available, is written to this 706 * byte stream. The stream is then closed. 707 * @return a CcFile proxy containing the wanted properties 708 * that are available on the client host without communicating with the server. 709 * @throws WvcmException ReasonCode: 710 * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}: 711 * The file MUST be available locally on the client machine. 712 */ 713 CcFile readContent(OutputStream content, Feedback feedback) throws WvcmException; 714 715 /** 716 * Resolve this file resource, but do not consult the ClearCase server. 717 * Unlike {@link CcResource#doResolve()}, use only information currently 718 * available information on the local client machine. 719 * @see CcResource#doResolve() 720 * @return a new file proxy of the correct, most specific resource type 721 * @throws WvcmException with NOT_FOUND reason code if this file does not 722 * exist on the local machine. 723 */ 724 CcFile resolve() throws WvcmException; 725 726 /** 727 * Whether this file is loaded, partially loaded, or not loaded in the 728 * file area in which it resides. 729 */ 730 PropertyName<LoadState> LOAD_STATE = 731 new PropertyName<LoadState>(PROPERTY_NAMESPACE, "load-state"); 732 733 /** 734 * Get the value of this resource's {@link #LOAD_STATE} property. 735 * @return LoadState.LOADED, LoadState.PARTIALLY_LOADED or LoadState.NOT_LOADED 736 * @throws WvcmException 737 * if this proxy doesn't define a value for this property. 738 */ 739 LoadState getLoadState() throws WvcmException; 740 741 /** 742 * <p>Version controlled files and directories may have both client state - 743 * state maintained in a local file area - and server state. When the 744 * client state and server state get out of synch, we call this <i>skew</i>. 745 * </p> 746 * <p>The caller can detect skew by including the {@link #SKEWED_PROPERTY_LIST} 747 * property in property requests to <code>doReadProperties()</code> and 748 * other <code>do</code> methods that accept property requests. 749 * The resulting value of this property is the list of names of properties 750 * in the request that differed between the client and the server for this 751 * particular file or directory. 752 * </p> 753 * <p>Note that only certain properties are checked for skew - properties 754 * where skew can cause significant problems. For example, 755 * {@link #IS_CHECKED_OUT}, {@link #IS_VERSION_CONTROLLED}, and 756 * {@link #VERSION_OID}. 757 * </p> 758 * <p>Note also that <i>only</i> properties in the current property request 759 * are checked for skew. 760 * </p> 761 */ 762 PropertyName<List<PropertyName>> SKEWED_PROPERTY_LIST = 763 new PropertyName<List<PropertyName>>(PROPERTY_NAMESPACE, "skewed-property-list"); 764 765 /** 766 * Get the value of this file's {@link #SKEWED_PROPERTY_LIST} property. 767 * @return a list of property names in the current property request whose 768 * values differed between the client and the server for this file 769 * or directory. 770 * @throws WvcmException 771 * if this proxy doesn't define a value for this property. 772 */ 773 List<PropertyName> getSkewedPropertyList() throws WvcmException; 774 775 /** 776 * The config spec rule that selects this file. 777 */ 778 PropertyName<String> SELECTION_RULE = 779 new PropertyName<String>(PROPERTY_NAMESPACE, "selection-rule"); 780 781 /** 782 * Get the value of this resource's {@link #SELECTION_RULE} property. 783 * @return this file's config spec rule, as a string. 784 * @throws WvcmException 785 * if this proxy doesn't define a value for this property. 786 */ 787 String getSelectionRule() throws WvcmException; 788 789 /** 790 * The version of this file that is currently the latest on the same branch. 791 */ 792 PropertyName<CcVersion> LATEST_VERSION_ON_BRANCH = 793 new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "latest-version-on-branch"); 794 795 /** 796 * Get the value of this resource's {@link #LATEST_VERSION_ON_BRANCH} property. 797 * @return the version of this file that is the latest on the same branch as the 798 * version in the view. 799 * @throws WvcmException 800 * if this proxy doesn't define a value for this property. 801 */ 802 CcVersion getLatestVersionOnBranch() throws WvcmException; 803 }