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, 2013.  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,
433                String label, Feedback feedback)
434            throws WvcmException;    
435        
436        /**
437         * Apply the specified label to the checked-in version of this controllable resource.
438         * @param flags array of flags which specify the behavior of the operation
439         * @param comment The comment for this operation, or null for no comment   
440         * @param label the label to be added to this version
441         * @param feedback 
442         * @return A new proxy for this resource, whose properties are specified by feedback.
443         * @throws WvcmException
444         */
445        ControllableResource doApplyLabel(ApplyLabelFlag[] flags, String comment,
446                String label, Feedback feedback)
447            throws WvcmException;
448        
449        /**
450         * Remove the specified label from the checked-in version of this controllable resource.
451         * @param flags array of flags which specify the behavior of the operation     
452         * @param label the label to be removed from this version
453         * @param feedback 
454         * @return A new proxy for this resource, whose properties are specified by feedback.
455         * @throws WvcmException
456         */
457        ControllableResource doRemoveLabel(RemoveLabelFlag[] flags,
458                String label, Feedback feedback)
459            throws WvcmException;
460        
461        /**
462         * Apply the specified rolemap to the element represented by this file/directory.
463         * @param flags array of flags which specify the behavior of the operation
464         * @param comment Comment (if any) to be used for operation.  Empty string if none.
465         * @param rolemap The name of the rolemap to be applied.
466         * @throws WvcmException
467         */
468        void doApplyRolemap(ApplyRolemapFlag[] flags, String comment, String rolemap)
469        throws WvcmException;
470        
471        /**
472         * <p>Check out this version-controlled file or directory resource.
473         * The resource is checked out to the ClearCase view implied by its location.
474         * </p>
475         * <p>If the view is a UCM view, the caller must insure there is a
476         * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation.
477         * The checked out file will be added to the current activity's change set.
478         * The caller may explicitly specify an activity using this resource's
479         * {@link javax.wvcm.ControllableResource#setActivity} method.  In that case,
480         * the specified activity will become the new current activity.
481         * Otherwise, the existing current activity will be used.
482         * If the view is a UCM view and there is no current activity, the operation
483         * will fail.
484         * </p>
485         * <p>The caller may optionally specify a checkout comment using this
486         * resource's {@link javax.wvcm.Resource#setComment} method.
487         * </p>
488         * @param flags array of flags which specify the behavior of the operation
489         * @param feedback 
490         * @return new CcFile proxy representing the checked out file.
491         * @throws WvcmException
492         */
493        CcFile doCcCheckout(CcCheckoutFlag[] flags, Feedback feedback)
494            throws WvcmException;
495    
496        /**
497         * Cancel the checkout of this version-controlled resource,
498         * and restore its content to the state of its CHECKED_IN version.
499         * @param flags array of flags which specify the behavior of the operation
500         * @param feedback 
501         * @return new CcFile proxy representing the file whose checkout has been canceled
502         * @throws WvcmException
503         * @see javax.wvcm.ControllableResource#doUncheckout
504         */
505        CcFile doUncheckout(UncheckoutFlag[] flags, Feedback feedback)
506            throws WvcmException;
507    
508        /**
509         * <p>Check in this checked out file or directory resource.
510         * </p>
511         * <p>If this resource is in a UCM view, it was added to an activity's
512         * change set at checkout time.  The caller may specify an alternate
513         * change set using this resource's
514         * {@link javax.wvcm.ControllableResource#setActivity} method just before
515         * calling <code>doCheckin</code>. 
516         * </p>
517         * <p>The caller may also specify a checkin comment using this
518         * resource's {@link javax.wvcm.Resource#setComment} method.
519         * This will override the comment specified at checkout time, if any.
520         * </p>
521         * @param flags array of flags which specify the behavior of the operation
522         * @param feedback 
523         * @return new ControllableResource proxy representing the checked in file.
524         * @throws WvcmException
525         * @see javax.wvcm.ControllableResource#doCheckin
526         * @see com.ibm.rational.wvcm.stp.cc.CcFile#doCheckout
527         */
528        ControllableResource doCheckin(CheckinFlag[] flags, Feedback feedback) 
529            throws WvcmException;
530    
531        /**
532         * Merges the contents of two or more versions, representing files or 
533         * directories, into this file. Versions must be of the same element as this
534         * file.
535         * 
536         * @param baseVersion Base contributor. Can be null.
537         * @param contribList One or more contributing versions.
538         * @param flags Specify options for the merge. Can be null.
539         * @param listener Callback notifier for the merge.
540         * @param feedback 
541         * @return new CcFile proxy representing the merged file.
542         * @throws WvcmException if there is an error during the merge.
543         */
544        CcFile doMerge(CcVersion baseVersion,
545                List<CcVersion> contribList,
546                CcMergeFlag[] flags,
547                CcListener listener,
548                Feedback feedback) throws WvcmException;
549        
550        /**
551         * Places the view-private file specified by this proxy under version control.
552         * <p>If the view is a UCM view, the caller must insure there is a
553         * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation.
554         * The newly version controlled file will be added to the current activity's change set
555         * and left in a checked-in state.
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 creation comment using this
564         * resource's {@link javax.wvcm.Resource#setComment} method.
565         * </p>
566         * <p>The caller may optionally specify the type of element to be created using
567         * this resource's {@link com.ibm.rational.wvcm.stp.cc.CcFile#setElementType} method.
568         * </p>
569         * @param feedback
570         * @return new ControllableResource proxy representing the version controlled file.
571         * @throws WvcmException
572         * @see javax.wvcm.ControllableResource#doVersionControl(javax.wvcm.Feedback)
573         */
574        ControllableResource
575        doVersionControl(Feedback feedback)
576            throws WvcmException;
577    
578        /**
579         * Enhanced variant of the doVersionControl that provides additional flags
580         * which modify the behaviour.<p>
581         * This method has two main difference from <code>doVersionControl</code>:
582         * <ol>
583         * <li>It does <b>not</b> automatically checkout the version controlled
584         * parent directory.  The caller must do this explicitly unless the
585         * {@link com.ibm.rational.wvcm.stp.cc.CcFile.CcVersionControlFlag#MAKE_PATH}
586         * flag is specified.
587         * <li>The newly version controlled file will be left in a checked-out state.
588         * To have the resulting file checked-in, specify the
589         * {@link com.ibm.rational.wvcm.stp.cc.CcFile.CcVersionControlFlag#CHECKIN} flag.
590         * </ol>
591         * @param flags array of flags which specify the behavior of the operation
592         * @param feedback
593         * @return A new proxy for this resource, whose properties are specified by feedback.
594         * @throws WvcmException
595         * @see com.ibm.rational.wvcm.stp.cc.CcFile#doVersionControl(javax.wvcm.Feedback)
596         */
597        ControllableResource
598        doCcVersionControl(CcVersionControlFlag flags[], Feedback feedback)
599            throws WvcmException;
600        
601        /**
602         * <p>
603         * Refresh this file or directory. Re-evaluate the
604         * view's config spec and update resources on the client to be whatever
605         * is currently selected by the config spec.  If this is a directory,
606         * recursively refresh its contents.
607         * </p>
608         * <p>
609         * Example: The config spec says "element * /main/LATEST", and you
610         * have version "/main/7" of this resource loaded. Someone else checks
611         * in a new version, thus creating a "/main/8". In that case,
612         * doRefresh() will cause version "/main/8" of this resource to
613         * be loaded into your view.
614         * </p>
615         * <p>
616         * Preconditions: This resource must be a version-controlled file
617         * or directory.
618         * </p>
619         * <p>
620         * Postconditions: This resource (and its descendants if this is a
621         * directory) are updated to be what is currently selected by the view's
622         * config spec.
623         * </p>
624         * @param flags array of flags which specify the behavior of the operation
625         * @param feedback a list of properties to fetch on the
626         * updated resources. The resources returned by the iterator returned
627         * by doRefresh will have these properties filled in.
628         * @return a new CcFile proxy representing the refreshed file
629         * @throws WvcmException if the precondition is not met or if an error
630         */
631        CcFile doRefresh(RefreshFlag[] flags, Feedback feedback)
632           throws WvcmException;
633    
634        /**
635         * <p>
636         * Refresh this file or directory. Re-evaluate the
637         * view's config spec and update resources on the client to be whatever
638         * is currently selected by the config spec.  If this is a directory,
639         * recursively refresh its contents.
640         * </p>
641         * <p>
642         * Example: The config spec says "element * /main/LATEST", and you
643         * have version "/main/7" of this resource loaded. Someone else checks
644         * in a new version, thus creating a "/main/8". In that case,
645         * doRefresh() will cause version "/main/8" of this resource to
646         * be loaded into your view.
647         * </p>
648         * <p>
649         * Preconditions: This resource must be a version-controlled file
650         * or directory.
651         * </p>
652         * <p>
653         * Postconditions: This resource (and its descendants if this is a
654         * directory) are updated to be what is currently selected by the view's
655         * config spec.
656         * </p>
657         * @param flags array of flags which specify the behavior of the operation
658         * @param listener Callback notifier for the merge.
659         * @param feedback a list of properties to fetch on the
660         * updated resources. The resources returned by the iterator returned
661         * by doRefresh will have these properties filled in.
662         * @return a new CcFile proxy representing the refreshed file
663         * @throws WvcmException if the precondition is not met or if an error
664         */
665        CcFile doCcRefresh(RefreshFlag[] flags, CcListener listener, Feedback feedback)
666        throws WvcmException;
667        
668        /**
669         * <p>
670         * Restore this file or directory. If this is a directory, recursively
671         * restore its contents. This repairs any damage to the portion of the file
672         * area database specified by this resource.
673         * </p>
674         * 
675         * @param flags array of flags which specify the behavior of the operation
676         * @param feedback
677         * @return a new CcFile proxy representing the restored file
678         * @throws WvcmException
679         */
680        CcFile doRestore(RefreshFlag[] flags, Feedback feedback)
681           throws WvcmException;
682    
683        /**
684         * <p>
685         * Load this controllable resource into the web view's local file area.
686         * If this is a controllable folder, loads the tree of controllable
687         * resources under this folder. 
688         * Also updates the web view's load rules if necessary
689         * to include this file or folder.
690         * </p>
691         * <p>
692         * If this resource was already loaded, doLoad is a no-op.
693         * </p>
694         * <p>
695         * Preconditions: This must be a version-controlled file or folder
696         * in a web view.
697         * </p>
698         * <p>
699         * Postconditions: This file, or the tree of files under this folder,
700         * is loaded into the web view. Thus, the file(s) appear, and the view's
701         * load rules are updated to include this file or folder.
702         * </p>
703         * @param feedback (optional) feedback's notifyIsModified() method will be
704         *           called for each file or directory as it is loaded
705         * @return a new CcFile proxy for the file that has been loaded
706         * @throws WvcmException
707         */
708        CcFile doLoad(Feedback feedback) throws WvcmException;
709    
710        /**
711         * Hijack this web view controllable resource.
712         * Make the resource writable and set its "last modified" time to the
713         * current time.  This operation does <i>not</i> contact the server.
714         * @param feedback 
715         * @return a new CcFile proxy for the hijacked file
716         * @throws WvcmException
717         */
718        CcFile hijack(Feedback feedback)
719           throws WvcmException;
720        
721        /**
722         * Undo a hijack on this hijacked controllable resource.  Reload the file's
723         * contents from the appropriate version on the server.
724         * @param flags Specify <code>KEEP</code> to save a copy of the hijacked
725         * file's contents in a ".keep" file before undoing the hijack.
726         * @param feedback 
727         * @return a new CcFile proxy for the unhijacked file
728         * @throws WvcmException
729         */
730        CcFile doUnhijack(UnhijackFlag[] flags, Feedback feedback)
731           throws WvcmException;
732    
733        /**
734          * For client resources, identifies the file system path to the local file
735          * representing this controllable resource.
736          */
737         PropertyName<File> CLIENT_PATH =
738             new PropertyName<File>(PROPERTY_NAMESPACE, "client-path");
739    
740         /**
741          * Returns the value of this proxy's {@link #CLIENT_PATH} property.
742          * @return The path to this ControllableResource in the local file area.
743          *         Will never be <code>null</code>.
744          * @throws WvcmException if requested of a ControllableResource without client state
745          */
746         File getClientPath() throws WvcmException;
747    
748         /**
749          * For version-controlled resources, this resource's element type.
750          */
751         PropertyName<CcElementType> ELEMENT_TYPE =
752             new PropertyName<CcElementType>(PROPERTY_NAMESPACE, "element-type");
753    
754         /**
755          * Returns the value of this proxy's {@link #ELEMENT_TYPE} property.
756          * @return This resource's element type.  Will be <code>null</code>
757          *         if resource is not version-controlled.
758         * @throws WvcmException  if this proxy doesn't define a value for this property.
759          */
760         CcElementType getElementType() throws WvcmException;
761    
762         /**
763          * Set the value of this file or directory's {@link #ELEMENT_TYPE} property.
764          * This property can only be set just prior to calling doVersionControl()
765          * on the resource.
766          * @param eltype resource's desired element type
767          */
768         void setElementType(CcElementType eltype);
769    
770         /**
771         * Is this file a web view file area database file?  File area DB files require
772         * special treatment.  For instance, they cannot be source controlled.
773         * For this reason, applications may choose to hide these files from
774         * the end user.
775         */
776        PropertyName<Boolean> IS_DB_FILE =
777            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-db-file");
778    
779        /**
780         * Get the value of this files {@link #IS_DB_FILE} property.
781         * @return true if this file is a file area database file, else false
782         * @throws WvcmException
783         *             if this proxy doesn't define a value for this property.
784         */
785        public boolean getIsDbFile() throws WvcmException;
786    
787        /**
788         * Property which is true/false depending on whether this version-controlled 
789         * resource has been hijacked.
790         */
791        PropertyName<Boolean> IS_HIJACKED =
792            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-hijacked");
793    
794        /**
795         * Get the value of this file's {@link #IS_HIJACKED} property.
796         * @return true if the file is hijacked, false otherwise
797         * @throws WvcmException
798         *             if this proxy doesn't define a value for this property.
799        */
800        public boolean getIsHijacked() throws WvcmException;
801    
802        /**
803         * Is this file actually a symbolic link?
804         */
805        PropertyName<Boolean> IS_SYMLINK =
806            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-symlink");
807    
808        /**
809         * Get the value of the {@link #IS_SYMLINK} property.
810         * @return true if this resource is a symbolic link, false otherwise.
811         * @throws WvcmException
812         *             if this proxy doesn't define a value for this property.
813        */
814        public boolean getIsSymlink() throws WvcmException;
815    
816        /**
817         * Returns the direct parent of this file.  The value will
818         * be <code>null</code> if the file has no parent (e.g. VOB root).
819         * Does not find parents of hard-linked names for the file.
820         */
821        public static final PropertyName<CcFile> PARENT =
822            new PropertyName<CcFile>(PROPERTY_NAMESPACE, "cc-parent");
823        
824        /**
825         * Get the value of the {@link #PARENT} property.
826         * @return A CcFile proxy for the parent, null if no parent
827         * @throws WvcmException
828         */
829        public CcFile getParent() throws WvcmException;
830    
831        /**
832         * <p>If this file is actually a symbolic link, the path to its target file
833         * or directory.  The path is interpreted relative to this file's parent 
834         * directory.</p>
835         * 
836         * <p>If this file is not a symbolic link, this value will be 
837         * <code>null</code>.</p>
838         */
839        PropertyName<String> SYMLINK_TARGET_PATH =
840            new PropertyName<String>(PROPERTY_NAMESPACE, "symlink-target-path");
841    
842        /**
843         * Get the value of this resource's {@link #SYMLINK_TARGET_PATH} property.
844         * @return path to symlink's target file or directory, or <code>null</code>
845         *         if this file is not a symbolic link.
846         * @throws WvcmException if property was not requested
847         */
848        public String getSymlinkTargetPath() throws WvcmException;
849    
850        /**
851         * The view-relative path for this resource.
852         */
853        PropertyName<String> VIEW_RELATIVE_PATH =
854            new PropertyName<String>(PROPERTY_NAMESPACE, "cr-view-relative-path");
855    
856        /**
857         * Get the value of this resource's {@link #VIEW_RELATIVE_PATH} property.
858         * @return view-relative path
859         * @throws WvcmException if property was not requested
860         */
861        public String getViewRelativePath() throws WvcmException;
862    
863        /**
864         * The CC version resource associated with this file.
865         * The value of this property will be null if this is not a version-
866         * controlled resource.
867         * @see javax.wvcm.ControllableResource#CHECKED_IN and 
868         * javax.wvcm.ControllableResource#CHECKED_OUT
869         */
870        PropertyName<CcVersion> VERSION =
871            new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "version");
872    
873        /**
874         * Get the value of this resource's {@link #VERSION} property.
875         * @return this file's version, or <code>null</code> if this file is
876         * not version controlled
877         * @throws WvcmException if property was not requested
878         */
879        public CcVersion getVersion() throws WvcmException;
880    
881        /**
882         * The OID of the CC version resource associated with this file.
883         * The value of this property will be null if this is not a version-
884         * controlled resource.
885         */
886        PropertyName<String> VERSION_OID =
887            new PropertyName<String>(PROPERTY_NAMESPACE, "version-oid");
888    
889        /**
890         * Get the value of this resource's {@link #VERSION_OID} property.
891         * @return this file's version oid, or <code>null</code> if this file is
892         * not version controlled
893         * @throws WvcmException if property was not requested
894         */
895        public String getVersionOid() throws WvcmException;
896    
897        /**
898         * The tag of the VOB in which this file resides.
899         */
900        PropertyName<CcVobTag> VOB_TAG =
901            new PropertyName<CcVobTag>(PROPERTY_NAMESPACE, "file-vob-tag");
902     
903        /**
904         * Get the value of this resource's {@link #VOB_TAG} property.
905         * @return the VOB tag for this file's VOB as a CcVobTag proxy, 
906         * or <code>null</code> if this file is not version controlled
907         * @throws WvcmException if property was not requested
908         */
909        public CcVobTag getVobTag() throws WvcmException;
910        
911        /**
912         * The CC element resource associated with this file.
913         * The value of this property will be null if this is not a version-
914         * controlled resource.
915         * @see javax.wvcm.ControllableResource#VERSION_HISTORY
916         */
917        PropertyName<CcElement> ELEMENT =
918            new PropertyName<CcElement>(PROPERTY_NAMESPACE, "element");
919    
920        /**
921         * Get the value of this resource's {@link #ELEMENT} property.
922         * @return this file's element, or <code>null</code> if this file is
923         * not version controlled
924         * @throws WvcmException if property was not requested
925         */
926        public CcElement getElement() throws WvcmException;
927    
928        /**
929         * Returns a {@link java.io.File File} representing the location of this
930         * client-side resource in the local file system, else <code>null</code> if
931         * this resource is a server-side resource only, e.g., if it is a proxy
932         * to an unloaded file in a web view.
933         * @return The location of this resource in the local file system, else
934         * <code>null</code> if this is a proxy to a server-side resource only.
935         * 
936         * @throws WvcmException Thrown if there was an error in determining the
937         * path for this client-side Resource.
938         */
939        File clientResourceFile() throws WvcmException;
940        
941        /**
942         * Reads the file's properties, if they are available locally on the client machine.
943         * @param feedback the properties to be available in the returned proxy,
944         *  and any other feedback desired, such as progress indications.
945         * @return a {@link CcFile} containing the wanted properties
946         * that are available locally on the client machine
947         * without communicating with the server.
948         * @see Resource#doReadProperties(Feedback) doReadProperties.
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 readProperties(Feedback feedback) throws WvcmException;
954    
955        /**
956         * Reads the file's content, if it is available locally on the client machine.
957         * @see Resource#doReadContent(OutputStream,Feedback) doReadContent
958         * @param feedback the properties to be available in the returned proxy,
959         *  and any other feedback desired, such as progress indications.
960         * @param content the file's content, if available, is written to this
961         * byte stream.  The stream is then closed.
962         * @return a CcFile proxy containing the wanted properties
963         * that are available on the client host without communicating with the server.
964         * @throws WvcmException ReasonCode:
965         * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}:
966         *  The file MUST be available locally on the client machine.
967         */
968        CcFile readContent(OutputStream content, Feedback feedback) throws WvcmException;
969    
970        /**
971         * Resolve this file resource, but do not consult the ClearCase server.
972         * Unlike {@link CcResource#doResolve()}, use only information currently
973         * available information on the local client machine.  
974         * @see CcResource#doResolve()
975         * @return a new file proxy of the correct, most specific resource type
976         * @throws WvcmException with NOT_FOUND reason code if this file does not
977         *         exist on the local machine.
978         */
979        CcFile resolve() throws WvcmException;
980        
981        /**
982         * Whether this file is loaded, partially loaded, or not loaded in the
983         * web view file area in which it resides.
984         */
985        PropertyName<LoadState> LOAD_STATE =
986            new PropertyName<LoadState>(PROPERTY_NAMESPACE, "load-state");
987    
988        /**
989         * Get the value of this resource's {@link #LOAD_STATE} property.
990         * @return LoadState.LOADED, LoadState.PARTIALLY_LOADED or LoadState.NOT_LOADED
991         * @throws WvcmException
992         *             if this proxy doesn't define a value for this property.
993         */
994        LoadState getLoadState() throws WvcmException;
995    
996        /**
997         * <p>Version controlled files and directories in a web view
998         * may have both client state -
999         * state maintained in a local file area - and server state.  When the
1000         * client state and server state get out of sync, we call this <i>skew</i>.
1001         * </p>
1002         * <p>By definition, skew cannot occur in a dynamic view.
1003         * </p>
1004         * <p>The caller can detect skew by including the {@link #SKEWED_PROPERTY_LIST}
1005         * property in property requests to <code>doReadProperties()</code> and
1006         * other <code>do</code> methods that accept property requests.
1007         * 
1008         * The resulting value of this property is the list of property names
1009         * in the request that differed between the client and the server for this
1010         * particular file or directory.
1011         * </p>
1012         * <p>Note that only certain properties are checked for skew - properties
1013         * where skew can cause significant problems.  For example,
1014         * {@link #IS_CHECKED_OUT}, {@link #IS_VERSION_CONTROLLED}, and
1015         * {@link #VERSION_OID}.
1016         * 
1017         * Note that skew can also be caused by elementness skew (file vs dir) and
1018         * loadness skew (loaded vs unloaded).
1019         * </p>
1020         * <p>Note also that <i>only</i> properties in the current property request
1021         * are checked for skew.
1022         * </p>
1023         * <p>NOTE: This should be used only as a trigger to do a real discordance
1024         * scan of the directory. These values are not reliable enough to use for
1025         * icon decoration or user messages. This is a quick and easy way to 
1026         * automatically detect skew, but it does not cover all edge cases 
1027         * (symlinks, aliases, and others) or discordance types.
1028         * </p>
1029         */
1030        PropertyName<List<PropertyName>> SKEWED_PROPERTY_LIST =
1031            new PropertyName<List<PropertyName>>(PROPERTY_NAMESPACE, "skewed-property-list");
1032    
1033        /**
1034         * Get the value of this file's {@link #SKEWED_PROPERTY_LIST} property.
1035         * 
1036         * NOTE: This should be used only as a trigger to do a real discordance
1037         * scan of the directory. These values are not reliable enough to use for
1038         * icon decoration or user messages. This is a quick and easy way to 
1039         * automatically detect skew, but it does not cover all edge cases 
1040         * (symlinks, aliases, and others) or discordance types.
1041         * 
1042         * @return a list of property names in the current property request whose
1043         *         values differed between the client and the server for this file
1044         *         or directory.
1045         * @throws WvcmException
1046         *             if this proxy doesn't define a value for this property.
1047         */
1048        List<PropertyName> getSkewedPropertyList() throws WvcmException;
1049        
1050        /**
1051         * The config spec rule that selects this file.
1052         */
1053        PropertyName<String> SELECTION_RULE =
1054            new PropertyName<String>(PROPERTY_NAMESPACE, "selection-rule");
1055        
1056        /**
1057         * Get the value of this resource's {@link #SELECTION_RULE} property.
1058         * @return this file's config spec rule, as a string.
1059         * @throws WvcmException
1060         *             if this proxy doesn't define a value for this property.
1061         */
1062        String getSelectionRule() throws WvcmException;
1063        
1064        /**
1065         * The version of this file that is currently the latest on the same branch.
1066         */
1067        PropertyName<CcVersion> LATEST_VERSION_ON_BRANCH =
1068            new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "latest-version-on-branch");
1069        
1070        /**
1071         * Get the value of this resource's {@link #LATEST_VERSION_ON_BRANCH} property.
1072         * @return the version of this file that is the latest on the same branch as the
1073         * version in the view.
1074         * @throws WvcmException
1075         *             if this proxy doesn't define a value for this property.
1076         */
1077        CcVersion getLatestVersionOnBranch() throws WvcmException;
1078    }