001    /*
002     * Licensed Materials - Property of IBM
003     * Restricted Materials of IBM 
004     *
005     * com.ibm.rational.wvcm.stp.cc.CcFile
006     *
007     * (C) Copyright IBM Corporation 2004, 2014.  All Rights Reserved.
008     * Note to U.S. Government Users Restricted Rights:  Use, duplication or 
009     * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp.
010     */
011    package com.ibm.rational.wvcm.stp.cc;
012    
013    import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
014    
015    import java.io.File;
016    import java.io.OutputStream;
017    import java.util.List;
018    
019    import javax.wvcm.ControllableResource;
020    import javax.wvcm.Feedback;
021    import javax.wvcm.PropertyNameList.PropertyName;
022    import javax.wvcm.Resource;
023    import javax.wvcm.WvcmException;
024    
025    import com.ibm.rational.wvcm.stp.cc.CcVersion.CcMergeFlag;
026    import com.ibm.rational.wvcm.stpex.StpExEnumeration;
027    
028    /**
029     * A proxy for a file, directory, or symbolic link resource in a ClearCase view.
030     * This resource is either under version control or could potentially be
031     * put under version control.
032     */
033    public interface CcFile
034        extends CcResource, ControllableResource
035    {
036        /** Flags for the doApplyAttribute and doRemoveAttribute methods */
037        enum AttributeOpFlag implements StpExEnumeration {
038    
039            /**
040             * Replace existing attribute instance.
041             * (Only applies to doApplyAttribute)
042             */
043            REPLACE("replace"),
044    
045            /**
046             * Apply/remove attribute recursively over sub-tree.
047             */
048            RECURSE("recurse"),
049    
050            /**
051             * If the attribute type was created with a default value, uses
052             * that value for the attribute instead of the value specified in
053             * the call. An error occurs if the attribute type was not created 
054             * with a default value. 
055             * (Only applies to doApplyAttribute)
056             */
057            DEFAULT("default");
058            
059            private String m_name;
060    
061            private AttributeOpFlag(String name) { m_name = name; }
062    
063            /* (non-Javadoc)
064             * @see java.lang.Object#toString()
065             */
066            public String toString() { return m_name; }
067        }
068    
069    
070        /** Flags for the doApplyLabel method */
071        enum ApplyLabelFlag implements StpExEnumeration {
072    
073            /**
074             * Replace existing label instance.
075             */
076            REPLACE("replace"),
077    
078            /**
079             * Apply label recursively over sub-tree.
080             */
081            RECURSE("recurse"),
082    
083            /**
084             * Follow symbolic links
085             */
086            FOLLOW_SYMLINKS("follow-symlinks");
087    
088            private String m_name;
089    
090            private ApplyLabelFlag(String name) { m_name = name; }
091    
092            /* (non-Javadoc)
093             * @see java.lang.Object#toString()
094             */
095            public String toString() { return m_name; }
096        }
097        
098        /** Flags for the doRemoveLabel method */
099        enum RemoveLabelFlag implements StpExEnumeration {
100    
101            /**
102             * Remove label recursively over sub-tree.
103             */
104            RECURSE("recurse"),
105    
106            /**
107             * Follow symbolic links
108             */
109            FOLLOW_SYMLINKS("follow-symlinks");
110    
111            private String m_name;
112    
113            private RemoveLabelFlag(String name) { m_name = name; }
114    
115            /* (non-Javadoc)
116             * @see java.lang.Object#toString()
117             */
118            public String toString() { return m_name; }
119        }
120    
121        /** Flags for the doApplyRolemap method */
122        enum ApplyRolemapFlag {
123            /**
124             * Apply rolemap recursively over sub-tree, if one exists.
125             */
126            RECURSE("recurse"),
127            
128            /**
129             * Restricts the command to changing file elements only.
130             * (Mutually exclusive with DIRECTORY.)
131             */
132            FILE("file"),
133            
134            /**
135             * Restricts the command to changing directory elements only.
136             * (Mutually exclusive with FILE.)
137             */
138            DIRECTORY("directory");
139            
140            private final String m_flag;
141    
142            ApplyRolemapFlag(String flag) {
143                m_flag = flag;
144            }
145    
146            public String toString() {
147                return m_flag;
148            }
149        }
150    
151        /** Flags for the doUncheckout method */
152        enum UncheckoutFlag implements StpExEnumeration {
153            /**
154             * Preserve changes in checked out version in a ".keep" file.
155             */
156            KEEP("keep");
157    
158            private String m_name;
159    
160            private UncheckoutFlag(String name) { m_name = name; }
161    
162            /* (non-Javadoc)
163             * @see java.lang.Object#toString()
164             */
165            public String toString() { return m_name; }
166        }
167    
168        /** Flags for the doUnhijack method */
169        enum UnhijackFlag implements StpExEnumeration {
170    
171            /**
172             * Preserve changes in hijacked version in a ".keep" file.
173             */
174            KEEP("keep");
175    
176            private UnhijackFlag(String name) { m_name = name; }
177    
178            /* (non-Javadoc)
179             * @see java.lang.Object#toString()
180             */
181            public String toString() { return m_name; }
182    
183            private String m_name;
184        }
185    
186        /**
187         * Flags for the <code>doRefresh</code> and <code>doRestore</code> methods.
188         */
189        enum RefreshFlag implements StpExEnumeration {
190    
191            /**
192             * Do <i>not</i> refresh hijacked files.
193             * Leave hijacked files in the hijacked state, and do not alter
194             * their contents.
195             * <p>
196             * Note: a deleted file or directory is considered to be hijacked.
197             * In order to refresh or restore a deleted file or directory,
198             * you must specify <code>OVERWRITE_HIJACKS</code> or
199             * <code>RENAME_HIJACKS</code>.
200             * </p>
201             * This is the default hijack behavior for both <code>doRefresh</code>
202             * and <code>doRestore</code>.
203             */
204            KEEP_HIJACKS("keep-hijacks"),
205    
206            /**
207             * If a file being refreshed is hijacked in this view,
208             * overwrite the hijacked contents with the new version's contents.
209             * Do not preserve the hijacked contents.
210             */
211            OVERWRITE_HIJACKS("overwrite-hijacks"),
212    
213            /**
214             * If a file being refreshed is hijacked in this view,
215             * preserve the hijacked contents by moving the hijacked file to
216             * <code><file-name>.keep</code>.
217             */
218            RENAME_HIJACKS("rename-hijacks"),
219    
220            /**
221             * When refreshing a file to a different version, set the file's
222             * "last modified" time to be the time when the version was created.
223             * <br />
224             * Web View:
225             * By default, a refreshed file's "last modified" time will simply be
226             * the time when the <code>doRefresh</code> is performed.
227             * <br />
228             * Snapshot View:
229             * If <code>PRESERVE_CREATION_TIME</code> or 
230             * <code>USE_CURRENT_TIME</code> is not set then the file's
231             *  "last modified" time will be set based on
232             *  <code>CcView.PRESERVE_VOB_MODIFIED_TIME</code>.
233             */
234            PRESERVE_CREATION_TIME("preserve-creation-time"),
235            
236            /**
237             * When refreshing a file to a different version, set the file's
238             * "last modified" time to be the time when 
239             * <code>doRefresh</code> is performed on the Snapshot view resource.
240             * Not applicable for other view types.
241             * <br />
242             * If <code>PRESERVE_CREATION_TIME</code> or 
243             * <code>USE_CURRENT_TIME</code> is not set then the file's
244             *  "last modified" time will be set based on
245             *  <code>CcView.PRESERVE_VOB_MODIFIED_TIME</code>.
246             */
247            USE_CURRENT_TIME("use-current-time"),
248    
249            /**
250             * Preview the refresh operation, but don't actually perform it.
251             * Invoke the caller's feedback methods to inform them what the
252             * refresh would do if it were performed right now.
253             */
254            PREVIEW_ONLY("preview-only"),
255            
256            /**
257             * Force the refresh/update of load-once rules in automatic views.
258             */
259            FORCE_LOAD_ONCE("force-load-once"),
260            
261            /**
262             * Resume a suspended update... 
263             * 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 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         * Property which is true/false depending on whether this version-controlled 
865         * resource has been hijacked.
866         */
867        PropertyName<Boolean> IS_HIJACKED =
868            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-hijacked");
869    
870        /**
871         * Get the value of this file's {@link #IS_HIJACKED} property.
872         * @return true if the file is hijacked, false otherwise
873         * @throws WvcmException
874         *             if this proxy doesn't define a value for this property.
875        */
876        public boolean getIsHijacked() throws WvcmException;
877    
878        /**
879         * Is this file actually a symbolic link?
880         */
881        PropertyName<Boolean> IS_SYMLINK =
882            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-symlink");
883    
884        /**
885         * Get the value of the {@link #IS_SYMLINK} property.
886         * @return true if this resource is a symbolic link, false otherwise.
887         * @throws WvcmException
888         *             if this proxy doesn't define a value for this property.
889        */
890        public boolean getIsSymlink() throws WvcmException;
891    
892        /**
893         * Returns the direct parent of this file.  The value will
894         * be <code>null</code> if the file has no parent (e.g. VOB root).
895         * Does not find parents of hard-linked names for the file.
896         */
897        public static final PropertyName<CcFile> PARENT =
898            new PropertyName<CcFile>(PROPERTY_NAMESPACE, "cc-parent");
899        
900        /**
901         * Get the value of the {@link #PARENT} property.
902         * @return A CcFile proxy for the parent, null if no parent
903         * @throws WvcmException
904         */
905        public CcFile getParent() throws WvcmException;
906    
907        /**
908         * <p>If this file is actually a symbolic link, the path to its target file
909         * or directory.  The path is interpreted relative to this file's parent 
910         * directory.</p>
911         * 
912         * <p>If this file is not a symbolic link, this value will be 
913         * <code>null</code>.</p>
914         */
915        PropertyName<String> SYMLINK_TARGET_PATH =
916            new PropertyName<String>(PROPERTY_NAMESPACE, "symlink-target-path");
917    
918        /**
919         * Get the value of this resource's {@link #SYMLINK_TARGET_PATH} property.
920         * @return path to symlink's target file or directory, or <code>null</code>
921         *         if this file is not a symbolic link.
922         * @throws WvcmException if property was not requested
923         */
924        public String getSymlinkTargetPath() throws WvcmException;
925    
926        /**
927         * The view-relative path for this resource.
928         */
929        PropertyName<String> VIEW_RELATIVE_PATH =
930            new PropertyName<String>(PROPERTY_NAMESPACE, "cr-view-relative-path");
931    
932        /**
933         * Get the value of this resource's {@link #VIEW_RELATIVE_PATH} property.
934         * @return view-relative path
935         * @throws WvcmException if property was not requested
936         */
937        public String getViewRelativePath() throws WvcmException;
938    
939        /**
940         * The CC version resource associated with this file.
941         * The value of this property will be null if this is not a version-
942         * controlled resource.
943         * @see javax.wvcm.ControllableResource#CHECKED_IN and 
944         * javax.wvcm.ControllableResource#CHECKED_OUT
945         */
946        PropertyName<CcVersion> VERSION =
947            new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "version");
948    
949        /**
950         * Get the value of this resource's {@link #VERSION} property.
951         * @return this file's version, or <code>null</code> if this file is
952         * not version controlled
953         * @throws WvcmException if property was not requested
954         */
955        public CcVersion getVersion() throws WvcmException;
956    
957        /**
958         * The OID of the CC version resource associated with this file.
959         * The value of this property will be null if this is not a version-
960         * controlled resource.
961         */
962        PropertyName<String> VERSION_OID =
963            new PropertyName<String>(PROPERTY_NAMESPACE, "version-oid");
964    
965        /**
966         * Get the value of this resource's {@link #VERSION_OID} property.
967         * @return this file's version oid, or <code>null</code> if this file is
968         * not version controlled
969         * @throws WvcmException if property was not requested
970         */
971        public String getVersionOid() throws WvcmException;
972    
973        /**
974         * The tag of the VOB in which this file resides.
975         */
976        PropertyName<CcVobTag> VOB_TAG =
977            new PropertyName<CcVobTag>(PROPERTY_NAMESPACE, "file-vob-tag");
978     
979        /**
980         * Get the value of this resource's {@link #VOB_TAG} property.
981         * @return the VOB tag for this file's VOB as a CcVobTag proxy, 
982         * or <code>null</code> if this file is not version controlled
983         * @throws WvcmException if property was not requested
984         */
985        public CcVobTag getVobTag() throws WvcmException;
986        
987        /**
988         * The CC element resource associated with this file.
989         * The value of this property will be null if this is not a version-
990         * controlled resource.
991         * @see javax.wvcm.ControllableResource#VERSION_HISTORY
992         */
993        PropertyName<CcElement> ELEMENT =
994            new PropertyName<CcElement>(PROPERTY_NAMESPACE, "element");
995    
996        /**
997         * Get the value of this resource's {@link #ELEMENT} property.
998         * @return this file's element, or <code>null</code> if this file is
999         * not version controlled
1000         * @throws WvcmException if property was not requested
1001         */
1002        public CcElement getElement() throws WvcmException;
1003    
1004        /**
1005         * Returns a {@link java.io.File File} representing the location of this
1006         * client-side resource in the local file system, else <code>null</code> if
1007         * this resource is a server-side resource only, e.g., if it is a proxy
1008         * to an unloaded file in a web view.
1009         * @return The location of this resource in the local file system, else
1010         * <code>null</code> if this is a proxy to a server-side resource only.
1011         * 
1012         * @throws WvcmException Thrown if there was an error in determining the
1013         * path for this client-side Resource.
1014         */
1015        File clientResourceFile() throws WvcmException;
1016        
1017        /**
1018         * Reads the file's properties, if they are available locally on the client machine.
1019         * @param feedback the properties to be available in the returned proxy,
1020         *  and any other feedback desired, such as progress indications.
1021         * @return a {@link CcFile} containing the wanted properties
1022         * that are available locally on the client machine
1023         * without communicating with the server.
1024         * Note that there is an exception to this for automatic views, where a request to
1025         * a connected automatic view may result in server communication to update local 
1026         * cached data. 
1027         * @see Resource#doReadProperties(Feedback) doReadProperties.
1028         * @throws WvcmException ReasonCode:
1029         * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}:
1030         *  The file MUST be available locally on the client machine.
1031         */
1032        CcFile readProperties(Feedback feedback) throws WvcmException;
1033    
1034        /**
1035         * Reads the file's content, if it is available locally on the client machine.
1036         * @see Resource#doReadContent(OutputStream,Feedback) doReadContent
1037         * @param feedback the properties to be available in the returned proxy,
1038         *  and any other feedback desired, such as progress indications.
1039         * @param content the file's content, if available, is written to this
1040         * byte stream.  The stream is then closed.
1041         * @return a CcFile proxy containing the wanted properties
1042         * that are available on the client host without communicating with the server. 
1043         * Note that there is an exception to this for automatic views, where a request to
1044         * a connected automatic view may result in server communication to update local 
1045         * cached data. 
1046         * @throws WvcmException ReasonCode:
1047         * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}:
1048         *  The file MUST be available locally on the client machine.
1049         */
1050        CcFile readContent(OutputStream content, Feedback feedback) throws WvcmException;
1051    
1052        /**
1053         * Resolve this file resource, but do not consult the ClearCase server.
1054         * Unlike {@link CcResource#doResolve()}, use only information currently
1055         * available information on the local client machine.  
1056         * @see CcResource#doResolve()
1057         * @return a new file proxy of the correct, most specific resource type
1058         * @throws WvcmException with NOT_FOUND reason code if this file does not
1059         *         exist on the local machine.
1060         */
1061        CcFile resolve() throws WvcmException;
1062        
1063        /**
1064         * Whether this file is loaded, partially loaded, or not loaded in
1065         * the file area in which it resides.
1066         */
1067        PropertyName<LoadState> LOAD_STATE =
1068            new PropertyName<LoadState>(PROPERTY_NAMESPACE, "load-state");
1069    
1070        /**
1071         * Get the value of this resource's {@link #LOAD_STATE} property.
1072         * @return LoadState.LOADED, LoadState.PARTIALLY_LOADED or LoadState.NOT_LOADED
1073         * @throws WvcmException
1074         *             if this proxy doesn't define a value for this property.
1075         */
1076        LoadState getLoadState() throws WvcmException;
1077    
1078        /**
1079         * <p>Version controlled files and directories in a web view
1080         * may have both client state -
1081         * state maintained in a local file area - and server state.  When the
1082         * client state and server state get out of sync, we call this <i>skew</i>.
1083         * </p>
1084         * <p>By definition, skew cannot occur in a dynamic or snapshot view.
1085         * </p>
1086         * <p>The caller can detect skew by including the {@link #SKEWED_PROPERTY_LIST}
1087         * property in property requests to <code>doReadProperties()</code> and
1088         * other <code>do</code> methods that accept property requests.
1089         * 
1090         * The resulting value of this property is the list of property names
1091         * in the request that differed between the client and the server for this
1092         * particular file or directory.
1093         * </p>
1094         * <p>Note that only certain properties are checked for skew - properties
1095         * where skew can cause significant problems.  For example,
1096         * {@link #IS_CHECKED_OUT}, {@link #IS_VERSION_CONTROLLED}, and
1097         * {@link #VERSION_OID}.
1098         * 
1099         * Note that skew can also be caused by elementness skew (file vs dir) and
1100         * loadness skew (loaded vs unloaded).
1101         * </p>
1102         * <p>Note also that <i>only</i> properties in the current property request
1103         * are checked for skew.
1104         * </p>
1105         * <p>NOTE: This should be used only as a trigger to do a real discordance
1106         * scan of the directory. These values are not reliable enough to use for
1107         * icon decoration or user messages. This is a quick and easy way to 
1108         * automatically detect skew, but it does not cover all edge cases 
1109         * (symlinks, aliases, and others) or discordance types.
1110         * </p>
1111         */
1112        PropertyName<List<PropertyName>> SKEWED_PROPERTY_LIST =
1113            new PropertyName<List<PropertyName>>(PROPERTY_NAMESPACE, "skewed-property-list");
1114    
1115        /**
1116         * Get the value of this file's {@link #SKEWED_PROPERTY_LIST} property.
1117         * 
1118         * NOTE: This should be used only as a trigger to do a real discordance
1119         * scan of the directory. These values are not reliable enough to use for
1120         * icon decoration or user messages. This is a quick and easy way to 
1121         * automatically detect skew, but it does not cover all edge cases 
1122         * (symlinks, aliases, and others) or discordance types.
1123         * 
1124         * @return a list of property names in the current property request whose
1125         *         values differed between the client and the server for this file
1126         *         or directory.
1127         * @throws WvcmException
1128         *             if this proxy doesn't define a value for this property.
1129         */
1130        List<PropertyName> getSkewedPropertyList() throws WvcmException;
1131        
1132        /**
1133         * The config spec rule that selects this file.
1134         */
1135        PropertyName<String> SELECTION_RULE =
1136            new PropertyName<String>(PROPERTY_NAMESPACE, "selection-rule");
1137        
1138        /**
1139         * Get the value of this resource's {@link #SELECTION_RULE} property.
1140         * @return this file's config spec rule, as a string.
1141         * @throws WvcmException
1142         *             if this proxy doesn't define a value for this property.
1143         */
1144        String getSelectionRule() throws WvcmException;
1145        
1146        /**
1147         * The version of this file that is currently the latest on the same branch.
1148         */
1149        PropertyName<CcVersion> LATEST_VERSION_ON_BRANCH =
1150            new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "latest-version-on-branch");
1151        
1152        /**
1153         * Get the value of this resource's {@link #LATEST_VERSION_ON_BRANCH} property.
1154         * @return the version of this file that is the latest on the same branch as the
1155         * version in the view.
1156         * @throws WvcmException
1157         *             if this proxy doesn't define a value for this property.
1158         */
1159        CcVersion getLatestVersionOnBranch() throws WvcmException;
1160    }