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 */
011package javax.wvcm;
012
013import javax.wvcm.PropertyNameList.PropertyName;
014import javax.wvcm.ResourceList.ResponseIterator;
015import 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 */
027public 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}