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, 2010. 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 sync, 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 *
890 * The resulting value of this property is the list of property names
891 * in the request that differed between the client and the server for this
892 * particular file or directory.
893 * </p>
894 * <p>Note that only certain properties are checked for skew - properties
895 * where skew can cause significant problems. For example,
896 * {@link #IS_CHECKED_OUT}, {@link #IS_VERSION_CONTROLLED}, and
897 * {@link #VERSION_OID}.
898 *
899 * Note that skew can also be caused by elementness skew (file vs dir) and
900 * loadness skew (loaded vs unloaded).
901 * </p>
902 * <p>Note also that <i>only</i> properties in the current property request
903 * are checked for skew.
904 * </p>
905 * <p>NOTE: This should be used only as a trigger to do a real discordance
906 * scan of the directory. These values are not reliable enough to use for
907 * icon decoration or user messages. This is a quick and easy way to
908 * automatically detect skew, but it does not cover all edge cases
909 * (symlinks, aliases, and others) or discordance types.
910 * </p>
911 */
912 PropertyName<List<PropertyName>> SKEWED_PROPERTY_LIST =
913 new PropertyName<List<PropertyName>>(PROPERTY_NAMESPACE, "skewed-property-list");
914
915 /**
916 * Get the value of this file's {@link #SKEWED_PROPERTY_LIST} property.
917 *
918 * NOTE: This should be used only as a trigger to do a real discordance
919 * scan of the directory. These values are not reliable enough to use for
920 * icon decoration or user messages. This is a quick and easy way to
921 * automatically detect skew, but it does not cover all edge cases
922 * (symlinks, aliases, and others) or discordance types.
923 *
924 * @return a list of property names in the current property request whose
925 * values differed between the client and the server for this file
926 * or directory.
927 * @throws WvcmException
928 * if this proxy doesn't define a value for this property.
929 */
930 List<PropertyName> getSkewedPropertyList() throws WvcmException;
931
932 /**
933 * The config spec rule that selects this file.
934 */
935 PropertyName<String> SELECTION_RULE =
936 new PropertyName<String>(PROPERTY_NAMESPACE, "selection-rule");
937
938 /**
939 * Get the value of this resource's {@link #SELECTION_RULE} property.
940 * @return this file's config spec rule, as a string.
941 * @throws WvcmException
942 * if this proxy doesn't define a value for this property.
943 */
944 String getSelectionRule() throws WvcmException;
945
946 /**
947 * The version of this file that is currently the latest on the same branch.
948 */
949 PropertyName<CcVersion> LATEST_VERSION_ON_BRANCH =
950 new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "latest-version-on-branch");
951
952 /**
953 * Get the value of this resource's {@link #LATEST_VERSION_ON_BRANCH} property.
954 * @return the version of this file that is the latest on the same branch as the
955 * version in the view.
956 * @throws WvcmException
957 * if this proxy doesn't define a value for this property.
958 */
959 CcVersion getLatestVersionOnBranch() throws WvcmException;
960 }