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