001    /*
002     * file CcVersion.java
003     *
004     * Licensed Materials - Property of IBM
005     * Restricted Materials of IBM 
006     *
007     * com.ibm.rational.wvcm.stp.cc.CcVersion
008     *
009     * (C) Copyright IBM Corporation 2004, 2016.  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    
014    package com.ibm.rational.wvcm.stp.cc;
015    
016    import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017    
018    import javax.wvcm.Feedback;
019    import javax.wvcm.PropertyNameList.PropertyName;
020    import javax.wvcm.ResourceList;
021    import javax.wvcm.Task;
022    import javax.wvcm.Version;
023    import javax.wvcm.WvcmException;
024    
025    /**
026     * <p>
027     * A proxy for a version of a ClearCase element.
028     * </p>
029     * <p>
030     * Each time a new revision of a version-controlled file or 
031     * directory is checked in, a new <i>version</i> of that element is created. 
032     * Versions are created, in sequence, on the branch of an element selected
033     * by the view's config spec. 
034     * </p>
035     * <p>
036     * For more information about version, see the ClearCase "Guide to Developing Software"
037     * manual.
038     * </p>
039     * @see com.ibm.rational.wvcm.stp.cc.CcBranch
040     * @see com.ibm.rational.wvcm.stp.cc.CcElement
041     * @see com.ibm.rational.wvcm.stp.cc.CcConfigSpec
042     * @see com.ibm.rational.wvcm.stp.cc.CcBranchType
043     */
044    public interface CcVersion
045        extends Version, CcVobResource 
046    {    
047        /** Flags for the <code>doCcCheckout</code> method. */
048        enum CcCheckoutFlag {
049            
050            /**
051             * Indicates whether to checkout this file reserved.
052             */
053            RESERVED,
054            
055            /**
056             * Fall back to unreserved if a reservation can not be obtained.
057             */
058            FALLBACK_TO_UNRESERVED,
059            
060            /**
061             * Indicates whether to checkout this file even if the
062             * relevant branch is mastered by another replica. The
063             * <code>RESERVED</code> flag must NOT be set with this flag.
064             * 
065             * <p>If the file is mastered by this replica, setting this
066             * flag has no effect.
067             */
068            NON_MASTERED_OK,
069            
070            /**
071             * After a file is 'checkedout', set the file's "last modified" 
072             * time to be the time when the version was first created.
073             * <p>This only applies to dynamic views.
074             */
075            PRESERVE_MODIFICATION_TIME;
076        }
077    
078        
079        /** Flags for the doMerge method */
080        enum CcMergeFlag {
081            /**
082             * Informs the merge that there is no data being sent.
083             * Just draw the merge arrow.
084             * Can not be specified with NO_ARROWS flag.
085             */
086            NO_DATA,
087            /**
088             * Requests to only merge the data sent. Do not draw the merge arrow.
089             * Can not be specified with NO_DATA flag.
090             */
091            NO_ARROWS,
092            /**
093             * If a merge arrow already exists, this will delete and replace that 
094             * merge arrow. Does nothing when specified with the NO_ARROWS flag.
095             * This flag is currently unsupported for merge in automatic views.
096             */
097            REPLACE;
098        }
099        
100        /**
101         * This version's branch.
102         */
103        PropertyName<CcBranch> BRANCH =
104            new PropertyName<CcBranch>(PROPERTY_NAMESPACE, "version-branch");
105    
106        /**
107         * Get the value of this version's {@link #BRANCH} property.
108         * 
109         * @return a proxy for this version's branch
110         * @throws WvcmException if property was not requested
111         */
112        public CcBranch getBranch() throws WvcmException;
113    
114        /**
115         * This version's element.
116         * @see javax.wvcm.Version#VERSION_HISTORY
117         */
118        PropertyName<CcElement> ELEMENT =
119            new PropertyName<CcElement>(PROPERTY_NAMESPACE, "version-element");
120    
121        /**
122         * Get the value of this version's {@link #ELEMENT} property.
123         * 
124         * @return a proxy for this version's element
125         * @throws WvcmException if property was not requested
126         */
127        public CcElement getElement() throws WvcmException;
128    
129        /**
130         * <p>
131         * The view-relative path for this version, possibly including
132         * the version extension.
133         * </p>
134         * <p>
135         * NOTE: This property is only available if it is retrieved
136         * using a method with a view context, such as
137         * Resource.doReadProperties(CcView, PropertyRequest).
138         * ClearCase needs a view context to resolve version paths.
139         * </p>
140         */
141        PropertyName<String> VIEW_RELATIVE_PATH =
142            new PropertyName<String>(PROPERTY_NAMESPACE, "version-view-relative-path");
143    
144        /**
145         * Get the value of this version's {@link #VIEW_RELATIVE_PATH} property.
146         * 
147         * @return view-relative path
148         * @throws WvcmException
149         *     if property was not requested, or if the view context
150         *     was not provided
151         */
152        public String getViewRelativePath() throws WvcmException;
153        
154        /**
155         * <p>
156         * The immediate predecessor of this version on this version's branch,
157         * or if this is the first version on the branch, the version from
158         * which the branch emanates.  Will be <code>null</code> if this version
159         * is the <code>/main/0</code> version of its element.
160         * </p>
161         */
162        PropertyName<CcVersion> PREDECESSOR = 
163            new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "predecessor");
164        
165        /**
166         * Get the value of this version's {@link #PREDECESSOR} property.
167         * @return a CcVersion proxy for this version's predecessor.
168         * @throws WvcmException if property was not requested.
169         */
170        public CcVersion getPredecessor() throws WvcmException;
171        
172        /**
173         * <p>
174         * The list of versions that were merged to create this version.
175         * This will be empty if this version was not created by a merge
176         * operation.
177         * </p>
178         */
179        PropertyName<ResourceList<CcVersion>> MERGE_CONTRIBUTOR_LIST = 
180            new PropertyName<ResourceList<CcVersion>>(PROPERTY_NAMESPACE, "merge-contributor-list");
181    
182        /**
183         * Get the value of this version's {@link #MERGE_CONTRIBUTOR_LIST} property.
184         * @return a list of the CcVersion proxies which represent merge contributors for this version.
185         * @throws WvcmException if property was not requested.
186         */
187        public ResourceList<CcVersion> getMergeContributorList() throws WvcmException;
188        
189        /**
190         * The list of tasks associated with this version.
191         */
192        public PropertyName<ResourceList<Task>> TASK_LIST =
193            new PropertyName<ResourceList<Task>>(PROPERTY_NAMESPACE, "version-task-list");
194        
195        /**
196         * Get the value of this versions's (@link #TASK_LIST) property.
197         * @return a list of the tasks associated with this version. 
198         * @throws WvcmException if property was not requested.
199         */
200        public ResourceList<Task> getTaskList() throws WvcmException;
201        
202        /**
203         * Set the specified list of tasks as being associated with this version.
204         * Overwrites any existing associations.  Can be used to clear all associations
205         * by setting an empty list.
206         * @param tasks List of tasks to be associated with this version.
207         */
208        public void setTaskList(ResourceList<Task> tasks) throws WvcmException;
209        
210        /**
211         * Modify the list of tasks associated with this version by adding and
212         * removing the items from the specified lists.
213         * An intersection between the addition and removal lists is considered an error.
214         * @param taskAdditions List of tasks to be added to the list of 
215         * associations for this version.  Items in this list which are already associated
216         * with the version are ignored.
217         * @param taskRemovals List of tasks to be removed from the list of 
218         * associations for this version.  Items in this list which are not associated
219         * with the version are ignored.
220         */
221        public void setTaskList(ResourceList<Task> taskAdditions, ResourceList<Task> taskRemovals) throws WvcmException;
222    
223        /**
224         * Add the specified label to the version.
225         * @param label Label to be applied
226         * @param view View context
227         * @throws WvcmException
228         * @see javax.wvcm.Version#doAddLabel(java.lang.String, javax.wvcm.Feedback)
229         */
230        public Version doAddLabel(String label, CcView view, Feedback feedback) throws WvcmException;    
231        
232        /**
233         * Add the specified label to the version.
234         * @param comment The comment for this operation, or null for no comment
235         * @param label Label to be applied
236         * @param view View context
237         * @throws WvcmException
238         * @see javax.wvcm.Version#doAddLabel(java.lang.String, javax.wvcm.Feedback)
239         */
240        public Version doAddLabel(String comment, String label, CcView view, Feedback feedback) throws WvcmException;
241    
242        /**
243         * Set the specified label on the version.
244         * @param label Label to be applied
245         * @param view View context
246         * @throws WvcmException
247         * @see javax.wvcm.Version#doSetLabel(java.lang.String, javax.wvcm.Feedback)
248         */
249        public Version doSetLabel(String label, CcView view, Feedback feedback) throws WvcmException;    
250        
251        
252        /**
253         * Set the specified label on the version.
254         * @param comment The comment for this operation, or null for no comment
255         * @param label Label to be applied
256         * @param view View context
257         * @throws WvcmException
258         * @see javax.wvcm.Version#doSetLabel(java.lang.String, javax.wvcm.Feedback)
259         */
260        public Version doSetLabel(String comment, String label, CcView view, Feedback feedback) throws WvcmException;
261        
262        /**
263         * Remove the specified label from the version.
264         * @param label Label to be removed
265         * @param view View context
266         * @throws WvcmException
267         * @see javax.wvcm.Version#doRemoveLabel(java.lang.String, javax.wvcm.Feedback)
268         */
269        public Version doRemoveLabel(String label, CcView view, Feedback feedback) throws WvcmException;
270    
271        /**
272         * Create a Merge hyperlink pointing from this version to the specified destination version.
273         * @param toVersion Destination version for the hyperlink
274         * @return A new proxy for this version, whose properties are specified by feedback.
275         */
276        public CcVersion doCreateMergeArrow(CcVersion toVersion, Feedback feedback) throws WvcmException;
277        
278        /**
279         * Create a Merge hyperlink pointing from this version to the specified destination version.
280         * @param toVersion Destination version for the hyperlink
281         * @param view View context (ensures path EVs set for mkhlink when a merge is being made).
282         * @return A new proxy for this version, whose properties are specified by feedback.
283         */
284        public CcVersion doCreateMergeArrow(CcVersion toVersion, CcView view, Feedback feedback) throws WvcmException;
285        
286        /**
287         * <p>Check out the specific version of a file or directory specified
288         * by this proxy.  The resource is checked out to the specified ClearCase view.
289         * Note that directory version checkout is only supported for dynamic views.
290         * </p>
291         * <p>If the view is a UCM view, the caller must insure there is a
292         * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation.
293         * The checked out file will be added to the current activity's change set.
294         * The caller may explicitly specify an activity using this resource's
295         * {@link javax.wvcm.ControllableResource#setActivity} method.  In that case,
296         * the specified activity will become the new current activity.
297         * Otherwise, the existing current activity will be used.
298         * If the view is a UCM view and there is no current activity, the operation
299         * will fail.
300         * </p>
301         * <p>The caller may optionally specify a checkout comment using this
302         * resource's {@link javax.wvcm.Resource#setComment} method.
303         * </p>
304         * @param flags array of flags which specify the behavior of the operation
305         * @param view View context
306         * @param feedback 
307         * @return new CcFile proxy representing the checked out file in the specified view
308         * @throws WvcmException
309         */    
310        CcFile doCcCheckout(CcCheckoutFlag[] flags, CcView view, Feedback feedback)
311            throws WvcmException;
312    
313        
314    }