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     * © Copyright IBM Corporation 2004, 2008.  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 doApplyLabel method */
040        enum ApplyLabelFlag implements StpExEnumeration {
041    
042            /**
043             * Replace existing label instance.
044             */
045            REPLACE("replace"),
046    
047            /**
048             * Apply label recursively over sub-tree.
049             */
050            RECURSE("recurse"),
051    
052            /**
053             * Follow symbolic links
054             */
055            FOLLOW_SYMLINKS("follow-symlinks");
056    
057            private String m_name;
058    
059            private ApplyLabelFlag(String name) { m_name = name; }
060    
061            /* (non-Javadoc)
062             * @see java.lang.Object#toString()
063             */
064            public String toString() { return m_name; }
065        }
066        
067        /** Flags for the doRemoveLabel method */
068        enum RemoveLabelFlag implements StpExEnumeration {
069    
070            /**
071             * Remove label recursively over sub-tree.
072             */
073            RECURSE("recurse"),
074    
075            /**
076             * Follow symbolic links
077             */
078            FOLLOW_SYMLINKS("follow-symlinks");
079    
080            private String m_name;
081    
082            private RemoveLabelFlag(String name) { m_name = name; }
083    
084            /* (non-Javadoc)
085             * @see java.lang.Object#toString()
086             */
087            public String toString() { return m_name; }
088        }
089    
090        /** Flags for the doUncheckout method */
091        enum UncheckoutFlag implements StpExEnumeration {
092            /**
093             * Preserve changes in checked out version in a ".keep" file.
094             */
095            KEEP("keep");
096    
097            private String m_name;
098    
099            private UncheckoutFlag(String name) { m_name = name; }
100    
101            /* (non-Javadoc)
102             * @see java.lang.Object#toString()
103             */
104            public String toString() { return m_name; }
105        }
106    
107        /** Flags for the doUnhijack method */
108        enum UnhijackFlag implements StpExEnumeration {
109    
110            /**
111             * Preserve changes in hijacked version in a ".keep" file.
112             */
113            KEEP("keep");
114    
115            private UnhijackFlag(String name) { m_name = name; }
116    
117            /* (non-Javadoc)
118             * @see java.lang.Object#toString()
119             */
120            public String toString() { return m_name; }
121    
122            private String m_name;
123        }
124    
125        /**
126         * Flags for the <code>doRefresh</code> and <code>doRestore</code> methods.
127         */
128        enum RefreshFlag implements StpExEnumeration {
129    
130            /**
131             * Do <i>not</i> refresh hijacked files.
132             * Leave hijacked files in the hijacked state, and do not alter
133             * their contents.
134             * <p>
135             * Note: a deleted file or directory is considered to be hijacked.
136             * In order to refresh or restore a deleted file or directory,
137             * you must specify <code>OVERWRITE_HIJACKS</code> or
138             * <code>RENAME_HIJACKS</code>.
139             * </p>
140             * This is the default hijack behavior for both <code>doRefresh</code>
141             * and <code>doRestore</code>.
142             */
143            KEEP_HIJACKS("keep-hijacks"),
144    
145            /**
146             * If a file being refreshed is hijacked in this view,
147             * overwrite the hijacked contents with the new version's contents.
148             * Do not preserve the hijacked contents.
149             */
150            OVERWRITE_HIJACKS("overwrite-hijacks"),
151    
152            /**
153             * If a file being refreshed is hijacked in this view,
154             * preserve the hijacked contents by moving the hijacked file to
155             * <code><file-name>.keep</code>.
156             */
157            RENAME_HIJACKS("rename-hijacks"),
158    
159            /**
160             * When refreshing a file to a different version, set the file's
161             * "last modified" time to be the time when the version was created.
162             * By default, a refreshed file's "last modified" time will simply be
163             * the time when the <code>doRefresh</code> was performed.
164             */
165            PRESERVE_CREATION_TIME("preserve-creation-time"),
166    
167            /**
168             * Preview the refresh operation, but don't actually perform it.
169             * Invoke the caller's feedback methods to inform them what the
170             * refresh would do if it were performed right now.
171             */
172            PREVIEW_ONLY("preview-only");
173    
174            private String m_name;
175    
176            private RefreshFlag(String name) { m_name = name; }
177    
178            /* (non-Javadoc)
179             * @see java.lang.Object#toString()
180             */
181            public String toString() { return m_name; }
182        }
183        
184        /** Flags for the <code>doCheckout</code> method. */
185        enum CcCheckoutFlag implements StpExEnumeration {
186            
187            /**
188             * Indicates whether to checkout this file reserved.
189             */
190            RESERVED("reserved"),
191            
192            /**
193             * Fall back to unreserved if a reservation can not be obtained.
194             */
195            FALLBACK_TO_UNRESERVED("fallback-to-unreserved"),
196            
197            /**
198             * Checkout the version of the file that is currently loaded in the
199             * view, even if that version is not the version selected by the
200             * view's config spec.
201             * 
202             * <p>If the loaded version is not the version selected by the view's
203             * config spec, and neither {@link #LOADED_NOT_LATEST} nor
204             * {@link #LATEST_NOT_LOADED} flags are set, the checkout operation
205             * will throw an exception with reason code <code>CHECKOUT_NOT_LATEST</code>.
206             */
207            LOADED_NOT_LATEST("checkout-loaded-not-latest"),
208            
209            /**
210             * Checkout the version of the file that is selected by the view's 
211             * config spec. If this version is not loaded at checkout time, then 
212             * load it prior to performing the checkout.
213             * 
214             * <p>If the loaded version is not the version selected by the view's
215             * config spec, and neither {@link #LOADED_NOT_LATEST} nor
216             * {@link #LATEST_NOT_LOADED} flags are set, the checkout operation
217             * will throw an exception with reason code <code>CHECKOUT_NOT_LATEST</code>.
218             */
219            LATEST_NOT_LOADED("checkout-latest-not-loaded"),
220            
221            /**
222             * Indicates whether to checkout this file even if the currently
223             * selected branch is mastered by another replica. The
224             * <code>RESERVED</code> flag must NOT be set with this flag.
225             * 
226             * <p>If the file is mastered by this replica, setting this
227             * flag has no effect.
228             */
229            NON_MASTERED_OK("non-mastered-ok"),
230            
231            /**
232             * If the file is hijacked, keep the hijacked contents upon checkout.
233             */
234            PRESERVE_HIJACK_CONTENTS("preserve-hijack-contents");
235            
236            private String m_name;
237    
238            private CcCheckoutFlag(String name) { m_name = name; }
239    
240            /* (non-Javadoc)
241             * @see java.lang.Object#toString()
242             */
243            public String toString() { return m_name; }
244        }
245    
246        /** Values for file or directory load state */
247        enum LoadState implements StpExEnumeration {
248    
249            /**
250             * This file or directory is loaded in its file area.
251             */
252            LOADED,
253    
254            /**
255             * This directory is partially loaded in its file area, i.e.,
256             * some but not all of its children are loaded.
257             */
258            PARTIALLY_LOADED,
259    
260            /**
261             * This file or directory is not loaded in its file area.
262             */
263            NOT_LOADED;
264        }
265    
266        /**
267         * Create a new view-private file at the location specified by this resource.
268         * The request will fail if a resource already exists at that location.
269         * @param feedback 
270         * @return a CcFile proxy for the new file
271         * @see javax.wvcm.ControllableResource#doCreateResource(Feedback)
272         */
273        public CcFile createCcFile(Feedback feedback) throws WvcmException;
274        
275        /**
276         * Apply the specified label to the checked-in version of this controllable resource.
277         * @param flags array of flags which specify the behavior of the operation
278         * @param label the label to be added to this version
279         * @param feedback 
280         * @return A new proxy for this resource, whose properties are specified by feedback.
281         * @throws WvcmException
282         */
283        ControllableResource doApplyLabel(ApplyLabelFlag[] flags, String label, Feedback feedback)
284            throws WvcmException;
285        
286        /**
287         * Remove the specified label from the checked-in version of this controllable resource.
288         * @param flags array of flags which specify the behavior of the operation
289         * @param label the label to be removed from this version
290         * @param feedback 
291         * @return A new proxy for this resource, whose properties are specified by feedback.
292         * @throws WvcmException
293         */
294        ControllableResource doRemoveLabel(RemoveLabelFlag[] flags, String label, Feedback feedback)
295            throws WvcmException;
296        
297        /**
298         * <p>Check out this version-controlled file or directory resource.
299         * The resource is checked out to the ClearCase view implied by its location.
300         * </p>
301         * <p>If the view is a UCM view, the caller must insure there is a
302         * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation.
303         * The checked out file will be added to the current activity's change set.
304         * The caller may explicitly specify an activity using this resource's
305         * {@link javax.wvcm.ControllableResource#setActivity} method.  In that case,
306         * the specified activity will become the new current activity.
307         * Otherwise, the existing current activity will be used.
308         * If the view is a UCM view and there is no current activity, the operation
309         * will fail.
310         * </p>
311         * <p>The caller may optionally specify a checkout comment using this
312         * resource's {@link javax.wvcm.Resource#setComment} method.
313         * </p>
314         * @param flags array of flags which specify the behavior of the operation
315         * @param feedback 
316         * @return new CcFile proxy representing the checked out file.
317         * @throws WvcmException
318         */
319        CcFile doCcCheckout(CcCheckoutFlag[] flags, Feedback feedback)
320            throws WvcmException;
321    
322        /**
323         * Cancel the checkout of this version-controlled resource,
324         * and restore its content to the state of its CHECKED_IN version.
325         * @param flags array of flags which specify the behavior of the operation
326         * @param feedback 
327         * @return new CcFile proxy representing the file whose checkout has been canceled
328         * @throws WvcmException
329         * @see javax.wvcm.ControllableResource#doUncheckout
330         */
331        CcFile doUncheckout(UncheckoutFlag[] flags, Feedback feedback)
332            throws WvcmException;
333    
334        /**
335         * <p>Check in this checked out file or directory resource.
336         * </p>
337         * <p>If this resource is in a UCM view, it was added to an activity's
338         * change set at checkout time.  The caller may specify an alternate
339         * change set using this resource's
340         * {@link javax.wvcm.ControllableResource#setActivity} method just before
341         * calling <code>doCheckin</code>. 
342         * </p>
343         * <p>The caller may also specify a checkin comment using this
344         * resource's {@link javax.wvcm.Resource#setComment} method.
345         * This will override the comment specified at checkout time, if any.
346         * </p>
347         * @param flags array of flags which specify the behavior of the operation
348         * @param feedback 
349         * @return new ControllableResource proxy representing the checked in file.
350         * @throws WvcmException
351         * @see javax.wvcm.ControllableResource#doCheckin
352         * @see com.ibm.rational.wvcm.stp.cc.CcFile#doCheckout
353         */
354        ControllableResource doCheckin(CheckinFlag[] flags, Feedback feedback) 
355            throws WvcmException;
356    
357        /**
358         * Places the view-private file specified by this proxy under version control.
359         * <p>If the view is a UCM view, the caller must insure there is a
360         * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation.
361         * The newly version controlled file will be added to the current activity's change set.
362         * The caller may explicitly specify an activity using this resource's
363         * {@link javax.wvcm.ControllableResource#setActivity} method.  In that case,
364         * the specified activity will become the new current activity.
365         * Otherwise, the existing current activity will be used.
366         * If the view is a UCM view and there is no current activity, the operation
367         * will fail.
368         * </p>
369         * <p>The caller may optionally specify a creation comment using this
370         * resource's {@link javax.wvcm.Resource#setComment} method.
371         * </p>
372         * @param feedback
373         * @return new ControllableResource proxy representing the version controlled file.
374         * @throws WvcmException
375         * @see javax.wvcm.ControllableResource#doVersionControl
376         */
377        ControllableResource
378        doVersionControl(Feedback feedback)
379            throws WvcmException;
380    
381        /**
382         * <p>
383         * Refresh this file or directory. Re-evaluate the
384         * view's config spec and update resources on the client to be whatever
385         * is currently selected by the config spec.  If this is a directory,
386         * recursively refresh its contents.
387         * </p>
388         * <p>
389         * Example: The config spec says "element * /main/LATEST", and you
390         * have version "/main/7" of this resource loaded. Someone else checks
391         * in a new version, thus creating a "/main/8". In that case,
392         * doRefresh() will cause version "/main/8" of this resource to
393         * be loaded into your view.
394         * </p>
395         * <p>
396         * Preconditions: This resource must be a version-controlled file
397         * or directory.
398         * </p>
399         * <p>
400         * Postconditions: This resource (and its descendants if this is a
401         * directory) are updated to be what is currently selected by the view's
402         * config spec.
403         * </p>
404         * @param flags array of flags which specify the behavior of the operation
405         * @param feedback a list of properties to fetch on the
406         * updated resources. The resources returned by the iterator returned
407         * by doRefresh will have these properties filled in.
408         * @return a new CcFile proxy representing the refreshed file
409         * @throws WvcmException if the precondition is not met or if an error
410         */
411        CcFile doRefresh(RefreshFlag[] flags, Feedback feedback)
412           throws WvcmException;
413    
414        /**
415         * <p>
416         * Restore this file or directory. If this is a directory, recursively
417         * restore its contents. This repairs any damage to the portion of the file
418         * area database specified by this resource.
419         * </p>
420         * 
421         * @param flags array of flags which specify the behavior of the operation
422         * @param feedback
423         * @return a new CcFile proxy representing the restored file
424         * @throws WvcmException
425         */
426        CcFile doRestore(RefreshFlag[] flags, Feedback feedback)
427           throws WvcmException;
428    
429        /**
430         * <p>
431         * Load this controllable resource into the view's local file area.
432         * If this is a controllable folder, loads the tree of controllable
433         * resources under this folder. 
434         * Also updates the view's load rules if necessary
435         * to include this file or folder.
436         * </p>
437         * <p>
438         * If this resource was already loaded, doLoad is a no-op.
439         * </p>
440         * <p>
441         * Preconditions: This must be a version-controlled file or folder
442         * in a web view.
443         * </p>
444         * <p>
445         * Postconditions: This file, or the tree of files under this folder,
446         * is loaded into the web view. Thus, the file(s) appear, and the view's
447         * load rules are updated to include this file or folder.
448         * </p>
449         * @param feedback (optional) feedback's notifyIsModified() method will be
450         *           called for each file or directory as it is loaded
451         * @return a new CcFile proxy for the file that has been loaded
452         * @throws WvcmException
453         */
454        CcFile doLoad(Feedback feedback) throws WvcmException;
455    
456        /**
457         * Hijack this controllable resource.
458         * Make the resource writable and set its "last modified" time to the
459         * current time.  This operation does <i>not</i> contact the server.
460         * @param feedback 
461         * @return a new CcFile proxy for the hijacked file
462         * @throws WvcmException
463         */
464        CcFile hijack(Feedback feedback)
465           throws WvcmException;
466        
467        /**
468         * Undo a hijack on this hijacked controllable resource.  Reload the file's
469         * contents from the appropriate version on the server.
470         * @param flags Specify <code>KEEP</code> to save a copy of the hijacked
471         * file's contents in a ".keep" file before undoing the hijack.
472         * @param feedback 
473         * @return a new CcFile proxy for the unhijacked file
474         * @throws WvcmException
475         */
476        CcFile doUnhijack(UnhijackFlag[] flags, Feedback feedback)
477           throws WvcmException;
478    
479        /**
480          * For client resources, identifies the file system path to the local file
481          * representing this controllable resource.
482          */
483         PropertyName<File> CLIENT_PATH =
484             new PropertyName<File>(StpExBase.STP_NAMESPACE, "client-path");
485    
486         /**
487          * Returns the value of this proxy's {@link #CLIENT_PATH} property.
488          * @return The path to this ControllableResource in the local file area.
489          *         Will never be <code>null</code>.
490          * @throws WvcmException if requested of a ControllableResource without client state
491          */
492         File getClientPath() throws WvcmException;
493    
494         /**
495          * For version-controlled resources, this resource's element type.
496          */
497         PropertyName<CcElementType> ELEMENT_TYPE =
498             new PropertyName<CcElementType>(STP_NAMESPACE, "element-type");
499    
500         /**
501          * Returns the value of this proxy's {@link #ELEMENT_TYPE} property.
502          * @return This resource's element type.  Will be <code>null</code>
503          *         if resource is not version-controlled.
504         * @throws WvcmException  if this proxy doesn't define a value for this property.
505          */
506         CcElementType getElementType() throws WvcmException;
507    
508         /**
509          * Set the value of this file or directory's {@link #ELEMENT_TYPE} property.
510          * This property can only be set just prior to calling doVersionControl()
511          * on the resource.
512          * @param eltype resource's desired element type
513          */
514         void setElementType(CcElementType eltype);
515    
516         /**
517         * Is this file a file area database file?  File area DB files require
518         * special treatment.  For instance, they cannot be source controlled.
519         * For this reason, applications may choose to hide these files from
520         * the end user.
521         */
522        PropertyName<Boolean> IS_DB_FILE =
523            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-db-file");
524    
525        /**
526         * Get the value of this files {@link #IS_DB_FILE} property.
527         * @return true if this file is a file area database file, else false
528         * @throws WvcmException
529         *             if this proxy doesn't define a value for this property.
530         */
531        public boolean getIsDbFile() throws WvcmException;
532    
533        /**
534         * Property which is true/false depending on whether this version-controlled 
535         * resource has been hijacked.
536         */
537        PropertyName<Boolean> IS_HIJACKED =
538            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-hijacked");
539    
540        /**
541         * Get the value of this file's {@link #IS_HIJACKED} property.
542         * @return true if the file is hijacked, false otherwise
543         * @throws WvcmException
544         *             if this proxy doesn't define a value for this property.
545        */
546        public boolean getIsHijacked() throws WvcmException;
547    
548        /**
549         * Is this file actually a symbolic link?
550         */
551        PropertyName<Boolean> IS_SYMLINK =
552            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-symlink");
553    
554        /**
555         * Get the value of the {@link #IS_SYMLINK} property.
556         * @return true if this resource is a symbolic link, false otherwise.
557         * @throws WvcmException
558         *             if this proxy doesn't define a value for this property.
559        */
560        public boolean getIsSymlink() throws WvcmException;
561    
562        /**
563         * Returns the direct parent of this file.  The value will
564         * be <code>null</code> if the file has no parent (e.g. VOB root).
565         * Does not find parents of hard-linked names for the file.
566         */
567        public static final PropertyName<CcDirectory> PARENT =
568            new PropertyName<CcDirectory>(PROPERTY_NAMESPACE, "cc-parent");
569        
570        /**
571         * Get the value of the {@link #PARENT} property.
572         * @return A CcDirectory proxy for the parent, null if no parent
573         * @throws WvcmException
574         */
575        public CcDirectory getParent() throws WvcmException;
576    
577        /**
578         * <p>If this file is actually a symbolic link, the path to its target file
579         * or directory.  The path is interpreted relative to this file's parent 
580         * directory.</p>
581         * 
582         * <p>If this file is not a symbolic link, this value will be 
583         * <code>null</code>.</p>
584         */
585        PropertyName<String> SYMLINK_TARGET_PATH =
586            new PropertyName<String>(PROPERTY_NAMESPACE, "symlink-target-path");
587    
588        /**
589         * Get the value of this resource's {@link #SYMLINK_TARGET_PATH} property.
590         * @return path to symlink's target file or directory, or <code>null</code>
591         *         if this file is not a symbolic link.
592         * @throws WvcmException if property was not requested
593         */
594        public String getSymlinkTargetPath() throws WvcmException;
595    
596        /**
597         * The view-relative path for this resource.
598         */
599        PropertyName<String> VIEW_RELATIVE_PATH =
600            new PropertyName<String>(PROPERTY_NAMESPACE, "cr-view-relative-path");
601    
602        /**
603         * Get the value of this resource's {@link #VIEW_RELATIVE_PATH} property.
604         * @return view-relative path
605         * @throws WvcmException if property was not requested
606         */
607        public String getViewRelativePath() throws WvcmException;
608    
609        /**
610         * The CC version resource associated with this file.
611         * The value of this property will be null if this is not a version-
612         * controlled resource.
613         * @see javax.wvcm.ControllableResource#CHECKED_IN and 
614         * javax.wvcm.ControllableResource#CHECKED_OUT
615         */
616        PropertyName<CcVersion> VERSION =
617            new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "version");
618    
619        /**
620         * Get the value of this resource's {@link #VERSION} property.
621         * @return this file's version, or <code>null</code> if this file is
622         * not version controlled
623         * @throws WvcmException if property was not requested
624         */
625        public CcVersion getVersion() throws WvcmException;
626    
627        /**
628         * The OID of the CC version resource associated with this file.
629         * The value of this property will be null if this is not a version-
630         * controlled resource.
631         */
632        PropertyName<String> VERSION_OID =
633            new PropertyName<String>(PROPERTY_NAMESPACE, "version-oid");
634    
635        /**
636         * Get the value of this resource's {@link #VERSION_OID} property.
637         * @return this file's version oid, or <code>null</code> if this file is
638         * not version controlled
639         * @throws WvcmException if property was not requested
640         */
641        public String getVersionOid() throws WvcmException;
642    
643        /**
644         * The tag of the VOB in which this file resides.
645         */
646        PropertyName<CcVobTag> VOB_TAG =
647            new PropertyName<CcVobTag>(PROPERTY_NAMESPACE, "file-vob-tag");
648     
649        /**
650         * Get the value of this resource's {@link #VOB_TAG} property.
651         * @return the VOB tag for this file's VOB as a CcVobTag proxy, 
652         * or <code>null</code> if this file is not version controlled
653         * @throws WvcmException if property was not requested
654         */
655        public CcVobTag getVobTag() throws WvcmException;
656        
657        /**
658         * The CC element resource associated with this file.
659         * The value of this property will be null if this is not a version-
660         * controlled resource.
661         * @see javax.wvcm.ControllableResource#VERSION_HISTORY
662         */
663        PropertyName<CcElement> ELEMENT =
664            new PropertyName<CcElement>(PROPERTY_NAMESPACE, "element");
665    
666        /**
667         * Get the value of this resource's {@link #ELEMENT} property.
668         * @return this file's element, or <code>null</code> if this file is
669         * not version controlled
670         * @throws WvcmException if property was not requested
671         */
672        public CcElement getElement() throws WvcmException;
673    
674        /**
675         * Returns a {@link java.io.File File} representing the location of this
676         * client-side Resource in the local file system, else <code>null</code> if
677         * this Resource is a server-side resource only.
678         * @return The location of this Resource in the local file system, else
679         * <code>null</code> if this is a proxy to a server-side resource only.
680         * 
681         * @throws WvcmException Thrown if there was an error in determining the
682         * path for this client-side Resource.
683         */
684        File clientResourceFile() throws WvcmException;
685        
686        /**
687         * Reads the file's properties, if they are available locally on the client machine.
688         * @param feedback the properties to be available in the returned proxy,
689         *  and any other feedback desired, such as progress indications.
690         * @return a {@link CcFile} containing the wanted properties
691         * that are available locally on the client machine
692         * without communicating with the server.
693         * @see Resource#doReadProperties(Feedback) doReadProperties.
694         * @throws WvcmException ReasonCode:
695         * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}:
696         *  The file MUST be available locally on the client machine.
697         */
698        CcFile readProperties(Feedback feedback) throws WvcmException;
699    
700        /**
701         * Reads the file's content, if it is available locally on the client machine.
702         * @see Resource#doReadContent(OutputStream,Feedback) doReadContent
703         * @param feedback the properties to be available in the returned proxy,
704         *  and any other feedback desired, such as progress indications.
705         * @param content the file's content, if available, is written to this
706         * byte stream.  The stream is then closed.
707         * @return a CcFile proxy containing the wanted properties
708         * that are available on the client host without communicating with the server.
709         * @throws WvcmException ReasonCode:
710         * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}:
711         *  The file MUST be available locally on the client machine.
712         */
713        CcFile readContent(OutputStream content, Feedback feedback) throws WvcmException;
714    
715        /**
716         * Resolve this file resource, but do not consult the ClearCase server.
717         * Unlike {@link CcResource#doResolve()}, use only information currently
718         * available information on the local client machine.  
719         * @see CcResource#doResolve()
720         * @return a new file proxy of the correct, most specific resource type
721         * @throws WvcmException with NOT_FOUND reason code if this file does not
722         *         exist on the local machine.
723         */
724        CcFile resolve() throws WvcmException;
725    
726        /**
727         * Whether this file is loaded, partially loaded, or not loaded in the
728         * file area in which it resides.
729         */
730        PropertyName<LoadState> LOAD_STATE =
731            new PropertyName<LoadState>(PROPERTY_NAMESPACE, "load-state");
732    
733        /**
734         * Get the value of this resource's {@link #LOAD_STATE} property.
735         * @return LoadState.LOADED, LoadState.PARTIALLY_LOADED or LoadState.NOT_LOADED
736         * @throws WvcmException
737         *             if this proxy doesn't define a value for this property.
738         */
739        LoadState getLoadState() throws WvcmException;
740    
741        /**
742         * <p>Version controlled files and directories may have both client state -
743         * state maintained in a local file area - and server state.  When the
744         * client state and server state get out of synch, we call this <i>skew</i>.
745         * </p>
746         * <p>The caller can detect skew by including the {@link #SKEWED_PROPERTY_LIST}
747         * property in property requests to <code>doReadProperties()</code> and
748         * other <code>do</code> methods that accept property requests.
749         * The resulting value of this property is the list of names of properties
750         * in the request that differed between the client and the server for this
751         * particular file or directory.
752         * </p>
753         * <p>Note that only certain properties are checked for skew - properties
754         * where skew can cause significant problems.  For example,
755         * {@link #IS_CHECKED_OUT}, {@link #IS_VERSION_CONTROLLED}, and
756         * {@link #VERSION_OID}.
757         * </p>
758         * <p>Note also that <i>only</i> properties in the current property request
759         * are checked for skew.
760         * </p>
761         */
762        PropertyName<List<PropertyName>> SKEWED_PROPERTY_LIST =
763            new PropertyName<List<PropertyName>>(PROPERTY_NAMESPACE, "skewed-property-list");
764    
765        /**
766         * Get the value of this file's {@link #SKEWED_PROPERTY_LIST} property.
767         * @return a list of property names in the current property request whose
768         *         values differed between the client and the server for this file
769         *         or directory.
770         * @throws WvcmException
771         *             if this proxy doesn't define a value for this property.
772         */
773        List<PropertyName> getSkewedPropertyList() throws WvcmException;
774        
775        /**
776         * The config spec rule that selects this file.
777         */
778        PropertyName<String> SELECTION_RULE =
779            new PropertyName<String>(PROPERTY_NAMESPACE, "selection-rule");
780        
781        /**
782         * Get the value of this resource's {@link #SELECTION_RULE} property.
783         * @return this file's config spec rule, as a string.
784         * @throws WvcmException
785         *             if this proxy doesn't define a value for this property.
786         */
787        String getSelectionRule() throws WvcmException;
788        
789        /**
790         * The version of this file that is currently the latest on the same branch.
791         */
792        PropertyName<CcVersion> LATEST_VERSION_ON_BRANCH =
793            new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "latest-version-on-branch");
794        
795        /**
796         * Get the value of this resource's {@link #LATEST_VERSION_ON_BRANCH} property.
797         * @return the version of this file that is the latest on the same branch as the
798         * version in the view.
799         * @throws WvcmException
800         *             if this proxy doesn't define a value for this property.
801         */
802        CcVersion getLatestVersionOnBranch() throws WvcmException;
803    }