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    }