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, 2015. 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 014package com.ibm.rational.wvcm.stp.cc; 015 016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE; 017 018import javax.wvcm.Feedback; 019import javax.wvcm.PropertyNameList.PropertyName; 020import javax.wvcm.Resource; 021import javax.wvcm.ResourceList; 022import javax.wvcm.ResourceList.ResponseIterator; 023import javax.wvcm.Workspace; 024import javax.wvcm.WvcmException; 025 026import 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 */ 055public 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 used to specify the components to be 393 * added to the dependency list of the component for which the baseline is 394 * created. 395 */ 396 PropertyName<ResourceList<CcComponent>> ADD_COMPONENT_DEPENDENCY_LIST = 397 new PropertyName<ResourceList<CcComponent>>(PROPERTY_NAMESPACE, "mkbl-add-component-dependency-list"); 398 399 /** 400 * Set the value of this proxy's {@link #ADD_COMPONENT_DEPENDENCY_LIST} 401 * property. This property can only be set at baseline creation time for 402 * use by the {@link #doMakeCcBaselines(MakeCcBaselinesFlag[], Feedback)} 403 * method. 404 * @param componentList List of components to be added to input component's 405 * dependency list. 406 * @throws WvcmException 407 */ 408 public void setAddComponentDependencyList(ResourceList<CcComponent> componentList) throws WvcmException; 409 410 /** 411 * A <em>write-only<em> property used to specify the components to be 412 * removed from the dependency list of the component for which the baseline 413 * is created. 414 */ 415 PropertyName<ResourceList<CcComponent>> REMOVE_COMPONENT_DEPENDENCY_LIST = 416 new PropertyName<ResourceList<CcComponent>>(PROPERTY_NAMESPACE, "mkbl-remove-component-dependency-list"); 417 418 /** 419 * Set the value of this proxy's {@link #REMOVE_COMPONENT_DEPENDENCY_LIST} 420 * property. This property can only be set at baseline creation time for 421 * use by the {@link #doMakeCcBaselines(MakeCcBaselinesFlag[], Feedback)} 422 * method. 423 * @param componentList List of components to be removed from input 424 * component's dependency list. 425 * @throws WvcmException 426 */ 427 public void setRemoveComponentDependencyList(ResourceList<CcComponent> componentList) throws WvcmException; 428 429 /** 430 * A <em>write-only</em> property which specifies the workspace which 431 * will be used to create baselines. Baselines are created in the stream 432 * that the workspace is attached to. Setting this overrides setting 433 * of the {@link #STREAM} property. 434 */ 435 PropertyName<Workspace> WORKSPACE = 436 new PropertyName<Workspace>(PROPERTY_NAMESPACE, "mkbl-workspace"); 437 438 /** 439 * Set the value of this proxy's {@link #WORKSPACE} property. 440 * This property can only be set at baseline creation time for use 441 * by the {@link #doMakeCcBaselines(MakeCcBaselinesFlag[], Feedback)} 442 * method. 443 * @param workspace Workspace which will be used to create baselines. 444 * @throws WvcmException 445 */ 446 public void setWorkspace(Workspace workspace) throws WvcmException; 447 448 /** 449 * <p> 450 * Create a new UCM baseline using the name segment of the client-specified 451 * location as the root portion of the baseline name. This interface 452 * does not support the use of baseline naming templates. 453 * </p> 454 * <p> 455 * The {@link #STREAM} property should be used to specify the stream 456 * on which the baseline(s) will be created. It is required unless 457 * the {@link #WORKSPACE} property is set. 458 * </p> 459 * <p> 460 * The {@link #WORKSPACE} property can be used to specify the workspace which 461 * will be used to create baselines. Baselines are created in the stream 462 * that the workspace is attached to. Setting this overrides setting 463 * of the {@link #STREAM} property. 464 * </p> 465 * <p> 466 * The following two properties are mutually exclusive: 467 * <ul> 468 * <li>The {@link #COMPONENT_LIST} property is used to specify the components for 469 * which baselines are created.</li> 470 * <li>The {@link #ACTIVITY_LIST} property is used to specify the activities to be 471 * included in a new baseline.</li> 472 * </ul> 473 * </p> 474 * <p> 475 * The following two properties can be used to create or change the dependency 476 * relationship of the component for which the baseline is created as specified 477 * in {@link #COMPONENT_LIST}. If multiple components are specified, dependency 478 * relationship of only the first component will be created or modified. 479 * <ul> 480 * <li>The {@link #ADD_COMPONENT_DEPENDENCY_LIST} property is used to specify the 481 * components to be added to dependency list.</li> 482 * <li>The {@link #REMOVE_COMPONENT_DEPENDENCY_LIST} property is used to specify 483 * the components to be removed from dependency list.</li> 484 * </ul> 485 * </p> 486 * <p> 487 * The {@link #LABELING_STATUS} property can be used to specify whether the 488 * baseline(s) should be unlabeled, incrementally labeled or full labeled. 489 * </p> 490 * <p> 491 * You may also set the following additional baseline properties prior to 492 * calling this method: 493 * <bl> 494 * <li> {@link #COMMENT} </li> 495 * </bl> 496 * </p> 497 * @param flags Resource-specific creation flags. 498 */ 499 public ResourceList<CcBaseline> doMakeCcBaselines(MakeCcBaselinesFlag[] flags, Feedback feedback) throws WvcmException; 500 501 /** 502 * <p> 503 * Variant of doMakeCcBaselines(MakeCcBaselinesFlag[] flags, Feedback feedback), 504 * that takes a listener which provides detailed messages from the baseline creation operation. 505 * </p> 506 */ 507 public ResourceList<CcBaseline> doMakeCcBaselines(MakeCcBaselinesFlag[] flags, CcListener listener, Feedback feedback) throws WvcmException; 508 509}