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    }