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, 2012.  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 which specifies the workspace which
393         * will be used to create baselines. Baselines are created in the stream 
394         * that the workspace is attached to.  Setting this overrides setting
395         * of the {@link #STREAM} property.
396         */
397        PropertyName<Workspace> WORKSPACE = 
398                new PropertyName<Workspace>(PROPERTY_NAMESPACE, "mkbl-workspace");
399    
400        /**
401         * Set the value of this proxy's {@link #WORKSPACE} property.
402         * This property can only be set at baseline creation time for use
403         * by the {@link #doMakeCcBaselines(MakeCcBaselinesFlag[], Feedback)}
404         * method.
405         * @param workspace Workspace which will be used to create baselines.
406         * @throws WvcmException
407         */
408        public void setWorkspace(Workspace workspace) throws WvcmException;
409    
410        /**
411         * <p>
412         * Create a new UCM baseline using the name segment of the client-specified 
413         * location as the root portion of the baseline name.  This interface
414         * does not support the use of baseline naming templates.
415         * </p>
416         * <p>
417         * The {@link #STREAM} property should be used to specify the stream
418         * on which the baseline(s) will be created.  It is required unless
419         * the {@link #WORKSPACE} property is set.
420         * </p>
421         * <p>
422         * The {@link #WORKSPACE} property can be used to specify the workspace which
423         * will be used to create baselines. Baselines are created in the stream 
424         * that the workspace is attached to.  Setting this overrides setting
425         * of the {@link #STREAM} property.
426         * </p>
427         * <p>
428         * The following two properties are mutually exclusive:
429         * <ul>
430         * <li>The {@link #COMPONENT_LIST} property is used to specify the components for
431         * which baselines are created.</li>
432         * <li>The {@link #ACTIVITY_LIST} property is used to specify the activities to be
433         * included in a new baseline.</li>
434         * </ul>
435         * </p>
436         * <p>
437         * The {@link #LABELING_STATUS} property can be used to specify whether the
438         * baseline(s) should be unlabeled, incrementally labeled or full labeled.
439         * </p>
440         * <p>
441         * You may also set the following additional baseline properties prior to
442         * calling this method:
443         * <bl>
444         * <li> {@link #COMMENT} </li>
445         * </bl>
446         * </p>
447         * @param flags Resource-specific creation flags.
448         */
449        public ResourceList<CcBaseline> doMakeCcBaselines(MakeCcBaselinesFlag[] flags, Feedback feedback) throws WvcmException;
450    
451    }