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 }