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