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