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 #RECOMMENDED_BASELINE_LIST_CLOSURE} property. 311 * @return a list of client proxies for this project's recommended baselines 312 * @throws WvcmException if this proxy doesn't define a value for this property. 313 */ 314 ResourceList<CcBaseline> getRecommendedBaselineListClosure() throws WvcmException; 315 316 /** 317 * Set the value of the this proxy's {@link #RECOMMENDED_BASELINE_LIST} property. 318 * @param recBls a list of client proxies for this project's recommended baselines 319 */ 320 void setRecommendedBaselineList(ResourceList<CcBaseline> recBls); 321 322 /** 323 * The list of substreams of this UCM stream, i.e., the streams 324 * for which this stream is the parent. 325 */ 326 PropertyName<ResourceList<CcStream>> SUBSTREAM_LIST = 327 new PropertyName<ResourceList<CcStream>>(PROPERTY_NAMESPACE, 328 "substream-list"); 329 330 /** 331 * Get the value of this stream's {@link #SUBSTREAM_LIST} property. 332 * 333 * @return a list of client proxies for this stream's substreams 334 * @throws WvcmException 335 * if this proxy doesn't define a value for this property. 336 */ 337 ResourceList<CcStream> getSubstreamList() throws WvcmException; 338 339 /** The views associated with this UCM stream. */ 340 PropertyName<ResourceList<CcView>> VIEW_LIST = 341 new PropertyName<ResourceList<CcView>>(PROPERTY_NAMESPACE, 342 "view-list"); 343 344 /** 345 * Get the value of this stream's {@link #VIEW_LIST} property. 346 * 347 * @return the list of views associated with this stream 348 * @throws WvcmException 349 * if this proxy doesn't define a value for this property. 350 */ 351 ResourceList<CcView> getViewList() throws WvcmException; 352 353 /** Is this UCM stream an integration stream? */ 354 PropertyName<Boolean> IS_INTEGRATION_STREAM = 355 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 356 "is-integration-stream"); 357 358 /** 359 * Get the value of this stream's {@link #IS_INTEGRATION_STREAM} property. 360 * 361 * @return true if this stream is an integration stream, else false 362 * @throws WvcmException 363 * if this proxy doesn't define a value for this property. 364 */ 365 boolean getIsIntegrationStream() throws WvcmException; 366 367 /** 368 * Set the value of this stream's {@link #IS_INTEGRATION_STREAM} property. 369 * This property can only be set at stream creation time. 370 * 371 * @param isInt 372 * true if this stream is an integration stream, else false 373 */ 374 void setIsIntegrationStream(boolean isInt); 375 376 /** Is this a read-only UCM stream? */ 377 PropertyName<Boolean> IS_READ_ONLY = 378 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 379 "is-read-only"); 380 381 /** 382 * Get the value of this stream's {@link #IS_READ_ONLY} property. 383 * 384 * @return true if this stream is read-only, else false 385 * @throws WvcmException 386 * if this proxy doesn't define a value for this property. 387 */ 388 boolean getIsReadOnly() throws WvcmException; 389 390 /** 391 * Set the value of this stream's {@link #IS_READ_ONLY} property. 392 * This property can only be set at stream creation time. 393 * 394 * @param readOnly 395 * true if this stream is to be read-only, else false 396 */ 397 void setIsReadOnly(boolean readOnly); 398 399 /** Is Delivery allowed with checkouts in this stream */ 400 PropertyName<Boolean> DELIVER_POLICY_NO_CHECKOUTS_IN_STREAM = 401 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 402 "deliver-policy-no-checkouts-stream"); 403 404 /** 405 * Get the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_STREAM } property. 406 * 407 * @return true if the policy to disallow Deliver with checkouts in this stream is enabled 408 * @throws WvcmException 409 * if this proxy doesn't define a value for this property. 410 */ 411 boolean getDeliverPolicyNoCheckoutsInStream() throws WvcmException; 412 413 /** 414 * Set the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_STREAM } property. 415 * 416 * 417 * @param enablePolicy 418 * true to enable the policy to disallow Deliver with checkouts in this stream 419 */ 420 void setDeliverPolicyNoCheckoutsInStream(boolean enablePolicy); 421 422 423 /** Is Delivery allowed with checkouts in selected activities */ 424 PropertyName<Boolean> DELIVER_POLICY_NO_CHECKOUTS_IN_ACTIVITIES = 425 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 426 "deliver-policy-no-checkouts-activities"); 427 428 /** 429 * Get the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_ACTIVITIES } property. 430 * 431 * @return true if the policy to disallow Deliver with checkouts in selected activities is enabled for this stream 432 * @throws WvcmException 433 * if this proxy doesn't define a value for this property. 434 */ 435 boolean getDeliverPolicyNoCheckoutsInActivities() throws WvcmException; 436 437 /** 438 * Set the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_ACTIVITIES } property. 439 * 440 * 441 * @param enablePolicy 442 * true to enable the policy to disallow Deliver with checkouts in selected activities for this stream 443 */ 444 void setDeliverPolicyNoCheckoutsInActivities(boolean enablePolicy); 445 446 447 /** This UCM stream's foundation baselines. */ 448 PropertyName<ResourceList<CcBaseline>> FOUNDATION_BASELINE_LIST = 449 new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, 450 "foundation-baseline-list"); 451 452 /** 453 * Get the value of this stream's {@link #FOUNDATION_BASELINE_LIST} 454 * property. 455 * 456 * @return a list of client proxies for this stream's foundation baselines 457 * @throws WvcmException 458 * if this proxy doesn't define a value for this property. 459 */ 460 ResourceList<CcBaseline> getFoundationBaselineList() throws WvcmException; 461 462 /** The list of components from this stream's complete list of foundation baselines */ 463 PropertyName<ResourceList<CcComponent>> COMPONENT_LIST = 464 new PropertyName<ResourceList<CcComponent>> (PROPERTY_NAMESPACE, 465 "component-list"); 466 467 /** 468 * Get the value of this stream's {@link #COMPONENT_LIST} 469 * property. 470 * 471 * @return a list of client proxies for this stream's components that are baselined by this 472 * stream's foundation baselines 473 * @throws WvcmException 474 * if this proxy doesn't define a value for this property. 475 */ 476 ResourceList<CcComponent> getComponentList() throws WvcmException; 477 478 /** The default target (stream) for this UCM stream's deliver operations. */ 479 PropertyName<CcStream> DEFAULT_DELIVER_TARGET = 480 new PropertyName<CcStream>(PROPERTY_NAMESPACE, 481 "default-deliver-target"); 482 483 /** 484 * Get the value of this stream's {@link #DEFAULT_DELIVER_TARGET} property. 485 * 486 * @return a client proxy for this stream's default deliver target, 487 * or <code>null</code> if there is no default deliver target 488 * defined for this stream 489 * @throws WvcmException 490 * if this proxy doesn't define a value for this property. 491 */ 492 CcStream getDefaultDeliverTarget() throws WvcmException; 493 494 /** 495 * Set the value of this stream's {@link #DEFAULT_DELIVER_TARGET} property. 496 * The default deliver target can only be changed on integration streams. 497 * The default deliver target for all non-integration streams is their parent 498 * stream. 499 * @param target 500 * this stream's new default deliver target or <code>null</code> to clear 501 * the deliver target 502 */ 503 void setDefaultDeliverTarget(CcStream target); 504 505 /** 506 * A list of streams that have posted deliveries in progress to this stream. 507 * A delivery is posted if the source stream is mastered at a different 508 * replica than the target stream at the time of the delivery. This property 509 * is not recursive; it only includes streams that are immediate children of 510 * this stream. 511 */ 512 PropertyName<ResourceList<CcStream>> POSTED_DELIVERY_LIST = 513 new PropertyName<ResourceList<CcStream>>(PROPERTY_NAMESPACE, "ccstream-posted-delivery-list"); 514 515 /** 516 * Get the value of this proxy's {@link #POSTED_DELIVERY_LIST} property. 517 * @return A list containing this stream's posted deliveries. 518 * @throws WvcmException 519 * if this proxy doesn't define a value for this property. 520 */ 521 ResourceList<CcStream> getPostedDeliveryList() throws WvcmException; 522 523 /** Is this UCM stream in the middle of a delivery? 524 */ 525 PropertyName<Boolean> HAS_DELIVERY_IN_PROGRESS = 526 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-delivery-in-progress"); 527 528 /** 529 * Get the value of this proxy's {@link #HAS_DELIVERY_IN_PROGRESS} property. 530 * @return true if this stream is delivering, else false. 531 * @throws WvcmException 532 * if this proxy doesn't define a value for this property. 533 */ 534 boolean getHasDeliveryInProgress() throws WvcmException; 535 536 /** Is this locally mastered UCM stream in the middle of a posted 537 * delivery to a remotely mastered target? 538 */ 539 PropertyName<Boolean> HAS_POSTED_DELIVERY_IN_PROGRESS = 540 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-posted-delivery-in-progress"); 541 542 /** 543 * Get the value of this proxy's {@link #HAS_POSTED_DELIVERY_IN_PROGRESS} property. 544 * @return true if this stream is delivering to a remotely mastered target, else false. 545 * @throws WvcmException 546 * if this proxy doesn't define a value for this property. 547 */ 548 boolean getHasPostedDeliveryInProgress() throws WvcmException; 549 550 /** 551 * Get the value of this proxy's {@link #DELIVER_OPERATION} proxy. 552 * @return deliver operation if there is one in progress, else null 553 * @throws WvcmException 554 */ 555 CcDeliverOperation getDeliverOperation() throws WvcmException; 556 557 PropertyName<CcDeliverOperation> DELIVER_OPERATION = 558 new PropertyName<CcDeliverOperation>(PROPERTY_NAMESPACE, "deliver-operation"); 559 560 561 /** Is this UCM stream in the middle of a Rebase? 562 */ 563 PropertyName<Boolean> HAS_REBASE_IN_PROGRESS = 564 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-rebase-in-progress"); 565 566 /** 567 * Get the value of this proxy's {@link #HAS_REBASE_IN_PROGRESS} property. 568 * @return true if this stream is rebasing, else false. 569 * @throws WvcmException 570 * if this proxy doesn't define a value for this property. 571 */ 572 boolean getHasRebaseInProgress() throws WvcmException; 573 574 /** 575 * @deprecated TODO Placeholder for probable future property to track 576 * the status of a delivery to the integration stream 577 */ 578 PropertyName INTEGRATION_STATUS = new PropertyName(PROPERTY_NAMESPACE, 579 "integration-status"); 580 }