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