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, 2013.  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
014package com.ibm.rational.wvcm.stp.cc;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import javax.wvcm.Baseline.CompareReport;
019import javax.wvcm.Feedback;
020import javax.wvcm.PropertyNameList.PropertyName;
021import javax.wvcm.Resource;
022import javax.wvcm.ResourceList;
023import javax.wvcm.ResourceList.ResponseIterator;
024import javax.wvcm.Stream;
025import javax.wvcm.WvcmException;
026
027import com.ibm.rational.wvcm.stp.StpActivity;
028import 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 */
062public 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    
474    /**
475     * Set the value of this stream's {@link #FOUNDATION_BASELINE_LIST} property.
476     * This property can only be set at stream creation time. 
477     * 
478     * @param foundationBaselines 
479     *            a list of client proxies for this stream's foundation baselines
480     *            or <code>null</code> to create a stream with empty foundation. 
481     */
482    void setFoundationBaselineList(ResourceList<CcBaseline> foundationBaselines); 
483
484    /** The list of components from this stream's complete list of foundation baselines */    
485    PropertyName<ResourceList<CcComponent>> COMPONENT_LIST =
486        new PropertyName<ResourceList<CcComponent>> (PROPERTY_NAMESPACE,
487                                                     "component-list");
488
489    /**
490     * Get the value of this stream's {@link #COMPONENT_LIST}
491     * property.
492     * 
493     * @return a list of client proxies for this stream's components that are baselined by this 
494     *         stream's foundation baselines
495     * @throws WvcmException
496     *             if this proxy doesn't define a value for this property.
497     */
498    ResourceList<CcComponent> getComponentList() throws WvcmException;
499    
500    /** The default target (stream) for this UCM stream's deliver operations. */
501    PropertyName<CcStream> DEFAULT_DELIVER_TARGET =
502        new PropertyName<CcStream>(PROPERTY_NAMESPACE,
503                                   "default-deliver-target");
504
505    /**
506     * Get the value of this stream's {@link #DEFAULT_DELIVER_TARGET} property.
507     * 
508     * @return a client proxy for this stream's default deliver target,
509     *         or <code>null</code> if there is no default deliver target
510     *         defined for this stream
511     * @throws WvcmException
512     *             if this proxy doesn't define a value for this property.
513     */
514    CcStream getDefaultDeliverTarget() throws WvcmException;
515
516    /**
517     * Set the value of this stream's {@link #DEFAULT_DELIVER_TARGET} property.
518     * The default deliver target can only be changed on integration streams.
519     * The default deliver target for all non-integration streams is their parent 
520     * stream.
521     * @param target
522     *            this stream's new default deliver target or <code>null</code> to clear 
523     *            the deliver target
524     */
525    void setDefaultDeliverTarget(CcStream target);
526    
527    /** 
528     * A list of streams that have posted deliveries in progress to this stream.
529     * A delivery is posted if the source stream is mastered at a different 
530     * replica than the target stream at the time of the delivery. This property
531     * is not recursive; it only includes streams that are immediate children of
532     * this stream.
533     */
534    PropertyName<ResourceList<CcStream>> POSTED_DELIVERY_LIST =
535        new PropertyName<ResourceList<CcStream>>(PROPERTY_NAMESPACE, "ccstream-posted-delivery-list");
536    
537    /**
538     * Get the value of this proxy's {@link #POSTED_DELIVERY_LIST} property.
539     * @return A list containing this stream's posted deliveries.
540     * @throws WvcmException 
541     *             if this proxy doesn't define a value for this property.
542     */
543    ResourceList<CcStream> getPostedDeliveryList() throws WvcmException;
544
545    /** Is this UCM stream in the middle of a delivery?
546     */
547    PropertyName<Boolean> HAS_DELIVERY_IN_PROGRESS =
548        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-delivery-in-progress");
549    
550    /**
551     * Get the value of this proxy's {@link #HAS_DELIVERY_IN_PROGRESS} property.
552     * @return true if this stream is delivering, else false.
553     * @throws WvcmException 
554     *             if this proxy doesn't define a value for this property.
555     */
556    boolean getHasDeliveryInProgress() throws WvcmException;
557    
558    /** Is this locally mastered UCM stream in the middle of a posted 
559     * delivery to a remotely mastered target?
560     */
561    PropertyName<Boolean> HAS_POSTED_DELIVERY_IN_PROGRESS =
562        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-posted-delivery-in-progress");
563    
564    /**
565     * Get the value of this proxy's {@link #HAS_POSTED_DELIVERY_IN_PROGRESS} property.
566     * @return true if this stream is delivering to a remotely mastered target, else false.
567     * @throws WvcmException 
568     *             if this proxy doesn't define a value for this property.
569     */
570    boolean getHasPostedDeliveryInProgress() throws WvcmException;
571    
572    /**
573     * Get the value of this proxy's {@link #DELIVER_OPERATION} proxy.
574     * @return deliver operation if there is one in progress, else null
575     * @throws WvcmException
576     */
577    CcDeliverOperation getDeliverOperation() throws WvcmException;
578    
579    PropertyName<CcDeliverOperation> DELIVER_OPERATION = 
580        new PropertyName<CcDeliverOperation>(PROPERTY_NAMESPACE, "deliver-operation");
581    
582    
583    /** Is this UCM stream in the middle of a Rebase?
584     */
585    PropertyName<Boolean> HAS_REBASE_IN_PROGRESS =
586        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-rebase-in-progress");
587    
588    /**
589     * Get the value of this proxy's {@link #HAS_REBASE_IN_PROGRESS} property.
590     * @return true if this stream is rebasing, else false.
591     * @throws WvcmException 
592     *             if this proxy doesn't define a value for this property.
593     */
594    boolean getHasRebaseInProgress() throws WvcmException;    
595    
596    /**
597     * @deprecated TODO Placeholder for probable future property to track
598     * the status of a delivery to the integration stream
599     */
600    PropertyName INTEGRATION_STATUS = new PropertyName(PROPERTY_NAMESPACE,
601                                                       "integration-status");
602}