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
014package com.ibm.rational.wvcm.stp.cc;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import javax.wvcm.Feedback;
019import javax.wvcm.PropertyNameList.PropertyName;
020import javax.wvcm.ResourceList;
021import javax.wvcm.Task;
022import javax.wvcm.Version;
023import 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 */
044public 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}