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 }