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