001 /*
002 * file CcBaseline.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * com.ibm.rational.wvcm.stp.cc.CcBaseline
008 *
009 * © Copyright IBM Corporation 2004, 2008. 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.Resource;
020 import javax.wvcm.ResourceList;
021 import javax.wvcm.WvcmException;
022 import javax.wvcm.PropertyNameList.PropertyName;
023 import javax.wvcm.ResourceList.ResponseIterator;
024 import javax.wvcm.WvcmException.ReasonCode;
025
026 import com.ibm.rational.wvcm.stpex.StpExEnumeration;
027
028 /**
029 * <p>A proxy for a ClearCase UCM baseline.
030 * </p>
031 * <p>
032 * A UCM baseline represents a snapshot of the changes made to a particular
033 * component in the context of a particular UCM stream: it is a version of a
034 * UCM component, recording a version of each element selected by the stream's
035 * configuration. The baseline also records the list of activities in the
036 * stream whose change sets contain versions of the component's elements.
037 * </p>
038 * <p>UCM baseline creation differs from the standard WVCM baseline creation model
039 * and cannot currently be performed using the CM API.
040 * Instead of checking out a UCM component to create a new UCM baseline, the
041 * user performs a <i>make baseline </i> operation in the UCM stream. By default this
042 * operation automatically creates a new baseline for every component in that
043 * stream's configuration that has been modified in that stream since the last
044 * <i>make baseline </i> operation.
045 * </p>
046 * <p>Every component has an <i>initial </i> (root) baseline, which is analogous to
047 * a ClearCase element's <i>/main/0 </i> version in that it is empty, and serves
048 * as the root of the baseline graph.
049 * </p>
050 * <p>An <i>import</i> baseline contains the set of versions labeled with a
051 * particular label, and is typically used to import non-UCM versions into
052 * a UCM project.
053 * </p>
054 */
055 public interface CcBaseline extends javax.wvcm.Baseline, CcVobResource {
056
057 /**
058 * @see javax.wvcm.Baseline.AddedActivity
059 */
060 public interface AddedActivityEx extends AddedActivity {
061
062 /**
063 * Get the list of versions in the added activity.
064 * @return List of CcVersion proxies
065 */
066 public ResourceList<CcVersion> getVersions();
067
068 }
069
070 /**
071 * @see javax.wvcm.Baseline.DeletedActivity
072 */
073 public interface DeletedActivityEx extends DeletedActivity {
074
075 /**
076 * Get the list of versions in the deleted activity.
077 * @return List of CcVersion proxies
078 */
079 public ResourceList<CcVersion> getVersions();
080 }
081
082 /**
083 * @see javax.wvcm.Baseline.PartiallyAddedActivity
084 */
085 public interface PartiallyAddedActivityEx extends PartiallyAddedActivity {
086
087 /**
088 * Get the list of versions in the partially added activity.
089 * @return List of CcVersion proxies
090 */
091 public ResourceList<CcVersion> getVersions();
092 }
093
094 /**
095 * @see javax.wvcm.Baseline.PartiallyDeletedActivity
096 */
097 public interface PartiallyDeletedActivityEx extends PartiallyDeletedActivity {
098
099 /**
100 * Get the list of versions in the partially deleted activity.
101 * @return List of CcVersion proxies
102 */
103 public ResourceList<CcVersion> getVersions();
104 }
105
106 /**
107 * Boolean flags for the doCompareReportEx method.
108 */
109 enum CompareFlagEx implements StpExEnumeration {
110 /**
111 * Provide differences in terms of activites.
112 */
113 ACTIVITIES("activities"),
114
115 /**
116 * Provide differences in terms of baselines.
117 */
118 BASELINES("baselines"),
119
120 /**
121 * Provide differences in terms of versions.
122 */
123 VERSIONS("versions");
124
125 private CompareFlagEx(String flagName) { _flagName = flagName; }
126
127 /**
128 * Returns a string representation of this flag suitable for diagnostics.
129 */
130 public String toString() { return _flagName; }
131
132 /**
133 * The string form of this flag.
134 */
135 private final String _flagName;
136 }
137
138 /**
139 * Labeling status of this baseline.
140 */
141 enum LabelingStatus implements StpExEnumeration {
142 /** Unlabeled baseline */
143 NOT_LABELED,
144
145 /** Incrementally labeled baseline */
146 INCREMENTALLY_LABELED,
147
148 /** Fully labeled baseline */
149 FULLY_LABELED,
150
151 /** Special case: not labeled but doesn't need to be */
152 IS_INITIAL,
153
154 /** Baseline of a rootless component */
155 NO_VERSIONS_TO_LABEL;
156 }
157
158 /**
159 * @deprecated use {@link #doCompareReportEx(CcBaseline, com.ibm.rational.wvcm.stp.cc.CcBaseline.CompareFlagEx[], Resource, Feedback)}
160 */
161
162 public ResponseIterator<CompareReport>
163 doCompareReportEx(CcBaseline baseline, CompareFlagEx[] flags, Feedback feedback)
164 throws WvcmException;
165
166 /**
167 * @deprecated use {@link #doCompareReportEx(CcStream, com.ibm.rational.wvcm.stp.cc.CcBaseline.CompareFlagEx[], Resource, Feedback)}
168 */
169 public ResponseIterator<CompareReport>
170 doCompareReportEx(CcStream stream, CompareFlagEx[] flags, Feedback feedback)
171 throws WvcmException;
172
173 /**
174 * <p>Compare two baselines, ClearCase-style.</p>
175 *
176 * @param baseline the baseline being compared to this CcBaseline.
177 * @param flags specifies the types of differences to include in the
178 * compare report.
179 * @param context optional resource (often CcView) providing context for the
180 * generation of certain properties in the returned report.
181 * May be <b>null</b>.
182 * @param feedback the properties available in the returned proxies.
183 * @return a ResponseIterator of CompareReport objects, that enumerate the
184 * differences between the versions selected by this CcBaseline and
185 * the baseline argument.
186 * @throws WvcmException
187 */
188 public ResponseIterator<CompareReport>
189 doCompareReportEx(CcBaseline baseline, CompareFlagEx[] flags, Resource context, Feedback feedback)
190 throws WvcmException;
191
192 /**
193 * <p>
194 * Compare this baseline with the specified stream.
195 * </p>
196 * <p>
197 * All baselines in the stream are used in the comparison as well
198 * as any changes in the stream that are not yet captured in a baseline.
199 * </p>
200 * @param stream the stream being compared to this CcBaseline.
201 * @param flags specifies the types of differences to include in the
202 * compare report.
203 * @param context optional resource (often CcView) providing context for the
204 * generation of certain properties in the returned report.
205 * May be <b>null</b>.
206 * @param feedback the properties available in the returned proxies.
207 * @return a ResponseIterator of CompareReport objects that enumerate the
208 * differences between the versions selected by this CcBaseline and
209 * the stream argument.
210 * @throws WvcmException
211 */
212 public ResponseIterator<CompareReport>
213 doCompareReportEx(CcStream stream, CompareFlagEx[] flags, Resource context, Feedback feedback)
214 throws WvcmException;
215
216 /**
217 * The UCM component for which this is a baseline.
218 */
219 PropertyName<CcComponent> COMPONENT =
220 new PropertyName<CcComponent>(PROPERTY_NAMESPACE, "baseline-component");
221
222 /**
223 * Get the the {@link #COMPONENT} property of this baseline.
224 * @return a client proxy for the UCM component that this baseline is in.
225 * Will never be null.
226 * @throws WvcmException if this proxy doesn't define a value for this property.
227 */
228 public CcComponent getComponent() throws WvcmException;
229
230 /**
231 * Is this baseline an "import" baseline?
232 */
233 PropertyName<Boolean> IS_IMPORT =
234 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "baseline-is-import");
235
236 /**
237 * Get the {@link #IS_IMPORT} property of this baseline.
238 * @return true if this is an import baseline, else false
239 * @throws WvcmException if this proxy doesn't define a value for this property.
240 */
241 boolean getIsImport() throws WvcmException;
242
243 /**
244 * Is this baseline the initial baseline for its component?
245 */
246 PropertyName<Boolean> IS_INITIAL =
247 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "baseline-is-initial");
248
249 /**
250 * Get the {@link #IS_INITIAL} property of this baseline.
251 * @return true if this is the initial baseline for its component, else false
252 * @throws WvcmException if this proxy doesn't define a value for this property.
253 */
254 boolean getIsInitial() throws WvcmException;
255
256 /** This baseline's labeling status. One of:
257 * <br>{@link LabelingStatus#NOT_LABELED}
258 * <br>{@link LabelingStatus#INCREMENTALLY_LABELED}
259 * <br>{@link LabelingStatus#FULLY_LABELED}
260 * <br>{@link LabelingStatus#IS_INITIAL}
261 * <br>{@link LabelingStatus#NO_VERSIONS_TO_LABEL}
262 */
263 PropertyName<LabelingStatus> LABELING_STATUS =
264 new PropertyName<LabelingStatus>(PROPERTY_NAMESPACE, "labeling-status");
265
266 /**
267 * Get the {@link #LABELING_STATUS} property of this baseline.
268 * @return A {@link LabelingStatus} enumerator indicating the labeling
269 * status of this baseline.
270 * @throws WvcmException if this proxy doesn't define a value for this property.
271 */
272 LabelingStatus getLabelingStatus() throws WvcmException;
273
274 /**
275 * The promotion level of this baseline.
276 * <p>
277 * Each project VOB includes an ordered set of promotion levels that
278 * can be assigned to baselines to indicate the quality or degree of
279 * completeness of the activities and versions represented by the baseline.
280 */
281 PropertyName<String> PROMOTION_LEVEL =
282 new PropertyName<String>(PROPERTY_NAMESPACE, "promotion-level");
283
284 /**
285 * Get the {@link #PROMOTION_LEVEL} property of this baseline.
286 * @return the {@link #PROMOTION_LEVEL} of this baseline, as a string.
287 * @throws WvcmException if this proxy doesn't define a value for this property.
288 */
289 String getPromotionLevel() throws WvcmException;
290
291 /**
292 * Set the value of this baseline's {@link #PROMOTION_LEVEL} property.
293 * @param promotionLevel the promotion level of this baseline.
294 */
295 void setPromotionLevel(String promotionLevel);
296
297 /**
298 * The stream in which this baseline was created. Will be null for "import"
299 * and "initial" baselines because they are not created in a stream context.
300 */
301 PropertyName<CcStream> STREAM =
302 new PropertyName<CcStream>(PROPERTY_NAMESPACE, "baseline-stream");
303
304 /**
305 * Get the the {@link #STREAM} property of this baseline.
306 * @return a client proxy for the UCM stream in which this baseline was
307 * created. Will be null if this is an import or initial baseline.
308 * @throws WvcmException if this proxy doesn't define a value for this property.
309 */
310 public CcStream getStream() throws WvcmException;
311
312 /**
313 * The list of sub-baselines of this composite baseline.
314 * As a configuration gets
315 * large, it is often useful to break it up into a set of smaller
316 * configurations that form the logical components of that configuration.
317 * The sub-baseline list of a baseline of a configuration captures the set
318 * of baselines of the component sub-configurations.
319 */
320 PropertyName<ResourceList<CcBaseline>> SUBBASELINE_LIST =
321 new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, "subbaseline-list");
322
323 /**
324 * Get the {@link #SUBBASELINE_LIST} property.
325 * @return list of CcBaseline proxies for this baseline
326 * @throws WvcmException if this proxy doesn't define a value for this property.
327 */
328 public ResourceList<CcBaseline> getSubbaselineList() throws WvcmException;
329 }