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 }