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     */
011    package javax.wvcm;
012    
013    import javax.wvcm.Baseline.CompareFlag;
014    import javax.wvcm.Baseline.CompareReport;
015    import javax.wvcm.PropertyNameList.PropertyName;
016    import javax.wvcm.ResourceList.ResponseIterator;
017    import 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     */
026    public 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    }