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 */
011package javax.wvcm;
012
013import javax.wvcm.PropertyNameList.PropertyName;
014import javax.wvcm.Workspace.MergeFlag;
015import 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 */
050public 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}