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