001 /* 002 * file CcStream.java 003 * 004 * Licensed Materials - Property of IBM 005 * Restricted Materials of IBM 006 * 007 * com.ibm.rational.wvcm.stp.cc.CcStream 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.Resource; 020 import javax.wvcm.ResourceList; 021 import javax.wvcm.Stream; 022 import javax.wvcm.WvcmException; 023 import javax.wvcm.Baseline.CompareReport; 024 import javax.wvcm.PropertyNameList.PropertyName; 025 import javax.wvcm.ResourceList.ResponseIterator; 026 027 import com.ibm.rational.wvcm.stp.StpActivity; 028 import com.ibm.rational.wvcm.stp.cc.CcBaseline.CompareFlagEx; 029 030 /** 031 * <p> 032 * A proxy for a ClearCase UCM stream. 033 * </p> 034 * <p> 035 * Each UCM stream represents a separate parallel development effort in 036 * ClearCase. Code changes made in one UCM stream are not visbile to other 037 * streams until the user chooses to share them via the UCM <i>deliver</i> or 038 * <i>rebase</i> operations. 039 * </p> 040 * <p> 041 * A UCM stream has one or more ClearCase views associated with it in which 042 * users view and modify their version-controlled resources. The stream 043 * determines these views' <i>configuration</i> - the set of components visible 044 * in those views and the particular version of each file in each component. 045 * This configuration consists of the versions selected by the stream's 046 * <i>foundation baseline list</i>, plus the versions in the change sets of the 047 * stream's activities. 048 * </p> 049 * <p> 050 * The stream user creates a UCM activity in the stream for each logical task 051 * they are working on. When the user checks in a version-controlled resource, 052 * the new version is collected in that activity's change set. The user may 053 * create as many activities as they need to complete their tasks. 054 * </p> 055 * <p> 056 * Each UCM project has a single <i>integration stream</i> to which the 057 * project's <i>development streams</i> deliver their changes. UCM supports 058 * multi-level stream hierarchies - development streams that have their own 059 * substreams and serve as <i>delivery targets</i> for those substreams. 060 * </p> 061 */ 062 public interface CcStream extends Stream, CcVobResource { 063 064 /** 065 * <p> 066 * Create a new UCM stream at the location specified by this proxy. The 067 * location should be an object name selector specifying the stream's name 068 * and the repository (project VOB) in which to create it. 069 * </p> 070 * <p> 071 * To create an integration stream, set the {@link #PARENT_PROJECT} property 072 * to the project in which to create the stream, and set the 073 * {@link #IS_INTEGRATION_STREAM} property to "true". A given project can 074 * have at most one integration stream. 075 * </p> 076 * <p> 077 * To create a non-integration stream, set the {@link #PARENT_STREAM} 078 * property to the integration stream under which to create the stream, and 079 * set the {@link #IS_INTEGRATION_STREAM} property to "false". 080 * </p> 081 * <p> 082 * You may also set the following additional stream properties prior to 083 * calling this method: 084 * <bl> 085 * <li> {@link #FOUNDATION_BASELINE_LIST} </li> 086 * <li> {@link #DEFAULT_DELIVER_TARGET} </li> 087 * <li> {@link #IS_READ_ONLY} </li> 088 * <li> {@link #COMMENT} </li> 089 * </bl> 090 * </p> 091 */ 092 public CcStream doCreateCcStream(Feedback feedback) throws WvcmException; 093 094 /** 095 * <p>Create a new UCM stream, allowing the provider to choose the 096 * new stream's name. 097 * The provider may use the client-specified location if it is valid, 098 * but can select a different location if the location is not valid 099 * or already identifies an stream. 100 * </p> 101 * @see #doCreateCcStream(Feedback) 102 */ 103 public CcStream doCreateGeneratedCcStream(Feedback feedback) throws WvcmException; 104 105 /** 106 * <p> 107 * Compare this CcStream with the specified stream. 108 * </p> 109 * <p> 110 * Specifically, compute the differences between these two streams in 111 * terms of baselines, activities, and/or versions. 112 * </p> 113 * @param stream stream to compare against 114 * @param flags specifies the types of differences to include in the 115 * compare report. 116 * @param context optional resource (often CcView) providing context for the 117 * generation of certain properties in the returned report. 118 * May be <b>null</b>. 119 * @param feedback the properties available in the returned proxies. 120 * @return a ResponseIterator of CompareReport objects, that enumerate the 121 * differences between the versions selected by this CcStream and 122 * the stream argument. 123 * @throws WvcmException 124 * @see CcBaseline#doCompareReportEx(CcStream, CompareFlagEx[], javax.wvcm.Resource, javax.wvcm.Feedback) 125 * for more information 126 */ 127 public ResponseIterator<CompareReport> 128 doCompareReportEx(CcStream stream, CompareFlagEx[] flags, Resource context, Feedback feedback) 129 throws WvcmException; 130 131 /** 132 * <p> 133 * List of all activities in the UCM stream. 134 * </p> 135 */ 136 PropertyName<ResourceList<CcActivity>> ACTIVITY_LIST = 137 new PropertyName<ResourceList<CcActivity>>(PROPERTY_NAMESPACE, 138 "activity-list"); 139 140 /** 141 * Get the value of this stream's {@link #ACTIVITY_LIST} property. 142 * 143 * @return a CcResourceList containing CcActivity instances, as described above 144 * @throws WvcmException 145 * if this proxy doesn't define a value for this property. 146 */ 147 ResourceList<CcActivity> getActivityList() throws WvcmException; 148 149 /** 150 * <p> 151 * The current user's activities in this UCM stream. The 152 * exact semantics of this property differ depending on whether the stream 153 * is associated with a ClearQuest-enabled UCM project. 154 * </p> 155 * <p> 156 * If this stream is associated with a ClearQuest-enabled UCM project, the 157 * resulting activity list is the result set from the <i>UCMCustomQuery1</i> 158 * query executed in the ClearQuest user database to which the UCM project 159 * is bound. In the out-of-the-box ClearQuest UCM schema, this query will 160 * return all CQ activities that are: 161 * </p> 162 * <ul> 163 * <li>assigned to the current user</li> 164 * <li>AND in the ready or active state,</li> 165 * <li>AND are NOT already bound to another project</li> 166 * </ul> 167 * <p> 168 * The UCMCustomQuery1 query can be modified by the customer, and if so will 169 * return other results. 170 * </p> 171 * <p> 172 * On the other hand, if this stream's project is <i>not</i> ClearQuest-enabled, 173 * the resulting activity list is simply all UCM activities in 174 * the stream that belong to the current user. 175 * </p> 176 * <p> 177 * In either case, the actual property value is a ResourceList of 178 * StpActivity instances. 179 * </p> 180 * @see com.ibm.rational.wvcm.stp.StpActivity 181 */ 182 PropertyName<ResourceList<StpActivity>> MY_ACTIVITY_LIST = 183 new PropertyName<ResourceList<StpActivity>>(PROPERTY_NAMESPACE, 184 "my-activity-list"); 185 186 /** 187 * Get the value of this stream's {@link #MY_ACTIVITY_LIST} property. 188 * 189 * @return a ResourceList of StpActivity instances, as described above 190 * @throws WvcmException 191 * if this proxy doesn't define a value for this property. 192 */ 193 ResourceList<StpActivity> getMyActivityList() throws WvcmException; 194 195 /** 196 * <p> 197 * This stream's baselines. A context of a CcComponent may be specified 198 * when reading this property in which case the list is limited to baselines 199 * for the specified CcComponent. 200 * </p> 201 * <p> 202 * When a stream is baselined, a new baseline is created for each component 203 * in the stream's configuration that was changed since the last time the 204 * stream was baselined. If a given component has not changed, no 205 * baseline is created for that component. 206 * </p> 207 */ 208 PropertyName<ResourceList<CcBaseline>> BASELINE_LIST = 209 new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, "baseline-list"); 210 211 /** 212 * Get the value of the this proxy's {@link #BASELINE_LIST} property. 213 * @return a list of client proxies for this project's baselines 214 * @throws WvcmException if this proxy doesn't define a value for this property. 215 */ 216 ResourceList<CcBaseline> getBaselineList() throws WvcmException; 217 218 /** 219 * <p> 220 * This stream's latest baselines. Specifically, the most recent baseline 221 * of each component in this stream's configuration that has been modified 222 * in this stream or the foundation baseline for components that have 223 * not been modified. 224 * </p> 225 * <p> 226 * When a stream is baselined, a new baseline is created for each component 227 * in the stream's configuration that was changed since the last time the 228 * stream was baselined. If a given component has not changed, no 229 * baseline is created for that component. 230 * </p> 231 */ 232 PropertyName<ResourceList<CcBaseline>> LATEST_BASELINE_LIST = 233 new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, "latest-baseline-list"); 234 235 /** 236 * Get the value of the this proxy's {@link #LATEST_BASELINE_LIST} property. 237 * @return a list of client proxies for this project's latest baselines 238 * @throws WvcmException if this proxy doesn't define a value for this property. 239 */ 240 ResourceList<CcBaseline> getLatestBaselineList() throws WvcmException; 241 242 /** 243 * The project to which this UCM stream belongs. 244 */ 245 PropertyName<CcProject> PARENT_PROJECT = 246 new PropertyName<CcProject>(PROPERTY_NAMESPACE, 247 "parent-project"); 248 249 /** 250 * Get the value of this stream's {@link #PARENT_PROJECT} property. 251 * 252 * @return stream's parent project 253 * @throws WvcmException 254 * if this proxy doesn't define a value for this property. 255 */ 256 CcProject getParentProject() throws WvcmException; 257 258 /** 259 * Set the value of this stream's {@link #PARENT_PROJECT} property. 260 * This property can only be set at stream creation time. 261 * 262 * @param parent 263 * stream's parent project 264 */ 265 void setParentProject(CcProject parent); 266 267 /** 268 * This UCM stream's parent stream. The value of this property is null 269 * if this is an integration stream. 270 */ 271 PropertyName<CcStream> PARENT_STREAM = new PropertyName<CcStream>(PROPERTY_NAMESPACE, 272 "parent-stream"); 273 274 /** 275 * Get the value of this stream's {@link #PARENT_STREAM} property. 276 * 277 * @return stream's parent stream, or null if this is an integration stream 278 * @throws WvcmException 279 * if this proxy doesn't define a value for this property. 280 */ 281 CcStream getParentStream() throws WvcmException; 282 283 /** 284 * Set the value of this stream's {@link #PARENT_STREAM} property. 285 * This property can only be set at stream creation time. 286 * 287 * @param parent 288 * stream's parent stream 289 */ 290 void setParentStream(CcStream parent); 291 292 /** This UCM stream's recommended baselines. */ 293 PropertyName<ResourceList<CcBaseline>> RECOMMENDED_BASELINE_LIST = 294 new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, 295 "recommended-baseline-list"); 296 297 /** 298 * Get the value of the this proxy's {@link #RECOMMENDED_BASELINE_LIST} property. 299 * @return a list of client proxies for this project's recommended baselines 300 * @throws WvcmException if this proxy doesn't define a value for this property. 301 */ 302 ResourceList<CcBaseline> getRecommendedBaselineList() throws WvcmException; 303 304 /** This UCM stream's full closure of recommended baselines. */ 305 PropertyName<ResourceList<CcBaseline>> RECOMMENDED_BASELINE_LIST_CLOSURE = 306 new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, 307 "recommended-baseline-list-closure"); 308 309 /** 310 * Get the value of the this proxy's {@link #EXPLICIT_BASELINE_LIST} property. 311 * @return a list of client proxies for this stream's explicit baselines 312 * @throws WvcmException if this proxy doesn't define a value for this property. 313 */ 314 ResourceList<CcBaseline> getExplicitBaselineList() throws WvcmException; 315 316 317 /** This UCM stream's list of explicit baselines. */ 318 PropertyName<ResourceList<CcBaseline>> EXPLICIT_BASELINE_LIST = 319 new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, 320 "explicit-baseline-list"); 321 322 /** 323 * Get the value of the this proxy's {@link #RECOMMENDED_BASELINE_LIST_CLOSURE} property. 324 * @return a list of client proxies for this project's recommended baselines 325 * @throws WvcmException if this proxy doesn't define a value for this property. 326 */ 327 ResourceList<CcBaseline> getRecommendedBaselineListClosure() throws WvcmException; 328 329 /** 330 * Set the value of the this proxy's {@link #RECOMMENDED_BASELINE_LIST} property. 331 * @param recBls a list of client proxies for this project's recommended baselines 332 */ 333 void setRecommendedBaselineList(ResourceList<CcBaseline> recBls); 334 335 /** 336 * The list of substreams of this UCM stream, i.e., the streams 337 * for which this stream is the parent. 338 */ 339 PropertyName<ResourceList<CcStream>> SUBSTREAM_LIST = 340 new PropertyName<ResourceList<CcStream>>(PROPERTY_NAMESPACE, 341 "substream-list"); 342 343 /** 344 * Get the value of this stream's {@link #SUBSTREAM_LIST} property. 345 * 346 * @return a list of client proxies for this stream's substreams 347 * @throws WvcmException 348 * if this proxy doesn't define a value for this property. 349 */ 350 ResourceList<CcStream> getSubstreamList() throws WvcmException; 351 352 /** The views associated with this UCM stream. */ 353 PropertyName<ResourceList<CcView>> VIEW_LIST = 354 new PropertyName<ResourceList<CcView>>(PROPERTY_NAMESPACE, 355 "view-list"); 356 357 /** 358 * Get the value of this stream's {@link #VIEW_LIST} property. 359 * 360 * @return the list of views associated with this stream 361 * @throws WvcmException 362 * if this proxy doesn't define a value for this property. 363 */ 364 ResourceList<CcView> getViewList() throws WvcmException; 365 366 /** Is this UCM stream an integration stream? */ 367 PropertyName<Boolean> IS_INTEGRATION_STREAM = 368 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 369 "is-integration-stream"); 370 371 /** 372 * Get the value of this stream's {@link #IS_INTEGRATION_STREAM} property. 373 * 374 * @return true if this stream is an integration stream, else false 375 * @throws WvcmException 376 * if this proxy doesn't define a value for this property. 377 */ 378 boolean getIsIntegrationStream() throws WvcmException; 379 380 /** 381 * Set the value of this stream's {@link #IS_INTEGRATION_STREAM} property. 382 * This property can only be set at stream creation time. 383 * 384 * @param isInt 385 * true if this stream is an integration stream, else false 386 */ 387 void setIsIntegrationStream(boolean isInt); 388 389 /** Is this a read-only UCM stream? */ 390 PropertyName<Boolean> IS_READ_ONLY = 391 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 392 "is-read-only"); 393 394 /** 395 * Get the value of this stream's {@link #IS_READ_ONLY} property. 396 * 397 * @return true if this stream is read-only, else false 398 * @throws WvcmException 399 * if this proxy doesn't define a value for this property. 400 */ 401 boolean getIsReadOnly() throws WvcmException; 402 403 /** 404 * Set the value of this stream's {@link #IS_READ_ONLY} property. 405 * This property can only be set at stream creation time. 406 * 407 * @param readOnly 408 * true if this stream is to be read-only, else false 409 */ 410 void setIsReadOnly(boolean readOnly); 411 412 /** Is Delivery allowed with checkouts in this stream */ 413 PropertyName<Boolean> DELIVER_POLICY_NO_CHECKOUTS_IN_STREAM = 414 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 415 "deliver-policy-no-checkouts-stream"); 416 417 /** 418 * Get the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_STREAM } property. 419 * 420 * @return true if the policy to disallow Deliver with checkouts in this stream is enabled 421 * @throws WvcmException 422 * if this proxy doesn't define a value for this property. 423 */ 424 boolean getDeliverPolicyNoCheckoutsInStream() throws WvcmException; 425 426 /** 427 * Set the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_STREAM } property. 428 * 429 * 430 * @param enablePolicy 431 * true to enable the policy to disallow Deliver with checkouts in this stream 432 */ 433 void setDeliverPolicyNoCheckoutsInStream(boolean enablePolicy); 434 435 436 /** Is Delivery allowed with checkouts in selected activities */ 437 PropertyName<Boolean> DELIVER_POLICY_NO_CHECKOUTS_IN_ACTIVITIES = 438 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 439 "deliver-policy-no-checkouts-activities"); 440 441 /** 442 * Get the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_ACTIVITIES } property. 443 * 444 * @return true if the policy to disallow Deliver with checkouts in selected activities is enabled for this stream 445 * @throws WvcmException 446 * if this proxy doesn't define a value for this property. 447 */ 448 boolean getDeliverPolicyNoCheckoutsInActivities() throws WvcmException; 449 450 /** 451 * Set the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_ACTIVITIES } property. 452 * 453 * 454 * @param enablePolicy 455 * true to enable the policy to disallow Deliver with checkouts in selected activities for this stream 456 */ 457 void setDeliverPolicyNoCheckoutsInActivities(boolean enablePolicy); 458 459 460 /** This UCM stream's foundation baselines. */ 461 PropertyName<ResourceList<CcBaseline>> FOUNDATION_BASELINE_LIST = 462 new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, 463 "foundation-baseline-list"); 464 465 /** 466 * Get the value of this stream's {@link #FOUNDATION_BASELINE_LIST} 467 * property. 468 * 469 * @return a list of client proxies for this stream's foundation baselines 470 * @throws WvcmException 471 * if this proxy doesn't define a value for this property. 472 */ 473 ResourceList<CcBaseline> getFoundationBaselineList() throws WvcmException; 474 475 /** The list of components from this stream's complete list of foundation baselines */ 476 PropertyName<ResourceList<CcComponent>> COMPONENT_LIST = 477 new PropertyName<ResourceList<CcComponent>> (PROPERTY_NAMESPACE, 478 "component-list"); 479 480 /** 481 * Get the value of this stream's {@link #COMPONENT_LIST} 482 * property. 483 * 484 * @return a list of client proxies for this stream's components that are baselined by this 485 * stream's foundation baselines 486 * @throws WvcmException 487 * if this proxy doesn't define a value for this property. 488 */ 489 ResourceList<CcComponent> getComponentList() throws WvcmException; 490 491 /** The default target (stream) for this UCM stream's deliver operations. */ 492 PropertyName<CcStream> DEFAULT_DELIVER_TARGET = 493 new PropertyName<CcStream>(PROPERTY_NAMESPACE, 494 "default-deliver-target"); 495 496 /** 497 * Get the value of this stream's {@link #DEFAULT_DELIVER_TARGET} property. 498 * 499 * @return a client proxy for this stream's default deliver target, 500 * or <code>null</code> if there is no default deliver target 501 * defined for this stream 502 * @throws WvcmException 503 * if this proxy doesn't define a value for this property. 504 */ 505 CcStream getDefaultDeliverTarget() throws WvcmException; 506 507 /** 508 * Set the value of this stream's {@link #DEFAULT_DELIVER_TARGET} property. 509 * The default deliver target can only be changed on integration streams. 510 * The default deliver target for all non-integration streams is their parent 511 * stream. 512 * @param target 513 * this stream's new default deliver target or <code>null</code> to clear 514 * the deliver target 515 */ 516 void setDefaultDeliverTarget(CcStream target); 517 518 /** 519 * A list of streams that have posted deliveries in progress to this stream. 520 * A delivery is posted if the source stream is mastered at a different 521 * replica than the target stream at the time of the delivery. This property 522 * is not recursive; it only includes streams that are immediate children of 523 * this stream. 524 */ 525 PropertyName<ResourceList<CcStream>> POSTED_DELIVERY_LIST = 526 new PropertyName<ResourceList<CcStream>>(PROPERTY_NAMESPACE, "ccstream-posted-delivery-list"); 527 528 /** 529 * Get the value of this proxy's {@link #POSTED_DELIVERY_LIST} property. 530 * @return A list containing this stream's posted deliveries. 531 * @throws WvcmException 532 * if this proxy doesn't define a value for this property. 533 */ 534 ResourceList<CcStream> getPostedDeliveryList() throws WvcmException; 535 536 /** Is this UCM stream in the middle of a delivery? 537 */ 538 PropertyName<Boolean> HAS_DELIVERY_IN_PROGRESS = 539 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-delivery-in-progress"); 540 541 /** 542 * Get the value of this proxy's {@link #HAS_DELIVERY_IN_PROGRESS} property. 543 * @return true if this stream is delivering, else false. 544 * @throws WvcmException 545 * if this proxy doesn't define a value for this property. 546 */ 547 boolean getHasDeliveryInProgress() throws WvcmException; 548 549 /** Is this locally mastered UCM stream in the middle of a posted 550 * delivery to a remotely mastered target? 551 */ 552 PropertyName<Boolean> HAS_POSTED_DELIVERY_IN_PROGRESS = 553 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-posted-delivery-in-progress"); 554 555 /** 556 * Get the value of this proxy's {@link #HAS_POSTED_DELIVERY_IN_PROGRESS} property. 557 * @return true if this stream is delivering to a remotely mastered target, else false. 558 * @throws WvcmException 559 * if this proxy doesn't define a value for this property. 560 */ 561 boolean getHasPostedDeliveryInProgress() throws WvcmException; 562 563 /** 564 * Get the value of this proxy's {@link #DELIVER_OPERATION} proxy. 565 * @return deliver operation if there is one in progress, else null 566 * @throws WvcmException 567 */ 568 CcDeliverOperation getDeliverOperation() throws WvcmException; 569 570 PropertyName<CcDeliverOperation> DELIVER_OPERATION = 571 new PropertyName<CcDeliverOperation>(PROPERTY_NAMESPACE, "deliver-operation"); 572 573 574 /** Is this UCM stream in the middle of a Rebase? 575 */ 576 PropertyName<Boolean> HAS_REBASE_IN_PROGRESS = 577 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-rebase-in-progress"); 578 579 /** 580 * Get the value of this proxy's {@link #HAS_REBASE_IN_PROGRESS} property. 581 * @return true if this stream is rebasing, else false. 582 * @throws WvcmException 583 * if this proxy doesn't define a value for this property. 584 */ 585 boolean getHasRebaseInProgress() throws WvcmException; 586 587 /** 588 * @deprecated TODO Placeholder for probable future property to track 589 * the status of a delivery to the integration stream 590 */ 591 PropertyName INTEGRATION_STATUS = new PropertyName(PROPERTY_NAMESPACE, 592 "integration-status"); 593 }