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