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