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