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     */
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 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    }