001/*
002 * file Stream.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * (c) Copyright IBM Corporation 2004, 2008.  All Rights Reserved. 
008 * Note to U.S. Government Users Restricted Rights:  Use, duplication or  
009 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp. 
010 */
011package javax.wvcm;
012
013import javax.wvcm.Baseline.CompareFlag;
014import javax.wvcm.Baseline.CompareReport;
015import javax.wvcm.PropertyNameList.PropertyName;
016import javax.wvcm.ResourceList.ResponseIterator;
017import javax.wvcm.WvcmException.ReasonCode;
018
019/**
020 * A proxy for a stream resource.
021 * 
022 * A stream resource is an activity whose versions are baselines.
023 * 
024 * @since 1.0
025 */
026public interface Stream extends Activity {
027
028    /**
029     * A list of all the versions that are the current versions in this stream.
030     */
031    public static final PropertyName<ResourceList<Version>> VERSION_LIST =
032        new PropertyName<ResourceList<Version>>("version-list"); //$NON-NLS-1$
033
034    /**
035     * Get the {@link #VERSION_LIST} property.
036     * 
037     * @return the {@link #VERSION_LIST} property.
038     * @throws WvcmException if this Stream was not created with 
039     * {@link #VERSION_LIST} as a wanted property.
040     */
041    public ResourceList<Version> getVersionList() throws WvcmException;
042
043    /**
044     * The stream to which changes in this stream are to be merged.
045     * An implementation MAY reject changing this property once the stream
046     * has been created. May be null.
047     * @see #getTarget
048     * @see #setTarget
049     */
050    public static final PropertyName<Stream> TARGET =
051        new PropertyName<Stream>("target"); //$NON-NLS-1$
052
053    /**
054     * Get the {@link #TARGET} property.
055     * 
056     * @return the {@link #TARGET} property.
057     * @throws WvcmException if this Version was not created with
058     * {@link #TARGET} as a wanted property.
059     */
060    public Stream getTarget() throws WvcmException;
061
062    /**
063     * Set the {@link #TARGET} property.
064     * 
065     * @param target the {@link Stream} object that
066     * identifies the {@link #TARGET} for this Stream.
067     * @see #getTarget
068     */
069    public void setTarget(Stream target);
070
071    /**
072     * A list of all streams which are declared to merge to this stream.
073     * The {@link #SOURCE_LIST} property is the computed inverse of the
074     * {@link #TARGET} property.
075     * @see #getSourceList
076     */
077    public static final PropertyName<ResourceList<Stream>> SOURCE_LIST =
078        new PropertyName<ResourceList<Stream>>("source-list"); //$NON-NLS-1$
079
080    /**
081     * Get the {@link #SOURCE_LIST} property.
082     * 
083     * @return the {@link #SOURCE_LIST} property.
084     * @throws WvcmException if this Version was not created with
085     * {@link #SOURCE_LIST} as a wanted property.
086     */
087    public ResourceList<Stream> getSourceList() throws WvcmException;
088
089    /** 
090     * A workspace that can be used to browse the contents of this stream.
091     * This workspace MAY refuse to allow any change other than a
092     * {@link Workspace#doUpdate} whose argument is this stream.
093     */
094    public static final PropertyName<Workspace> WORKSPACE =
095        new PropertyName<Workspace>("workspace"); //$NON-NLS-1$
096
097    /**
098     * Get the {@link #WORKSPACE} property.
099     * 
100     * @return the {@link #WORKSPACE} property.
101     * @throws WvcmException if this Stream was not created with
102     * {@link #WORKSPACE} as a wanted property.
103     */
104    public Workspace getWorkspace() throws WvcmException;
105
106    /**
107     * Compare this Stream with another stream.
108     * 
109     * @param stream the stream being compared to this Stream.
110     * @param flags boolean flags for the compare report.
111     * @param feedback the properties available in the returned proxies.
112     * @return a ResponseIterator of CompareReport objects, that enumerate the differences between the
113     * versions selected by this Stream and the stream argument.
114     * @throws WvcmException ReasonCode:
115     * <li>{@link ReasonCode#METHOD_NOT_SUPPORTED}:
116     *  This resource does not support this report.
117     * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}:
118     * The resource identified by the <code>stream</code> argument must be a stream.
119     */
120    public ResponseIterator<CompareReport> doCompareReport(
121            Stream stream,
122            CompareFlag[] flags, 
123            Feedback feedback)
124    throws WvcmException;
125
126    /**
127     * Compare this Stream with a baseline.
128     * 
129     * @param baseline the baseline being compared to this Stream.
130     * @param flags boolean flags for the compare report.
131     * @param feedback the properties available in the returned proxies.
132     * @return a ResponseIterator of CompareReport objects, that enumerate the differences between the
133     * versions selected by this Stream and the baseline argument.
134     * @throws WvcmException ReasonCode:
135     * <li>{@link ReasonCode#METHOD_NOT_SUPPORTED}:
136     *  This resource does not support this report.
137     * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}:
138     * The resource identified by the <code>baseline</code> argument must be a baseline.
139     */
140    public ResponseIterator<CompareReport> doCompareReport(
141            Baseline baseline,
142            CompareFlag[] flags, 
143            Feedback feedback)
144    throws WvcmException;
145
146    /**
147     * Update the {@link #VERSION_LIST} of this stream to contain the versions
148     * specified in the sourceList argument.
149     * If {@link #VERSION_LIST} already contains a version from the same VersionHistory
150     * as the source version already, that version is replaced by the source version.
151     * <p>
152     * Postconditions:
153     * <li>(update-sources): Each of the versions in the sourceList MUST have updated
154     *  the {@link #VERSION_LIST} of this Stream.
155     * 
156     * @param sourceList the list of resources specifying the versions whose target in this stream should be updated.
157     * If a member of sourceList is an activity, it must not be a stream, and
158     * each version in the {@link Activity#ACTIVITY_VERSION_LIST} is a source version.
159     * If a member of sourceList is a version-controlled resource,
160     * the checked-in version of the member is a source version;
161     * if that version-controlled resource is a folder, all members
162     * of that folder are considered members of the sourceList.
163     * @param feedback Specifies optional feedback to the caller.
164     * @return A new proxy for this resource, whose properties are specified by feedback.
165     * @throws WvcmException An implementation may throw a single exception on the first error encountered,
166     * or may attempt to update all of the source versions, with any errors accumulated in the
167     * {@link WvcmException#getNestedExceptions} list.
168     * <br>ReasonCode:
169     * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}:
170     *  The resources identified by the <code>sourceList</code> argument must be versions, activities,
171     *  streams, or controllable resources.
172     * <li>{@link ReasonCode#MUST_BE_CHECKED_IN}:
173     *  A version-controlled resource in the sourceList must be checked in.
174     */
175    public <T extends Resource> Stream doUpdate(ResourceList<T> sourceList, Feedback feedback)
176    throws WvcmException;
177}