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