001 /*
002 * file Baseline.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.PropertyNameList.PropertyName;
014 import javax.wvcm.ResourceList.ResponseIterator;
015 import javax.wvcm.WvcmException.ReasonCode;
016
017 /**
018 * A proxy for a baseline resource.
019 *
020 * A baseline resource is a version resource that captures the state of each
021 * version-controlled member of a configuration. New baselines of a
022 * configuration are created by checking out and then checking in the
023 * configuration.
024 *
025 * @since 1.0
026 */
027 public interface Baseline extends Version {
028
029 /**
030 * A description of the difference between two sets of versions.
031 * In the {@link Baseline#doCompareReport} method, the old set of versions is
032 * specified by the object for which the method was invoked, and the new set of versions
033 * is specified by the argument of the method.
034 */
035 public interface CompareReport { }
036
037 /**
038 * A version from a given version history that is in the new set of versions
039 * but no version from the version history of that version is in the old set.
040 */
041 public interface AddedVersion extends CompareReport {
042
043 /**
044 * Return the added version.
045 *
046 * @return the version of a resource added in the new set of versions.
047 */
048 public Version getVersion();
049 }
050
051 /**
052 * A version from a given version history that is in the old set of versions
053 * but no version from that version history is in the new set of versions.
054 */
055 public interface DeletedVersion extends CompareReport {
056
057 /**
058 * Return the deleted version.
059 *
060 * @return the version of a resource removed from the new set of versions.
061 */
062 public Version getVersion();
063 }
064
065 /**
066 * A version from a given version history that is in the old set of versions
067 * where a different version from that version history is in the new set of versions.
068 * @see Baseline#doCompareReport doCompareReport
069 */
070 public interface ChangedVersion extends CompareReport {
071
072 /**
073 * Return the version from the old baseline.
074 *
075 * @return the version of the resource in the old baseline.
076 */
077 public Version getOldVersion();
078
079 /**
080 * Return the version from the new baseline.
081 *
082 * @return the version of the resource in the new baseline.
083 */
084 public Version getNewVersion();
085 }
086
087 /**
088 * An activity whose versions were added by the new set of versions.
089 */
090 public interface AddedActivity extends CompareReport {
091
092 /**
093 * Return the added activity.
094 *
095 * @return the activity all of whose versions were added by the new set of versions.
096 */
097 public Activity getActivity();
098 }
099
100 /**
101 * An activity some of whose versions were added by the new set of versions.
102 */
103 public interface PartiallyAddedActivity extends CompareReport {
104
105 /**
106 * Return the partially added activity.
107 *
108 * @return the activity some of whose versions were added by the new set of versions.
109 */
110 public Activity getActivity();
111 }
112
113 /**
114 * An activity whose versions were deleted by the new baseline.
115 */
116 public interface DeletedActivity extends CompareReport {
117
118 /**
119 * Return the deleted activity.
120 *
121 * @return the activity whose versions were deleted by the new set of versions.
122 */
123 public Activity getActivity();
124 }
125
126 /**
127 * An activity some of whose versions were deleted by the new set of versions.
128 */
129 public interface PartiallyDeletedActivity extends CompareReport {
130
131 /**
132 * Return the partially deleted activity.
133 *
134 * @return the activity some of whose versions were deleted by the new set of versions.
135 */
136 public Activity getActivity();
137 }
138
139 /**
140 * An activity whose versions were both added and removed by the new set of versions.
141 */
142 public interface ChangedActivity extends CompareReport {
143
144 /**
145 * Return the changed activity.
146 *
147 * @return the activity some of whose versions were added and some of whose versions
148 * were deleted by the new set of versions.
149 */
150 public Activity getActivity();
151 }
152
153 /** Boolean flags for the doCompareReport method */
154 public static class CompareFlag
155 {
156 private CompareFlag(String flagName) { _flagName = flagName; }
157
158 /**
159 * Returns a string representation of this flag suitable for diagnostics.
160 */
161 @Override
162 public String toString() { return _flagName; }
163
164 /**
165 * The string form of this flag.
166 */
167 private final String _flagName;
168
169 /**
170 * Indicates that the comparison should include information about activities whose
171 * {@link Activity#ACTIVITY_VERSION_LIST} contain versions that are an ancestor of
172 * an old version or an ancestor of a new version, but not both.
173 * <p>
174 * In particular, let NewVersions be the set of versions that are a new version or an ancestor of
175 * a new version, but not an old version or an ancestor of an old version; and let OldVersions be the
176 * set of versions that are an old version or an ancestor of an old version, but not a new version
177 * or an ancestor of a new version.
178 * Then an activity is considered:
179 * <li>"added" if every version in its {@link Activity#ACTIVITY_VERSION_LIST}
180 * is in the NewVersions set.
181 * <li>"deleted" if every version in its {@link Activity#ACTIVITY_VERSION_LIST}
182 * is in the OldVersions set.
183 * <li>"partially added" if some versions in its {@link Activity#ACTIVITY_VERSION_LIST}
184 * are in the NewVersions set and the rest are in neither set.
185 * <li>"partially deleted" if some versions in its {@link Activity#ACTIVITY_VERSION_LIST}
186 * are in the OldVersions set and the rest are in neither set.
187 * <li>"changed" if some versions in its {@link Activity#ACTIVITY_VERSION_LIST} are in
188 * the NewVersions set and some are in the OldVersions set.
189 */
190 public static final CompareFlag ACTIVITIES = new CompareFlag("activities"); //$NON-NLS-1$
191
192 /**
193 * Report only on versions in the new set of versions.
194 * Changed versions are reported as added versions,
195 * and deleted versions are not reported at all.
196 */
197 public static final CompareFlag NEW_ONLY = new CompareFlag("new-only"); //$NON-NLS-1$
198
199 }
200
201
202 /**
203 * Compare two baselines.
204 *
205 * @param baseline the baseline being compared to this Baseline.
206 * @param flags boolean flags for the compare report.
207 * @param feedback the properties available in the returned proxies.
208 * @return a ResponseIterator of CompareReport objects, that enumerate the differences between the
209 * versions selected by this Baseline and the baseline argument.
210 * @throws WvcmException ReasonCode:
211 * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}:
212 * The resource identified by the <code>baseline</code> argument must be a baseline.
213 */
214 public ResponseIterator<CompareReport> doCompareReport(
215 Baseline baseline,
216 CompareFlag[] flags,
217 Feedback feedback)
218 throws WvcmException;
219
220 /**
221 * Compare this Baseline with a stream.
222 *
223 * @param stream the stream being compared to this Baseline.
224 * @param flags boolean flags for the compare report.
225 * @param feedback the properties available in the returned proxies.
226 * @return a ResponseIterator of CompareReport objects, that enumerate the differences between the
227 * versions selected by this Stream and the stream argument.
228 * @throws WvcmException ReasonCode:
229 * <li>{@link ReasonCode#METHOD_NOT_SUPPORTED}:
230 * This resource does not support this report.
231 * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}:
232 * The resource identified by the <code>stream</code> argument must be a stream.
233 */
234 public ResponseIterator<CompareReport> doCompareReport(
235 Stream stream,
236 CompareFlag[] flags,
237 Feedback feedback)
238 throws WvcmException;
239
240 /**
241 * A list of all the versions that make up this baseline. The list is
242 * created from all the {@link ControllableResource#CHECKED_IN} versions of
243 * all the version-controlled members of the
244 * {@link Configuration#ROOT_FOLDER} of the configuration at the time the
245 * baseline identified by this Baseline was created.
246 */
247 public static final PropertyName<ResourceList<Version>> VERSION_LIST =
248 new PropertyName<ResourceList<Version>>("version-list"); //$NON-NLS-1$
249
250 /**
251 * Get the {@link #VERSION_LIST} property.
252 *
253 * @return the {@link #VERSION_LIST} property.
254 * @throws WvcmException if this Baseline was not created with
255 * {@link #VERSION_LIST} as a wanted property.
256 */
257 public ResourceList<Version> getVersionList() throws WvcmException;
258
259 }