001    /*
002     * file Version.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 java.util.List;
014    
015    import javax.wvcm.PropertyNameList.PropertyName;
016    import javax.wvcm.WvcmException.ReasonCode;
017    
018    /**
019     * A proxy for a version resource.
020     * 
021     * A version resource contains an immutable copy of the properties of a
022     * version-controlled resource. A version resource also contains mutable
023     * properties with metadata about that version.
024     * 
025     * @since 1.0
026     */
027    public interface Version extends Resource {
028    
029        /**
030         * Get the workspace provider of this resource.
031         * 
032         * @return the {@link WorkspaceProvider} for this Resource.
033         */
034        public WorkspaceProvider workspaceProvider();
035    
036        /**
037         * The {@link Activity} object that identify the
038         * activity to which this version contributes.
039         * A provider may refuse to allow the activity of a version to be modified.
040         * This version must be on the same line of descent
041         * as all other versions with this activity from the same version history.
042         * If the {@link Activity#ACTIVITY_CHECKOUT_LIST} of the activity identifies a
043         * controllable resource that is reserved and checks out a version
044         * in the version history of this version,
045         * then the checked-out version must be a successor of all other
046         * versions with this activity from the same version history. 
047         * @see #setActivity
048         * @see #getActivity
049         */
050        public static final PropertyName<Activity> ACTIVITY =
051            new PropertyName<Activity>("activity"); //$NON-NLS-1$
052    
053        /**
054         * Get the {@link #ACTIVITY} property.
055         * 
056         * @return the {@link #ACTIVITY} property.
057         * @throws WvcmException if this property was not set and
058         * this Version was not created with
059         * {@link #ACTIVITY} as a wanted property.
060         * @see #setActivity
061         */
062        public Activity getActivity() throws WvcmException;
063    
064        /**
065         * Set the {@link #ACTIVITY} property.
066         * 
067         * @param activity an {@link Activity} object that specifies
068         * the new {@link #ACTIVITY} property for this Version.
069         * @see #getActivity
070         */
071        public void setActivity(Activity activity);
072    
073        /**
074         * Valid values for the {@link #CHECKIN_FORK} and {@link #CHECKOUT_FORK} properties.
075         */
076        public enum Fork {
077    
078            /**
079             * Forking is allowed without special options.
080             */
081            OK("ok"), //$NON-NLS-1$
082    
083            /**
084             * Forking is allowed only if specifically requested.
085             */
086            DISCOURAGED("discouraged"), //$NON-NLS-1$
087    
088            /**
089             * Forking is not allowed.
090             */
091            FORBIDDEN("forbidden"); //$NON-NLS-1$
092    
093            private final String _forkType;
094    
095            private Fork(String forkType) {
096                _forkType = forkType;
097            }
098    
099            /**
100             * Returns a string representation of this Fork suitable for diagnostics.
101             */
102            @Override
103            public String toString() { return _forkType; }
104        }
105    
106        /**
107         * An enumeration that determines whether this Version can be given
108         * more than one successor.
109         * If {@link #CHECKIN_FORK} is {@link Fork#DISCOURAGED}, a doCheckin request
110         * MUST fail unless forkOk is specified in the doCheckin request.
111         * If the {@link #CHECKIN_FORK} of a version is {@link Fork#FORBIDDEN},
112         * a doCheckin request MUST fail if it would result in that version
113         * appearing in the {@link #PREDECESSOR_LIST} of more than one version.
114         * A server MAY reject attempts to modify the {@link #CHECKIN_FORK} of a version.
115         * @see #setCheckinFork
116         * @see #getCheckinFork
117         */
118        public static final PropertyName<Fork> CHECKIN_FORK =
119            new PropertyName<Fork>("checkin-fork"); //$NON-NLS-1$
120    
121        /**
122         * Get the {@link #CHECKIN_FORK} property.
123         * 
124         * @return the {@link #CHECKIN_FORK} property.
125         * @throws WvcmException if this property was not set and
126         * this Version was not created with
127         * {@link #CHECKIN_FORK} as a wanted property.
128         * @see #setCheckinFork
129         */
130        public Fork getCheckinFork() throws WvcmException;
131    
132        /**
133         * Set the {@link #CHECKIN_FORK} property.
134         * 
135         * @param val the new {@link #CHECKIN_FORK} value for this Version.
136         * @see #getCheckinFork
137         */
138        public void setCheckinFork(Fork val);
139    
140        /**
141         * An enumeration that determines whether a version-controlled resource
142         * selecting this Version can be checked out when it already has
143         * a successor version.
144         * If {@link #CHECKOUT_FORK} is {@link Fork#DISCOURAGED}, a doCheckout request MUST fail
145         * unless forkOk is specified in the doCheckout request.
146         * If the {@link #CHECKOUT_FORK} of a version is {@link Fork#FORBIDDEN},
147         * a doCheckout request will fail if it would result in that version
148         * appearing in the {@link #PREDECESSOR_LIST} or {@link ControllableResource#CHECKED_OUT} property
149         * of more than one version or checked-out resource.
150         * A server MAY reject attempts to modify the {@link #CHECKOUT_FORK} of a version.
151         * @see #setCheckoutFork
152         * @see #getCheckoutFork
153         */
154        public static final PropertyName<Fork> CHECKOUT_FORK =
155            new PropertyName<Fork>("checkout-fork"); //$NON-NLS-1$
156    
157        /**
158         * Get the {@link #CHECKOUT_FORK} property.
159         * 
160         * @return the {@link #CHECKOUT_FORK} property.
161         * @throws WvcmException if this property was not set and
162         * this Version was not created with
163         * {@link #CHECKOUT_FORK} as a wanted property.
164         * @see #setCheckoutFork
165         */
166        public Fork getCheckoutFork() throws WvcmException;
167    
168        /**
169         * Set the {@link #CHECKOUT_FORK} property.
170         * 
171         * @param val the new {@link #CHECKOUT_FORK} value for this Version.
172         * @see #getCheckoutFork
173         */
174        public void setCheckoutFork(Fork val);
175    
176        /**
177         * A list of all controllable resources that are checked out from this version.
178         * This is the computed inverse of the {@link ControllableResource#CHECKED_OUT} property.
179         * @see #getCheckoutList
180         */
181        public static final PropertyName<ResourceList<ControllableResource>> CHECKOUT_LIST =
182            new PropertyName<ResourceList<ControllableResource>>("checkout-list"); //$NON-NLS-1$
183    
184        /**
185         * Get the {@link #CHECKOUT_LIST} property.
186         * 
187         * @return the {@link #CHECKOUT_LIST} property.
188         * @throws WvcmException if this Version was not created with
189         * {@link #CHECKOUT_LIST} as a wanted property.
190         */
191        public ResourceList<ControllableResource> getCheckoutList()
192        throws WvcmException;
193    
194        /**
195         * A list of strings that identify the labels
196         * that currently select this Version.
197         * @see #getLabelNameList
198         */
199        public static final PropertyName<List<String>> LABEL_NAME_LIST =
200            new PropertyName<List<String>>("label-name-list"); //$NON-NLS-1$
201    
202        /**
203         * Get the {@link #LABEL_NAME_LIST} property.
204         * @return the {@link #LABEL_NAME_LIST} property.
205         * @throws WvcmException if this Version was not created with
206         * {@link #LABEL_NAME_LIST} as a wanted property.
207         */
208        public List<String> getLabelNameList() throws WvcmException;
209    
210        /**
211         *  A list of all versions that are direct predecessors of this version.
212         * @see #getPredecessorList
213         */
214        public static final PropertyName<ResourceList<Version>> PREDECESSOR_LIST =
215            new PropertyName<ResourceList<Version>>("predecessor-list"); //$NON-NLS-1$
216    
217        /**
218         * Get the {@link #PREDECESSOR_LIST} property.
219         * @return the {@link #PREDECESSOR_LIST} property.
220         * @throws WvcmException if this Version was not created with
221         * {@link #PREDECESSOR_LIST} as a wanted property.
222         */
223        public ResourceList<Version> getPredecessorList() throws WvcmException;
224    
225        /**
226         * A list of all versions that are direct successors of this version.
227         * The {@link #SUCCESSOR_LIST} property is the computed inverse of the
228         * {@link #PREDECESSOR_LIST} property.
229         * @see #getSuccessorList
230         */
231        public static final PropertyName<ResourceList<Version>> SUCCESSOR_LIST =
232            new PropertyName<ResourceList<Version>>("successor-list"); //$NON-NLS-1$
233    
234        /**
235         * Get the {@link #SUCCESSOR_LIST} property.
236         * 
237         * @return the {@link #SUCCESSOR_LIST} property.
238         * @throws WvcmException if this Version was not created with
239         * {@link #SUCCESSOR_LIST} as a wanted property.
240         */
241        public ResourceList<Version> getSuccessorList() throws WvcmException;
242    
243        /**
244         * The version history that contains this version.
245         * @see #getVersionHistory
246         */
247        public static final PropertyName<VersionHistory> VERSION_HISTORY =
248            new PropertyName<VersionHistory>("version-history"); //$NON-NLS-1$
249    
250        /**
251         * Get the {@link #VERSION_HISTORY} property.
252         * 
253         * @return the {@link #VERSION_HISTORY} property.
254         * @throws WvcmException if this Version was not created with
255         * {@link #VERSION_HISTORY} as a wanted property.
256         */
257        public VersionHistory getVersionHistory() throws WvcmException;
258    
259        /**
260         * A server-defined string that is different for each version
261         * in the version history of this version.
262         * This string is intended for display to a user, 
263         * unlike the location of a version, which is normally only used by a client
264         * and not displayed to a user.
265         * @see #getVersionName
266         */
267        public static final PropertyName<String> VERSION_NAME =
268            new PropertyName<String>("version-name"); //$NON-NLS-1$
269    
270        /**
271         * Get the {@link #VERSION_NAME} property.
272         * 
273         * @return the {@link #VERSION_NAME} property.
274         * @throws WvcmException if this Version was not created with
275         * {@link #VERSION_NAME} as a wanted property.
276         */
277        public String getVersionName() throws WvcmException;
278    
279        /**
280         * Add the specified label to this version.
281         * 
282         * @param label the label to be added to this version
283         * @param feedback Specifies optional feedback to the caller.
284         * @return A new proxy for this resource, whose properties are specified by feedback.
285         * @throws WvcmException
286         * <li>{@link ReasonCode#ADD_MUST_BE_NEW_LABEL}:
287         *  The label MUST NOT already identify a version in the version history of this version.
288         */
289        public Version doAddLabel(String label, Feedback feedback) throws WvcmException;
290    
291        /**
292         * Remove the specified label from this version.
293         * 
294         * @param label the label to be removed from this version.
295         * @param feedback Specifies optional feedback to the caller.
296         * @return A new proxy for this resource, whose properties are specified by feedback.
297         * @throws WvcmException ReasonCode:
298         * <li>{@link ReasonCode#CANNOT_REMOVE_LABEL_DOES_NOT_EXIST}:
299         *  The label must be on this version.
300         */
301        public Version doRemoveLabel(String label, Feedback feedback) throws WvcmException;
302    
303        /**
304         * Set the specified label on this version.
305         * 
306         * @param label The label to be set on this version
307         * @param feedback Specifies optional feedback to the caller.
308         * @return A new proxy for this resource, whose properties are specified by feedback.
309         * @throws WvcmException if label cannot be set
310         */
311        public Version doSetLabel(String label, Feedback feedback) throws WvcmException;
312    
313        /**
314         * A list of all workspaces that have a controllable resource that contains
315         * this version in its {@link ControllableResource#CHECKED_IN} or
316         * {@link ControllableResource#CHECKED_OUT} property.
317         * Because there can be many workspaces that contain a given version,
318         * this property is most commonly used in a {@link Resource#doFind} request.
319         * @see #getInWorkspaceList
320         */
321        public static final PropertyName<ResourceList<Workspace>> IN_WORKSPACE_LIST =
322            new PropertyName<ResourceList<Workspace>>("in-workspace-list"); //$NON-NLS-1$
323    
324        /**
325         * Get the {@link #IN_WORKSPACE_LIST} property.
326         * 
327         * @return the {@link #IN_WORKSPACE_LIST} property.
328         * @throws WvcmException if this Version was not created with
329         * {@link #IN_WORKSPACE_LIST} as a wanted property.
330         */
331        public ResourceList<Workspace> getInWorkspaceList()
332        throws WvcmException;
333    
334        /**
335         * A list of all baselines that contain this version in their {@link Baseline#VERSION_LIST}
336         * property.
337         * This is the computed inverse of the {@link Baseline#VERSION_LIST} property.
338         * Because there can be many baselines that contain a given version,
339         * this property is most commonly used in a {@link Resource#doFind} request.
340         * @see #getInBaselineList
341         */
342        public static final PropertyName<ResourceList<Baseline>> IN_BASELINE_LIST =
343            new PropertyName<ResourceList<Baseline>>("in-baseline-list"); //$NON-NLS-1$
344    
345        /**
346         * Get the {@link #IN_BASELINE_LIST} property.
347         * 
348         * @return the {@link #IN_BASELINE_LIST} property.
349         * @throws WvcmException if this Version was not created with
350         * {@link #IN_BASELINE_LIST} as a wanted property.
351         */
352        public ResourceList<Baseline> getInBaselineList()
353        throws WvcmException;
354    
355    }