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    }