001 /*
002 * file ControllableResource.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.Workspace.MergeFlag;
015 import javax.wvcm.WvcmException.ReasonCode;
016
017 /**
018 * A proxy for a controllable resource.
019 *
020 * A controllable resource is always the member of
021 * a special type of controllable folder called a "workspace".
022 * A controllable resource is either a version-controllable resource,
023 * a baseline-controllable resource, or both.
024 * <p>
025 * A version-controlled resource is a resource that is under control
026 * of a Checkout/Checkin protocol.
027 * The controlled state (content, controlled properties, and bindings to version-controlled members)
028 * of a version-controlled resource cannot be modified by a client
029 * unless that version-controlled resource is checked out.
030 * <p>
031 * When a version-controlled resource is checked in,
032 * a new version of that resource is created.
033 * The controlled state of the version-controlled resource is captured immutably in the new version.
034 * <p>
035 * The persistent state for a version-controlled resource may be
036 * stored on the client, on the server, or both.
037 * Storing the state on the server allows it to be shared
038 * by multiple clients. Storing the state on the client
039 * provides access to that state even when the client is
040 * disconnected from the server, and often provides more
041 * efficient access to that state.
042 * Note that the choice of what part of the state of a
043 * version-controlled resource is stored on the client
044 * is completely up to the implementation. In particular,
045 * although most implementations will cache some state on the client,
046 * an implementation may chose to store no local state.
047 *
048 * @since 1.0
049 */
050 public interface ControllableResource extends Resource {
051
052 // Basic Methods
053
054 /**
055 * Get the workspace provider of this resource.
056 *
057 * @return the {@link WorkspaceProvider} for this Resource.
058 */
059 public WorkspaceProvider workspaceProvider();
060
061 /**
062 * Create a new persistent resource at the location identified by this ControllableResource.
063 * The request will fail if a resource already exists at that location.
064 *
065 * <p>
066 * Postconditions:
067 * <li>(initialize-resource): A new resource of the specified type
068 * exists at the location of this Resource.
069 *
070 * @param feedback Specifies optional feedback to the caller.
071 * @return A proxy for this new resource, whose properties are specified by feedback.
072 * @throws WvcmException ReasonCode:
073 * <li>{@link ReasonCode#RESOURCE_ALREADY_EXISTS_AT_LOCATION}:
074 * A resource MUST NOT exist at the location of this Resource.
075 * <li>{@link ReasonCode#CANNOT_CREATE_AT_THIS_LOCATION}:
076 * The location of this Resource MUST identify a valid location to create this Resource.
077 * For a workspace, a client can determine locations where workspaces can be created
078 * from the {@link Resource#WORKSPACE_FOLDER_LIST} property.
079 */
080 public ControllableResource doCreateResource(Feedback feedback) throws WvcmException;
081
082 /**
083 * Place this resource under version-control.
084 * When under version-control, the resource must be checked out to be modified
085 * and checked in to commit the modifications as a new version
086 * in the version history of the resource.
087 * <p>
088 * Postconditions:
089 * <li>(put-under-version-control): If this ControllableResource identified
090 * a resource that was not under version-control at the time of the request,
091 * the request MUST have created a new version history
092 * and MUST have created a new version resource in that version history.
093 * The {@link #IS_VERSION_CONTROLLED} property of this ControllableResource MUST be true.
094 * The {@link #IS_CHECKED_OUT} property of this ControllableResource MUST be false.
095 * The resource MUST have a {@link #CHECKED_IN} property that identifies the new version.
096 * The content and controlled properties of the new version MUST be the same as that of the resource.
097 * Note that an implementation can choose to locate the version history
098 * and version resources anywhere that it wishes. In particular, it could locate them
099 * on the same host and server as the version-controlled resource,
100 * on a different virtual host maintained by the same server,
101 * on the same host maintained by a different server,
102 * or on a different host maintained by a different server.
103 * <li>(must-not-change-existing-checked-in-out): If this ControllableResource
104 * identified a resource already under version-control at the time of the request,
105 * the request MUST NOT change the {@link #CHECKED_IN}
106 * or {@link #CHECKED_OUT} property of that version-controlled resource.
107 * <li>(new-version-history): If the request created a new version history,
108 * the request MUST have allocated a new server-defined location for that version history
109 * that MUST NOT have previously identified any other resource,
110 * and MUST NOT ever identify a resource other than this version history.
111 * <li>(update-stream): If the {@link Workspace#STREAM} property of the workspace
112 * of this controllable resource is non-null, the {@link Stream#VERSION_LIST} of the stream
113 * is updated to contain the new version resource.
114 * <li>(auto-checkout-parent): If the parent of this ControllableResource
115 * was a checked-in version-controlled folder and this ControllableResource
116 * is not already under version-control, the request MAY have checked out
117 * the parent folder.
118 *
119 * @param feedback Specifies optional feedback to the caller.
120 * @return A new proxy for this resource, whose properties are specified by feedback.
121 * @throws WvcmException ReasonCode:
122 * <li>{@link ReasonCode#FORBIDDEN}
123 * If the {@link #IS_VERSION_CONTROLLABLE} property of this resource is false, the request MUST fail.
124 *
125 */
126 public ControllableResource doVersionControl(Feedback feedback) throws WvcmException;
127
128 // Basic Properties
129
130 /**
131 * The workspace of which this ControllableResource is a member.
132 * By definition, the workspace property of a workspace
133 * identifies itself, and the workspace property of any other
134 * type of resource must identify the same workspace as its parent.
135 */
136 public static final PropertyName<Workspace> WORKSPACE =
137 new PropertyName<Workspace>("workspace"); //$NON-NLS-1$
138
139 /**
140 * Get the {@link #WORKSPACE} property.
141 *
142 * @return the {@link #WORKSPACE} property.
143 * @throws WvcmException if this ControllableResource was not created with
144 * {@link #WORKSPACE} as a wanted property.
145 */
146 public Workspace getWorkspace() throws WvcmException;
147
148 /** true if the resource is version-controlled, false otherwise. */
149 public static final PropertyName<Boolean> IS_VERSION_CONTROLLED =
150 new PropertyName<Boolean>("is-version-controlled"); //$NON-NLS-1$
151
152 /**
153 * Get the {@link #IS_VERSION_CONTROLLED} property.
154 *
155 * @return the {@link #IS_VERSION_CONTROLLED} property.
156 * @throws WvcmException if this ControllableResource was not created with
157 * {@link #IS_VERSION_CONTROLLED} as a wanted property.
158 */
159 public boolean getIsVersionControlled() throws WvcmException;
160
161 /** true if the resource is checked out, false otherwise. */
162 public static final PropertyName<Boolean> IS_CHECKED_OUT =
163 new PropertyName<Boolean>("is-checked-out"); //$NON-NLS-1$
164
165 /**
166 * Get the {@link #IS_CHECKED_OUT} property.
167 *
168 * @return the {@link #IS_CHECKED_OUT} property.
169 * @throws WvcmException if this ControllableResource was not created with
170 * {@link #IS_CHECKED_OUT} as a wanted property.
171 */
172 public boolean getIsCheckedOut() throws WvcmException;
173
174
175 /**
176 * Create a new version-controlled resource at the location identified by the proxy.
177 * The resource is associated with an existing version history,
178 * and if possible, is initialized with a specified version from that version history.
179 * If the specified version must be restored at a specific location,
180 * the new version-controlled resource is created at that specific location
181 * instead of the location of this ControllableResource.
182 * The request will fail if a resource already exists at that location.
183 * <p>
184 * Postconditions:
185 * <li>(new-version-controlled-resource): A new version-controlled resource is created
186 * for the version history of the specified version. If possible, the initial
187 * {@link ControllableResource#CHECKED_IN} property of the new version-controlled
188 * resource is set to be the specified version; if not, the version is implementation dependent.
189 * Otherwise, same semantics as the {@link Workspace#doUpdate}.
190 * <li>(new-version-controlled-folder): Same semantics as the update of a
191 * folder target in {@link Workspace#doUpdate}.
192 * <li>(auto-checkout-parent): If the parent of this ControllableResource
193 * was a checked-in version-controlled folder, the request MAY automatically check out
194 * the parent folder.
195 *
196 * @param version the version used to initialize the version-controlled
197 * resource.
198 * @param feedback Specifies optional feedback to the caller.
199 * @return A proxy for this new resource, whose properties are specified by feedback.
200 * @throws WvcmException ReasonCode:
201 * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}:
202 * The resource identified by the <code>version</code> argument must be a version.
203 * <li>{@link ReasonCode#CANNOT_CREATE_AT_THIS_LOCATION}:
204 * The location for the new version-controlled resource is not a valid location for a version-controlled resource.
205 * <li>{@link ReasonCode#RESOURCE_ALREADY_EXISTS_AT_LOCATION}:
206 * The location for the new version-controlled resource MUST NOT identify an existing resource.
207 * <li>{@link ReasonCode#ONE_CONTROLLED_RESOURCE_PER_HISTORY_PER_WORKSPACE}:
208 * The workspace of this ControllableResource MUST NOT have a member
209 * whose {@link #VERSION_HISTORY} property identifies the version history
210 * of the version specified in the request.
211 */
212 public ControllableResource doCreateVersionControlledResource(Version version, Feedback feedback)
213 throws WvcmException;
214
215 /** Boolean flags for the doCheckin method */
216 public static class CheckinFlag
217 {
218 private CheckinFlag(String flagName) { _flagName = flagName; }
219
220 /**
221 * Returns a string representation of this flag suitable for diagnostics.
222 */
223 @Override
224 public String toString() { return _flagName; }
225
226 /**
227 * A string representation of this flag.
228 */
229 private final String _flagName;
230
231 /**
232 * Indicates whether to fork even if forking is discouraged.
233 */
234 public static final CheckinFlag FORK_OK = new CheckinFlag("fork-ok"); //$NON-NLS-1$
235
236 /**
237 * Indicates whether to checkout the resource again immediately after checking it in.
238 */
239 public static final CheckinFlag KEEP_CHECKED_OUT = new CheckinFlag("keep-checked-out"); //$NON-NLS-1$
240
241 /**
242 * Indicates whether a checkin will be performed if the persistent state
243 * of the new version would be identical to that of the previous
244 * version. If this flag is not set, a checkin operation on an unchanged
245 * controllable resource will uncheckout that resource.
246 */
247 public static final CheckinFlag CHECKIN_IDENTICAL = new CheckinFlag("checkin-identical"); //$NON-NLS-1$
248 }
249
250
251 /** Boolean flags for the doCheckout method */
252 public static class CheckoutFlag
253 {
254 private CheckoutFlag(String flagName) { _flagName = flagName; }
255
256 /**
257 * Returns a string representation of this flag suitable for diagnostics.
258 */
259 @Override
260 public String toString() { return _flagName; }
261
262 /**
263 * The string form of this flag.
264 */
265 private final String _flagName;
266
267 /**
268 * Indicates whether to fork even if forking is discouraged.
269 */
270 public static final CheckoutFlag FORK_OK = new CheckoutFlag("fork-ok"); //$NON-NLS-1$
271
272 /**
273 * Indicates whether to fail the checkout if there already is a reserved checkout
274 * from the currently selected version in the checkout activity.
275 */
276 @SuppressWarnings("hiding") //$NON-NLS-1$
277 public static final CheckoutFlag RESERVED = new CheckoutFlag("reserved"); //$NON-NLS-1$
278 }
279
280
281 /**
282 * Changes the state of the resource identified by this ControllableResource
283 * to be checked-in, and synchronizes the persistent state
284 * of the resource to be that of the persistent state
285 * on the client. The current content and controlled properties of the resource are captured
286 * in a new version resource at a server-defined location.
287 * A doCheckin request can be applied to a checked-out configuration
288 * to produce a new baseline whose {@link Baseline#VERSION_LIST} captures the
289 * current state of the version-controlled members of the {@link Configuration#ROOT_FOLDER}
290 * of the configuration.
291 * <p>
292 * Postconditions:
293 * <li>(uncheckout-identical): If the controlled state of this resource is the same as its CHECKED_OUT version,
294 * and if the PREDECESSOR_LIST only contains the CHECKED_OUT version,
295 * and if the flag {@link CheckinFlag#CHECKIN_IDENTICAL} has not been passed in,
296 * an uncheckout on this resource will be automatically performed.
297 * <li>(complete-merge): If the {@link #MERGE_LIST} or the {@link #AUTO_MERGE_LIST} are non-empty,
298 * the versions within them are first moved to {@link #PREDECESSOR_LIST}.
299 * <li>(create-version): The request MUST have created a new version in the version history
300 * of the {@link #CHECKED_OUT} version. The request MUST have allocated a distinct new location
301 * for the new version, and that location MUST NOT ever identify any resource other than that version.
302 * <li>(initialize-version-content-and-properties): The content and controlled properties
303 * of the new version MUST be copied from the checked-out resource.
304 * The {@link Version#VERSION_NAME} of the new version MUST be set to a server-defined value
305 * distinct from all other {@link Version#VERSION_NAME} values of other versions in the same
306 * version history.
307 * The {@link #COMMENT} and {@link #PREDECESSOR_LIST} of the version-controlled resource
308 * MUST have been set to <code>null</code> after it was copied to the new version.
309 * <li>(checked-in): If keepCheckedOut is not specified in the request,
310 * the {@link #CHECKED_OUT} property of the version-controlled resource MUST have been removed
311 * and a {@link #CHECKED_IN} property that identifies the new version MUST have been added.
312 * <li>(keep-checked-out): If keepCheckedOut is specified in the request,
313 * the {@link #CHECKED_OUT} property of the checked-out resource MUST have been updated
314 * to identify the new version.
315 * <li>(add-to-history): The new version resource MUST have been added as a new bound member
316 * of the version history of the {@link #CHECKED_OUT} version.
317 * <li>(initialize-activity): The {@link Version#ACTIVITY} of the new version
318 * MUST have been initialized to be the same as the {@link #ACTIVITY} of the checked-out resource.
319 * The {@link #ACTIVITY} of the version-controlled resource MUST have been set to NULL
320 * after it was copied to the new version.
321 * <li>(initialize-folder-version-bindings): If this ControllableResource identifies
322 * a version-controlled folder, then for each version-controlled bound member of this
323 * ControllableResource, the new folder version MUST contain a bound member which
324 * is the version history of that version-controlled bound member, and whose binding
325 * name is the binding name of the version-controlled bound member.
326 * <li>(create-baseline-version-list): If this ControllableResource identifies a configuration,
327 * the {@link Baseline#VERSION_LIST} of the new baseline identifies a
328 * list of the {@link #CHECKED_IN} versions of each version-controlled member
329 * of the {@link Configuration#ROOT_FOLDER} of the configuration at the time of the request.
330 * <li>(update-stream): The {@link Stream#VERSION_LIST} of the {@link Workspace#STREAM}
331 * is updated to contain the new version resource.
332 * If the {@link Stream#VERSION_LIST} had previously contained a different version from the version history of the new version,
333 * that different version is removed.
334 *
335 * @param flags Array of boolean flags (may be null):
336 * <li>{@link CheckinFlag#KEEP_CHECKED_OUT} indicates whether to checkout the
337 * resource again immediately after checking it in.
338 * If <code>true</code>, the {@link #ACTIVITY}
339 * and {@link #RESERVED} properties should not be changed by the checkout.
340 * <li>{@link CheckinFlag#FORK_OK} indicates whether to fork even if forking is discouraged.
341 * <li>{@link CheckinFlag#CHECKIN_IDENTICAL} will force a checkin even if the controlled
342 * state is the same as its CHECKED_IN version. Otherwise, an uncheckout will be performed if
343 * the controlled state of this resource is the same as its CHECKED_IN version,
344 * and if the PREDECESSOR_LIST only contains the CHECKED_OUT version.
345 * @param feedback Specifies optional feedback to the caller.
346 * @return A new proxy for this resource, whose properties are specified by feedback.
347 * @throws WvcmException ReasonCode:
348 * <li>{@link ReasonCode#MUST_BE_CHECKED_OUT}:
349 * This ControllableResource MUST identify a resource whose {@link #IS_CHECKED_OUT} property is true.
350 * <li>{@link ReasonCode#VERSION_HISTORY_MUST_BE_A_TREE}:
351 * The versions identified by the {@link #PREDECESSOR_LIST}, {@link #MERGE_LIST}
352 * and {@link #AUTO_MERGE_LIST} of the checked-out resource MUST be descendants of
353 * the root version of the version history for the {@link #CHECKED_OUT} version.
354 * <li>{@link ReasonCode#CANNOT_FORK}:
355 * A doCheckin request MUST fail if it would cause a version
356 * whose {@link Version#CHECKIN_FORK} is {@link Version.Fork#FORBIDDEN} to
357 * appear in the {@link Version#PREDECESSOR_LIST} of more than one version.
358 * <li>{@link ReasonCode#CANNOT_CHECKIN_FORK_DISCOURAGED}:
359 * A doCheckin request MUST fail if it would cause a version
360 * whose {@link Version#CHECKIN_FORK} is {@link Version.Fork#DISCOURAGED} to
361 * appear in the {@link Version#PREDECESSOR_LIST} of more than one version,
362 * unless forkOk is specified in the request.
363 * <li>{@link ReasonCode#CANNOT_CREATE_BRANCH_IN_ACTIVITY}:
364 * Any version which is in the version history of the checked-out resource
365 * and whose {@link Version#ACTIVITY} identifies the {@link #ACTIVITY}
366 * of the checked-out resource MUST be an ancestor of the
367 * checked-out resource.
368 * <li>@{@link ReasonCode#CANNOT_CHECKIN_TO_RESERVED_ACTIVITY}
369 * If in another workspace there is a version-controlled resource
370 * whose {@link #CHECKED_OUT} property identifies a version in the version history
371 * of this resource, then the {@link #RESERVED} property of that version-controlled
372 * resource MUST be true.
373 * <li>{@link ReasonCode#NO_CHECKED_OUT_BASELINE_CONTROLLED_FOLDER_MEMBERS}:
374 * If this ControllableResource
375 * identifies a configuration, all version-controlled members
376 * of the {@link Configuration#ROOT_FOLDER} of the configuration MUST be checked-in.
377 * <li>{@link ReasonCode#CANNOT_CREATE_BRANCH_IN_STREAM}:
378 * If the {@link Stream#VERSION_LIST} of the {@link Workspace#STREAM} of this ControllableResource
379 * contains a version from the version history of this controllable resource,
380 * then the {@link Stream#VERSION_LIST}
381 * MUST contain one of the versions in the {@link #PREDECESSOR_LIST} of this controllable resource.
382 *
383 */
384 public ControllableResource doCheckin(CheckinFlag[] flags, Feedback feedback)
385 throws WvcmException;
386
387 /**
388 * Checkout this ControllableResource so that its controlled state can be modified.
389 * <p>
390 * Postconditions:
391 * <li>(is-checked-out): The resource identified by this ControllableResource
392 * MUST have an {@link #IS_CHECKED_OUT} property whose value is true.
393 * <li>(has-checked-out-version): The checked-out resource MUST have a {@link #CHECKED_OUT} property
394 * that identifies the {@link #CHECKED_IN} version preceding the checkout.
395 * The version-controlled resource MUST NOT have a {@link #CHECKED_IN} property.
396 * <li>(initialize-predecessor-list): The {@link #PREDECESSOR_LIST} property of the checked-out resource
397 * MUST be initialized to be the {@link #CHECKED_OUT} version.
398 * <li>(initialize-activity): The {@link #ACTIVITY} of the checked-out resource is set as follows:
399 * - If the resource is a configuration, then the activity is the {@link Workspace#STREAM} of
400 * the workspace (possibly null).
401 * - Otherwise, if the resource is not a configuration, the {@link Workspace#CURRENT_ACTIVITY}
402 * of the workspace is used. If the {@link Workspace#CURRENT_ACTIVITY} is <code>null</code>,
403 * the server MAY automatically set the {@link Workspace#CURRENT_ACTIVITY} to be a newly created activity.
404 * <li>(initialize-reserved): If reserved was specified in the request,
405 * then the {@link #RESERVED} property of the checked-out resource MUST be true.
406 * @param flags Array of boolean flags (may be null):
407 * @param feedback Specifies optional feedback to the caller.
408 * @return A new proxy for this resource, whose properties are specified by feedback.
409 * @throws WvcmException ReasonCode:
410 * <li>{@link ReasonCode#MUST_BE_CHECKED_IN}:
411 * The {@link #IS_CHECKED_OUT} property of this ControllableResource MUST be false.
412 * <li>{@link ReasonCode#CANNOT_CHECKOUT_FORKING_IS_FORBIDDEN}:
413 * If the {@link Version#CHECKOUT_FORK} property
414 * of the version being checked out is {@link Version.Fork#FORBIDDEN}, the request MUST fail
415 * if the checked-out version has a non-empty list of successors.
416 * <li>{@link ReasonCode#CANNOT_CHECKOUT_FORKING_IS_DISCOURAGED}:
417 * If the {@link Version#CHECKOUT_FORK} property
418 * of the version being checked out is {@link Version.Fork#DISCOURAGED}, the request MUST fail
419 * if the checked-out version has a non-empty list of successors unless forkOk is specified
420 * in the request.
421 * <li>{@link ReasonCode#CANNOT_CHECKOUT_MULTI_CHECKOUT_IS_DISCOURAGED}:
422 * If the {@link Version#CHECKOUT_FORK} property
423 * of the version being checked out is {@link Version.Fork#DISCOURAGED}, the request MUST fail
424 * if a checked-out resource identifies that version in its {@link #CHECKED_OUT} property
425 * unless forkOk is specified in the request.
426 * <li>{@link ReasonCode#CANNOT_CHECKOUT_MULTI_CHECKOUT_IS_FORBIDDEN}:
427 * If the {@link Version#CHECKOUT_FORK} property
428 * of the version being checked out is {@link Version.Fork#FORBIDDEN}, the request MUST fail
429 * if a checked-out resource identifies that version in its {@link #CHECKED_OUT} property.
430 * <li>{@link ReasonCode#ONE_CHECKOUT_PER_ACTIVITY_PER_HISTORY}:
431 * If there is a request activity set,
432 * and if Reserved is specified, an existing reserved checkout from a version
433 * of that version history MUST NOT select an activity in that activity set.
434 * <li>{@link ReasonCode#CANNOT_CREATE_BRANCH_IN_ACTIVITY}:
435 * If there is a request activity set, and if Reserved is specified,
436 * the selected version MUST be a descendant of all other versions of that version history
437 * that select that activity.
438 * <li>{@link ReasonCode#CANNOT_CREATE_BRANCH_IN_STREAM}:
439 * If the {@link Workspace#STREAM} property of the workspace of this controllable resource
440 * is non-null, one of the following MUST be true:
441 * <br> - the {@link Stream#VERSION_LIST} of the stream contains no version from the version history
442 * of the {@link #CHECKED_IN} version.
443 * <br> - the {@link Stream#VERSION_LIST} of the stream contains the {@link #CHECKED_IN} version,
444 * <br> - the {@link CheckoutFlag#RESERVED} was not specified in the flags argument.
445 * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}:
446 * If the controllable resource is a configuration, and there is a request activity set,
447 * the <code>activity</code> argument MUST identify a stream; otherwise, the <code>activity</code>
448 * MUST identify an activity.
449 */
450 public ControllableResource doCheckout(
451 CheckoutFlag[] flags,
452 Feedback feedback)
453 throws WvcmException;
454
455 /**
456 * Cancels the checkout of a version-controlled resource,
457 * and restores its controlled state to the state of its {@link #CHECKED_OUT} version.
458 * <p>
459 * Postconditions:
460 * <li>(cancel-checked-out): The value of the {@link #CHECKED_IN} property is that of the
461 * {@link #CHECKED_OUT} property prior to the request, and the {@link #CHECKED_OUT} property has been removed.
462 * <li>(restore-content): The controlled state of the version-controlled resource
463 * corresponds to that of its {@link #CHECKED_IN} version.
464 *
465 * @param feedback Specifies optional feedback to the caller.
466 * @return A new proxy for this resource, whose properties are specified by feedback.
467 * @throws WvcmException ReasonCode:
468 * <li>{@link ReasonCode#MUST_BE_CHECKED_OUT}:
469 * This ControllableResource
470 * MUST identify a version-controlled resource with a {@link #CHECKED_OUT} property.
471 */
472 public ControllableResource doUncheckout(Feedback feedback) throws WvcmException;
473
474 /**
475 * Add the specified label to the checked-in version of this controllable resource.
476 * @see Version#doAddLabel
477 */
478 public ControllableResource doAddLabel(String label, Feedback feedback) throws WvcmException;
479
480 /**
481 * Remove the specified lable from the {@link #CHECKED_IN} version of this controllable resource.
482 * @see Version#doRemoveLabel
483 */
484 public ControllableResource doRemoveLabel(String label, Feedback feedback) throws WvcmException;
485
486 /**
487 * Set the specified label on the checked-in version of this controllable resource.
488 * @see Version#doSetLabel
489 */
490 public ControllableResource doSetLabel(String label, Feedback feedback) throws WvcmException;
491
492 /**
493 * Apply {@link Resource#doReadProperties}
494 * to the version selected by <code>label</code> from the version history
495 * of this ControllableResource.
496 *
497 * @param label the label identifying the version to be selected
498 * @param feedback the list of properties that will be available on
499 * the returned version.
500 * @return a proxy for the selected version, with the wanted properties.
501 * @throws WvcmException ReasonCode:
502 * <li>{@link ReasonCode#MUST_BE_CHECKED_IN}:
503 * The {@link #CHECKED_IN} property of this ControllableResource MUST identify a version.
504 * <li>{@link ReasonCode#NOT_FOUND}:
505 * The label was not found.
506 */
507 public Version doReadLabelledVersionProperties(
508 String label,
509 Feedback feedback)
510 throws WvcmException;
511
512 // Versioning Properties
513
514 /**
515 * A boolean value indicating whether this resource can be placed under version-control.
516 * @see #doVersionControl doVersionControl
517 */
518 public static final PropertyName<Boolean> IS_VERSION_CONTROLLABLE =
519 new PropertyName<Boolean>("is-version-controllable"); //$NON-NLS-1$
520
521 /**
522 * Get the {@link #IS_VERSION_CONTROLLABLE} property.
523 *
524 * @return the {@link #IS_VERSION_CONTROLLABLE} property.
525 * @throws WvcmException if this ControllableResource was not created with
526 * {@link #IS_VERSION_CONTROLLABLE} as a wanted property.
527 */
528 public boolean getIsVersionControllable() throws WvcmException;
529
530 /**
531 * The version history of a version-controlled resource.
532 * This is the version history of the {@link #CHECKED_IN} or {@link #CHECKED_OUT} version.
533 */
534 public static final PropertyName<VersionHistory> VERSION_HISTORY =
535 new PropertyName<VersionHistory>("version-history"); //$NON-NLS-1$
536
537 /**
538 * Get the {@link #VERSION_HISTORY} property.
539 *
540 * @return the {@link #VERSION_HISTORY} property.
541 * @throws WvcmException if this ControllableResource was not created with
542 * {@link #VERSION_HISTORY} as a wanted property.
543 */
544 public VersionHistory getVersionHistory() throws WvcmException;
545
546 /**
547 * The configuration to which this resource belongs.
548 */
549 public static final PropertyName<Configuration> CONFIGURATION =
550 new PropertyName<Configuration>("configuration"); //$NON-NLS-1$
551
552 /**
553 * Get the {@link #CONFIGURATION} property.
554 *
555 * @return the {@link #CONFIGURATION} property.
556 * @throws WvcmException if this property was not set and
557 * this ControllableResource was not created with
558 * {@link #CONFIGURATION} as a wanted property.
559 */
560 public Configuration getConfiguration()
561 throws WvcmException;
562
563 /**
564 * The checked-in {@link Version} of this version-controlled resource.
565 * If this ControllableResource is checked-in,
566 * this is the version whose content and controlled properties
567 * are identical to those of this ControllableResource;
568 * otherwise, this is <code>null</code>.
569 */
570 public static final PropertyName<Version> CHECKED_IN =
571 new PropertyName<Version>("checked-in"); //$NON-NLS-1$
572
573 /**
574 * Get the {@link #CHECKED_IN} property.
575 *
576 * @return the {@link #CHECKED_IN} property.
577 * @throws WvcmException if this ControllableResource was not created with
578 * {@link #CHECKED_IN} as a wanted property.
579 */
580 public Version getCheckedIn() throws WvcmException;
581
582 /**
583 * The checked-out version of a version-controlled resource.
584 * if this ControllableResource is checked-out,
585 * this is the checked-in version at the time
586 * the checkout was performed; otherwise, this is <code>null</code>.
587 */
588 public static final PropertyName<Version> CHECKED_OUT =
589 new PropertyName<Version>("checked-out"); //$NON-NLS-1$
590
591 /**
592 * Get the {@link #CHECKED_OUT} property.
593 *
594 * @return the {@link #CHECKED_OUT} property.
595 * @throws WvcmException if this ControllableResource was not created with
596 * {@link #CHECKED_OUT} as a wanted property.
597 */
598 public Version getCheckedOut() throws WvcmException;
599
600 /**
601 * If this ControllableResource is checked-out,
602 * this is a list of the versions that
603 * will become the predecessors of the version created
604 * when this ControllableResource is checked in;
605 * otherwise, this is <code>null</code>.
606 * @see #getPredecessorList
607 * @see #setPredecessorList
608 */
609 public static final PropertyName<ResourceList<Version>> PREDECESSOR_LIST =
610 new PropertyName<ResourceList<Version>>("predecessor-list"); //$NON-NLS-1$
611
612 /**
613 * Get the {@link #PREDECESSOR_LIST} property.
614 *
615 * @return the {@link #PREDECESSOR_LIST} property.
616 * @throws WvcmException if this property was not set and
617 * this ControllableResource was not created with
618 * {@link #PREDECESSOR_LIST} as a wanted property.
619 * @see #setPredecessorList
620 */
621 public ResourceList<Version> getPredecessorList() throws WvcmException;
622
623 /**
624 * Set the {@link #PREDECESSOR_LIST} property.
625 *
626 * @param versionList a list of versions that will
627 * be the predecessors of the version created when this ControllableResource
628 * is checked in.
629 * @see #getPredecessorList
630 */
631 public void setPredecessorList(ResourceList<Version> versionList);
632
633 /**
634 * If the controllable resource is checked-out, this identifies the activity
635 * that will become the {@link Version#ACTIVITY} of the version created
636 * when the controllable resource is checked in; otherwise, this is <code>null</code>.
637 * If the controllable resource is not checked-out, an attempt to modify this
638 * property MUST fail.
639 * If the controllable resource is a Configuration, and the {@link #ACTIVITY} is not <code>null</code>,
640 * the activity must be a {@link Stream}.
641 * @see #setActivity
642 * @see #getActivity
643 */
644 public static final PropertyName<Activity> ACTIVITY =
645 new PropertyName<Activity>("activity"); //$NON-NLS-1$
646
647 /**
648 * Get the {@link #ACTIVITY} property.
649 *
650 * @return the {@link #ACTIVITY} property.
651 * @throws WvcmException if this property was not set and
652 * this ControllableResource was not created with
653 * {@link #ACTIVITY} as a wanted property.
654 * @see #setActivity
655 */
656 public Activity getActivity() throws WvcmException;
657
658 /**
659 * Set the {@link #ACTIVITY} property.
660 *
661 * @param activity a list of {@link Activity} objects that identify
662 * the new value for the {@link #ACTIVITY} property.
663 * @see #getActivity
664 */
665 public void setActivity(Activity activity);
666
667 /**
668 * A Boolean that indicates whether the checked-out version
669 * of this checked-out version-controlled resource can
670 * concurrently be checked-out to the same activity in
671 * another version-controlled resource.
672 * <p>In particular, this indicates whether the {@link #ACTIVITY}
673 * of another checked-out resource associated with the
674 * version history of this version-controlled resource
675 * can have be the activity that is also identified by the
676 * {@link #ACTIVITY} property of this checked-out resource.
677 * Since an activity must form a single line of descent through
678 * a given version history, a <code>doCheckin</code> may fail
679 * when a checkout is not reserved, because another version-controlled
680 * resource may have checked-in a parallel version into the
681 * activity. In this case, the user will first have
682 * to merge into this checked-out resource the latest
683 * version selected by that activity from that version history,
684 * and then modify the {@link #PREDECESSOR_LIST} of this checked-out resource
685 * to identify that version.
686 * @see #setReserved
687 * @see #getReserved
688 */
689 public static final PropertyName<Boolean> RESERVED =
690 new PropertyName<Boolean>("reserved"); //$NON-NLS-1$
691
692 /**
693 * Get the {@link #RESERVED} property.
694 *
695 * @return the {@link #RESERVED} property.
696 * @throws WvcmException if this property was not set and
697 * this ControllableResource was not created with
698 * {@link #RESERVED} as a wanted property.
699 * @see #setReserved
700 */
701 public boolean getReserved() throws WvcmException;
702
703 /**
704 * Set the {@link #RESERVED} property.
705 *
706 * @param val the new value for the {@link #RESERVED} property of this ControllableResource.
707 * @see #getReserved
708 */
709 public void setReserved(boolean val);
710
711 /**
712 * A list of {@link Version} objects that identify the versions whose
713 * content and controlled properties must be merged by the client into this
714 * checked-out ControllableResource.
715 * <p>
716 * After a merge operation, the merge list of each merge target contains a
717 * list of merge source versions, indicating the versions whose content or
718 * controlled properties are yet to be merged. For each entry in the merge
719 * list, it is the client's responsibility to update the controlled state of
720 * the checked-out merge target so that it reflects the logical merge of the
721 * merge source into the current controlled state of the merge target. The
722 * client indicates that it has completed the update of the merge target by
723 * deleting the merge source from the merge list of the checked-out merge
724 * target, and adding it to the predecessor list.
725 * <p>
726 * As an error check for a client forgetting to complete a merge, the server
727 * MUST fail an attempt to <code>doCheckin()</code> a version-controlled
728 * resource with a non-empty merge list.
729 *
730 * @see #setMergeList
731 * @see #getMergeList
732 */
733 public static final PropertyName<ResourceList<Version>> MERGE_LIST =
734 new PropertyName<ResourceList<Version>>("merge-list"); //$NON-NLS-1$
735
736 /**
737 * Get the {@link #MERGE_LIST} property.
738 *
739 * @return the {@link #MERGE_LIST} property.
740 * @throws WvcmException if this property was not set and
741 * this ControllableResource was not created with
742 * {@link #MERGE_LIST} as a wanted property.
743 * @see #setMergeList
744 */
745 public ResourceList<Version> getMergeList() throws WvcmException;
746
747 /**
748 * Set the {@link #MERGE_LIST} property.
749 *
750 * @param versionList a list of {@link Version} objects that will be
751 * the value of the {@link #MERGE_LIST} property.
752 * @see #getMergeList
753 */
754 public void setMergeList(ResourceList<Version> versionList);
755
756 /**
757 * A list of {@link Version} objects that identify each version whose
758 * controlled state has been merged by the server into this checked-out
759 * ControllableResource.
760 * <p>
761 * When a server has the ability to automatically update the controlled
762 * state of the merge target to reflect the logical merge of the merge
763 * source, it may do so unless {@link MergeFlag#NO_AUTO_MERGE} is specified
764 * in the {@link Workspace#doMerge} request.
765 * <p>
766 * After a merge operation, the auto-merge list of each merge target
767 * contains a list of merge source versions whose controlled state was
768 * automatically merged into that merge target. Automatically merged source
769 * versions appear only in the auto-merge list, and not the merge list.
770 * <p>
771 * The client is responsible for deleting entries from the
772 * {@link #AUTO_MERGE_LIST} and adding them to the {@link #PREDECESSOR_LIST}
773 * after the user has verified that the automatic merge was performed
774 * correctly by the server.
775 *
776 * @see #setAutoMergeList
777 * @see #getAutoMergeList
778 */
779 public static final PropertyName<ResourceList<Version>> AUTO_MERGE_LIST =
780 new PropertyName<ResourceList<Version>>("auto-merge-list"); //$NON-NLS-1$
781
782 /**
783 * Get the {@link #AUTO_MERGE_LIST} property.
784 *
785 * @return the {@link #AUTO_MERGE_LIST} property.
786 * @throws WvcmException if this property was not set and
787 * this ControllableResource was not created with
788 * {@link #AUTO_MERGE_LIST} as a wanted property.
789 * @see #setAutoMergeList
790 */
791 public ResourceList<Version> getAutoMergeList() throws WvcmException;
792
793 /**
794 * Set the {@link #AUTO_MERGE_LIST} property.
795 *
796 * @param versionList a list of {@link Version} objects that identify
797 * the new value for the {@link #AUTO_MERGE_LIST} property.
798 * @see #getAutoMergeList
799 */
800 public void setAutoMergeList(ResourceList<Version> versionList);
801
802 }