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 }