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 * (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.Resource;
021 import javax.wvcm.ResourceList;
022 import javax.wvcm.ResourceList.ResponseIterator;
023 import javax.wvcm.Workspace;
024 import javax.wvcm.WvcmException;
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 {
110 /**
111 * Provide differences in terms of activites.
112 */
113 ACTIVITIES,
114
115 /**
116 * Provide differences in terms of baselines.
117 */
118 BASELINES,
119
120 /**
121 * Provide differences in terms of versions.
122 */
123 VERSIONS;
124 }
125
126 /**
127 * Labeling status of this baseline.
128 */
129 enum LabelingStatus implements StpExEnumeration {
130 /** Unlabeled baseline */
131 NOT_LABELED,
132
133 /** Incrementally labeled baseline */
134 INCREMENTALLY_LABELED,
135
136 /** Fully labeled baseline */
137 FULLY_LABELED,
138
139 /** Special case: not labeled but doesn't need to be */
140 IS_INITIAL,
141
142 /** Baseline of a rootless component */
143 NO_VERSIONS_TO_LABEL;
144 }
145
146 /**
147 * <p>Compare two baselines, ClearCase-style.</p>
148 *
149 * @param baseline the baseline being compared to this CcBaseline.
150 * @param flags specifies the types of differences to include in the
151 * compare report.
152 * @param context optional resource (often CcView) providing context for the
153 * generation of certain properties in the returned report.
154 * May be <b>null</b>.
155 * @param feedback the properties available in the returned proxies.
156 * @return a ResponseIterator of CompareReport objects, that enumerate the
157 * differences between the versions selected by this CcBaseline and
158 * the baseline argument.
159 * @throws WvcmException
160 */
161 public ResponseIterator<CompareReport>
162 doCompareReportEx(CcBaseline baseline, CompareFlagEx[] flags, Resource context, Feedback feedback)
163 throws WvcmException;
164
165 /**
166 * <p>
167 * Compare this baseline with the specified stream.
168 * </p>
169 * <p>
170 * All baselines in the stream are used in the comparison as well
171 * as any changes in the stream that are not yet captured in a baseline.
172 * </p>
173 * @param stream the stream being compared to this CcBaseline.
174 * @param flags specifies the types of differences to include in the
175 * compare report.
176 * @param context optional resource (often CcView) providing context for the
177 * generation of certain properties in the returned report.
178 * May be <b>null</b>.
179 * @param feedback the properties available in the returned proxies.
180 * @return a ResponseIterator of CompareReport objects that enumerate the
181 * differences between the versions selected by this CcBaseline and
182 * the stream argument.
183 * @throws WvcmException
184 */
185 public ResponseIterator<CompareReport>
186 doCompareReportEx(CcStream stream, CompareFlagEx[] flags, Resource context, Feedback feedback)
187 throws WvcmException;
188
189 /**
190 * The UCM component for which this is a baseline.
191 */
192 PropertyName<CcComponent> COMPONENT =
193 new PropertyName<CcComponent>(PROPERTY_NAMESPACE, "baseline-component");
194
195 /**
196 * Get the the {@link #COMPONENT} property of this baseline.
197 * @return a client proxy for the UCM component that this baseline is in.
198 * Will never be null.
199 * @throws WvcmException if this proxy doesn't define a value for this property.
200 */
201 public CcComponent getComponent() throws WvcmException;
202
203 /**
204 * Is this baseline an "import" baseline?
205 */
206 PropertyName<Boolean> IS_IMPORT =
207 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "baseline-is-import");
208
209 /**
210 * Get the {@link #IS_IMPORT} property of this baseline.
211 * @return true if this is an import baseline, else false
212 * @throws WvcmException if this proxy doesn't define a value for this property.
213 */
214 boolean getIsImport() throws WvcmException;
215
216 /**
217 * Is this baseline a composite baseline?
218 */
219 PropertyName<Boolean> IS_COMPOSITE =
220 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "baseline-is-composite");
221
222 /**
223 * Get the {@link #IS_COMPOSITE} property of this baseline.
224 * @return true if this is a composite baseline, else false
225 * @throws WvcmException if this proxy doesn't define a value for this property.
226 */
227 boolean getIsComposite() throws WvcmException;
228
229 /**
230 * Is this baseline the initial baseline for its component?
231 */
232 PropertyName<Boolean> IS_INITIAL =
233 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "baseline-is-initial");
234
235 /**
236 * Get the {@link #IS_INITIAL} property of this baseline.
237 * @return true if this is the initial baseline for its component, else false
238 * @throws WvcmException if this proxy doesn't define a value for this property.
239 */
240 boolean getIsInitial() throws WvcmException;
241
242 /** This baseline's labeling status. One of:
243 * <br>{@link LabelingStatus#NOT_LABELED}
244 * <br>{@link LabelingStatus#INCREMENTALLY_LABELED}
245 * <br>{@link LabelingStatus#FULLY_LABELED}
246 * <br>{@link LabelingStatus#IS_INITIAL}
247 * <br>{@link LabelingStatus#NO_VERSIONS_TO_LABEL}
248 */
249 PropertyName<LabelingStatus> LABELING_STATUS =
250 new PropertyName<LabelingStatus>(PROPERTY_NAMESPACE, "labeling-status");
251
252 /**
253 * Get the {@link #LABELING_STATUS} property of this baseline.
254 * @return A {@link LabelingStatus} enumerator indicating the labeling
255 * status of this baseline.
256 * @throws WvcmException if this proxy doesn't define a value for this property.
257 */
258 LabelingStatus getLabelingStatus() throws WvcmException;
259
260 /**
261 * Set the value of this baseline's {@link #LABELING_STATUS} property.
262 * @param labelingStatus new labeling status for this baseline.
263 * The only valid values are {@link LabelingStatus#INCREMENTALLY_LABELED} (if
264 * the current labeling status is {@link LabelingStatus#NOT_LABELED}) or
265 * {@link LabelingStatus#FULLY_LABELED} (if the current labeling status
266 * is {@link LabelingStatus#NOT_LABELED} or
267 * {@link LabelingStatus#INCREMENTALLY_LABELED}).
268 * When used on a composite baseline, the specified change is applied recursively
269 * to its member baselines.
270 * Can also be set at creation time to specify the labeling status of
271 * baselines(s) created via the {@link #doMakeCcBaselines(MakeCcBaselinesFlag[], Feedback)}
272 * method.
273 */
274 void setLabelingStatus(LabelingStatus labelingStatus);
275
276 /**
277 * The promotion level of this baseline.
278 * <p>
279 * Each project VOB includes an ordered set of promotion levels that
280 * can be assigned to baselines to indicate the quality or degree of
281 * completeness of the activities and versions represented by the baseline.
282 */
283 PropertyName<String> PROMOTION_LEVEL =
284 new PropertyName<String>(PROPERTY_NAMESPACE, "promotion-level");
285
286 /**
287 * Get the {@link #PROMOTION_LEVEL} property of this baseline.
288 * @return the {@link #PROMOTION_LEVEL} of this baseline, as a string.
289 * @throws WvcmException if this proxy doesn't define a value for this property.
290 */
291 String getPromotionLevel() throws WvcmException;
292
293 /**
294 * Set the value of this baseline's {@link #PROMOTION_LEVEL} property.
295 * @param promotionLevel the promotion level of this baseline.
296 */
297 void setPromotionLevel(String promotionLevel);
298
299 /**
300 * The stream in which this baseline was created. Will be null for "import"
301 * and "initial" baselines because they are not created in a stream context.
302 */
303 PropertyName<CcStream> STREAM =
304 new PropertyName<CcStream>(PROPERTY_NAMESPACE, "baseline-stream");
305
306 /**
307 * Get the the {@link #STREAM} property of this baseline.
308 * @return a client proxy for the UCM stream in which this baseline was
309 * created. Will be null if this is an import or initial baseline.
310 * @throws WvcmException if this proxy doesn't define a value for this property.
311 */
312 public CcStream getStream() throws WvcmException;
313
314 /**
315 * Set the value of this proxy's {@link #STREAM} property.
316 * This property can only be set at baseline creation time for use
317 * by the {@link #doMakeCcBaselines(MakeCcBaselinesFlag[], Feedback)}
318 * method.
319 * @param stream Stream on which the new baseline should be created
320 * @throws WvcmException
321 */
322 public void setStream(CcStream stream) throws WvcmException;
323
324 /**
325 * The list of sub-baselines of this composite baseline.
326 * As a configuration gets
327 * large, it is often useful to break it up into a set of smaller
328 * configurations that form the logical components of that configuration.
329 * The sub-baseline list of a baseline of a configuration captures the set
330 * of baselines of the component sub-configurations.
331 */
332 PropertyName<ResourceList<CcBaseline>> SUBBASELINE_LIST =
333 new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, "subbaseline-list");
334
335 /**
336 * Get the {@link #SUBBASELINE_LIST} property.
337 * @return list of CcBaseline proxies for this baseline
338 * @throws WvcmException if this proxy doesn't define a value for this property.
339 */
340 public ResourceList<CcBaseline> getSubbaselineList() throws WvcmException;
341
342 /**
343 * Flags for the <code>doMakeCcBaselines</code> method.
344 */
345 enum MakeCcBaselinesFlag {
346 /**
347 * Create the baseline(s) regardless of whether modifications have occurred
348 */
349 IDENTICAL,
350
351 /**
352 * Recommend the baseline(s) after creation.
353 */
354 RECOMMEND;
355 }
356
357 /**
358 * A <em>write-only</em> property used to specify the activities to be
359 * included in a new baseline.
360 */
361 PropertyName<ResourceList<CcActivity>> ACTIVITY_LIST =
362 new PropertyName<ResourceList<CcActivity>>(PROPERTY_NAMESPACE, "mkbl-activity-list");
363
364 /**
365 * Set the value of this proxy's {@link #ACTIVITY_LIST} property.
366 * This property can only be set at baseline creation time for use
367 * by the {@link #doMakeCcBaselines(MakeCcBaselinesFlag[], Feedback)}
368 * method.
369 * @param activityList List of activities to be used for baseline creation.
370 * @throws WvcmException
371 */
372 public void setActivityList(ResourceList<CcActivity> activityList) throws WvcmException;
373
374 /**
375 * A <em>write-only</em> property used to specify the components for
376 * which baselines are created.
377 */
378 PropertyName<ResourceList<CcComponent>> COMPONENT_LIST =
379 new PropertyName<ResourceList<CcComponent>>(PROPERTY_NAMESPACE, "mkbl-component-list");
380
381 /**
382 * Set the value of this proxy's {@link #COMPONENT_LIST} property.
383 * This property can only be set at baseline creation time for use
384 * by the {@link #doMakeCcBaselines(MakeCcBaselinesFlag[], Feedback)}
385 * method.
386 * @param componentList List of components to be used for baseline creation.
387 * @throws WvcmException
388 */
389 public void setComponentList(ResourceList<CcComponent> componentList) throws WvcmException;
390
391 /**
392 * A <em>write-only</em> property used to specify the components to be
393 * added to the dependency list of the component for which the baseline is
394 * created.
395 */
396 PropertyName<ResourceList<CcComponent>> ADD_COMPONENT_DEPENDENCY_LIST =
397 new PropertyName<ResourceList<CcComponent>>(PROPERTY_NAMESPACE, "mkbl-add-component-dependency-list");
398
399 /**
400 * Set the value of this proxy's {@link #ADD_COMPONENT_DEPENDENCY_LIST}
401 * property. This property can only be set at baseline creation time for
402 * use by the {@link #doMakeCcBaselines(MakeCcBaselinesFlag[], Feedback)}
403 * method.
404 * @param componentList List of components to be added to input component's
405 * dependency list.
406 * @throws WvcmException
407 */
408 public void setAddComponentDependencyList(ResourceList<CcComponent> componentList) throws WvcmException;
409
410 /**
411 * A <em>write-only<em> property used to specify the components to be
412 * removed from the dependency list of the component for which the baseline
413 * is created.
414 */
415 PropertyName<ResourceList<CcComponent>> REMOVE_COMPONENT_DEPENDENCY_LIST =
416 new PropertyName<ResourceList<CcComponent>>(PROPERTY_NAMESPACE, "mkbl-remove-component-dependency-list");
417
418 /**
419 * Set the value of this proxy's {@link #REMOVE_COMPONENT_DEPENDENCY_LIST}
420 * property. This property can only be set at baseline creation time for
421 * use by the {@link #doMakeCcBaselines(MakeCcBaselinesFlag[], Feedback)}
422 * method.
423 * @param componentList List of components to be removed from input
424 * component's dependency list.
425 * @throws WvcmException
426 */
427 public void setRemoveComponentDependencyList(ResourceList<CcComponent> componentList) throws WvcmException;
428
429 /**
430 * A <em>write-only</em> property which specifies the workspace which
431 * will be used to create baselines. Baselines are created in the stream
432 * that the workspace is attached to. Setting this overrides setting
433 * of the {@link #STREAM} property.
434 */
435 PropertyName<Workspace> WORKSPACE =
436 new PropertyName<Workspace>(PROPERTY_NAMESPACE, "mkbl-workspace");
437
438 /**
439 * Set the value of this proxy's {@link #WORKSPACE} property.
440 * This property can only be set at baseline creation time for use
441 * by the {@link #doMakeCcBaselines(MakeCcBaselinesFlag[], Feedback)}
442 * method.
443 * @param workspace Workspace which will be used to create baselines.
444 * @throws WvcmException
445 */
446 public void setWorkspace(Workspace workspace) throws WvcmException;
447
448 /**
449 * <p>
450 * Create a new UCM baseline using the name segment of the client-specified
451 * location as the root portion of the baseline name. This interface
452 * does not support the use of baseline naming templates.
453 * </p>
454 * <p>
455 * The {@link #STREAM} property should be used to specify the stream
456 * on which the baseline(s) will be created. It is required unless
457 * the {@link #WORKSPACE} property is set.
458 * </p>
459 * <p>
460 * The {@link #WORKSPACE} property can be used to specify the workspace which
461 * will be used to create baselines. Baselines are created in the stream
462 * that the workspace is attached to. Setting this overrides setting
463 * of the {@link #STREAM} property.
464 * </p>
465 * <p>
466 * The following two properties are mutually exclusive:
467 * <ul>
468 * <li>The {@link #COMPONENT_LIST} property is used to specify the components for
469 * which baselines are created.</li>
470 * <li>The {@link #ACTIVITY_LIST} property is used to specify the activities to be
471 * included in a new baseline.</li>
472 * </ul>
473 * </p>
474 * <p>
475 * The following two properties can be used to create or change the dependency
476 * relationship of the component for which the baseline is created as specified
477 * in {@link #COMPONENT_LIST}. If multiple components are specified, dependency
478 * relationship of only the first component will be created or modified.
479 * <ul>
480 * <li>The {@link #ADD_COMPONENT_DEPENDENCY_LIST} property is used to specify the
481 * components to be added to dependency list.</li>
482 * <li>The {@link #REMOVE_COMPONENT_DEPENDENCY_LIST} property is used to specify
483 * the components to be removed from dependency list.</li>
484 * </ul>
485 * </p>
486 * <p>
487 * The {@link #LABELING_STATUS} property can be used to specify whether the
488 * baseline(s) should be unlabeled, incrementally labeled or full labeled.
489 * </p>
490 * <p>
491 * You may also set the following additional baseline properties prior to
492 * calling this method:
493 * <bl>
494 * <li> {@link #COMMENT} </li>
495 * </bl>
496 * </p>
497 * @param flags Resource-specific creation flags.
498 */
499 public ResourceList<CcBaseline> doMakeCcBaselines(MakeCcBaselinesFlag[] flags, Feedback feedback) throws WvcmException;
500
501 /**
502 * <p>
503 * Variant of doMakeCcBaselines(MakeCcBaselinesFlag[] flags, Feedback feedback),
504 * that takes a listener which provides detailed messages from the baseline creation operation.
505 * </p>
506 */
507 public ResourceList<CcBaseline> doMakeCcBaselines(MakeCcBaselinesFlag[] flags, CcListener listener, Feedback feedback) throws WvcmException;
508
509 }