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
014package com.ibm.rational.wvcm.stp.cc;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import javax.wvcm.Feedback;
019import javax.wvcm.PropertyNameList.PropertyName;
020import javax.wvcm.Resource;
021import javax.wvcm.ResourceList;
022import javax.wvcm.ResourceList.ResponseIterator;
023import javax.wvcm.Workspace;
024import javax.wvcm.WvcmException;
025
026import 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 */
055public 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}