001    /*
002    * file CcStream.java
003    *
004    * Licensed Materials - Property of IBM
005    * Restricted Materials of IBM
006    * 
007    * com.ibm.rational.wvcm.stp.cc.CcStream
008    *
009    * (C) Copyright IBM Corporation 2004, 2012.  All Rights Reserved. 
010    * Note to U.S. Government Users Restricted Rights:  Use, duplication or  
011    * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp. 
012    */
013    
014    package com.ibm.rational.wvcm.stp.cc;
015    
016    import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017    
018    import javax.wvcm.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 #IS_READ_ONLY} </li>
086         * <li> {@link #COMMENT} </li>
087         * </bl>
088         * </p>
089         */
090        public CcStream doCreateCcStream(Feedback feedback) throws WvcmException;
091    
092        /**
093         * <p>Create a new UCM stream, allowing the provider to choose the
094         * new stream's name.
095         * The provider may use the client-specified location if it is valid,
096         * but can select a different location if the location is not valid
097         * or already identifies an stream.
098         * </p>
099         * @see #doCreateCcStream(Feedback)
100         */
101        public CcStream doCreateGeneratedCcStream(Feedback feedback) throws WvcmException;
102    
103        /**
104         * <p>
105         * Compare this CcStream with the specified stream.
106         * </p>
107         * <p>
108         * Specifically, compute the differences between these two streams in
109         * terms of baselines, activities, and/or versions. 
110         * </p>
111         * @param stream stream to compare against
112         * @param flags specifies the types of differences to include in the
113         *              compare report.
114         * @param context optional resource (often CcView) providing context for the
115         *                generation of certain properties in the returned report. 
116         *                May be <b>null</b>.
117         * @param feedback the properties available in the returned proxies.
118         * @return a ResponseIterator of CompareReport objects, that enumerate the 
119         *         differences between the versions selected by this CcStream and 
120         *         the stream argument.
121         * @throws WvcmException
122         * @see CcBaseline#doCompareReportEx(CcStream, CompareFlagEx[], javax.wvcm.Resource, javax.wvcm.Feedback)
123         *      for more information
124         */
125        public ResponseIterator<CompareReport>
126        doCompareReportEx(CcStream stream, CompareFlagEx[] flags, Resource context, Feedback feedback)
127            throws WvcmException;
128    
129        /**
130         * <p>
131         * List of all activities in the UCM stream. 
132         * </p>
133         */
134        PropertyName<ResourceList<CcActivity>> ACTIVITY_LIST =
135            new PropertyName<ResourceList<CcActivity>>(PROPERTY_NAMESPACE,
136                                                       "activity-list");
137    
138        /**
139         * Get the value of this stream's {@link #ACTIVITY_LIST} property.
140         * 
141         * @return a CcResourceList containing CcActivity instances, as described above
142         * @throws WvcmException
143         *             if this proxy doesn't define a value for this property.
144         */
145        ResourceList<CcActivity> getActivityList() throws WvcmException;
146    
147        /**
148         * <p>
149         * The current user's activities in this UCM stream. The
150         * exact semantics of this property differ depending on whether the stream
151         * is associated with a ClearQuest-enabled UCM project.
152         * </p>
153         * <p>
154         * If this stream is associated with a ClearQuest-enabled UCM project, the
155         * resulting activity list is the result set from the <i>UCMCustomQuery1</i>
156         * query executed in the ClearQuest user database to which the UCM project
157         * is bound. In the out-of-the-box ClearQuest UCM schema, this query will
158         * return all CQ activities that are:
159         * </p>
160         * <ul>
161         * <li>assigned to the current user</li>
162         * <li>AND in the ready or active state,</li>
163         * <li>AND are NOT already bound to another project</li>
164         * </ul>
165         * <p>
166         * The UCMCustomQuery1 query can be modified by the customer, and if so will
167         * return other results.
168         * </p>
169         * <p>
170         * On the other hand, if this stream's project is <i>not</i> ClearQuest-enabled,
171         * the resulting activity list is simply all UCM activities in
172         * the stream that belong to the current user.
173         * </p>
174         * <p>
175         * In either case, the actual property value is a ResourceList of
176         * StpActivity instances.
177         * </p>
178         * @see com.ibm.rational.wvcm.stp.StpActivity
179         */
180        PropertyName<ResourceList<StpActivity>> MY_ACTIVITY_LIST =
181            new PropertyName<ResourceList<StpActivity>>(PROPERTY_NAMESPACE,
182                                                       "my-activity-list");
183    
184        /**
185         * Get the value of this stream's {@link #MY_ACTIVITY_LIST} property.
186         * 
187         * @return a ResourceList of StpActivity instances, as described above
188         * @throws WvcmException
189         *             if this proxy doesn't define a value for this property.
190         */
191        ResourceList<StpActivity> getMyActivityList() throws WvcmException;
192     
193        /**
194         * <p>
195         * This stream's baselines.  A context of a CcComponent may be specified
196         * when reading this property in which case the list is limited to baselines
197         * for the specified CcComponent.
198         * </p>
199         * <p>
200         * When a stream is baselined, a new baseline is created for each component
201         * in the stream's configuration that was changed since the last time the
202         * stream was baselined.  If a given component has not changed, no
203         * baseline is created for that component.
204         * </p>
205         */
206        PropertyName<ResourceList<CcBaseline>> BASELINE_LIST =
207            new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, "baseline-list");
208    
209        /**
210         * Get the value of the this proxy's {@link #BASELINE_LIST} property.
211         * @return a list of client proxies for this project's baselines
212         * @throws WvcmException if this proxy doesn't define a value for this property.
213         */
214        ResourceList<CcBaseline> getBaselineList() throws WvcmException;
215    
216        /**
217         * <p>
218         * This stream's latest baselines.  Specifically, the most recent baseline
219         * of each component in this stream's configuration that has been modified
220         * in this stream or the foundation baseline for components that have
221         * not been modified.
222         * </p>
223         * <p>
224         * When a stream is baselined, a new baseline is created for each component
225         * in the stream's configuration that was changed since the last time the
226         * stream was baselined.  If a given component has not changed, no
227         * baseline is created for that component.
228         * </p>
229         */
230        PropertyName<ResourceList<CcBaseline>> LATEST_BASELINE_LIST =
231            new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, "latest-baseline-list");
232    
233        /**
234         * Get the value of the this proxy's {@link #LATEST_BASELINE_LIST} property.
235         * @return a list of client proxies for this project's latest baselines
236         * @throws WvcmException if this proxy doesn't define a value for this property.
237         */
238        ResourceList<CcBaseline> getLatestBaselineList() throws WvcmException;
239    
240        /**
241         * The project to which this UCM stream belongs.
242         */
243        PropertyName<CcProject> PARENT_PROJECT =
244            new PropertyName<CcProject>(PROPERTY_NAMESPACE,
245                                        "parent-project");
246    
247        /**
248         * Get the value of this stream's {@link #PARENT_PROJECT} property.
249         * 
250         * @return stream's parent project
251         * @throws WvcmException
252         *             if this proxy doesn't define a value for this property.
253         */
254        CcProject getParentProject() throws WvcmException;
255    
256        /**
257         * Set the value of this stream's {@link #PARENT_PROJECT} property.
258         * This property can only be set at stream creation time.
259         * 
260         * @param parent
261         *            stream's parent project
262         */
263        void setParentProject(CcProject parent);
264    
265        /**
266         * This UCM stream's parent stream.  The value of this property is null
267         * if this is an integration stream.
268         */
269        PropertyName<CcStream> PARENT_STREAM = new PropertyName<CcStream>(PROPERTY_NAMESPACE,
270                "parent-stream");
271    
272        /**
273         * Get the value of this stream's {@link #PARENT_STREAM} property.
274         * 
275         * @return stream's parent stream, or null if this is an integration stream
276         * @throws WvcmException
277         *             if this proxy doesn't define a value for this property.
278         */
279        CcStream getParentStream() throws WvcmException;
280    
281        /**
282         * Set the value of this stream's {@link #PARENT_STREAM} property.
283         * This property can only be set at stream creation time.
284         * 
285         * @param parent
286         *            stream's parent stream
287         */
288        void setParentStream(CcStream parent);
289    
290        /** This UCM stream's recommended baselines. */
291        PropertyName<ResourceList<CcBaseline>> RECOMMENDED_BASELINE_LIST =
292            new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE,
293                                                       "recommended-baseline-list");
294    
295        /**
296         * Get the value of the this proxy's {@link #RECOMMENDED_BASELINE_LIST} property.
297         * @return a list of client proxies for this project's recommended baselines
298         * @throws WvcmException if this proxy doesn't define a value for this property.
299         */
300        ResourceList<CcBaseline> getRecommendedBaselineList() throws WvcmException;
301    
302        /** This UCM stream's full closure of recommended baselines. */
303        PropertyName<ResourceList<CcBaseline>> RECOMMENDED_BASELINE_LIST_CLOSURE =
304            new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE,
305                                                       "recommended-baseline-list-closure");
306    
307        /**
308         * Get the value of the this proxy's {@link #EXPLICIT_BASELINE_LIST} property.
309         * @return a list of client proxies for this stream's explicit baselines
310         * @throws WvcmException if this proxy doesn't define a value for this property.
311         */
312        ResourceList<CcBaseline> getExplicitBaselineList() throws WvcmException;    
313     
314        
315        /** This UCM stream's list of explicit baselines. */
316        PropertyName<ResourceList<CcBaseline>> EXPLICIT_BASELINE_LIST =
317            new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE,
318                                                       "explicit-baseline-list");
319    
320        /**
321         * Get the value of the this proxy's {@link #RECOMMENDED_BASELINE_LIST_CLOSURE} property.
322         * @return a list of client proxies for this project's recommended baselines
323         * @throws WvcmException if this proxy doesn't define a value for this property.
324         */
325        ResourceList<CcBaseline> getRecommendedBaselineListClosure() throws WvcmException;
326        
327        /**
328         * Set the value of the this proxy's {@link #RECOMMENDED_BASELINE_LIST} property.
329         * @param recBls a list of client proxies for this project's recommended baselines
330         */
331        void setRecommendedBaselineList(ResourceList<CcBaseline> recBls);    
332        
333        /**
334         * The list of substreams of this UCM stream, i.e., the streams
335         * for which this stream is the parent.
336         */
337        PropertyName<ResourceList<CcStream>> SUBSTREAM_LIST =
338            new PropertyName<ResourceList<CcStream>>(PROPERTY_NAMESPACE,
339                                                     "substream-list");
340    
341        /**
342         * Get the value of this stream's {@link #SUBSTREAM_LIST} property.
343         * 
344         * @return a list of client proxies for this stream's substreams
345         * @throws WvcmException
346         *             if this proxy doesn't define a value for this property.
347         */
348        ResourceList<CcStream> getSubstreamList() throws WvcmException;
349    
350        /** The views associated with this UCM stream. */
351        PropertyName<ResourceList<CcView>> VIEW_LIST =
352            new PropertyName<ResourceList<CcView>>(PROPERTY_NAMESPACE,
353                                                   "view-list");
354    
355        /**
356         * Get the value of this stream's {@link #VIEW_LIST} property.
357         * 
358         * @return the list of views associated with this stream
359         * @throws WvcmException
360         *             if this proxy doesn't define a value for this property.
361         */
362        ResourceList<CcView> getViewList() throws WvcmException;
363    
364        /** Is this UCM stream an integration stream? */
365        PropertyName<Boolean> IS_INTEGRATION_STREAM =
366            new PropertyName<Boolean>(PROPERTY_NAMESPACE,
367                                      "is-integration-stream");
368    
369        /**
370         * Get the value of this stream's {@link #IS_INTEGRATION_STREAM} property.
371         * 
372         * @return true if this stream is an integration stream, else false
373         * @throws WvcmException
374         *             if this proxy doesn't define a value for this property.
375         */
376        boolean getIsIntegrationStream() throws WvcmException;
377    
378        /**
379         * Set the value of this stream's {@link #IS_INTEGRATION_STREAM} property.
380         * This property can only be set at stream creation time.
381         * 
382         * @param isInt
383         *            true if this stream is an integration stream, else false
384         */
385        void setIsIntegrationStream(boolean isInt);
386    
387        /** Is this a read-only UCM stream? */
388        PropertyName<Boolean> IS_READ_ONLY =
389            new PropertyName<Boolean>(PROPERTY_NAMESPACE,
390                                      "is-read-only");
391    
392        /**
393         * Get the value of this stream's {@link #IS_READ_ONLY} property.
394         * 
395         * @return true if this stream is read-only, else false
396         * @throws WvcmException
397         *             if this proxy doesn't define a value for this property.
398         */
399        boolean getIsReadOnly() throws WvcmException;
400    
401        /**
402         * Set the value of this stream's {@link #IS_READ_ONLY} property.
403         * This property can only be set at stream creation time.
404         * 
405         * @param readOnly
406         *            true if this stream is to be read-only, else false
407         */
408        void setIsReadOnly(boolean readOnly);
409    
410        /** Is Delivery allowed with checkouts in this stream */
411        PropertyName<Boolean> DELIVER_POLICY_NO_CHECKOUTS_IN_STREAM =
412            new PropertyName<Boolean>(PROPERTY_NAMESPACE,
413                "deliver-policy-no-checkouts-stream");     
414        
415        /**
416         * Get the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_STREAM } property.
417         * 
418         * @return true if the policy to disallow Deliver with checkouts in this stream is enabled
419         * @throws WvcmException
420         *             if this proxy doesn't define a value for this property.
421         */
422        boolean getDeliverPolicyNoCheckoutsInStream() throws WvcmException;    
423            
424        /**
425         * Set the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_STREAM } property.
426         *
427         * 
428         * @param enablePolicy
429         *            true to enable the policy to disallow Deliver with checkouts in this stream
430         */    
431        void setDeliverPolicyNoCheckoutsInStream(boolean enablePolicy); 
432        
433    
434        /** Is Delivery allowed with checkouts in selected activities */
435        PropertyName<Boolean> DELIVER_POLICY_NO_CHECKOUTS_IN_ACTIVITIES =
436            new PropertyName<Boolean>(PROPERTY_NAMESPACE,
437                "deliver-policy-no-checkouts-activities");     
438        
439        /**
440         * Get the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_ACTIVITIES } property.
441         * 
442         * @return true if the policy to disallow Deliver with checkouts in selected activities is enabled for this stream
443         * @throws WvcmException
444         *             if this proxy doesn't define a value for this property.
445         */
446        boolean getDeliverPolicyNoCheckoutsInActivities() throws WvcmException;    
447            
448        /**
449         * Set the value of this stream's {@link #DELIVER_POLICY_NO_CHECKOUTS_IN_ACTIVITIES } property.
450         *
451         * 
452         * @param enablePolicy
453         *            true to enable the policy to disallow Deliver with checkouts in selected activities for this stream
454         */    
455        void setDeliverPolicyNoCheckoutsInActivities(boolean enablePolicy);    
456        
457        
458        /** This UCM stream's foundation baselines. */
459        PropertyName<ResourceList<CcBaseline>> FOUNDATION_BASELINE_LIST =
460            new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE,
461                                                       "foundation-baseline-list");
462    
463        /**
464         * Get the value of this stream's {@link #FOUNDATION_BASELINE_LIST}
465         * property.
466         * 
467         * @return a list of client proxies for this stream's foundation baselines
468         * @throws WvcmException
469         *             if this proxy doesn't define a value for this property.
470         */
471        ResourceList<CcBaseline> getFoundationBaselineList() throws WvcmException;
472    
473        /** The list of components from this stream's complete list of foundation baselines */    
474        PropertyName<ResourceList<CcComponent>> COMPONENT_LIST =
475            new PropertyName<ResourceList<CcComponent>> (PROPERTY_NAMESPACE,
476                                                         "component-list");
477    
478        /**
479         * Get the value of this stream's {@link #COMPONENT_LIST}
480         * property.
481         * 
482         * @return a list of client proxies for this stream's components that are baselined by this 
483         *         stream's foundation baselines
484         * @throws WvcmException
485         *             if this proxy doesn't define a value for this property.
486         */
487        ResourceList<CcComponent> getComponentList() throws WvcmException;
488        
489        /** The default target (stream) for this UCM stream's deliver operations. */
490        PropertyName<CcStream> DEFAULT_DELIVER_TARGET =
491            new PropertyName<CcStream>(PROPERTY_NAMESPACE,
492                                       "default-deliver-target");
493    
494        /**
495         * Get the value of this stream's {@link #DEFAULT_DELIVER_TARGET} property.
496         * 
497         * @return a client proxy for this stream's default deliver target,
498         *         or <code>null</code> if there is no default deliver target
499         *         defined for this stream
500         * @throws WvcmException
501         *             if this proxy doesn't define a value for this property.
502         */
503        CcStream getDefaultDeliverTarget() throws WvcmException;
504    
505        /**
506         * Set the value of this stream's {@link #DEFAULT_DELIVER_TARGET} property.
507         * The default deliver target can only be changed on integration streams.
508         * The default deliver target for all non-integration streams is their parent 
509         * stream.
510         * @param target
511         *            this stream's new default deliver target or <code>null</code> to clear 
512         *            the deliver target
513         */
514        void setDefaultDeliverTarget(CcStream target);
515        
516        /** 
517         * A list of streams that have posted deliveries in progress to this stream.
518         * A delivery is posted if the source stream is mastered at a different 
519         * replica than the target stream at the time of the delivery. This property
520         * is not recursive; it only includes streams that are immediate children of
521         * this stream.
522         */
523        PropertyName<ResourceList<CcStream>> POSTED_DELIVERY_LIST =
524            new PropertyName<ResourceList<CcStream>>(PROPERTY_NAMESPACE, "ccstream-posted-delivery-list");
525        
526        /**
527         * Get the value of this proxy's {@link #POSTED_DELIVERY_LIST} property.
528         * @return A list containing this stream's posted deliveries.
529         * @throws WvcmException 
530         *             if this proxy doesn't define a value for this property.
531         */
532        ResourceList<CcStream> getPostedDeliveryList() throws WvcmException;
533    
534        /** Is this UCM stream in the middle of a delivery?
535         */
536        PropertyName<Boolean> HAS_DELIVERY_IN_PROGRESS =
537            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-delivery-in-progress");
538        
539        /**
540         * Get the value of this proxy's {@link #HAS_DELIVERY_IN_PROGRESS} property.
541         * @return true if this stream is delivering, else false.
542         * @throws WvcmException 
543         *             if this proxy doesn't define a value for this property.
544         */
545        boolean getHasDeliveryInProgress() throws WvcmException;
546        
547        /** Is this locally mastered UCM stream in the middle of a posted 
548         * delivery to a remotely mastered target?
549         */
550        PropertyName<Boolean> HAS_POSTED_DELIVERY_IN_PROGRESS =
551            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-posted-delivery-in-progress");
552        
553        /**
554         * Get the value of this proxy's {@link #HAS_POSTED_DELIVERY_IN_PROGRESS} property.
555         * @return true if this stream is delivering to a remotely mastered target, else false.
556         * @throws WvcmException 
557         *             if this proxy doesn't define a value for this property.
558         */
559        boolean getHasPostedDeliveryInProgress() throws WvcmException;
560        
561        /**
562         * Get the value of this proxy's {@link #DELIVER_OPERATION} proxy.
563         * @return deliver operation if there is one in progress, else null
564         * @throws WvcmException
565         */
566        CcDeliverOperation getDeliverOperation() throws WvcmException;
567        
568        PropertyName<CcDeliverOperation> DELIVER_OPERATION = 
569            new PropertyName<CcDeliverOperation>(PROPERTY_NAMESPACE, "deliver-operation");
570        
571        
572        /** Is this UCM stream in the middle of a Rebase?
573         */
574        PropertyName<Boolean> HAS_REBASE_IN_PROGRESS =
575            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-rebase-in-progress");
576        
577        /**
578         * Get the value of this proxy's {@link #HAS_REBASE_IN_PROGRESS} property.
579         * @return true if this stream is rebasing, else false.
580         * @throws WvcmException 
581         *             if this proxy doesn't define a value for this property.
582         */
583        boolean getHasRebaseInProgress() throws WvcmException;    
584    
585        /**
586         * @deprecated TODO Placeholder for probable future property to track
587         * the status of a delivery to the integration stream
588         */
589        PropertyName INTEGRATION_STATUS = new PropertyName(PROPERTY_NAMESPACE,
590                                                           "integration-status");
591    }