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, 2015.  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 doMerge method */
048    enum CcMergeFlag {
049        /**
050         * Informs the merge that there is no data being sent.
051         * Just draw the merge arrow.
052         * Can not be specified with NO_ARROWS flag.
053         */
054        NO_DATA,
055        /**
056         * Requests to only merge the data sent. Do not draw the merge arrow.
057         * Can not be specified with NO_DATA flag.
058         */
059        NO_ARROWS,
060        /**
061         * If a merge arrow already exists, this will delete and replace that 
062         * merge arrow. Does nothing when specified with the NO_ARROWS flag.
063         * This flag is currently unsupported for merge in automatic views.
064         */
065        REPLACE;
066    }
067    
068    /**
069     * This version's branch.
070     */
071    PropertyName<CcBranch> BRANCH =
072        new PropertyName<CcBranch>(PROPERTY_NAMESPACE, "version-branch");
073
074    /**
075     * Get the value of this version's {@link #BRANCH} property.
076     * 
077     * @return a proxy for this version's branch
078     * @throws WvcmException if property was not requested
079     */
080    public CcBranch getBranch() throws WvcmException;
081
082    /**
083     * This version's element.
084     * @see javax.wvcm.Version#VERSION_HISTORY
085     */
086    PropertyName<CcElement> ELEMENT =
087        new PropertyName<CcElement>(PROPERTY_NAMESPACE, "version-element");
088
089    /**
090     * Get the value of this version's {@link #ELEMENT} property.
091     * 
092     * @return a proxy for this version's element
093     * @throws WvcmException if property was not requested
094     */
095    public CcElement getElement() throws WvcmException;
096
097    /**
098     * <p>
099     * The view-relative path for this version, possibly including
100     * the version extension.
101     * </p>
102     * <p>
103     * NOTE: This property is only available if it is retrieved
104     * using a method with a view context, such as
105     * Resource.doReadProperties(CcView, PropertyRequest).
106     * ClearCase needs a view context to resolve version paths.
107     * </p>
108     */
109    PropertyName<String> VIEW_RELATIVE_PATH =
110        new PropertyName<String>(PROPERTY_NAMESPACE, "version-view-relative-path");
111
112    /**
113     * Get the value of this version's {@link #VIEW_RELATIVE_PATH} property.
114     * 
115     * @return view-relative path
116     * @throws WvcmException
117     *     if property was not requested, or if the view context
118     *     was not provided
119     */
120    public String getViewRelativePath() throws WvcmException;
121    
122    /**
123     * <p>
124     * The immediate predecessor of this version on this version's branch,
125     * or if this is the first version on the branch, the version from
126     * which the branch emanates.  Will be <code>null</code> if this version
127     * is the <code>/main/0</code> version of its element.
128     * </p>
129     */
130    PropertyName<CcVersion> PREDECESSOR = 
131        new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "predecessor");
132    
133    /**
134     * Get the value of this version's {@link #PREDECESSOR} property.
135     * @return a CcVersion proxy for this version's predecessor.
136     * @throws WvcmException if property was not requested.
137     */
138    public CcVersion getPredecessor() throws WvcmException;
139    
140    /**
141     * <p>
142     * The list of versions that were merged to create this version.
143     * This will be empty if this version was not created by a merge
144     * operation.
145     * </p>
146     */
147    PropertyName<ResourceList<CcVersion>> MERGE_CONTRIBUTOR_LIST = 
148        new PropertyName<ResourceList<CcVersion>>(PROPERTY_NAMESPACE, "merge-contributor-list");
149
150    /**
151     * Get the value of this version's {@link #MERGE_CONTRIBUTOR_LIST} property.
152     * @return a list of the CcVersion proxies which represent merge contributors for this version.
153     * @throws WvcmException if property was not requested.
154     */
155    public ResourceList<CcVersion> getMergeContributorList() throws WvcmException;
156    
157    /**
158     * The list of tasks associated with this version.
159     */
160    public PropertyName<ResourceList<Task>> TASK_LIST =
161        new PropertyName<ResourceList<Task>>(PROPERTY_NAMESPACE, "version-task-list");
162    
163    /**
164     * Get the value of this versions's (@link #TASK_LIST) property.
165     * @return a list of the tasks associated with this version. 
166     * @throws WvcmException if property was not requested.
167     */
168    public ResourceList<Task> getTaskList() throws WvcmException;
169    
170    /**
171     * Set the specified list of tasks as being associated with this version.
172     * Overwrites any existing associations.  Can be used to clear all associations
173     * by setting an empty list.
174     * @param tasks List of tasks to be associated with this version.
175     */
176    public void setTaskList(ResourceList<Task> tasks) throws WvcmException;
177    
178    /**
179     * Modify the list of tasks associated with this version by adding and
180     * removing the items from the specified lists.
181     * An intersection between the addition and removal lists is considered an error.
182     * @param taskAdditions List of tasks to be added to the list of 
183     * associations for this version.  Items in this list which are already associated
184     * with the version are ignored.
185     * @param taskRemovals List of tasks to be removed from the list of 
186     * associations for this version.  Items in this list which are not associated
187     * with the version are ignored.
188     */
189    public void setTaskList(ResourceList<Task> taskAdditions, ResourceList<Task> taskRemovals) throws WvcmException;
190
191    /**
192     * Add the specified label to the version.
193     * @param label Label to be applied
194     * @param view View context
195     * @throws WvcmException
196     * @see javax.wvcm.Version#doAddLabel(java.lang.String, javax.wvcm.Feedback)
197     */
198    public Version doAddLabel(String label, CcView view, Feedback feedback) throws WvcmException;    
199    
200    /**
201     * Add the specified label to the version.
202     * @param comment The comment for this operation, or null for no comment
203     * @param label Label to be applied
204     * @param view View context
205     * @throws WvcmException
206     * @see javax.wvcm.Version#doAddLabel(java.lang.String, javax.wvcm.Feedback)
207     */
208    public Version doAddLabel(String comment, String label, CcView view, Feedback feedback) throws WvcmException;
209
210    /**
211     * Set the specified label on the version.
212     * @param label Label to be applied
213     * @param view View context
214     * @throws WvcmException
215     * @see javax.wvcm.Version#doSetLabel(java.lang.String, javax.wvcm.Feedback)
216     */
217    public Version doSetLabel(String label, CcView view, Feedback feedback) throws WvcmException;    
218    
219    
220    /**
221     * Set the specified label on the version.
222     * @param comment The comment for this operation, or null for no comment
223     * @param label Label to be applied
224     * @param view View context
225     * @throws WvcmException
226     * @see javax.wvcm.Version#doSetLabel(java.lang.String, javax.wvcm.Feedback)
227     */
228    public Version doSetLabel(String comment, String label, CcView view, Feedback feedback) throws WvcmException;
229    
230    /**
231     * Remove the specified label from the version.
232     * @param label Label to be removed
233     * @param view View context
234     * @throws WvcmException
235     * @see javax.wvcm.Version#doRemoveLabel(java.lang.String, javax.wvcm.Feedback)
236     */
237    public Version doRemoveLabel(String label, CcView view, Feedback feedback) throws WvcmException;
238
239    /**
240     * Create a Merge hyperlink pointing from this version to the specified destination version.
241     * @param toVersion Destination version for the hyperlink
242     * @return A new proxy for this version, whose properties are specified by feedback.
243     */
244    public CcVersion doCreateMergeArrow(CcVersion toVersion, Feedback feedback) throws WvcmException;
245    
246    /**
247     * Create a Merge hyperlink pointing from this version to the specified destination version.
248     * @param toVersion Destination version for the hyperlink
249     * @param view View context (ensures path EVs set for mkhlink when a merge is being made).
250     * @return A new proxy for this version, whose properties are specified by feedback.
251     */
252    public CcVersion doCreateMergeArrow(CcVersion toVersion, CcView view, Feedback feedback) throws WvcmException;
253    
254}