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