001/*
002 * Licensed Materials - Property of IBM and/or HCL
003 * Restricted Materials of IBM and/or HCL
004 *
005 * com.ibm.rational.wvcm.stp.cc.CcFile
006 *
007 * (C) Copyright IBM Corporation 2004, 2016.  All Rights Reserved.
008 * (C) Copyright HCL Technologies Ltd. 2017.  All Rights Reserved.
009 * Note to U.S. Government Users Restricted Rights:  Use, duplication or 
010 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp.
011 */
012package com.ibm.rational.wvcm.stp.cc;
013
014import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
015
016import java.io.File;
017import java.io.OutputStream;
018import java.util.List;
019
020import javax.wvcm.ControllableResource;
021import javax.wvcm.Feedback;
022import javax.wvcm.PropertyNameList.PropertyName;
023import javax.wvcm.Resource;
024import javax.wvcm.WvcmException;
025
026import com.ibm.rational.wvcm.stp.cc.CcVersion.CcMergeFlag;
027import com.ibm.rational.wvcm.stpex.StpExEnumeration;
028
029/**
030 * A proxy for a file, directory, or symbolic link resource in a ClearCase view.
031 * This resource is either under version control or could potentially be
032 * put under version control.
033 */
034public interface CcFile
035    extends CcResource, ControllableResource
036{
037    /** Flags for the doApplyAttribute and doRemoveAttribute methods */
038    enum AttributeOpFlag implements StpExEnumeration {
039
040        /**
041         * Replace existing attribute instance.
042         * (Only applies to doApplyAttribute)
043         */
044        REPLACE("replace"),
045
046        /**
047         * Apply/remove attribute recursively over sub-tree.
048         */
049        RECURSE("recurse"),
050
051        /**
052         * If the attribute type was created with a default value, uses
053         * that value for the attribute instead of the value specified in
054         * the call. An error occurs if the attribute type was not created 
055         * with a default value. 
056         * (Only applies to doApplyAttribute)
057         */
058        DEFAULT("default");
059        
060        private String m_name;
061
062        private AttributeOpFlag(String name) { m_name = name; }
063
064        /* (non-Javadoc)
065         * @see java.lang.Object#toString()
066         */
067        public String toString() { return m_name; }
068    }
069
070
071    /** Flags for the doApplyLabel method */
072    enum ApplyLabelFlag implements StpExEnumeration {
073
074        /**
075         * Replace existing label instance.
076         */
077        REPLACE("replace"),
078
079        /**
080         * Apply label recursively over sub-tree.
081         */
082        RECURSE("recurse"),
083
084        /**
085         * Follow symbolic links
086         */
087        FOLLOW_SYMLINKS("follow-symlinks");
088
089        private String m_name;
090
091        private ApplyLabelFlag(String name) { m_name = name; }
092
093        /* (non-Javadoc)
094         * @see java.lang.Object#toString()
095         */
096        public String toString() { return m_name; }
097    }
098    
099    /** Flags for the doRemoveLabel method */
100    enum RemoveLabelFlag implements StpExEnumeration {
101
102        /**
103         * Remove label recursively over sub-tree.
104         */
105        RECURSE("recurse"),
106
107        /**
108         * Follow symbolic links
109         */
110        FOLLOW_SYMLINKS("follow-symlinks");
111
112        private String m_name;
113
114        private RemoveLabelFlag(String name) { m_name = name; }
115
116        /* (non-Javadoc)
117         * @see java.lang.Object#toString()
118         */
119        public String toString() { return m_name; }
120    }
121
122    /** Flags for the doApplyRolemap method */
123    enum ApplyRolemapFlag {
124        /**
125         * Apply rolemap recursively over sub-tree, if one exists.
126         */
127        RECURSE("recurse"),
128        
129        /**
130         * Restricts the command to changing file elements only.
131         * (Mutually exclusive with DIRECTORY.)
132         */
133        FILE("file"),
134        
135        /**
136         * Restricts the command to changing directory elements only.
137         * (Mutually exclusive with FILE.)
138         */
139        DIRECTORY("directory");
140        
141        private final String m_flag;
142
143        ApplyRolemapFlag(String flag) {
144            m_flag = flag;
145        }
146
147        public String toString() {
148            return m_flag;
149        }
150    }
151
152    /** Flags for the doUncheckout method */
153    enum UncheckoutFlag implements StpExEnumeration {
154        /**
155         * Preserve changes in checked out version in a ".keep" file.
156         */
157        KEEP("keep");
158
159        private String m_name;
160
161        private UncheckoutFlag(String name) { m_name = name; }
162
163        /* (non-Javadoc)
164         * @see java.lang.Object#toString()
165         */
166        public String toString() { return m_name; }
167    }
168
169    /** Flags for the doUnhijack method */
170    enum UnhijackFlag implements StpExEnumeration {
171
172        /**
173         * Preserve changes in hijacked version in a ".keep" file.
174         */
175        KEEP("keep");
176
177        private UnhijackFlag(String name) { m_name = name; }
178
179        /* (non-Javadoc)
180         * @see java.lang.Object#toString()
181         */
182        public String toString() { return m_name; }
183
184        private String m_name;
185    }
186
187    /**
188     * Flags for the <code>doRefresh</code> and <code>doRestore</code> methods.
189     */
190    enum RefreshFlag implements StpExEnumeration {
191
192        /**
193         * Do <i>not</i> refresh hijacked files.
194         * Leave hijacked files in the hijacked state, and do not alter
195         * their contents.
196         * <p>
197         * Note: a deleted file or directory is considered to be hijacked.
198         * In order to refresh or restore a deleted file or directory,
199         * you must specify <code>OVERWRITE_HIJACKS</code> or
200         * <code>RENAME_HIJACKS</code>.
201         * </p>
202         * This is the default hijack behavior for both <code>doRefresh</code>
203         * and <code>doRestore</code>.
204         */
205        KEEP_HIJACKS("keep-hijacks"),
206
207        /**
208         * If a file being refreshed is hijacked in this view,
209         * overwrite the hijacked contents with the new version's contents.
210         * Do not preserve the hijacked contents.
211         */
212        OVERWRITE_HIJACKS("overwrite-hijacks"),
213
214        /**
215         * If a file being refreshed is hijacked in this view,
216         * preserve the hijacked contents by moving the hijacked file to
217         * <code><file-name>.keep</code>.
218         */
219        RENAME_HIJACKS("rename-hijacks"),
220
221        /**
222         * When refreshing a file to a different version, set the file's
223         * "last modified" time to be the time when the version was created.
224         * <br />
225         * Web View:
226         * By default, a refreshed file's "last modified" time will simply be
227         * the time when the <code>doRefresh</code> is performed.
228         * <br />
229         * Snapshot View:
230         * If <code>PRESERVE_CREATION_TIME</code> or 
231         * <code>USE_CURRENT_TIME</code> is not set then the file's
232         *  "last modified" time will be set based on
233         *  <code>CcView.PRESERVE_VOB_MODIFIED_TIME</code>.
234         */
235        PRESERVE_CREATION_TIME("preserve-creation-time"),
236        
237        /**
238         * When refreshing a file to a different version, set the file's
239         * "last modified" time to be the time when 
240         * <code>doRefresh</code> is performed on the Snapshot view resource.
241         * Not applicable for other view types.
242         * <br />
243         * If <code>PRESERVE_CREATION_TIME</code> or 
244         * <code>USE_CURRENT_TIME</code> is not set then the file's
245         *  "last modified" time will be set based on
246         *  <code>CcView.PRESERVE_VOB_MODIFIED_TIME</code>.
247         */
248        USE_CURRENT_TIME("use-current-time"),
249
250        /**
251         * Preview the refresh operation, but don't actually perform it.
252         * Invoke the caller's feedback methods to inform them what the
253         * refresh would do if it were performed right now.
254         */
255        PREVIEW_ONLY("preview-only"),
256        
257        /**
258         * Force the refresh/update of load-once rules in automatic views.
259         */
260        FORCE_LOAD_ONCE("force-load-once"),
261        
262        /**
263         * Resume a suspended update... 
264         * Applies only to automatic views
265         */
266        RESUME_UPDATE("resume-update"),
267        
268        /**
269         * Reset local view db - used to restore a view
270         * Applies only to automatic views
271         */
272        DO_RESET("do_reset"),
273        
274        /**
275         * Master DB is on server - used to restore a view
276         * Applies only to automatic views
277         */
278        RESTORE_FROM_SERVER("server"),
279        
280        /**
281         * Master DB is on client - used to restore a view
282         * Applies only to automatic views
283         */
284        RESTORE_FROM_CLIENT("client");
285
286        private String m_name;
287
288        private RefreshFlag(String name) { m_name = name; }
289
290        /* (non-Javadoc)
291         * @see java.lang.Object#toString()
292         */
293        public String toString() { return m_name; }
294    }
295    
296    /** Flags for the <code>doCcCheckin</code> method. */
297    enum CcCheckinFlag implements StpExEnumeration {
298
299        /**
300         * Check in the element even if the checked out version 
301         * is identical to the predecessor version.
302         */
303        CHECKIN_IDENTICAL("checkin-identical"),
304        
305        /**
306         * Preserve changes in checked out version in a ".keep" file.
307         * This is the default behaviour if using the FROM_FILE property.
308         * <p>Note: Currently, only dynamic and snapshot view support is provided. 
309         */
310        KEEP("keep"),
311        
312        /**
313         * Removes the view private copy of the checkout version after
314         * creating the new version.  This is the default for dynamic views if
315         * not using the FROM_FILE property.
316         * <p>Note: Currently, only dynamic and snapshot view support is provided. 
317         */
318        REMOVE("remove");
319
320        private String m_name;
321
322        private CcCheckinFlag(String name) { m_name = name; }
323
324        /* (non-Javadoc)
325         * @see java.lang.Object#toString()
326         */
327        public String toString() { return m_name; }
328       
329    }
330    
331    /** Flags for the <code>doCheckout</code> method. */
332    enum CcCheckoutFlag implements StpExEnumeration {
333        
334        /**
335         * Indicates whether to checkout this file reserved.
336         */
337        RESERVED("reserved"),
338        
339        /**
340         * Fall back to unreserved if a reservation can not be obtained.
341         */
342        FALLBACK_TO_UNRESERVED("fallback-to-unreserved"),
343        
344        /**
345         * Checkout the version of the file that is currently loaded in the
346         * view, even if that version is not the version selected by the
347         * view's config spec.
348         * 
349         * <p>If the loaded version is not the version selected by the view's
350         * config spec, and neither {@link #LOADED_NOT_LATEST} nor
351         * {@link #LATEST_NOT_LOADED} flags are set, the checkout operation
352         * will throw an exception with reason code <code>CHECKOUT_NOT_LATEST</code>.
353         */
354        LOADED_NOT_LATEST("checkout-loaded-not-latest"),
355        
356        /**
357         * Checkout the version of the file that is selected by the view's 
358         * config spec. If this version is not loaded at checkout time, then 
359         * load it prior to performing the checkout.
360         * 
361         * <p>If the loaded version is not the version selected by the view's
362         * config spec, and neither {@link #LOADED_NOT_LATEST} nor
363         * {@link #LATEST_NOT_LOADED} flags are set, the checkout operation
364         * will throw an exception with reason code <code>CHECKOUT_NOT_LATEST</code>.
365         */
366        LATEST_NOT_LOADED("checkout-latest-not-loaded"),
367        
368        /**
369         * For dynamic views only.
370         * 
371         * <p>Checkout the version of the file that is the latest on the branch
372         * even if that version is not currently selected by the view.
373         * 
374         * <p>If the version selected by the view's config spec is not the latest
375         * on the branch and neither {@link #LATEST_ON_BRANCH} nor 
376         * {@link #VIEW_SELECTED_VERSION} flags are specified, the checkout 
377         * operation will will throw an exception with reason code 
378         * <code>CHECKOUT_NOT_LATEST</code>.
379         */
380        LATEST_ON_BRANCH("latest-on-branch"),
381        
382        /**
383         * Indicates whether to checkout this file even if the currently
384         * selected branch is mastered by another replica. The
385         * <code>RESERVED</code> flag must NOT be set with this flag.
386         * 
387         * <p>If the file is mastered by this replica, setting this
388         * flag has no effect.
389         */
390        NON_MASTERED_OK("non-mastered-ok"),
391        
392        /**
393         * If the file is hijacked, keep the hijacked contents upon checkout.
394         */
395        PRESERVE_HIJACK_CONTENTS("preserve-hijack-contents"),
396        
397        /**
398         * After a file is 'checkedout', set the file's "last modified" 
399         * time to be the time when the version was first created.
400         * <p>This applies only to automatic, dynamic and snapshot views.
401         */
402        PRESERVE_MODIFICATION_TIME("preserve-modification-time"),  
403        
404        /**
405         * For dynamic views only.
406         * 
407         * <p>Checkout the version of the file that is currently selected by
408         * the view, even if that version is not the latest on the branch.
409         * 
410         * <p>If the version selected by the view's config spec is not the latest
411         * on the branch and neither {@link #LATEST_ON_BRANCH} nor 
412         * {@link #VIEW_SELECTED_VERSION} flags are specified, the checkout 
413         * operation will will throw an exception with reason code 
414         * <code>CHECKOUT_NOT_LATEST</code>.
415         */
416        VIEW_SELECTED_VERSION("view-selected-version");
417        
418        private String m_name;
419
420        private CcCheckoutFlag(String name) { m_name = name; }
421
422        /* (non-Javadoc)
423         * @see java.lang.Object#toString()
424         */
425        public String toString() { return m_name; }
426    }
427
428    /** Flags for the <code>doCcVersionControl</code> method. */
429    enum CcVersionControlFlag implements StpExEnumeration {
430        
431        /**
432         * Indicates whether to checkin this file after it is added to version control.
433         * The default is to leave it checked out.<p>
434         * This flag is mutually exclusive with {@link CcVersionControlFlag#NO_CHECKOUT}.
435         */
436        CHECKIN("checkin"),
437        
438        /**
439         * Do not checkout the file after adding to version control.<p>
440         * This flag is mutually exclusive with {@link CcVersionControlFlag#CHECKIN}.
441         */
442        NO_CHECKOUT("no-checkout"),
443        
444        /**
445         * Assigns mastership of the <b>main</b> branch of the newly version controlled
446         * file to the VOB replica in which you execute operation.  By default
447         * mastership of the file's <b>main</b> branch is assigned to the VOB replica 
448         * that masters the <b>main</b> branch type. <p>
449         * This flag is mutually exclusive with {@link CcVersionControlFlag#MAKE_PATH}.
450         */
451        MASTER_LOCALLY("master-locally"),
452        
453        /**
454         * Automatically checkout the version controlled parent directory and
455         * check back in after new file has been added to version control.
456         * Any view private parent directories below the version controlled parent
457         * and the desired file, will also be version controlled.<p>
458         * This flag is mutually exclusive with {@link CcVersionControlFlag#MASTER_LOCALLY}.
459         */
460        MAKE_PATH("mkpath");
461        
462        private String m_name;
463
464        private CcVersionControlFlag(String name) { m_name = name; }
465
466        /* (non-Javadoc)
467         * @see java.lang.Object#toString()
468         */
469        public String toString() { return m_name; }
470    }
471
472    /** Values for file or directory load state */
473    enum LoadState implements StpExEnumeration {
474
475        /**
476         * This file or directory is loaded in its file area.
477         */
478        LOADED,
479
480        /**
481         * This directory is partially loaded in its file area, i.e.,
482         * some but not all of its children are loaded.
483         */
484        PARTIALLY_LOADED,
485
486        /**
487         * This file or directory is not loaded in its file area.
488         */
489        NOT_LOADED;
490    }
491
492    /**
493     * Create a new view-private file at the location specified by this resource.
494     * The request will fail if a resource already exists at that location.
495     * @param feedback 
496     * @return a CcFile proxy for the new file
497     * @see javax.wvcm.ControllableResource#doCreateResource(Feedback)
498     */
499    public CcFile createCcFile(Feedback feedback) throws WvcmException;
500    
501    /**
502     * Apply the specified attribute to the checked-in version of this controllable resource.
503     * @param flags array of flags which specify the behavior of the operation
504     * @param comment Comment (if any) to be used for operation.  Empty string if none.
505     * @param attributeName Name of an existing attribute type to be used to create 
506     * an instance will to be applied to this resource.
507     * @param attributeValue Value of attribute instance.  If the vtype of the attribute type is
508     * a string, it must be enclosed in additional quotes <em>within the string</em>.  For example, if
509     * specified as a constant it would appear as <code>"\"string value\""</code>.  If the
510     * vtype is not a string, this should be a string representation of the given value 
511     * (e.g. <code>"3.1415"</code>, <code>"0xa413"</code>, etc.).
512     * @param versionId Applies the attribute to the explicitly specified version,
513     * overriding the version selected by the view. 
514     * This string must only represent the version suffix (e.g. /main/314).
515     * @param feedback 
516     * @return A new proxy for this resource, whose properties are specified by feedback.
517     * @throws WvcmException
518     */
519    ControllableResource doApplyAttribute(AttributeOpFlag[] flags, String comment, 
520            String attributeName, String attributeValue, String versionId, Feedback feedback)
521    throws WvcmException;
522    
523    /**
524     * Remove the specified attribute from the checked-in version of this controllable resource.
525     * @param flags array of flags which specify the behavior of the operation
526     * @param comment Comment (if any) to be used for operation.  Empty string if none.
527     * @param attributeName Name of the attribute to be removed from this resource
528     * @param versionId Removes the attribute from the explicitly specified version,
529     * overriding the version selected by the view.
530     * @param feedback 
531     * @return A new proxy for this resource, whose properties are specified by feedback.
532     * @throws WvcmException
533     */
534    ControllableResource doRemoveAttribute(AttributeOpFlag[] flags, String comment, 
535            String attributeName, String versionId, Feedback feedback)
536    throws WvcmException;
537
538    /**
539     * Apply the specified label to the checked-in version of this controllable resource.
540     * @param flags array of flags which specify the behavior of the operation    
541     * @param label the label to be added to this version
542     * @param feedback 
543     * @return A new proxy for this resource, whose properties are specified by feedback.
544     * @throws WvcmException
545     */
546    ControllableResource doApplyLabel(ApplyLabelFlag[] flags,
547            String label, Feedback feedback)
548        throws WvcmException;    
549    
550    /**
551     * Apply the specified label to the checked-in version of this controllable resource.
552     * @param flags array of flags which specify the behavior of the operation
553     * @param comment The comment for this operation, or null for no comment   
554     * @param label the label to be added to this version
555     * @param feedback 
556     * @return A new proxy for this resource, whose properties are specified by feedback.
557     * @throws WvcmException
558     */
559    ControllableResource doApplyLabel(ApplyLabelFlag[] flags, String comment,
560            String label, Feedback feedback)
561        throws WvcmException;
562    
563    /**
564     * Remove the specified label from the checked-in version of this controllable resource.
565     * @param flags array of flags which specify the behavior of the operation     
566     * @param label the label to be removed from this version
567     * @param feedback 
568     * @return A new proxy for this resource, whose properties are specified by feedback.
569     * @throws WvcmException
570     */
571    ControllableResource doRemoveLabel(RemoveLabelFlag[] flags,
572            String label, Feedback feedback)
573        throws WvcmException;
574    
575    /**
576     * Apply the specified rolemap to the element represented by this file/directory.
577     * @param flags array of flags which specify the behavior of the operation
578     * @param comment Comment (if any) to be used for operation.  Empty string if none.
579     * @param rolemap The name of the rolemap to be applied.
580     * @throws WvcmException
581     */
582    void doApplyRolemap(ApplyRolemapFlag[] flags, String comment, String rolemap)
583    throws WvcmException;
584    
585    /**
586     * <p>Check out this version-controlled file or directory resource.
587     * The resource is checked out to the ClearCase view implied by its location.
588     * </p>
589     * <p>If the view is a UCM view, the caller must insure there is a
590     * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation.
591     * The checked out file will be added to the current activity's change set.
592     * The caller may explicitly specify an activity using this resource's
593     * {@link javax.wvcm.ControllableResource#setActivity} method.  In that case,
594     * the specified activity will become the new current activity.
595     * Otherwise, the existing current activity will be used.
596     * If the view is a UCM view and there is no current activity, the operation
597     * will fail.
598     * </p>
599     * <p>The caller may optionally specify a checkout comment using this
600     * resource's {@link javax.wvcm.Resource#setComment} method.
601     * </p>
602     * @param flags array of flags which specify the behavior of the operation
603     * @param feedback 
604     * @return new CcFile proxy representing the checked out file.
605     * @throws WvcmException
606     */
607    CcFile doCcCheckout(CcCheckoutFlag[] flags, Feedback feedback)
608        throws WvcmException;
609
610    /**
611     * Cancel the checkout of this version-controlled resource,
612     * and restore its content to the state of its CHECKED_IN version.
613     * @param flags array of flags which specify the behavior of the operation
614     * @param feedback 
615     * @return new CcFile proxy representing the file whose checkout has been canceled
616     * @throws WvcmException
617     * @see javax.wvcm.ControllableResource#doUncheckout
618     */
619    CcFile doUncheckout(UncheckoutFlag[] flags, Feedback feedback)
620        throws WvcmException;
621
622    /**
623     * <p>Check in this checked out file or directory resource.
624     * </p>
625     * <p>If this resource is in a UCM view, it was added to an activity's
626     * change set at checkout time.  The caller may specify an alternate
627     * change set using this resource's
628     * {@link javax.wvcm.ControllableResource#setActivity} method just before
629     * calling <code>doCheckin</code>. 
630     * </p>
631     * <p>The caller may also specify a checkin comment using this
632     * resource's {@link javax.wvcm.Resource#setComment} method.
633     * This will override the comment specified at checkout time, if any.
634     * </p>
635     * @param flags array of flags which specify the behavior of the operation
636     * @param feedback 
637     * @return new ControllableResource proxy representing the checked in file.
638     * @throws WvcmException
639     * @see javax.wvcm.ControllableResource#doCheckin
640     * @see com.ibm.rational.wvcm.stp.cc.CcFile#doCheckout
641     */
642    ControllableResource doCcCheckin(CcCheckinFlag[] flags, Feedback feedback) 
643        throws WvcmException;
644
645    /**
646     * <p>Check in this checked out file or directory resource.
647     * </p>
648     * <p>If this resource is in a UCM view, it was added to an activity's
649     * change set at checkout time.  The caller may specify an alternate
650     * change set using this resource's
651     * {@link javax.wvcm.ControllableResource#setActivity} method just before
652     * calling <code>doCheckin</code>. 
653     * </p>
654     * <p>The caller may also specify a checkin comment using this
655     * resource's {@link javax.wvcm.Resource#setComment} method.
656     * This will override the comment specified at checkout time, if any.
657     * </p>
658     * @param flags array of flags which specify the behavior of the operation
659     * @param feedback 
660     * @return new ControllableResource proxy representing the checked in file.
661     * @throws WvcmException
662     * @see javax.wvcm.ControllableResource#doCheckin
663     * @see com.ibm.rational.wvcm.stp.cc.CcFile#doCheckout
664     */
665    ControllableResource doCheckin(CheckinFlag[] flags, Feedback feedback) 
666        throws WvcmException;
667
668    /**
669     * Merges the contents of two or more versions, representing files or 
670     * directories, into this file. Versions must be of the same element as this
671     * file.
672     * 
673     * @param baseVersion Base contributor. Can be null.
674     * @param contribList One or more contributing versions.
675     * @param flags Specify options for the merge. Can be null.
676     * @param listener Callback notifier for the merge.
677     * @param feedback 
678     * @return new CcFile proxy representing the merged file.
679     * @throws WvcmException if there is an error during the merge.
680     */
681    CcFile doMerge(CcVersion baseVersion,
682            List<CcVersion> contribList,
683            CcMergeFlag[] flags,
684            CcListener listener,
685            Feedback feedback) throws WvcmException;
686    
687    /**
688     * Places the view-private file specified by this proxy under version control.
689     * <p>If the view is a UCM view, the caller must insure there is a
690     * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation.
691     * The newly version controlled file will be added to the current activity's change set
692     * and left in a checked-in state.
693     * The caller may explicitly specify an activity using this resource's
694     * {@link javax.wvcm.ControllableResource#setActivity} method.  In that case,
695     * the specified activity will become the new current activity.
696     * Otherwise, the existing current activity will be used.
697     * If the view is a UCM view and there is no current activity, the operation
698     * will fail.
699     * </p>
700     * <p>The caller may optionally specify a creation comment using this
701     * resource's {@link javax.wvcm.Resource#setComment} method.
702     * </p>
703     * <p>The caller may optionally specify the type of element to be created using
704     * this resource's {@link com.ibm.rational.wvcm.stp.cc.CcFile#setElementType} method.
705     * </p>
706     * @param feedback
707     * @return new ControllableResource proxy representing the version controlled file.
708     * @throws WvcmException
709     * @see javax.wvcm.ControllableResource#doVersionControl(javax.wvcm.Feedback)
710     */
711    ControllableResource
712    doVersionControl(Feedback feedback)
713        throws WvcmException;
714
715    /**
716     * Enhanced variant of the doVersionControl that provides additional flags
717     * which modify the behaviour.<p>
718     * This method has two main difference from <code>doVersionControl</code>:
719     * <ol>
720     * <li>It does <b>not</b> automatically checkout the version controlled
721     * parent directory.  The caller must do this explicitly unless the
722     * {@link com.ibm.rational.wvcm.stp.cc.CcFile.CcVersionControlFlag#MAKE_PATH}
723     * flag is specified.
724     * <li>The newly version controlled file will be left in a checked-out state.
725     * To have the resulting file checked-in, specify the
726     * {@link com.ibm.rational.wvcm.stp.cc.CcFile.CcVersionControlFlag#CHECKIN} flag.
727     * </ol>
728     * @param flags array of flags which specify the behavior of the operation
729     * @param feedback
730     * @return A new proxy for this resource, whose properties are specified by feedback.
731     * @throws WvcmException
732     * @see com.ibm.rational.wvcm.stp.cc.CcFile#doVersionControl(javax.wvcm.Feedback)
733     */
734    ControllableResource
735    doCcVersionControl(CcVersionControlFlag flags[], Feedback feedback)
736        throws WvcmException;
737    
738    /**
739     * <p>
740     * Refresh this file or directory. Re-evaluate the
741     * view's config spec and update resources on the client to be whatever
742     * is currently selected by the config spec.  If this is a directory,
743     * recursively refresh its contents.
744     * </p>
745     * <p>
746     * Example: The config spec says "element * /main/LATEST", and you
747     * have version "/main/7" of this resource loaded. Someone else checks
748     * in a new version, thus creating a "/main/8". In that case,
749     * doRefresh() will cause version "/main/8" of this resource to
750     * be loaded into your view.
751     * </p>
752     * <p>
753     * Preconditions: This resource must be a version-controlled file
754     * or directory.
755     * </p>
756     * <p>
757     * Postconditions: This resource (and its descendants if this is a
758     * directory) are updated to be what is currently selected by the view's
759     * config spec.
760     * </p>
761     * @param flags array of flags which specify the behavior of the operation
762     * @param feedback (optional) a list of properties to fetch on the
763     * updated resources or a DetailedFeedback. If properties are provided,
764     * the returned resources will have them filled in.  If a DetailedFeedback
765     * is provided, the appropriate notification methods will be called for each
766     * resource which is refreshed as part of the operation.
767     * by doRefresh will have these properties filled in.
768     * @return a new CcFile proxy representing the refreshed file
769     * @throws WvcmException if the precondition is not met or if an error
770     */
771    CcFile doRefresh(RefreshFlag[] flags, Feedback feedback)
772       throws WvcmException;
773
774    /**
775     * <p>
776     * Refresh this file or directory. Re-evaluate the
777     * view's config spec and update resources on the client to be whatever
778     * is currently selected by the config spec.  If this is a directory,
779     * recursively refresh its contents.
780     * </p>
781     * <p>
782     * Example: The config spec says "element * /main/LATEST", and you
783     * have version "/main/7" of this resource loaded. Someone else checks
784     * in a new version, thus creating a "/main/8". In that case,
785     * doRefresh() will cause version "/main/8" of this resource to
786     * be loaded into your view.
787     * </p>
788     * <p>
789     * Preconditions: This resource must be a version-controlled file
790     * or directory.
791     * </p>
792     * <p>
793     * Postconditions: This resource (and its descendants if this is a
794     * directory) are updated to be what is currently selected by the view's
795     * config spec.
796     * </p>
797     * @param flags array of flags which specify the behavior of the operation
798     * @param listener Callback notifier for the merge.
799     * @param feedback (optional) a list of properties to fetch on the
800     * updated resources or a DetailedFeedback. If properties are provided,
801     * the returned resources will have them filled in.  If a DetailedFeedback
802     * is provided, the appropriate notification methods will be called for each
803     * resource which is refreshed as part of the operation.
804     * by doRefresh will have these properties filled in.
805     * @return a new CcFile proxy representing the refreshed file
806     * @throws WvcmException if the precondition is not met or if an error
807     */
808    CcFile doCcRefresh(RefreshFlag[] flags, CcListener listener, Feedback feedback)
809    throws WvcmException;
810    
811    /**
812     * <p>
813     * Restore this file or directory. If this is a directory, recursively
814     * restore its contents. This repairs any damage to the portion of the file
815     * area database specified by this resource.
816     * </p>
817     * 
818     * @param flags array of flags which specify the behavior of the operation
819     * @param feedback
820     * @return a new CcFile proxy representing the restored file
821     * @throws WvcmException
822     */
823    CcFile doRestore(RefreshFlag[] flags, Feedback feedback)
824       throws WvcmException;
825
826    /**
827     * <p>
828     * Load this controllable resource into a web or snapshot view's local 
829     * file area, or load the controllable resource into the automatic view.
830     * If this is a controllable folder, loads the tree of controllable
831     * resources under this folder. 
832     * Also updates the view's load rules if necessary
833     * to include this file or folder.
834     * </p>
835     * <p>
836     * If this resource was already loaded, doLoad is a no-op.
837     * </p>
838     * <p>
839     * Preconditions: This must be a version-controlled file or folder
840     * in a web, snapshot or automatic view.
841     * </p>
842     * <p>
843     * Postconditions: 
844     * </p>
845     * <p>
846     * This file, or the tree of files under this folder,
847     * is loaded into the view. Thus, the file(s) appear, and the view's
848     * load rules are updated to include this file or folder.
849     * </p>
850     * <p>
851     * Snapshot view: <br />
852     * This file, or the tree of files under this folder,
853     * is loaded into the view. Thus, the file(s) appear, and the view's
854     * load rules are updated to include this file or folder.
855     * </p>
856     * <p>
857     * Note that automatic views do not support load of individual 
858     * resources. Addition of a load rule for a controllable resource in an
859     * automatic view must be done directly in the config spec.
860     * </p>
861     * <p>
862     * Note that automatic views do not support load of individual 
863     * resources. Addition of a load rule for a controllable resource in an
864     * automatic view must be done directly in the config spec.
865     * </p>
866     * @param feedback (optional) feedback's notifyIsModified() method will be
867     *           called for each file or directory as it is loaded
868     * @return a new CcFile proxy for the file that has been loaded
869     * @throws WvcmException
870     */
871    CcFile doLoad(Feedback feedback) throws WvcmException;
872
873    /**
874     * Hijack this web, automatic or snapshot view controllable resource.
875     * Make the resource writable and set its "last modified" time to the
876     * current time.  This operation does <i>not</i> contact the server.
877     * @param feedback 
878     * @return a new CcFile proxy for the hijacked file
879     * @throws WvcmException
880     */
881    CcFile hijack(Feedback feedback)
882       throws WvcmException;
883    
884    /**
885     * Undo a hijack on this hijacked controllable resource.  Reload the file's
886     * contents from the appropriate version on the server.
887     * @param flags Specify <code>KEEP</code> to save a copy of the hijacked
888     * file's contents in a ".keep" file before undoing the hijack.
889     * @param feedback 
890     * @return a new CcFile proxy for the unhijacked file
891     * @throws WvcmException
892     */
893    CcFile doUnhijack(UnhijackFlag[] flags, Feedback feedback)
894       throws WvcmException;
895
896    /**
897      * For client resources, identifies the file system path to the local file
898      * representing this controllable resource.
899      */
900     PropertyName<File> CLIENT_PATH =
901         new PropertyName<File>(PROPERTY_NAMESPACE, "client-path");
902
903     /**
904      * Returns the value of this proxy's {@link #CLIENT_PATH} property.
905      * @return The path to this ControllableResource in the local file area.
906      *         Will never be <code>null</code>.
907      * @throws WvcmException if requested of a ControllableResource without client state
908      */
909     File getClientPath() throws WvcmException;
910
911     /**
912      * For version-controlled resources, this resource's element type.
913      */
914     PropertyName<CcElementType> ELEMENT_TYPE =
915         new PropertyName<CcElementType>(PROPERTY_NAMESPACE, "element-type");
916
917     /**
918      * Returns the value of this proxy's {@link #ELEMENT_TYPE} property.
919      * @return This resource's element type.  Will be <code>null</code>
920      *         if resource is not version-controlled.
921     * @throws WvcmException  if this proxy doesn't define a value for this property.
922      */
923     CcElementType getElementType() throws WvcmException;
924
925     /**
926      * Set the value of this file or directory's {@link #ELEMENT_TYPE} property.
927      * This property can only be set just prior to calling doVersionControl()
928      * on the resource.
929      * @param eltype resource's desired element type
930      */
931     void setElementType(CcElementType eltype);
932
933     /**
934      * For checked-out file, specifies an alternate
935      * location to provide content for the new version on checkin.
936      * Not supported for directories or atomic checkin.
937      * <p>Note: Currently, only dynamic and snapshot view support is provided. 
938      */
939     PropertyName<File> FROM_FILE =
940         new PropertyName<File>(PROPERTY_NAMESPACE, "from-file");
941
942     /**
943      * Set the value of this file's {@link #FROM_FILE} property.
944      * This property can only be set just prior to calling doCcCheckin()
945      * on the file.
946      * <p>Note: Currently, only dynamic and snapshot view support is provided. 
947      * @param source file for new version content
948      */
949     void setFromFile(File fromFile);
950
951     /**
952      * Is this file a web view file area database file?  File area DB files require
953      * special treatment.  For instance, they cannot be source controlled.
954      * For this reason, applications may choose to hide these files from
955      * the end user.
956      */
957    PropertyName<Boolean> IS_DB_FILE =
958        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-db-file");
959
960    /**
961     * Get the value of this files {@link #IS_DB_FILE} property.
962     * @return true if this file is a file area database file, else false
963     * @throws WvcmException
964     *             if this proxy doesn't define a value for this property.
965     */
966    public boolean getIsDbFile() throws WvcmException;
967
968    /**
969     * Is this a view-private file that is eclipsing a VOB file with
970     * the same name? 
971     */
972    PropertyName<Boolean> IS_ECLIPSING = 
973            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-eclipsing");
974    
975    /**
976     * Get the value of this files {@link #IS_ECLIPSING} property.
977     * @return {@code true} if this is a view-private file that eclipses a VOB file 
978     * with the same name, else {@code false}
979     * @throws WvcmException
980     *             if this proxy doesn't define a value for this property.
981     */
982    public boolean getIsEclipsing() throws WvcmException;
983
984    /**
985     * Property which is true/false depending on whether this version-controlled 
986     * resource has been hijacked.
987     */
988    PropertyName<Boolean> IS_HIJACKED =
989        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-hijacked");
990
991    /**
992     * Get the value of this file's {@link #IS_HIJACKED} property.
993     * @return true if the file is hijacked, false otherwise
994     * @throws WvcmException
995     *             if this proxy doesn't define a value for this property.
996    */
997    public boolean getIsHijacked() throws WvcmException;
998
999    /**
1000     * Is this file actually a symbolic link?
1001     */
1002    PropertyName<Boolean> IS_SYMLINK =
1003        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-symlink");
1004
1005    /**
1006     * Get the value of the {@link #IS_SYMLINK} property.
1007     * @return true if this resource is a symbolic link, false otherwise.
1008     * @throws WvcmException
1009     *             if this proxy doesn't define a value for this property.
1010    */
1011    public boolean getIsSymlink() throws WvcmException;
1012
1013    /**
1014     * Returns the direct parent of this file.  The value will
1015     * be <code>null</code> if the file has no parent (e.g. VOB root).
1016     * Does not find parents of hard-linked names for the file.
1017     */
1018    public static final PropertyName<CcFile> PARENT =
1019        new PropertyName<CcFile>(PROPERTY_NAMESPACE, "cc-parent");
1020    
1021    /**
1022     * Get the value of the {@link #PARENT} property.
1023     * @return A CcFile proxy for the parent, null if no parent
1024     * @throws WvcmException
1025     */
1026    public CcFile getParent() throws WvcmException;
1027
1028    /**
1029     * <p>If this file is actually a symbolic link, the path to its target file
1030     * or directory.  The path is interpreted relative to this file's parent 
1031     * directory.</p>
1032     * 
1033     * <p>If this file is not a symbolic link, this value will be 
1034     * <code>null</code>.</p>
1035     */
1036    PropertyName<String> SYMLINK_TARGET_PATH =
1037        new PropertyName<String>(PROPERTY_NAMESPACE, "symlink-target-path");
1038
1039    /**
1040     * Get the value of this resource's {@link #SYMLINK_TARGET_PATH} property.
1041     * @return path to symlink's target file or directory, or <code>null</code>
1042     *         if this file is not a symbolic link.
1043     * @throws WvcmException if property was not requested
1044     */
1045    public String getSymlinkTargetPath() throws WvcmException;
1046
1047    /**
1048     * The view-relative path for this resource.
1049     */
1050    PropertyName<String> VIEW_RELATIVE_PATH =
1051        new PropertyName<String>(PROPERTY_NAMESPACE, "cr-view-relative-path");
1052
1053    /**
1054     * Get the value of this resource's {@link #VIEW_RELATIVE_PATH} property.
1055     * @return view-relative path
1056     * @throws WvcmException if property was not requested
1057     */
1058    public String getViewRelativePath() throws WvcmException;
1059
1060    /**
1061     * The CC version resource associated with this file.
1062     * The value of this property will be null if this is not a version-
1063     * controlled resource.
1064     * @see javax.wvcm.ControllableResource#CHECKED_IN and 
1065     * javax.wvcm.ControllableResource#CHECKED_OUT
1066     */
1067    PropertyName<CcVersion> VERSION =
1068        new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "version");
1069
1070    /**
1071     * Get the value of this resource's {@link #VERSION} property.
1072     * @return this file's version, or <code>null</code> if this file is
1073     * not version controlled
1074     * @throws WvcmException if property was not requested
1075     */
1076    public CcVersion getVersion() throws WvcmException;
1077
1078    /**
1079     * The OID of the CC version resource associated with this file.
1080     * The value of this property will be null if this is not a version-
1081     * controlled resource.
1082     */
1083    PropertyName<String> VERSION_OID =
1084        new PropertyName<String>(PROPERTY_NAMESPACE, "version-oid");
1085
1086    /**
1087     * Get the value of this resource's {@link #VERSION_OID} property.
1088     * @return this file's version oid, or <code>null</code> if this file is
1089     * not version controlled
1090     * @throws WvcmException if property was not requested
1091     */
1092    public String getVersionOid() throws WvcmException;
1093
1094    /**
1095     * The tag of the VOB in which this file resides.
1096     */
1097    PropertyName<CcVobTag> VOB_TAG =
1098        new PropertyName<CcVobTag>(PROPERTY_NAMESPACE, "file-vob-tag");
1099 
1100    /**
1101     * Get the value of this resource's {@link #VOB_TAG} property.
1102     * @return the VOB tag for this file's VOB as a CcVobTag proxy, 
1103     * or <code>null</code> if this file is not version controlled
1104     * @throws WvcmException if property was not requested
1105     */
1106    public CcVobTag getVobTag() throws WvcmException;
1107    
1108    /**
1109     * The CC element resource associated with this file.
1110     * The value of this property will be null if this is not a version-
1111     * controlled resource.
1112     * @see javax.wvcm.ControllableResource#VERSION_HISTORY
1113     */
1114    PropertyName<CcElement> ELEMENT =
1115        new PropertyName<CcElement>(PROPERTY_NAMESPACE, "element");
1116
1117    /**
1118     * Get the value of this resource's {@link #ELEMENT} property.
1119     * @return this file's element, or <code>null</code> if this file is
1120     * not version controlled
1121     * @throws WvcmException if property was not requested
1122     */
1123    public CcElement getElement() throws WvcmException;
1124
1125    /**
1126     * Returns a {@link java.io.File File} representing the location of this
1127     * client-side resource in the local file system, else <code>null</code> if
1128     * this resource is a server-side resource only, e.g., if it is a proxy
1129     * to an unloaded file in a web view.
1130     * @return The location of this resource in the local file system, else
1131     * <code>null</code> if this is a proxy to a server-side resource only.
1132     * 
1133     * @throws WvcmException Thrown if there was an error in determining the
1134     * path for this client-side Resource.
1135     */
1136    File clientResourceFile() throws WvcmException;
1137    
1138    /**
1139     * Reads the file's properties, if they are available locally on the client machine.
1140     * @param feedback the properties to be available in the returned proxy,
1141     *  and any other feedback desired, such as progress indications.
1142     * @return a {@link CcFile} containing the wanted properties
1143     * that are available locally on the client machine
1144     * without communicating with the server.
1145     * Note that there is an exception to this for automatic views, where a request to
1146     * a connected automatic view may result in server communication to update local 
1147     * cached data. 
1148     * @see Resource#doReadProperties(Feedback) doReadProperties.
1149     * @throws WvcmException ReasonCode:
1150     * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}:
1151     *  The file MUST be available locally on the client machine.
1152     */
1153    CcFile readProperties(Feedback feedback) throws WvcmException;
1154
1155    /**
1156     * Reads the file's content, if it is available locally on the client machine.
1157     * @see Resource#doReadContent(OutputStream,Feedback) doReadContent
1158     * @param feedback the properties to be available in the returned proxy,
1159     *  and any other feedback desired, such as progress indications.
1160     * @param content the file's content, if available, is written to this
1161     * byte stream.  The stream is then closed.
1162     * @return a CcFile proxy containing the wanted properties
1163     * that are available on the client host without communicating with the server. 
1164     * Note that there is an exception to this for automatic views, where a request to
1165     * a connected automatic view may result in server communication to update local 
1166     * cached data. 
1167     * @throws WvcmException ReasonCode:
1168     * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}:
1169     *  The file MUST be available locally on the client machine.
1170     */
1171    CcFile readContent(OutputStream content, Feedback feedback) throws WvcmException;
1172
1173    /**
1174     * Resolve this file resource, but do not consult the ClearCase server.
1175     * Unlike {@link CcResource#doResolve()}, use only information currently
1176     * available information on the local client machine.  
1177     * @see CcResource#doResolve()
1178     * @return a new file proxy of the correct, most specific resource type
1179     * @throws WvcmException with NOT_FOUND reason code if this file does not
1180     *         exist on the local machine.
1181     */
1182    CcFile resolve() throws WvcmException;
1183    
1184    /**
1185     * Whether this file is loaded, partially loaded, or not loaded in
1186     * the file area in which it resides.
1187     */
1188    PropertyName<LoadState> LOAD_STATE =
1189        new PropertyName<LoadState>(PROPERTY_NAMESPACE, "load-state");
1190
1191    /**
1192     * Get the value of this resource's {@link #LOAD_STATE} property.
1193     * @return LoadState.LOADED, LoadState.PARTIALLY_LOADED or LoadState.NOT_LOADED
1194     * @throws WvcmException
1195     *             if this proxy doesn't define a value for this property.
1196     */
1197    LoadState getLoadState() throws WvcmException;
1198
1199    /**
1200     * <p>Version controlled files and directories in a web view
1201     * may have both client state -
1202     * state maintained in a local file area - and server state.  When the
1203     * client state and server state get out of sync, we call this <i>skew</i>.
1204     * </p>
1205     * <p>By definition, skew cannot occur in a dynamic or snapshot view.
1206     * </p>
1207     * <p>The caller can detect skew by including the {@link #SKEWED_PROPERTY_LIST}
1208     * property in property requests to <code>doReadProperties()</code> and
1209     * other <code>do</code> methods that accept property requests.
1210     * 
1211     * The resulting value of this property is the list of property names
1212     * in the request that differed between the client and the server for this
1213     * particular file or directory.
1214     * </p>
1215     * <p>Note that only certain properties are checked for skew - properties
1216     * where skew can cause significant problems.  For example,
1217     * {@link #IS_CHECKED_OUT}, {@link #IS_VERSION_CONTROLLED}, and
1218     * {@link #VERSION_OID}.
1219     * 
1220     * Note that skew can also be caused by elementness skew (file vs dir) and
1221     * loadness skew (loaded vs unloaded).
1222     * </p>
1223     * <p>Note also that <i>only</i> properties in the current property request
1224     * are checked for skew.
1225     * </p>
1226     * <p>NOTE: This should be used only as a trigger to do a real discordance
1227     * scan of the directory. These values are not reliable enough to use for
1228     * icon decoration or user messages. This is a quick and easy way to 
1229     * automatically detect skew, but it does not cover all edge cases 
1230     * (symlinks, aliases, and others) or discordance types.
1231     * </p>
1232     */
1233    PropertyName<List<PropertyName>> SKEWED_PROPERTY_LIST =
1234        new PropertyName<List<PropertyName>>(PROPERTY_NAMESPACE, "skewed-property-list");
1235
1236    /**
1237     * Get the value of this file's {@link #SKEWED_PROPERTY_LIST} property.
1238     * 
1239     * NOTE: This should be used only as a trigger to do a real discordance
1240     * scan of the directory. These values are not reliable enough to use for
1241     * icon decoration or user messages. This is a quick and easy way to 
1242     * automatically detect skew, but it does not cover all edge cases 
1243     * (symlinks, aliases, and others) or discordance types.
1244     * 
1245     * @return a list of property names in the current property request whose
1246     *         values differed between the client and the server for this file
1247     *         or directory.
1248     * @throws WvcmException
1249     *             if this proxy doesn't define a value for this property.
1250     */
1251    List<PropertyName> getSkewedPropertyList() throws WvcmException;
1252    
1253    /**
1254     * The config spec rule that selects this file.
1255     */
1256    PropertyName<String> SELECTION_RULE =
1257        new PropertyName<String>(PROPERTY_NAMESPACE, "selection-rule");
1258    
1259    /**
1260     * Get the value of this resource's {@link #SELECTION_RULE} property.
1261     * @return this file's config spec rule, as a string.
1262     * @throws WvcmException
1263     *             if this proxy doesn't define a value for this property.
1264     */
1265    String getSelectionRule() throws WvcmException;
1266    
1267    /**
1268     * The version of this file that is currently the latest on the same branch.
1269     */
1270    PropertyName<CcVersion> LATEST_VERSION_ON_BRANCH =
1271        new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "latest-version-on-branch");
1272    
1273    /**
1274     * Get the value of this resource's {@link #LATEST_VERSION_ON_BRANCH} property.
1275     * @return the version of this file that is the latest on the same branch as the
1276     * version in the view.
1277     * @throws WvcmException
1278     *             if this proxy doesn't define a value for this property.
1279     */
1280    CcVersion getLatestVersionOnBranch() throws WvcmException;
1281}