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