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