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, 2016. 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 * For dynamic views only.
334 *
335 * <p>Checkout the version of the file that is the latest on the branch
336 * even if that version is not currently selected by the view.
337 *
338 * <p>If the version selected by the view's config spec is not the latest
339 * on the branch and neither {@link #LATEST_ON_BRANCH} nor
340 * {@link #VIEW_SELECTED_VERSION} flags are specified, the checkout
341 * operation will will throw an exception with reason code
342 * <code>CHECKOUT_NOT_LATEST</code>.
343 */
344 LATEST_ON_BRANCH("latest-on-branch"),
345
346 /**
347 * Indicates whether to checkout this file even if the currently
348 * selected branch is mastered by another replica. The
349 * <code>RESERVED</code> flag must NOT be set with this flag.
350 *
351 * <p>If the file is mastered by this replica, setting this
352 * flag has no effect.
353 */
354 NON_MASTERED_OK("non-mastered-ok"),
355
356 /**
357 * If the file is hijacked, keep the hijacked contents upon checkout.
358 */
359 PRESERVE_HIJACK_CONTENTS("preserve-hijack-contents"),
360
361 /**
362 * After a file is 'checkedout', set the file's "last modified"
363 * time to be the time when the version was first created.
364 * <p>This applies only to automatic, dynamic and snapshot views.
365 */
366 PRESERVE_MODIFICATION_TIME("preserve-modification-time"),
367
368 /**
369 * For dynamic views only.
370 *
371 * <p>Checkout the version of the file that is currently selected by
372 * the view, even if that version is not the latest on the branch.
373 *
374 * <p>If the version selected by the view's config spec is not the latest
375 * on the branch and neither {@link #LATEST_ON_BRANCH} nor
376 * {@link #VIEW_SELECTED_VERSION} flags are specified, the checkout
377 * operation will will throw an exception with reason code
378 * <code>CHECKOUT_NOT_LATEST</code>.
379 */
380 VIEW_SELECTED_VERSION("view-selected-version");
381
382 private String m_name;
383
384 private CcCheckoutFlag(String name) { m_name = name; }
385
386 /* (non-Javadoc)
387 * @see java.lang.Object#toString()
388 */
389 public String toString() { return m_name; }
390 }
391
392 /** Flags for the <code>doCcVersionControl</code> method. */
393 enum CcVersionControlFlag implements StpExEnumeration {
394
395 /**
396 * Indicates whether to checkin this file after it is added to version control.
397 * The default is to leave it checked out.<p>
398 * This flag is mutually exclusive with {@link CcVersionControlFlag#NO_CHECKOUT}.
399 */
400 CHECKIN("checkin"),
401
402 /**
403 * Do not checkout the file after adding to version control.<p>
404 * This flag is mutually exclusive with {@link CcVersionControlFlag#CHECKIN}.
405 */
406 NO_CHECKOUT("no-checkout"),
407
408 /**
409 * Assigns mastership of the <b>main</b> branch of the newly version controlled
410 * file to the VOB replica in which you execute operation. By default
411 * mastership of the file's <b>main</b> branch is assigned to the VOB replica
412 * that masters the <b>main</b> branch type. <p>
413 * This flag is mutually exclusive with {@link CcVersionControlFlag#MAKE_PATH}.
414 */
415 MASTER_LOCALLY("master-locally"),
416
417 /**
418 * Automatically checkout the version controlled parent directory and
419 * check back in after new file has been added to version control.
420 * Any view private parent directories below the version controlled parent
421 * and the desired file, will also be version controlled.<p>
422 * This flag is mutually exclusive with {@link CcVersionControlFlag#MASTER_LOCALLY}.
423 */
424 MAKE_PATH("mkpath");
425
426 private String m_name;
427
428 private CcVersionControlFlag(String name) { m_name = name; }
429
430 /* (non-Javadoc)
431 * @see java.lang.Object#toString()
432 */
433 public String toString() { return m_name; }
434 }
435
436 /** Values for file or directory load state */
437 enum LoadState implements StpExEnumeration {
438
439 /**
440 * This file or directory is loaded in its file area.
441 */
442 LOADED,
443
444 /**
445 * This directory is partially loaded in its file area, i.e.,
446 * some but not all of its children are loaded.
447 */
448 PARTIALLY_LOADED,
449
450 /**
451 * This file or directory is not loaded in its file area.
452 */
453 NOT_LOADED;
454 }
455
456 /**
457 * Create a new view-private file at the location specified by this resource.
458 * The request will fail if a resource already exists at that location.
459 * @param feedback
460 * @return a CcFile proxy for the new file
461 * @see javax.wvcm.ControllableResource#doCreateResource(Feedback)
462 */
463 public CcFile createCcFile(Feedback feedback) throws WvcmException;
464
465 /**
466 * Apply the specified attribute to the checked-in version of this controllable resource.
467 * @param flags array of flags which specify the behavior of the operation
468 * @param comment Comment (if any) to be used for operation. Empty string if none.
469 * @param attributeName Name of an existing attribute type to be used to create
470 * an instance will to be applied to this resource.
471 * @param attributeValue Value of attribute instance. If the vtype of the attribute type is
472 * a string, it must be enclosed in additional quotes <em>within the string</em>. For example, if
473 * specified as a constant it would appear as <code>"\"string value\""</code>. If the
474 * vtype is not a string, this should be a string representation of the given value
475 * (e.g. <code>"3.1415"</code>, <code>"0xa413"</code>, etc.).
476 * @param versionId Applies the attribute to the explicitly specified version,
477 * overriding the version selected by the view.
478 * This string must only represent the version suffix (e.g. /main/314).
479 * @param feedback
480 * @return A new proxy for this resource, whose properties are specified by feedback.
481 * @throws WvcmException
482 */
483 ControllableResource doApplyAttribute(AttributeOpFlag[] flags, String comment,
484 String attributeName, String attributeValue, String versionId, Feedback feedback)
485 throws WvcmException;
486
487 /**
488 * Remove the specified attribute from the checked-in version of this controllable resource.
489 * @param flags array of flags which specify the behavior of the operation
490 * @param comment Comment (if any) to be used for operation. Empty string if none.
491 * @param attributeName Name of the attribute to be removed from this resource
492 * @param versionId Removes the attribute from the explicitly specified version,
493 * overriding the version selected by the view.
494 * @param feedback
495 * @return A new proxy for this resource, whose properties are specified by feedback.
496 * @throws WvcmException
497 */
498 ControllableResource doRemoveAttribute(AttributeOpFlag[] flags, String comment,
499 String attributeName, String versionId, Feedback feedback)
500 throws WvcmException;
501
502 /**
503 * Apply the specified label to the checked-in version of this controllable resource.
504 * @param flags array of flags which specify the behavior of the operation
505 * @param label the label to be added to this version
506 * @param feedback
507 * @return A new proxy for this resource, whose properties are specified by feedback.
508 * @throws WvcmException
509 */
510 ControllableResource doApplyLabel(ApplyLabelFlag[] flags,
511 String label, Feedback feedback)
512 throws WvcmException;
513
514 /**
515 * Apply the specified label to the checked-in version of this controllable resource.
516 * @param flags array of flags which specify the behavior of the operation
517 * @param comment The comment for this operation, or null for no comment
518 * @param label the label to be added to this version
519 * @param feedback
520 * @return A new proxy for this resource, whose properties are specified by feedback.
521 * @throws WvcmException
522 */
523 ControllableResource doApplyLabel(ApplyLabelFlag[] flags, String comment,
524 String label, Feedback feedback)
525 throws WvcmException;
526
527 /**
528 * Remove the specified label from the checked-in version of this controllable resource.
529 * @param flags array of flags which specify the behavior of the operation
530 * @param label the label to be removed from this version
531 * @param feedback
532 * @return A new proxy for this resource, whose properties are specified by feedback.
533 * @throws WvcmException
534 */
535 ControllableResource doRemoveLabel(RemoveLabelFlag[] flags,
536 String label, Feedback feedback)
537 throws WvcmException;
538
539 /**
540 * Apply the specified rolemap to the element represented by this file/directory.
541 * @param flags array of flags which specify the behavior of the operation
542 * @param comment Comment (if any) to be used for operation. Empty string if none.
543 * @param rolemap The name of the rolemap to be applied.
544 * @throws WvcmException
545 */
546 void doApplyRolemap(ApplyRolemapFlag[] flags, String comment, String rolemap)
547 throws WvcmException;
548
549 /**
550 * <p>Check out this version-controlled file or directory resource.
551 * The resource is checked out to the ClearCase view implied by its location.
552 * </p>
553 * <p>If the view is a UCM view, the caller must insure there is a
554 * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation.
555 * The checked out file will be added to the current activity's change set.
556 * The caller may explicitly specify an activity using this resource's
557 * {@link javax.wvcm.ControllableResource#setActivity} method. In that case,
558 * the specified activity will become the new current activity.
559 * Otherwise, the existing current activity will be used.
560 * If the view is a UCM view and there is no current activity, the operation
561 * will fail.
562 * </p>
563 * <p>The caller may optionally specify a checkout comment using this
564 * resource's {@link javax.wvcm.Resource#setComment} method.
565 * </p>
566 * @param flags array of flags which specify the behavior of the operation
567 * @param feedback
568 * @return new CcFile proxy representing the checked out file.
569 * @throws WvcmException
570 */
571 CcFile doCcCheckout(CcCheckoutFlag[] flags, Feedback feedback)
572 throws WvcmException;
573
574 /**
575 * Cancel the checkout of this version-controlled resource,
576 * and restore its content to the state of its CHECKED_IN version.
577 * @param flags array of flags which specify the behavior of the operation
578 * @param feedback
579 * @return new CcFile proxy representing the file whose checkout has been canceled
580 * @throws WvcmException
581 * @see javax.wvcm.ControllableResource#doUncheckout
582 */
583 CcFile doUncheckout(UncheckoutFlag[] flags, Feedback feedback)
584 throws WvcmException;
585
586 /**
587 * <p>Check in this checked out file or directory resource.
588 * </p>
589 * <p>If this resource is in a UCM view, it was added to an activity's
590 * change set at checkout time. The caller may specify an alternate
591 * change set using this resource's
592 * {@link javax.wvcm.ControllableResource#setActivity} method just before
593 * calling <code>doCheckin</code>.
594 * </p>
595 * <p>The caller may also specify a checkin comment using this
596 * resource's {@link javax.wvcm.Resource#setComment} method.
597 * This will override the comment specified at checkout time, if any.
598 * </p>
599 * @param flags array of flags which specify the behavior of the operation
600 * @param feedback
601 * @return new ControllableResource proxy representing the checked in file.
602 * @throws WvcmException
603 * @see javax.wvcm.ControllableResource#doCheckin
604 * @see com.ibm.rational.wvcm.stp.cc.CcFile#doCheckout
605 */
606 ControllableResource doCheckin(CheckinFlag[] flags, Feedback feedback)
607 throws WvcmException;
608
609 /**
610 * Merges the contents of two or more versions, representing files or
611 * directories, into this file. Versions must be of the same element as this
612 * file.
613 *
614 * @param baseVersion Base contributor. Can be null.
615 * @param contribList One or more contributing versions.
616 * @param flags Specify options for the merge. Can be null.
617 * @param listener Callback notifier for the merge.
618 * @param feedback
619 * @return new CcFile proxy representing the merged file.
620 * @throws WvcmException if there is an error during the merge.
621 */
622 CcFile doMerge(CcVersion baseVersion,
623 List<CcVersion> contribList,
624 CcMergeFlag[] flags,
625 CcListener listener,
626 Feedback feedback) throws WvcmException;
627
628 /**
629 * Places the view-private file specified by this proxy under version control.
630 * <p>If the view is a UCM view, the caller must insure there is a
631 * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation.
632 * The newly version controlled file will be added to the current activity's change set
633 * and left in a checked-in state.
634 * The caller may explicitly specify an activity using this resource's
635 * {@link javax.wvcm.ControllableResource#setActivity} method. In that case,
636 * the specified activity will become the new current activity.
637 * Otherwise, the existing current activity will be used.
638 * If the view is a UCM view and there is no current activity, the operation
639 * will fail.
640 * </p>
641 * <p>The caller may optionally specify a creation comment using this
642 * resource's {@link javax.wvcm.Resource#setComment} method.
643 * </p>
644 * <p>The caller may optionally specify the type of element to be created using
645 * this resource's {@link com.ibm.rational.wvcm.stp.cc.CcFile#setElementType} method.
646 * </p>
647 * @param feedback
648 * @return new ControllableResource proxy representing the version controlled file.
649 * @throws WvcmException
650 * @see javax.wvcm.ControllableResource#doVersionControl(javax.wvcm.Feedback)
651 */
652 ControllableResource
653 doVersionControl(Feedback feedback)
654 throws WvcmException;
655
656 /**
657 * Enhanced variant of the doVersionControl that provides additional flags
658 * which modify the behaviour.<p>
659 * This method has two main difference from <code>doVersionControl</code>:
660 * <ol>
661 * <li>It does <b>not</b> automatically checkout the version controlled
662 * parent directory. The caller must do this explicitly unless the
663 * {@link com.ibm.rational.wvcm.stp.cc.CcFile.CcVersionControlFlag#MAKE_PATH}
664 * flag is specified.
665 * <li>The newly version controlled file will be left in a checked-out state.
666 * To have the resulting file checked-in, specify the
667 * {@link com.ibm.rational.wvcm.stp.cc.CcFile.CcVersionControlFlag#CHECKIN} flag.
668 * </ol>
669 * @param flags array of flags which specify the behavior of the operation
670 * @param feedback
671 * @return A new proxy for this resource, whose properties are specified by feedback.
672 * @throws WvcmException
673 * @see com.ibm.rational.wvcm.stp.cc.CcFile#doVersionControl(javax.wvcm.Feedback)
674 */
675 ControllableResource
676 doCcVersionControl(CcVersionControlFlag flags[], Feedback feedback)
677 throws WvcmException;
678
679 /**
680 * <p>
681 * Refresh this file or directory. Re-evaluate the
682 * view's config spec and update resources on the client to be whatever
683 * is currently selected by the config spec. If this is a directory,
684 * recursively refresh its contents.
685 * </p>
686 * <p>
687 * Example: The config spec says "element * /main/LATEST", and you
688 * have version "/main/7" of this resource loaded. Someone else checks
689 * in a new version, thus creating a "/main/8". In that case,
690 * doRefresh() will cause version "/main/8" of this resource to
691 * be loaded into your view.
692 * </p>
693 * <p>
694 * Preconditions: This resource must be a version-controlled file
695 * or directory.
696 * </p>
697 * <p>
698 * Postconditions: This resource (and its descendants if this is a
699 * directory) are updated to be what is currently selected by the view's
700 * config spec.
701 * </p>
702 * @param flags array of flags which specify the behavior of the operation
703 * @param feedback (optional) a list of properties to fetch on the
704 * updated resources or a DetailedFeedback. If properties are provided,
705 * the returned resources will have them filled in. If a DetailedFeedback
706 * is provided, the appropriate notification methods will be called for each
707 * resource which is refreshed as part of the operation.
708 * by doRefresh will have these properties filled in.
709 * @return a new CcFile proxy representing the refreshed file
710 * @throws WvcmException if the precondition is not met or if an error
711 */
712 CcFile doRefresh(RefreshFlag[] flags, Feedback feedback)
713 throws WvcmException;
714
715 /**
716 * <p>
717 * Refresh this file or directory. Re-evaluate the
718 * view's config spec and update resources on the client to be whatever
719 * is currently selected by the config spec. If this is a directory,
720 * recursively refresh its contents.
721 * </p>
722 * <p>
723 * Example: The config spec says "element * /main/LATEST", and you
724 * have version "/main/7" of this resource loaded. Someone else checks
725 * in a new version, thus creating a "/main/8". In that case,
726 * doRefresh() will cause version "/main/8" of this resource to
727 * be loaded into your view.
728 * </p>
729 * <p>
730 * Preconditions: This resource must be a version-controlled file
731 * or directory.
732 * </p>
733 * <p>
734 * Postconditions: This resource (and its descendants if this is a
735 * directory) are updated to be what is currently selected by the view's
736 * config spec.
737 * </p>
738 * @param flags array of flags which specify the behavior of the operation
739 * @param listener Callback notifier for the merge.
740 * @param feedback (optional) a list of properties to fetch on the
741 * updated resources or a DetailedFeedback. If properties are provided,
742 * the returned resources will have them filled in. If a DetailedFeedback
743 * is provided, the appropriate notification methods will be called for each
744 * resource which is refreshed as part of the operation.
745 * by doRefresh will have these properties filled in.
746 * @return a new CcFile proxy representing the refreshed file
747 * @throws WvcmException if the precondition is not met or if an error
748 */
749 CcFile doCcRefresh(RefreshFlag[] flags, CcListener listener, Feedback feedback)
750 throws WvcmException;
751
752 /**
753 * <p>
754 * Restore this file or directory. If this is a directory, recursively
755 * restore its contents. This repairs any damage to the portion of the file
756 * area database specified by this resource.
757 * </p>
758 *
759 * @param flags array of flags which specify the behavior of the operation
760 * @param feedback
761 * @return a new CcFile proxy representing the restored file
762 * @throws WvcmException
763 */
764 CcFile doRestore(RefreshFlag[] flags, Feedback feedback)
765 throws WvcmException;
766
767 /**
768 * <p>
769 * Load this controllable resource into a web or snapshot view's local
770 * file area, or load the controllable resource into the automatic view.
771 * If this is a controllable folder, loads the tree of controllable
772 * resources under this folder.
773 * Also updates the view's load rules if necessary
774 * to include this file or folder.
775 * </p>
776 * <p>
777 * If this resource was already loaded, doLoad is a no-op.
778 * </p>
779 * <p>
780 * Preconditions: This must be a version-controlled file or folder
781 * in a web, snapshot or automatic view.
782 * </p>
783 * <p>
784 * Postconditions:
785 * </p>
786 * <p>
787 * This file, or the tree of files under this folder,
788 * is loaded into the view. Thus, the file(s) appear, and the view's
789 * load rules are updated to include this file or folder.
790 * </p>
791 * <p>
792 * Snapshot view: <br />
793 * This file, or the tree of files under this folder,
794 * is loaded into the view. Thus, the file(s) appear, and the view's
795 * load rules are updated to include this file or folder.
796 * </p>
797 * <p>
798 * Note that automatic views do not support load of individual
799 * resources. Addition of a load rule for a controllable resource in an
800 * automatic view must be done directly in the config spec.
801 * </p>
802 * <p>
803 * Note that automatic views do not support load of individual
804 * resources. Addition of a load rule for a controllable resource in an
805 * automatic view must be done directly in the config spec.
806 * </p>
807 * @param feedback (optional) feedback's notifyIsModified() method will be
808 * called for each file or directory as it is loaded
809 * @return a new CcFile proxy for the file that has been loaded
810 * @throws WvcmException
811 */
812 CcFile doLoad(Feedback feedback) throws WvcmException;
813
814 /**
815 * Hijack this web, automatic or snapshot view controllable resource.
816 * Make the resource writable and set its "last modified" time to the
817 * current time. This operation does <i>not</i> contact the server.
818 * @param feedback
819 * @return a new CcFile proxy for the hijacked file
820 * @throws WvcmException
821 */
822 CcFile hijack(Feedback feedback)
823 throws WvcmException;
824
825 /**
826 * Undo a hijack on this hijacked controllable resource. Reload the file's
827 * contents from the appropriate version on the server.
828 * @param flags Specify <code>KEEP</code> to save a copy of the hijacked
829 * file's contents in a ".keep" file before undoing the hijack.
830 * @param feedback
831 * @return a new CcFile proxy for the unhijacked file
832 * @throws WvcmException
833 */
834 CcFile doUnhijack(UnhijackFlag[] flags, Feedback feedback)
835 throws WvcmException;
836
837 /**
838 * For client resources, identifies the file system path to the local file
839 * representing this controllable resource.
840 */
841 PropertyName<File> CLIENT_PATH =
842 new PropertyName<File>(PROPERTY_NAMESPACE, "client-path");
843
844 /**
845 * Returns the value of this proxy's {@link #CLIENT_PATH} property.
846 * @return The path to this ControllableResource in the local file area.
847 * Will never be <code>null</code>.
848 * @throws WvcmException if requested of a ControllableResource without client state
849 */
850 File getClientPath() throws WvcmException;
851
852 /**
853 * For version-controlled resources, this resource's element type.
854 */
855 PropertyName<CcElementType> ELEMENT_TYPE =
856 new PropertyName<CcElementType>(PROPERTY_NAMESPACE, "element-type");
857
858 /**
859 * Returns the value of this proxy's {@link #ELEMENT_TYPE} property.
860 * @return This resource's element type. Will be <code>null</code>
861 * if resource is not version-controlled.
862 * @throws WvcmException if this proxy doesn't define a value for this property.
863 */
864 CcElementType getElementType() throws WvcmException;
865
866 /**
867 * Set the value of this file or directory's {@link #ELEMENT_TYPE} property.
868 * This property can only be set just prior to calling doVersionControl()
869 * on the resource.
870 * @param eltype resource's desired element type
871 */
872 void setElementType(CcElementType eltype);
873
874 /**
875 * Is this file a web view file area database file? File area DB files require
876 * special treatment. For instance, they cannot be source controlled.
877 * For this reason, applications may choose to hide these files from
878 * the end user.
879 */
880 PropertyName<Boolean> IS_DB_FILE =
881 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-db-file");
882
883 /**
884 * Get the value of this files {@link #IS_DB_FILE} property.
885 * @return true if this file is a file area database file, else false
886 * @throws WvcmException
887 * if this proxy doesn't define a value for this property.
888 */
889 public boolean getIsDbFile() throws WvcmException;
890
891 /**
892 * Is this a view-private file that is eclipsing a VOB file with
893 * the same name?
894 */
895 PropertyName<Boolean> IS_ECLIPSING =
896 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-eclipsing");
897
898 /**
899 * Get the value of this files {@link #IS_ECLIPSING} property.
900 * @return {@code true} if this is a view-private file that eclipses a VOB file
901 * with the same name, else {@code false}
902 * @throws WvcmException
903 * if this proxy doesn't define a value for this property.
904 */
905 public boolean getIsEclipsing() throws WvcmException;
906
907 /**
908 * Property which is true/false depending on whether this version-controlled
909 * resource has been hijacked.
910 */
911 PropertyName<Boolean> IS_HIJACKED =
912 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-hijacked");
913
914 /**
915 * Get the value of this file's {@link #IS_HIJACKED} property.
916 * @return true if the file is hijacked, false otherwise
917 * @throws WvcmException
918 * if this proxy doesn't define a value for this property.
919 */
920 public boolean getIsHijacked() throws WvcmException;
921
922 /**
923 * Is this file actually a symbolic link?
924 */
925 PropertyName<Boolean> IS_SYMLINK =
926 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-symlink");
927
928 /**
929 * Get the value of the {@link #IS_SYMLINK} property.
930 * @return true if this resource is a symbolic link, false otherwise.
931 * @throws WvcmException
932 * if this proxy doesn't define a value for this property.
933 */
934 public boolean getIsSymlink() throws WvcmException;
935
936 /**
937 * Returns the direct parent of this file. The value will
938 * be <code>null</code> if the file has no parent (e.g. VOB root).
939 * Does not find parents of hard-linked names for the file.
940 */
941 public static final PropertyName<CcFile> PARENT =
942 new PropertyName<CcFile>(PROPERTY_NAMESPACE, "cc-parent");
943
944 /**
945 * Get the value of the {@link #PARENT} property.
946 * @return A CcFile proxy for the parent, null if no parent
947 * @throws WvcmException
948 */
949 public CcFile getParent() throws WvcmException;
950
951 /**
952 * <p>If this file is actually a symbolic link, the path to its target file
953 * or directory. The path is interpreted relative to this file's parent
954 * directory.</p>
955 *
956 * <p>If this file is not a symbolic link, this value will be
957 * <code>null</code>.</p>
958 */
959 PropertyName<String> SYMLINK_TARGET_PATH =
960 new PropertyName<String>(PROPERTY_NAMESPACE, "symlink-target-path");
961
962 /**
963 * Get the value of this resource's {@link #SYMLINK_TARGET_PATH} property.
964 * @return path to symlink's target file or directory, or <code>null</code>
965 * if this file is not a symbolic link.
966 * @throws WvcmException if property was not requested
967 */
968 public String getSymlinkTargetPath() throws WvcmException;
969
970 /**
971 * The view-relative path for this resource.
972 */
973 PropertyName<String> VIEW_RELATIVE_PATH =
974 new PropertyName<String>(PROPERTY_NAMESPACE, "cr-view-relative-path");
975
976 /**
977 * Get the value of this resource's {@link #VIEW_RELATIVE_PATH} property.
978 * @return view-relative path
979 * @throws WvcmException if property was not requested
980 */
981 public String getViewRelativePath() throws WvcmException;
982
983 /**
984 * The CC version resource associated with this file.
985 * The value of this property will be null if this is not a version-
986 * controlled resource.
987 * @see javax.wvcm.ControllableResource#CHECKED_IN and
988 * javax.wvcm.ControllableResource#CHECKED_OUT
989 */
990 PropertyName<CcVersion> VERSION =
991 new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "version");
992
993 /**
994 * Get the value of this resource's {@link #VERSION} property.
995 * @return this file's version, or <code>null</code> if this file is
996 * not version controlled
997 * @throws WvcmException if property was not requested
998 */
999 public CcVersion getVersion() throws WvcmException;
1000
1001 /**
1002 * The OID of the CC version resource associated with this file.
1003 * The value of this property will be null if this is not a version-
1004 * controlled resource.
1005 */
1006 PropertyName<String> VERSION_OID =
1007 new PropertyName<String>(PROPERTY_NAMESPACE, "version-oid");
1008
1009 /**
1010 * Get the value of this resource's {@link #VERSION_OID} property.
1011 * @return this file's version oid, or <code>null</code> if this file is
1012 * not version controlled
1013 * @throws WvcmException if property was not requested
1014 */
1015 public String getVersionOid() throws WvcmException;
1016
1017 /**
1018 * The tag of the VOB in which this file resides.
1019 */
1020 PropertyName<CcVobTag> VOB_TAG =
1021 new PropertyName<CcVobTag>(PROPERTY_NAMESPACE, "file-vob-tag");
1022
1023 /**
1024 * Get the value of this resource's {@link #VOB_TAG} property.
1025 * @return the VOB tag for this file's VOB as a CcVobTag proxy,
1026 * or <code>null</code> if this file is not version controlled
1027 * @throws WvcmException if property was not requested
1028 */
1029 public CcVobTag getVobTag() throws WvcmException;
1030
1031 /**
1032 * The CC element resource associated with this file.
1033 * The value of this property will be null if this is not a version-
1034 * controlled resource.
1035 * @see javax.wvcm.ControllableResource#VERSION_HISTORY
1036 */
1037 PropertyName<CcElement> ELEMENT =
1038 new PropertyName<CcElement>(PROPERTY_NAMESPACE, "element");
1039
1040 /**
1041 * Get the value of this resource's {@link #ELEMENT} property.
1042 * @return this file's element, or <code>null</code> if this file is
1043 * not version controlled
1044 * @throws WvcmException if property was not requested
1045 */
1046 public CcElement getElement() throws WvcmException;
1047
1048 /**
1049 * Returns a {@link java.io.File File} representing the location of this
1050 * client-side resource in the local file system, else <code>null</code> if
1051 * this resource is a server-side resource only, e.g., if it is a proxy
1052 * to an unloaded file in a web view.
1053 * @return The location of this resource in the local file system, else
1054 * <code>null</code> if this is a proxy to a server-side resource only.
1055 *
1056 * @throws WvcmException Thrown if there was an error in determining the
1057 * path for this client-side Resource.
1058 */
1059 File clientResourceFile() throws WvcmException;
1060
1061 /**
1062 * Reads the file's properties, if they are available locally on the client machine.
1063 * @param feedback the properties to be available in the returned proxy,
1064 * and any other feedback desired, such as progress indications.
1065 * @return a {@link CcFile} containing the wanted properties
1066 * that are available locally on the client machine
1067 * without communicating with the server.
1068 * Note that there is an exception to this for automatic views, where a request to
1069 * a connected automatic view may result in server communication to update local
1070 * cached data.
1071 * @see Resource#doReadProperties(Feedback) doReadProperties.
1072 * @throws WvcmException ReasonCode:
1073 * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}:
1074 * The file MUST be available locally on the client machine.
1075 */
1076 CcFile readProperties(Feedback feedback) throws WvcmException;
1077
1078 /**
1079 * Reads the file's content, if it is available locally on the client machine.
1080 * @see Resource#doReadContent(OutputStream,Feedback) doReadContent
1081 * @param feedback the properties to be available in the returned proxy,
1082 * and any other feedback desired, such as progress indications.
1083 * @param content the file's content, if available, is written to this
1084 * byte stream. The stream is then closed.
1085 * @return a CcFile proxy containing the wanted properties
1086 * that are available on the client host without communicating with the server.
1087 * Note that there is an exception to this for automatic views, where a request to
1088 * a connected automatic view may result in server communication to update local
1089 * cached data.
1090 * @throws WvcmException ReasonCode:
1091 * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}:
1092 * The file MUST be available locally on the client machine.
1093 */
1094 CcFile readContent(OutputStream content, Feedback feedback) throws WvcmException;
1095
1096 /**
1097 * Resolve this file resource, but do not consult the ClearCase server.
1098 * Unlike {@link CcResource#doResolve()}, use only information currently
1099 * available information on the local client machine.
1100 * @see CcResource#doResolve()
1101 * @return a new file proxy of the correct, most specific resource type
1102 * @throws WvcmException with NOT_FOUND reason code if this file does not
1103 * exist on the local machine.
1104 */
1105 CcFile resolve() throws WvcmException;
1106
1107 /**
1108 * Whether this file is loaded, partially loaded, or not loaded in
1109 * the file area in which it resides.
1110 */
1111 PropertyName<LoadState> LOAD_STATE =
1112 new PropertyName<LoadState>(PROPERTY_NAMESPACE, "load-state");
1113
1114 /**
1115 * Get the value of this resource's {@link #LOAD_STATE} property.
1116 * @return LoadState.LOADED, LoadState.PARTIALLY_LOADED or LoadState.NOT_LOADED
1117 * @throws WvcmException
1118 * if this proxy doesn't define a value for this property.
1119 */
1120 LoadState getLoadState() throws WvcmException;
1121
1122 /**
1123 * <p>Version controlled files and directories in a web view
1124 * may have both client state -
1125 * state maintained in a local file area - and server state. When the
1126 * client state and server state get out of sync, we call this <i>skew</i>.
1127 * </p>
1128 * <p>By definition, skew cannot occur in a dynamic or snapshot view.
1129 * </p>
1130 * <p>The caller can detect skew by including the {@link #SKEWED_PROPERTY_LIST}
1131 * property in property requests to <code>doReadProperties()</code> and
1132 * other <code>do</code> methods that accept property requests.
1133 *
1134 * The resulting value of this property is the list of property names
1135 * in the request that differed between the client and the server for this
1136 * particular file or directory.
1137 * </p>
1138 * <p>Note that only certain properties are checked for skew - properties
1139 * where skew can cause significant problems. For example,
1140 * {@link #IS_CHECKED_OUT}, {@link #IS_VERSION_CONTROLLED}, and
1141 * {@link #VERSION_OID}.
1142 *
1143 * Note that skew can also be caused by elementness skew (file vs dir) and
1144 * loadness skew (loaded vs unloaded).
1145 * </p>
1146 * <p>Note also that <i>only</i> properties in the current property request
1147 * are checked for skew.
1148 * </p>
1149 * <p>NOTE: This should be used only as a trigger to do a real discordance
1150 * scan of the directory. These values are not reliable enough to use for
1151 * icon decoration or user messages. This is a quick and easy way to
1152 * automatically detect skew, but it does not cover all edge cases
1153 * (symlinks, aliases, and others) or discordance types.
1154 * </p>
1155 */
1156 PropertyName<List<PropertyName>> SKEWED_PROPERTY_LIST =
1157 new PropertyName<List<PropertyName>>(PROPERTY_NAMESPACE, "skewed-property-list");
1158
1159 /**
1160 * Get the value of this file's {@link #SKEWED_PROPERTY_LIST} property.
1161 *
1162 * NOTE: This should be used only as a trigger to do a real discordance
1163 * scan of the directory. These values are not reliable enough to use for
1164 * icon decoration or user messages. This is a quick and easy way to
1165 * automatically detect skew, but it does not cover all edge cases
1166 * (symlinks, aliases, and others) or discordance types.
1167 *
1168 * @return a list of property names in the current property request whose
1169 * values differed between the client and the server for this file
1170 * or directory.
1171 * @throws WvcmException
1172 * if this proxy doesn't define a value for this property.
1173 */
1174 List<PropertyName> getSkewedPropertyList() throws WvcmException;
1175
1176 /**
1177 * The config spec rule that selects this file.
1178 */
1179 PropertyName<String> SELECTION_RULE =
1180 new PropertyName<String>(PROPERTY_NAMESPACE, "selection-rule");
1181
1182 /**
1183 * Get the value of this resource's {@link #SELECTION_RULE} property.
1184 * @return this file's config spec rule, as a string.
1185 * @throws WvcmException
1186 * if this proxy doesn't define a value for this property.
1187 */
1188 String getSelectionRule() throws WvcmException;
1189
1190 /**
1191 * The version of this file that is currently the latest on the same branch.
1192 */
1193 PropertyName<CcVersion> LATEST_VERSION_ON_BRANCH =
1194 new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "latest-version-on-branch");
1195
1196 /**
1197 * Get the value of this resource's {@link #LATEST_VERSION_ON_BRANCH} property.
1198 * @return the version of this file that is the latest on the same branch as the
1199 * version in the view.
1200 * @throws WvcmException
1201 * if this proxy doesn't define a value for this property.
1202 */
1203 CcVersion getLatestVersionOnBranch() throws WvcmException;
1204 }