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 #RECOMMENDED_BASELINE_LIST_CLOSURE} property.
311         * @return a list of client proxies for this project's recommended baselines
312         * @throws WvcmException if this proxy doesn't define a value for this property.
313         */
314        ResourceList<CcBaseline> getRecommendedBaselineListClosure() throws WvcmException;
315        
316        /**
317         * Set the value of the this proxy's {@link #RECOMMENDED_BASELINE_LIST} property.
318         * @param recBls a list of client proxies for this project's recommended baselines
319         */
320        void setRecommendedBaselineList(ResourceList<CcBaseline> recBls);
321     
322        /**
323         * The list of substreams of this UCM stream, i.e., the streams
324         * for which this stream is the parent.
325         */
326        PropertyName<ResourceList<CcStream>> SUBSTREAM_LIST =
327            new PropertyName<ResourceList<CcStream>>(PROPERTY_NAMESPACE,
328                                                     "substream-list");
329    
330        /**
331         * Get the value of this stream's {@link #SUBSTREAM_LIST} property.
332         * 
333         * @return a list of client proxies for this stream's substreams
334         * @throws WvcmException
335         *             if this proxy doesn't define a value for this property.
336         */
337        ResourceList<CcStream> getSubstreamList() throws WvcmException;
338    
339        /** The views associated with this UCM stream. */
340        PropertyName<ResourceList<CcView>> VIEW_LIST =
341            new PropertyName<ResourceList<CcView>>(PROPERTY_NAMESPACE,
342                                                   "view-list");
343    
344        /**
345         * Get the value of this stream's {@link #VIEW_LIST} property.
346         * 
347         * @return the list of views associated with this stream
348         * @throws WvcmException
349         *             if this proxy doesn't define a value for this property.
350         */
351        ResourceList<CcView> getViewList() throws WvcmException;
352    
353        /** Is this UCM stream an integration stream? */
354        PropertyName<Boolean> IS_INTEGRATION_STREAM =
355            new PropertyName<Boolean>(PROPERTY_NAMESPACE,
356                                      "is-integration-stream");
357    
358        /**
359         * Get the value of this stream's {@link #IS_INTEGRATION_STREAM} property.
360         * 
361         * @return true if this stream is an integration stream, else false
362         * @throws WvcmException
363         *             if this proxy doesn't define a value for this property.
364         */
365        boolean getIsIntegrationStream() throws WvcmException;
366    
367        /**
368         * Set the value of this stream's {@link #IS_INTEGRATION_STREAM} property.
369         * This property can only be set at stream creation time.
370         * 
371         * @param isInt
372         *            true if this stream is an integration stream, else false
373         */
374        void setIsIntegrationStream(boolean isInt);
375    
376        /** Is this a read-only UCM stream? */
377        PropertyName<Boolean> IS_READ_ONLY =
378            new PropertyName<Boolean>(PROPERTY_NAMESPACE,
379                                      "is-read-only");
380    
381        /**
382         * Get the value of this stream's {@link #IS_READ_ONLY} property.
383         * 
384         * @return true if this stream is read-only, else false
385         * @throws WvcmException
386         *             if this proxy doesn't define a value for this property.
387         */
388        boolean getIsReadOnly() throws WvcmException;
389    
390        /**
391         * Set the value of this stream's {@link #IS_READ_ONLY} property.
392         * This property can only be set at stream creation time.
393         * 
394         * @param readOnly
395         *            true if this stream is to be read-only, else false
396         */
397        void setIsReadOnly(boolean readOnly);
398    
399        /** Is Delivery allowed with checkouts in this stream */
400        PropertyName<Boolean> DELIVER_POLICY_NO_CHECKOUTS_IN_STREAM =
401            new PropertyName<Boolean>(PROPERTY_NAMESPACE,
402                "deliver-policy-no-checkouts-stream");     
403        
404        /**
405         * Get the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_STREAM } property.
406         * 
407         * @return true if the policy to disallow Deliver with checkouts in this stream is enabled
408         * @throws WvcmException
409         *             if this proxy doesn't define a value for this property.
410         */
411        boolean getDeliverPolicyNoCheckoutsInStream() throws WvcmException;    
412            
413        /**
414         * Set the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_STREAM } property.
415         *
416         * 
417         * @param enablePolicy
418         *            true to enable the policy to disallow Deliver with checkouts in this stream
419         */    
420        void setDeliverPolicyNoCheckoutsInStream(boolean enablePolicy); 
421        
422    
423        /** Is Delivery allowed with checkouts in selected activities */
424        PropertyName<Boolean> DELIVER_POLICY_NO_CHECKOUTS_IN_ACTIVITIES =
425            new PropertyName<Boolean>(PROPERTY_NAMESPACE,
426                "deliver-policy-no-checkouts-activities");     
427        
428        /**
429         * Get the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_ACTIVITIES } property.
430         * 
431         * @return true if the policy to disallow Deliver with checkouts in selected activities is enabled for this stream
432         * @throws WvcmException
433         *             if this proxy doesn't define a value for this property.
434         */
435        boolean getDeliverPolicyNoCheckoutsInActivities() throws WvcmException;    
436            
437        /**
438         * Set the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_ACTIVITIES } property.
439         *
440         * 
441         * @param enablePolicy
442         *            true to enable the policy to disallow Deliver with checkouts in selected activities for this stream
443         */    
444        void setDeliverPolicyNoCheckoutsInActivities(boolean enablePolicy);    
445        
446        
447        /** This UCM stream's foundation baselines. */
448        PropertyName<ResourceList<CcBaseline>> FOUNDATION_BASELINE_LIST =
449            new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE,
450                                                       "foundation-baseline-list");
451    
452        /**
453         * Get the value of this stream's {@link #FOUNDATION_BASELINE_LIST}
454         * property.
455         * 
456         * @return a list of client proxies for this stream's foundation baselines
457         * @throws WvcmException
458         *             if this proxy doesn't define a value for this property.
459         */
460        ResourceList<CcBaseline> getFoundationBaselineList() throws WvcmException;
461    
462        /** The list of components from this stream's complete list of foundation baselines */    
463        PropertyName<ResourceList<CcComponent>> COMPONENT_LIST =
464            new PropertyName<ResourceList<CcComponent>> (PROPERTY_NAMESPACE,
465                                                         "component-list");
466    
467        /**
468         * Get the value of this stream's {@link #COMPONENT_LIST}
469         * property.
470         * 
471         * @return a list of client proxies for this stream's components that are baselined by this 
472         *         stream's foundation baselines
473         * @throws WvcmException
474         *             if this proxy doesn't define a value for this property.
475         */
476        ResourceList<CcComponent> getComponentList() throws WvcmException;
477        
478        /** The default target (stream) for this UCM stream's deliver operations. */
479        PropertyName<CcStream> DEFAULT_DELIVER_TARGET =
480            new PropertyName<CcStream>(PROPERTY_NAMESPACE,
481                                       "default-deliver-target");
482    
483        /**
484         * Get the value of this stream's {@link #DEFAULT_DELIVER_TARGET} property.
485         * 
486         * @return a client proxy for this stream's default deliver target,
487         *         or <code>null</code> if there is no default deliver target
488         *         defined for this stream
489         * @throws WvcmException
490         *             if this proxy doesn't define a value for this property.
491         */
492        CcStream getDefaultDeliverTarget() throws WvcmException;
493    
494        /**
495         * Set the value of this stream's {@link #DEFAULT_DELIVER_TARGET} property.
496         * The default deliver target can only be changed on integration streams.
497         * The default deliver target for all non-integration streams is their parent 
498         * stream.
499         * @param target
500         *            this stream's new default deliver target or <code>null</code> to clear 
501         *            the deliver target
502         */
503        void setDefaultDeliverTarget(CcStream target);
504        
505        /** 
506         * A list of streams that have posted deliveries in progress to this stream.
507         * A delivery is posted if the source stream is mastered at a different 
508         * replica than the target stream at the time of the delivery. This property
509         * is not recursive; it only includes streams that are immediate children of
510         * this stream.
511         */
512        PropertyName<ResourceList<CcStream>> POSTED_DELIVERY_LIST =
513            new PropertyName<ResourceList<CcStream>>(PROPERTY_NAMESPACE, "ccstream-posted-delivery-list");
514        
515        /**
516         * Get the value of this proxy's {@link #POSTED_DELIVERY_LIST} property.
517         * @return A list containing this stream's posted deliveries.
518         * @throws WvcmException 
519         *             if this proxy doesn't define a value for this property.
520         */
521        ResourceList<CcStream> getPostedDeliveryList() throws WvcmException;
522    
523        /** Is this UCM stream in the middle of a delivery?
524         */
525        PropertyName<Boolean> HAS_DELIVERY_IN_PROGRESS =
526            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-delivery-in-progress");
527        
528        /**
529         * Get the value of this proxy's {@link #HAS_DELIVERY_IN_PROGRESS} property.
530         * @return true if this stream is delivering, else false.
531         * @throws WvcmException 
532         *             if this proxy doesn't define a value for this property.
533         */
534        boolean getHasDeliveryInProgress() throws WvcmException;
535        
536        /** Is this locally mastered UCM stream in the middle of a posted 
537         * delivery to a remotely mastered target?
538         */
539        PropertyName<Boolean> HAS_POSTED_DELIVERY_IN_PROGRESS =
540            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-posted-delivery-in-progress");
541        
542        /**
543         * Get the value of this proxy's {@link #HAS_POSTED_DELIVERY_IN_PROGRESS} property.
544         * @return true if this stream is delivering to a remotely mastered target, else false.
545         * @throws WvcmException 
546         *             if this proxy doesn't define a value for this property.
547         */
548        boolean getHasPostedDeliveryInProgress() throws WvcmException;
549        
550        /**
551         * Get the value of this proxy's {@link #DELIVER_OPERATION} proxy.
552         * @return deliver operation if there is one in progress, else null
553         * @throws WvcmException
554         */
555        CcDeliverOperation getDeliverOperation() throws WvcmException;
556        
557        PropertyName<CcDeliverOperation> DELIVER_OPERATION = 
558            new PropertyName<CcDeliverOperation>(PROPERTY_NAMESPACE, "deliver-operation");
559        
560        
561        /** Is this UCM stream in the middle of a Rebase?
562         */
563        PropertyName<Boolean> HAS_REBASE_IN_PROGRESS =
564            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-rebase-in-progress");
565        
566        /**
567         * Get the value of this proxy's {@link #HAS_REBASE_IN_PROGRESS} property.
568         * @return true if this stream is rebasing, else false.
569         * @throws WvcmException 
570         *             if this proxy doesn't define a value for this property.
571         */
572        boolean getHasRebaseInProgress() throws WvcmException;    
573    
574        /**
575         * @deprecated TODO Placeholder for probable future property to track
576         * the status of a delivery to the integration stream
577         */
578        PropertyName INTEGRATION_STATUS = new PropertyName(PROPERTY_NAMESPACE,
579                                                           "integration-status");
580    }