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