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 }