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
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 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 }