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    }