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    * © Copyright IBM Corporation 2004, 2008.  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         * @deprecated use {@link #doCompareReportEx(CcStream, CompareFlagEx[], Resource, Feedback)}
107         */
108        public ResponseIterator<CompareReport>
109        doCompareReportEx(CcStream stream, CompareFlagEx[] flags, Feedback feedback)
110            throws WvcmException;
111    
112        /**
113         * <p>
114         * Compare this CcStream with the specified stream.
115         * </p>
116         * <p>
117         * Specifically, compute the differences between these two streams in
118         * terms of baselines, activities, and/or versions. 
119         * </p>
120         * @param stream stream to compare against
121         * @param flags specifies the types of differences to include in the
122         *              compare report.
123         * @param context optional resource (often CcView) providing context for the
124         *                generation of certain properties in the returned report. 
125         *                May be <b>null</b>.
126         * @param feedback the properties available in the returned proxies.
127         * @return a ResponseIterator of CompareReport objects, that enumerate the 
128         *         differences between the versions selected by this CcStream and 
129         *         the stream argument.
130         * @throws WvcmException
131         * @see CcBaseline#doCompareReportEx(CcStream, CompareFlagEx[], Feedback) for more information
132         */
133        public ResponseIterator<CompareReport>
134        doCompareReportEx(CcStream stream, CompareFlagEx[] flags, Resource context, Feedback feedback)
135            throws WvcmException;
136    
137        /**
138         * <p>
139         * List of all activities in the UCM stream. 
140         * </p>
141         */
142        PropertyName<ResourceList<CcActivity>> ACTIVITY_LIST =
143            new PropertyName<ResourceList<CcActivity>>(PROPERTY_NAMESPACE,
144                                                       "activity-list");
145    
146        /**
147         * Get the value of this stream's {@link #ACTIVITY_LIST} property.
148         * 
149         * @return a CcResourceList containing CcActivity instances, as described above
150         * @throws WvcmException
151         *             if this proxy doesn't define a value for this property.
152         */
153        ResourceList<CcActivity> getActivityList() throws WvcmException;
154    
155        /**
156         * <p>
157         * The current user's activities in this UCM stream. The
158         * exact semantics of this property differ depending on whether the stream
159         * is associated with a ClearQuest-enabled UCM project.
160         * </p>
161         * <p>
162         * If this stream is associated with a ClearQuest-enabled UCM project, the
163         * resulting activity list is the result set from the <i>UCMCustomQuery1</i>
164         * query executed in the ClearQuest user database to which the UCM project
165         * is bound. In the out-of-the-box ClearQuest UCM schema, this query will
166         * return all CQ activities that are:
167         * </p>
168         * <ul>
169         * <li>assigned to the current user</li>
170         * <li>AND in the ready or active state,</li>
171         * <li>AND are NOT already bound to another project</li>
172         * </ul>
173         * <p>
174         * The UCMCustomQuery1 query can be modified by the customer, and if so will
175         * return other results.
176         * </p>
177         * <p>
178         * On the other hand, if this stream's project is <i>not</i> ClearQuest-enabled,
179         * the resulting activity list is simply all UCM activities in
180         * the stream that belong to the current user.
181         * </p>
182         * <p>
183         * In either case, the actual property value is a ResourceList of
184         * StpActivity instances.
185         * </p>
186         * @see com.ibm.rational.wvcm.stp.StpActivity
187         */
188        PropertyName<ResourceList<StpActivity>> MY_ACTIVITY_LIST =
189            new PropertyName<ResourceList<StpActivity>>(PROPERTY_NAMESPACE,
190                                                       "my-activity-list");
191    
192        /**
193         * Get the value of this stream's {@link #MY_ACTIVITY_LIST} property.
194         * 
195         * @return a ResourceList of StpActivity instances, as described above
196         * @throws WvcmException
197         *             if this proxy doesn't define a value for this property.
198         */
199        ResourceList<StpActivity> getMyActivityList() throws WvcmException;
200     
201        /**
202         * <p>
203         * This stream's baselines.  A context of a CcComponent may be specified
204         * when reading this property in which case the list is limited to baselines
205         * for the specified CcComponent.
206         * </p>
207         * <p>
208         * When a stream is baselined, a new baseline is created for each component
209         * in the stream's configuration that was changed since the last time the
210         * stream was baselined.  If a given component has not changed, no
211         * baseline is created for that component.
212         * </p>
213         */
214        PropertyName<ResourceList<CcBaseline>> BASELINE_LIST =
215            new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, "baseline-list");
216    
217        /**
218         * Get the value of the this proxy's {@link #BASELINE_LIST} property.
219         * @return a list of client proxies for this project's baselines
220         * @throws WvcmException if this proxy doesn't define a value for this property.
221         */
222        ResourceList<CcBaseline> getBaselineList() throws WvcmException;
223    
224        /**
225         * <p>
226         * This stream's latest baselines.  Specifically, the most recent baseline
227         * of each component in this stream's configuration that has been modified
228         * in this stream or the foundation baseline for components that have
229         * not been modified.
230         * </p>
231         * <p>
232         * When a stream is baselined, a new baseline is created for each component
233         * in the stream's configuration that was changed since the last time the
234         * stream was baselined.  If a given component has not changed, no
235         * baseline is created for that component.
236         * </p>
237         */
238        PropertyName<ResourceList<CcBaseline>> LATEST_BASELINE_LIST =
239            new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, "latest-baseline-list");
240    
241        /**
242         * Get the value of the this proxy's {@link #LATEST_BASELINE_LIST} property.
243         * @return a list of client proxies for this project's latest baselines
244         * @throws WvcmException if this proxy doesn't define a value for this property.
245         */
246        ResourceList<CcBaseline> getLatestBaselineList() throws WvcmException;
247    
248        /**
249         * The project to which this UCM stream belongs.
250         */
251        PropertyName<CcProject> PARENT_PROJECT =
252            new PropertyName<CcProject>(PROPERTY_NAMESPACE,
253                                        "parent-project");
254    
255        /**
256         * Get the value of this stream's {@link #PARENT_PROJECT} property.
257         * 
258         * @return stream's parent project
259         * @throws WvcmException
260         *             if this proxy doesn't define a value for this property.
261         */
262        CcProject getParentProject() throws WvcmException;
263    
264        /**
265         * Set the value of this stream's {@link #PARENT_PROJECT} property.
266         * This property can only be set at stream creation time.
267         * 
268         * @param parent
269         *            stream's parent project
270         */
271        void setParentProject(CcProject parent);
272    
273        /**
274         * This UCM stream's parent stream.  The value of this property is null
275         * if this is an integration stream.
276         */
277        PropertyName<CcStream> PARENT_STREAM = new PropertyName<CcStream>(PROPERTY_NAMESPACE,
278                "parent-stream");
279    
280        /**
281         * Get the value of this stream's {@link #PARENT_STREAM} property.
282         * 
283         * @return stream's parent stream, or null if this is an integration stream
284         * @throws WvcmException
285         *             if this proxy doesn't define a value for this property.
286         */
287        CcStream getParentStream() throws WvcmException;
288    
289        /**
290         * Set the value of this stream's {@link #PARENT_STREAM} property.
291         * This property can only be set at stream creation time.
292         * 
293         * @param parent
294         *            stream's parent stream
295         */
296        void setParentStream(CcStream parent);
297    
298        /** This UCM stream's recommended baselines. */
299        PropertyName<ResourceList<CcBaseline>> RECOMMENDED_BASELINE_LIST =
300            new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE,
301                                                       "recommended-baseline-list");
302    
303        /**
304         * Get the value of the this proxy's {@link #RECOMMENDED_BASELINE_LIST} property.
305         * @return a list of client proxies for this project's recommended baselines
306         * @throws WvcmException if this proxy doesn't define a value for this property.
307         */
308        ResourceList<CcBaseline> getRecommendedBaselineList() throws WvcmException;
309    
310        /**
311         * Set the value of the this proxy's {@link #RECOMMENDED_BASELINE_LIST} property.
312         * @param recBls a list of client proxies for this project's recommended baselines
313         */
314        void setRecommendedBaselineList(ResourceList<CcBaseline> recBls);
315     
316        /**
317         * The list of substreams of this UCM stream, i.e., the streams
318         * for which this stream is the parent.
319         */
320        PropertyName<ResourceList<CcStream>> SUBSTREAM_LIST =
321            new PropertyName<ResourceList<CcStream>>(PROPERTY_NAMESPACE,
322                                                     "substream-list");
323    
324        /**
325         * Get the value of this stream's {@link #SUBSTREAM_LIST} property.
326         * 
327         * @return a list of client proxies for this stream's substreams
328         * @throws WvcmException
329         *             if this proxy doesn't define a value for this property.
330         */
331        ResourceList<CcStream> getSubstreamList() throws WvcmException;
332    
333        /** The views associated with this UCM stream. */
334        PropertyName<ResourceList<CcView>> VIEW_LIST =
335            new PropertyName<ResourceList<CcView>>(PROPERTY_NAMESPACE,
336                                                   "view-list");
337    
338        /**
339         * Get the value of this stream's {@link #VIEW_LIST} property.
340         * 
341         * @return the list of views associated with this stream
342         * @throws WvcmException
343         *             if this proxy doesn't define a value for this property.
344         */
345        ResourceList<CcView> getViewList() throws WvcmException;
346    
347        /** Is this UCM stream an integration stream? */
348        PropertyName<Boolean> IS_INTEGRATION_STREAM =
349            new PropertyName<Boolean>(PROPERTY_NAMESPACE,
350                                      "is-integration-stream");
351    
352        /**
353         * Get the value of this stream's {@link #IS_INTEGRATION_STREAM} property.
354         * 
355         * @return true if this stream is an integration stream, else false
356         * @throws WvcmException
357         *             if this proxy doesn't define a value for this property.
358         */
359        boolean getIsIntegrationStream() throws WvcmException;
360    
361        /**
362         * Set the value of this stream's {@link #IS_INTEGRATION_STREAM} property.
363         * This property can only be set at stream creation time.
364         * 
365         * @param isInt
366         *            true if this stream is an integration stream, else false
367         */
368        void setIsIntegrationStream(boolean isInt);
369    
370        /** Is this a read-only UCM stream? */
371        PropertyName<Boolean> IS_READ_ONLY =
372            new PropertyName<Boolean>(PROPERTY_NAMESPACE,
373                                      "is-read-only");
374    
375        /**
376         * Get the value of this stream's {@link #IS_READ_ONLY} property.
377         * 
378         * @return true if this stream is read-only, else false
379         * @throws WvcmException
380         *             if this proxy doesn't define a value for this property.
381         */
382        boolean getIsReadOnly() throws WvcmException;
383    
384        /**
385         * Set the value of this stream's {@link #IS_READ_ONLY} property.
386         * This property can only be set at stream creation time.
387         * 
388         * @param readOnly
389         *            true if this stream is to be read-only, else false
390         */
391        void setIsReadOnly(boolean readOnly);
392    
393        /** This UCM stream's foundation baselines. */
394        PropertyName<ResourceList<CcBaseline>> FOUNDATION_BASELINE_LIST =
395            new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE,
396                                                       "foundation-baseline-list");
397    
398        /**
399         * Get the value of this stream's {@link #FOUNDATION_BASELINE_LIST}
400         * property.
401         * 
402         * @return a list of client proxies for this stream's foundation baselines
403         * @throws WvcmException
404         *             if this proxy doesn't define a value for this property.
405         */
406        ResourceList<CcBaseline> getFoundationBaselineList() throws WvcmException;
407    
408        /** The default target (stream) for this UCM stream's deliver operations. */
409        PropertyName<CcStream> DEFAULT_DELIVER_TARGET =
410            new PropertyName<CcStream>(PROPERTY_NAMESPACE,
411                                       "default-deliver-target");
412    
413        /**
414         * Get the value of this stream's {@link #DEFAULT_DELIVER_TARGET} property.
415         * 
416         * @return a client proxy for this stream's default deliver target
417         * @throws WvcmException
418         *             if this proxy doesn't define a value for this property.
419         */
420        CcStream getDefaultDeliverTarget() throws WvcmException;
421    
422        /**
423         * Set the value of this stream's {@link #DEFAULT_DELIVER_TARGET} property.
424         * The default deliver target for all non-integration streams is their parent 
425         * stream.
426         * @param target
427         *            this stream's new default deliver target or <code>null</code> to clear 
428         *            the deliver target
429         */
430        void setDefaultDeliverTarget(CcStream target);
431        
432        /** 
433         * A list of streams that have posted deliveries in progress to this stream.
434         * A delivery is posted if the source stream is mastered at a different 
435         * replica than the target stream at the time of the delivery. This property
436         * is not recursive; it only includes streams that are immediate children of
437         * this stream.
438         */
439        PropertyName<ResourceList<CcStream>> POSTED_DELIVERY_LIST =
440            new PropertyName<ResourceList<CcStream>>(PROPERTY_NAMESPACE, "ccstream-posted-delivery-list");
441        
442        /**
443         * Get the value of this proxy's {@link #POSTED_DELIVERY_LIST} property.
444         * @return A list containing this stream's posted deliveries.
445         * @throws WvcmException 
446         *             if this proxy doesn't define a value for this property.
447         */
448        ResourceList<CcStream> getPostedDeliveryList() throws WvcmException;
449    
450        /** Is this locally mastered UCM stream in the middle of a posted 
451         * delivery to a remotely mastered target?
452         */
453        PropertyName<Boolean> HAS_POSTED_DELIVERY_IN_PROGRESS =
454            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-posted-delivery-in-progress");
455        
456        /**
457         * Get the value of this proxy's {@link #HAS_POSTED_DELIVERY_IN_PROGRESS} property.
458         * @return true if this stream is delivering to a remotely mastered target, else false.
459         * @throws WvcmException 
460         *             if this proxy doesn't define a value for this property.
461         */
462        boolean getHasPostedDeliveryInProgress() throws WvcmException;
463        
464        /**
465         * @deprecated TODO Placeholder for probable future property to track
466         * the status of a delivery to the integration stream
467         */
468        PropertyName INTEGRATION_STATUS = new PropertyName(PROPERTY_NAMESPACE,
469                                                           "integration-status");
470    }