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