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