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.Baseline.CompareReport;
019 import javax.wvcm.Feedback;
020 import javax.wvcm.PropertyNameList.PropertyName;
021 import javax.wvcm.Resource;
022 import javax.wvcm.ResourceList;
023 import javax.wvcm.ResourceList.ResponseIterator;
024 import javax.wvcm.Stream;
025 import javax.wvcm.WvcmException;
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 }