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 }