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 * © Copyright IBM Corporation 2004, 2008. 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 * @deprecated use {@link #doCompareReportEx(CcStream, CompareFlagEx[], Resource, Feedback)} 107 */ 108 public ResponseIterator<CompareReport> 109 doCompareReportEx(CcStream stream, CompareFlagEx[] flags, Feedback feedback) 110 throws WvcmException; 111 112 /** 113 * <p> 114 * Compare this CcStream with the specified stream. 115 * </p> 116 * <p> 117 * Specifically, compute the differences between these two streams in 118 * terms of baselines, activities, and/or versions. 119 * </p> 120 * @param stream stream to compare against 121 * @param flags specifies the types of differences to include in the 122 * compare report. 123 * @param context optional resource (often CcView) providing context for the 124 * generation of certain properties in the returned report. 125 * May be <b>null</b>. 126 * @param feedback the properties available in the returned proxies. 127 * @return a ResponseIterator of CompareReport objects, that enumerate the 128 * differences between the versions selected by this CcStream and 129 * the stream argument. 130 * @throws WvcmException 131 * @see CcBaseline#doCompareReportEx(CcStream, CompareFlagEx[], Feedback) for more information 132 */ 133 public ResponseIterator<CompareReport> 134 doCompareReportEx(CcStream stream, CompareFlagEx[] flags, Resource context, Feedback feedback) 135 throws WvcmException; 136 137 /** 138 * <p> 139 * List of all activities in the UCM stream. 140 * </p> 141 */ 142 PropertyName<ResourceList<CcActivity>> ACTIVITY_LIST = 143 new PropertyName<ResourceList<CcActivity>>(PROPERTY_NAMESPACE, 144 "activity-list"); 145 146 /** 147 * Get the value of this stream's {@link #ACTIVITY_LIST} property. 148 * 149 * @return a CcResourceList containing CcActivity instances, as described above 150 * @throws WvcmException 151 * if this proxy doesn't define a value for this property. 152 */ 153 ResourceList<CcActivity> getActivityList() throws WvcmException; 154 155 /** 156 * <p> 157 * The current user's activities in this UCM stream. The 158 * exact semantics of this property differ depending on whether the stream 159 * is associated with a ClearQuest-enabled UCM project. 160 * </p> 161 * <p> 162 * If this stream is associated with a ClearQuest-enabled UCM project, the 163 * resulting activity list is the result set from the <i>UCMCustomQuery1</i> 164 * query executed in the ClearQuest user database to which the UCM project 165 * is bound. In the out-of-the-box ClearQuest UCM schema, this query will 166 * return all CQ activities that are: 167 * </p> 168 * <ul> 169 * <li>assigned to the current user</li> 170 * <li>AND in the ready or active state,</li> 171 * <li>AND are NOT already bound to another project</li> 172 * </ul> 173 * <p> 174 * The UCMCustomQuery1 query can be modified by the customer, and if so will 175 * return other results. 176 * </p> 177 * <p> 178 * On the other hand, if this stream's project is <i>not</i> ClearQuest-enabled, 179 * the resulting activity list is simply all UCM activities in 180 * the stream that belong to the current user. 181 * </p> 182 * <p> 183 * In either case, the actual property value is a ResourceList of 184 * StpActivity instances. 185 * </p> 186 * @see com.ibm.rational.wvcm.stp.StpActivity 187 */ 188 PropertyName<ResourceList<StpActivity>> MY_ACTIVITY_LIST = 189 new PropertyName<ResourceList<StpActivity>>(PROPERTY_NAMESPACE, 190 "my-activity-list"); 191 192 /** 193 * Get the value of this stream's {@link #MY_ACTIVITY_LIST} property. 194 * 195 * @return a ResourceList of StpActivity instances, as described above 196 * @throws WvcmException 197 * if this proxy doesn't define a value for this property. 198 */ 199 ResourceList<StpActivity> getMyActivityList() throws WvcmException; 200 201 /** 202 * <p> 203 * This stream's baselines. A context of a CcComponent may be specified 204 * when reading this property in which case the list is limited to baselines 205 * for the specified CcComponent. 206 * </p> 207 * <p> 208 * When a stream is baselined, a new baseline is created for each component 209 * in the stream's configuration that was changed since the last time the 210 * stream was baselined. If a given component has not changed, no 211 * baseline is created for that component. 212 * </p> 213 */ 214 PropertyName<ResourceList<CcBaseline>> BASELINE_LIST = 215 new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, "baseline-list"); 216 217 /** 218 * Get the value of the this proxy's {@link #BASELINE_LIST} property. 219 * @return a list of client proxies for this project's baselines 220 * @throws WvcmException if this proxy doesn't define a value for this property. 221 */ 222 ResourceList<CcBaseline> getBaselineList() throws WvcmException; 223 224 /** 225 * <p> 226 * This stream's latest baselines. Specifically, the most recent baseline 227 * of each component in this stream's configuration that has been modified 228 * in this stream or the foundation baseline for components that have 229 * not been modified. 230 * </p> 231 * <p> 232 * When a stream is baselined, a new baseline is created for each component 233 * in the stream's configuration that was changed since the last time the 234 * stream was baselined. If a given component has not changed, no 235 * baseline is created for that component. 236 * </p> 237 */ 238 PropertyName<ResourceList<CcBaseline>> LATEST_BASELINE_LIST = 239 new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, "latest-baseline-list"); 240 241 /** 242 * Get the value of the this proxy's {@link #LATEST_BASELINE_LIST} property. 243 * @return a list of client proxies for this project's latest baselines 244 * @throws WvcmException if this proxy doesn't define a value for this property. 245 */ 246 ResourceList<CcBaseline> getLatestBaselineList() throws WvcmException; 247 248 /** 249 * The project to which this UCM stream belongs. 250 */ 251 PropertyName<CcProject> PARENT_PROJECT = 252 new PropertyName<CcProject>(PROPERTY_NAMESPACE, 253 "parent-project"); 254 255 /** 256 * Get the value of this stream's {@link #PARENT_PROJECT} property. 257 * 258 * @return stream's parent project 259 * @throws WvcmException 260 * if this proxy doesn't define a value for this property. 261 */ 262 CcProject getParentProject() throws WvcmException; 263 264 /** 265 * Set the value of this stream's {@link #PARENT_PROJECT} property. 266 * This property can only be set at stream creation time. 267 * 268 * @param parent 269 * stream's parent project 270 */ 271 void setParentProject(CcProject parent); 272 273 /** 274 * This UCM stream's parent stream. The value of this property is null 275 * if this is an integration stream. 276 */ 277 PropertyName<CcStream> PARENT_STREAM = new PropertyName<CcStream>(PROPERTY_NAMESPACE, 278 "parent-stream"); 279 280 /** 281 * Get the value of this stream's {@link #PARENT_STREAM} property. 282 * 283 * @return stream's parent stream, or null if this is an integration stream 284 * @throws WvcmException 285 * if this proxy doesn't define a value for this property. 286 */ 287 CcStream getParentStream() throws WvcmException; 288 289 /** 290 * Set the value of this stream's {@link #PARENT_STREAM} property. 291 * This property can only be set at stream creation time. 292 * 293 * @param parent 294 * stream's parent stream 295 */ 296 void setParentStream(CcStream parent); 297 298 /** This UCM stream's recommended baselines. */ 299 PropertyName<ResourceList<CcBaseline>> RECOMMENDED_BASELINE_LIST = 300 new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, 301 "recommended-baseline-list"); 302 303 /** 304 * Get the value of the this proxy's {@link #RECOMMENDED_BASELINE_LIST} property. 305 * @return a list of client proxies for this project's recommended baselines 306 * @throws WvcmException if this proxy doesn't define a value for this property. 307 */ 308 ResourceList<CcBaseline> getRecommendedBaselineList() throws WvcmException; 309 310 /** 311 * Set the value of the this proxy's {@link #RECOMMENDED_BASELINE_LIST} property. 312 * @param recBls a list of client proxies for this project's recommended baselines 313 */ 314 void setRecommendedBaselineList(ResourceList<CcBaseline> recBls); 315 316 /** 317 * The list of substreams of this UCM stream, i.e., the streams 318 * for which this stream is the parent. 319 */ 320 PropertyName<ResourceList<CcStream>> SUBSTREAM_LIST = 321 new PropertyName<ResourceList<CcStream>>(PROPERTY_NAMESPACE, 322 "substream-list"); 323 324 /** 325 * Get the value of this stream's {@link #SUBSTREAM_LIST} property. 326 * 327 * @return a list of client proxies for this stream's substreams 328 * @throws WvcmException 329 * if this proxy doesn't define a value for this property. 330 */ 331 ResourceList<CcStream> getSubstreamList() throws WvcmException; 332 333 /** The views associated with this UCM stream. */ 334 PropertyName<ResourceList<CcView>> VIEW_LIST = 335 new PropertyName<ResourceList<CcView>>(PROPERTY_NAMESPACE, 336 "view-list"); 337 338 /** 339 * Get the value of this stream's {@link #VIEW_LIST} property. 340 * 341 * @return the list of views associated with this stream 342 * @throws WvcmException 343 * if this proxy doesn't define a value for this property. 344 */ 345 ResourceList<CcView> getViewList() throws WvcmException; 346 347 /** Is this UCM stream an integration stream? */ 348 PropertyName<Boolean> IS_INTEGRATION_STREAM = 349 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 350 "is-integration-stream"); 351 352 /** 353 * Get the value of this stream's {@link #IS_INTEGRATION_STREAM} property. 354 * 355 * @return true if this stream is an integration stream, else false 356 * @throws WvcmException 357 * if this proxy doesn't define a value for this property. 358 */ 359 boolean getIsIntegrationStream() throws WvcmException; 360 361 /** 362 * Set the value of this stream's {@link #IS_INTEGRATION_STREAM} property. 363 * This property can only be set at stream creation time. 364 * 365 * @param isInt 366 * true if this stream is an integration stream, else false 367 */ 368 void setIsIntegrationStream(boolean isInt); 369 370 /** Is this a read-only UCM stream? */ 371 PropertyName<Boolean> IS_READ_ONLY = 372 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 373 "is-read-only"); 374 375 /** 376 * Get the value of this stream's {@link #IS_READ_ONLY} property. 377 * 378 * @return true if this stream is read-only, else false 379 * @throws WvcmException 380 * if this proxy doesn't define a value for this property. 381 */ 382 boolean getIsReadOnly() throws WvcmException; 383 384 /** 385 * Set the value of this stream's {@link #IS_READ_ONLY} property. 386 * This property can only be set at stream creation time. 387 * 388 * @param readOnly 389 * true if this stream is to be read-only, else false 390 */ 391 void setIsReadOnly(boolean readOnly); 392 393 /** This UCM stream's foundation baselines. */ 394 PropertyName<ResourceList<CcBaseline>> FOUNDATION_BASELINE_LIST = 395 new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, 396 "foundation-baseline-list"); 397 398 /** 399 * Get the value of this stream's {@link #FOUNDATION_BASELINE_LIST} 400 * property. 401 * 402 * @return a list of client proxies for this stream's foundation baselines 403 * @throws WvcmException 404 * if this proxy doesn't define a value for this property. 405 */ 406 ResourceList<CcBaseline> getFoundationBaselineList() throws WvcmException; 407 408 /** The default target (stream) for this UCM stream's deliver operations. */ 409 PropertyName<CcStream> DEFAULT_DELIVER_TARGET = 410 new PropertyName<CcStream>(PROPERTY_NAMESPACE, 411 "default-deliver-target"); 412 413 /** 414 * Get the value of this stream's {@link #DEFAULT_DELIVER_TARGET} property. 415 * 416 * @return a client proxy for this stream's default deliver target 417 * @throws WvcmException 418 * if this proxy doesn't define a value for this property. 419 */ 420 CcStream getDefaultDeliverTarget() throws WvcmException; 421 422 /** 423 * Set the value of this stream's {@link #DEFAULT_DELIVER_TARGET} property. 424 * The default deliver target for all non-integration streams is their parent 425 * stream. 426 * @param target 427 * this stream's new default deliver target or <code>null</code> to clear 428 * the deliver target 429 */ 430 void setDefaultDeliverTarget(CcStream target); 431 432 /** 433 * A list of streams that have posted deliveries in progress to this stream. 434 * A delivery is posted if the source stream is mastered at a different 435 * replica than the target stream at the time of the delivery. This property 436 * is not recursive; it only includes streams that are immediate children of 437 * this stream. 438 */ 439 PropertyName<ResourceList<CcStream>> POSTED_DELIVERY_LIST = 440 new PropertyName<ResourceList<CcStream>>(PROPERTY_NAMESPACE, "ccstream-posted-delivery-list"); 441 442 /** 443 * Get the value of this proxy's {@link #POSTED_DELIVERY_LIST} property. 444 * @return A list containing this stream's posted deliveries. 445 * @throws WvcmException 446 * if this proxy doesn't define a value for this property. 447 */ 448 ResourceList<CcStream> getPostedDeliveryList() throws WvcmException; 449 450 /** Is this locally mastered UCM stream in the middle of a posted 451 * delivery to a remotely mastered target? 452 */ 453 PropertyName<Boolean> HAS_POSTED_DELIVERY_IN_PROGRESS = 454 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-posted-delivery-in-progress"); 455 456 /** 457 * Get the value of this proxy's {@link #HAS_POSTED_DELIVERY_IN_PROGRESS} property. 458 * @return true if this stream is delivering to a remotely mastered target, else false. 459 * @throws WvcmException 460 * if this proxy doesn't define a value for this property. 461 */ 462 boolean getHasPostedDeliveryInProgress() throws WvcmException; 463 464 /** 465 * @deprecated TODO Placeholder for probable future property to track 466 * the status of a delivery to the integration stream 467 */ 468 PropertyName INTEGRATION_STATUS = new PropertyName(PROPERTY_NAMESPACE, 469 "integration-status"); 470 }