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 }