001/*
002 * file Workspace.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.ResourceList.ResponseIterator;
015import javax.wvcm.WvcmException.ReasonCode;
016
017/**
018 * A proxy for a workspace resource.
019 *
020 * A workspace resource provides an environment within which a user can make persistent modifications
021 * to a configuration of resources without interfering or disrupting the work of other users of those resources.
022 * This requires that the user be able to persist changes to resources (both content changes and naming changes)
023 * without those changes being immediately visible to other users.  To provide this functionality,
024 * the persistent changes saved in one workspace (also known as a "sandbox" or a "view") are visible
025 * in other workspaces only after the user of that workspace explicitly exposes those changes for use by other workspaces,
026 * and after a user of another workspace explicitly requests to see the changes that have been exposed. </p>
027 * 
028 * @since 1.0
029 */
030public interface Workspace extends ControllableFolder {
031
032    /**
033     * Create a persistent workspace, where the provider can allocate the location
034     * for the new workspace.
035     * The provider should use the client-specified location if it is valid,
036     * but can select a different location if the location is not valid
037     * or already identifies a workspace.
038     * <p>
039     * Postconditions:
040     * <li>(initialize-resource): A new persistent workspace resource exists at the location
041     *  of this Workspace.
042     * @see ControllableResource#doCreateResource
043     * 
044     * @param feedback Specifies optional feedback to the caller.
045     * @return a proxy for the newly created workspace, whose properties are specified by feedback.
046     * @throws WvcmException ReasonCode:
047     * <li>{@link ReasonCode#METHOD_NOT_SUPPORTED}:
048     *  If the provider does not support the creation of workspaces, this request MUST fail.
049     *  A client can determine a valid location for this method
050     *  with a {@link Provider#rootLocation()} request.
051     */
052    public Workspace doCreateGeneratedResource(Feedback feedback) throws WvcmException;
053
054    /**
055     * This property identifies a folder in the workspace that can contain bound members
056     * that are not folders.
057     * <p>
058     * Some workspaces do not allow the creation of non-folder resources
059     * as bound members of the workspace itself, and instead reserve bound members
060     * of the workspace for folders that represent different repositories or configuration roots.
061     */
062    public static final PropertyName<ControllableFolder> CONTROLLABLE_RESOURCE_HOME =
063        new PropertyName<ControllableFolder>("controllable-resource-home"); //$NON-NLS-1$
064
065    /**
066     * Get the {@link #CONTROLLABLE_RESOURCE_HOME} property.
067     * 
068     * @return the {@link #CONTROLLABLE_RESOURCE_HOME} property.
069     * @throws WvcmException if this Workspace was not created with
070     * {@link #CONTROLLABLE_RESOURCE_HOME} as a wanted property.
071     */
072    public ControllableFolder getControllableResourceHome() throws WvcmException;
073
074    /**
075     * This property identifies a folder in the workspace that can contain bound members
076     * that are baseline-controlled folders.
077     * This property returns <code>null</code> if this Workspace does not support
078     * baseline-controlled folders.
079     */
080    public static final PropertyName<ControllableFolder> CONFIGURATION_ROOT_FOLDER_HOME =
081        new PropertyName<ControllableFolder>("configuration-root-folder-home"); //$NON-NLS-1$
082
083    /**
084     * Get the {@link #CONFIGURATION_ROOT_FOLDER_HOME} property.
085     * 
086     * @return the {@link #CONFIGURATION_ROOT_FOLDER_HOME} property.
087     * @throws WvcmException if this Workspace was not created with
088     * {@link #CONFIGURATION_ROOT_FOLDER_HOME} as a wanted property.
089     */
090    public ControllableFolder getConfigurationRootFolderHome() throws WvcmException;
091
092    /**
093     * This property identifies a list of folders that can contain activities for this workspace.
094     * This list is empty if this Workspace does not provide activity support.
095     */
096    public static final PropertyName<ResourceList<Folder>> ACTIVITY_FOLDER_LIST =
097        new PropertyName<ResourceList<Folder>>("activity-folder-list"); //$NON-NLS-1$
098
099    /**
100     * Get the {@link #ACTIVITY_FOLDER_LIST} property.
101     * 
102     * @return the {@link #ACTIVITY_FOLDER_LIST} property.
103     * @throws WvcmException if this Workspace was not created with
104     * {@link #ACTIVITY_FOLDER_LIST} as a wanted property.
105     */
106    public ResourceList<Folder> getActivityFolderList() throws WvcmException;
107
108    /**
109     * This property identifies a list of folders that contain the version
110     * history resources for the version-controlled resources in this workspace.
111     */
112    public static final PropertyName<ResourceList<Folder>> VERSION_HISTORY_FOLDER_LIST =
113        new PropertyName<ResourceList<Folder>>("version-history-folder-list"); //$NON-NLS-1$
114
115    /**
116     * Get the {@link #VERSION_HISTORY_FOLDER_LIST} property.
117     * 
118     * @return the {@link #VERSION_HISTORY_FOLDER_LIST} property.
119     * @throws WvcmException if this Workspace was not created with
120     * {@link #VERSION_HISTORY_FOLDER_LIST} as a wanted property.
121     */
122    public ResourceList<Folder> getVersionHistoryFolderList() throws WvcmException;
123
124    /**
125     * The list of root folders of configurations in this workspace.
126     */
127    public static final PropertyName<ResourceList<ControllableFolder>> BASELINE_CONTROLLED_FOLDER_LIST =
128        new PropertyName<ResourceList<ControllableFolder>>("baseline-controlled-folder-list"); //$NON-NLS-1$
129
130    /**
131     * Get the {@link #BASELINE_CONTROLLED_FOLDER_LIST} property.
132     * 
133     * @return the {@link #BASELINE_CONTROLLED_FOLDER_LIST} property.
134     * @throws WvcmException if this Workspace was not created with
135     * {@link #BASELINE_CONTROLLED_FOLDER_LIST} as a wanted property.
136     */
137    public ResourceList<ControllableFolder> getBaselineControlledFolderList()
138    throws WvcmException;
139
140    /**
141     * The activity that currently is being performed in this workspace.
142     * <p>
143     * When a member of this workspace is
144     * checked out, if no activity is specified in the checkout request, the
145     * {@link #CURRENT_ACTIVITY} will be used.  This allows an activity-unaware
146     * client to update a workspace in which activity tracking is required. </p>
147     * <p>
148     * The {@link #CURRENT_ACTIVITY} of a controlled workspace can be modified
149     * while the workspace is checked in.
150     * @see #getCurrentActivity
151     * @see #setCurrentActivity
152     */
153    public static final PropertyName<Activity> CURRENT_ACTIVITY =
154        new PropertyName<Activity>("current-activity"); //$NON-NLS-1$
155
156    /**
157     * Get the {@link #CURRENT_ACTIVITY} property.
158     * 
159     * @return the {@link #CURRENT_ACTIVITY} property.
160     * @throws WvcmException if this property was not set and
161     * this Workspace was not created with
162     * {@link #CURRENT_ACTIVITY} as a wanted property.
163     * @see #setCurrentActivity
164     */
165    public Activity getCurrentActivity() throws WvcmException;
166
167    /**
168     * Set the {@link #CURRENT_ACTIVITY} property.
169     * 
170     * @param activity the {@link Activity} object that
171     * identifies the new {@link #CURRENT_ACTIVITY} for this Workspace.
172     * @see #getCurrentActivity
173     */
174    public void setCurrentActivity(Activity activity);
175
176    /**
177     * The stream of this workspace.
178     * <p>
179     * When a controllable resource in this workspace is checked in,
180     * the new version that is created is automatically added to the {@link Stream#VERSION_LIST}
181     * of the {@link #STREAM} of the workspace.
182     * When a configuration of this workspace is
183     * checked out, if no stream is specified in the checkout request, the
184     * {@link #STREAM} will be used. </p>
185     * <p>
186     * An implementation may refuse to modify the {@link #STREAM} of an existing workspace.
187     * @see #getStream
188     * @see #setTarget
189     * @see #setIsolatedTarget
190     */
191    public static final PropertyName<Stream> STREAM =
192        new PropertyName<Stream>("stream"); //$NON-NLS-1$
193
194    /**
195     * Get the {@link #STREAM} property.
196     * 
197     * @return the {@link #STREAM} property.
198     * @throws WvcmException if this property was not set and
199     * this Workspace was not created with
200     * {@link #STREAM} as a wanted property.
201     * @see #setTarget
202     * @see #setIsolatedTarget
203     */
204    public Stream getStream() throws WvcmException;
205
206    /**
207     * The current target stream of this workspace.
208     * <p>
209     * It is expected that the target stream periodically
210     * will be merged into and updated by this workspace.
211     * The target stream of a workspace MAY be the {@link #STREAM} of that workspace.
212     * and therefore checking in a controllable resource in the workspace MAY
213     * (but is not guaranteed to) change the {@link Stream#VERSION_LIST} of the target stream.
214     * <p>
215     * An implementation may refuse to modify the {@link #TARGET} of an existing workspace.
216     * @see #getTarget
217     * @see #setTarget
218     */
219    public static final PropertyName<Stream> TARGET =
220        new PropertyName<Stream>("target"); //$NON-NLS-1$
221
222    /**
223     * Get the {@link #TARGET} property.
224     * 
225     * @return the {@link #TARGET} property.
226     * @throws WvcmException if this property was not set and
227     * this Workspace was not created with {@link #TARGET} as a wanted property.
228     * @see #setTarget
229     */
230    public Stream getTarget() throws WvcmException;
231
232    /**
233     * Set the {@link #TARGET} property.
234     * 
235     * @param stream the {@link Stream} object that
236     * identifies the {@link #TARGET} for this Workspace.
237     * @see #getTarget
238     */
239    public void setTarget(Stream stream);
240
241    /**
242     * The current isolated target stream of this workspace.
243     * <p>
244     * It is expected that the isolated target stream periodically
245     * will be merged into and updated by this workspace.
246     * The isolated target stream of a workspace MUST NOT be the {@link #STREAM} of that workspace,
247     * and therefore checking in a controllable resource in the workspace is guaranteed
248     * not to change the {@link Stream#VERSION_LIST} of the isolated target stream.
249     * <p>
250     * An implementation may refuse to modify the {@link #ISOLATED_TARGET} of an existing workspace.
251     * @see #getIsolatedTarget
252     * @see #setIsolatedTarget
253     */
254    public static final PropertyName<Stream> ISOLATED_TARGET =
255        new PropertyName<Stream>("isolated-target"); //$NON-NLS-1$
256
257    /**
258     * Get the {@link #ISOLATED_TARGET} property.
259     * 
260     * @return the {@link #ISOLATED_TARGET} property.
261     * @throws WvcmException if this property was not set and
262     * this Workspace was not created with {@link #ISOLATED_TARGET} as a wanted property.
263     * @see #setIsolatedTarget
264     */
265    public Stream getIsolatedTarget() throws WvcmException;
266
267    /**
268     * Set the {@link #ISOLATED_TARGET} property.
269     * 
270     * @param stream the {@link Stream} object that
271     * identifies the {@link #ISOLATED_TARGET} for this Workspace.
272     * @see #getIsolatedTarget
273     */
274    public void setIsolatedTarget(Stream stream);
275
276    /**
277     * The list of current source streams of this workspace.
278     * <p>
279     * It is expected that a source stream periodically will be merged into this workspace.
280     * <p>
281     * An implementation may refuse to modify the {@link #SOURCE_LIST} of an existing workspace.
282     * @see #getSourceList
283     * @see #setSourceList
284     */
285    public static final PropertyName<ResourceList<Stream>> SOURCE_LIST =
286        new PropertyName<ResourceList<Stream>>("source-list"); //$NON-NLS-1$
287
288    /**
289     * Get the {@link #SOURCE_LIST} property.
290     * 
291     * @return the {@link #SOURCE_LIST} property.
292     * @throws WvcmException if this property was not set and
293     * this Workspace was not created with {@link #SOURCE_LIST} as a wanted property.
294     * @see #setSourceList
295     */
296    public ResourceList<Stream> getSourceList() throws WvcmException;
297
298    /**
299     * Set the {@link #SOURCE_LIST} property.
300     * 
301     * @param streamList the list of {@link Stream} objects that
302     * identifies the {@link #SOURCE_LIST} for this Workspace.
303     * @see #getSourceList
304     */
305    public void setSourceList(ResourceList<Stream> streamList);
306
307    /** 
308     * This property identifies each checked-out ControlledResource 
309     * in this workspace. 
310     */
311    public static final PropertyName<ResourceList<ControllableResource>> WORKSPACE_CHECKOUT_LIST =
312        new PropertyName<ResourceList<ControllableResource>>("workspace-checkout-list"); //$NON-NLS-1$
313
314    /**
315     * Get the {@link #WORKSPACE_CHECKOUT_LIST} property.
316     * 
317     * @return the {@link #WORKSPACE_CHECKOUT_LIST} property.
318     * @throws WvcmException if this Workspace was not created with
319     * {@link #WORKSPACE_CHECKOUT_LIST} as a wanted property.
320     */
321    public ResourceList<ControllableResource> getWorkspaceCheckoutList() throws WvcmException;
322
323    /**
324     * Apply {@link ControllableResource#doVersionControl}
325     * to each element of the resourceList.
326     * 
327     * @param resourceList the list of resources to be put under version control.
328     * @param feedback Specifies optional feedback to the caller.
329     * @return A new proxy for this resource, whose properties are specified by feedback.
330     * @throws WvcmException ReasonCode:
331     * <li>{@link ReasonCode#MULTI_STATUS}:
332     *  At least one resource in the list could not be put under version control.
333     *  If any of the resources in the resourceList cannot be put under version control,
334     *  the provider MAY fail the request.
335     */
336    public <T extends Resource> Workspace doVersionControl(
337            ResourceList<T> resourceList,
338            Feedback feedback) throws WvcmException;
339
340    /**
341     * Apply {@link ControllableResource#doCheckin} to each element of the resourceList.
342     * 
343     * @param resourceList the list of resources to be checked in.
344     * @param comment A comment for any new version whose controllable resource has no comment.
345     * @param flags passed through to {@link ControllableResource#doCheckin doCheckin}.
346     * @param feedback Specifies optional feedback to the caller.
347     * @return A new proxy for this resource, whose properties are specified by feedback.
348     * @throws WvcmException ReasonCode:
349     * <li>See {@link ControllableResource#doCheckin}
350     * <li>{@link ReasonCode#MULTI_STATUS}:
351     *  At least one resource in the list could not be checked in.
352     *  If any of the checked-out resources in the resourceList cannot be checked in,
353     *  the provider MAY fail the request.
354     */
355    public <T extends Resource> Workspace doCheckin(
356            ResourceList<T> resourceList,
357            String comment,
358            CheckinFlag[] flags, Feedback feedback) throws WvcmException;
359
360    /**
361     * Apply {@link ControllableResource#doCheckin} to each resource in {@link #WORKSPACE_CHECKOUT_LIST}.
362     * @param comment A comment for any new version whose controllable resource has no comment.
363     * @param flags passed through to {@link ControllableResource#doCheckin doCheckin}.
364     * @param feedback Specifies optional feedback to the caller.
365     * @return A new proxy for this resource, whose properties are specified by feedback.
366     * @throws WvcmException ReasonCode:
367     * <li>See {@link ControllableResource#doVersionControl}
368     * <li>{@link ReasonCode#MULTI_STATUS}:
369     *  At least one of the checked out resources could not be checked in.
370     *  If any of the checked-out resources in the {@link Workspace#WORKSPACE_CHECKOUT_LIST} cannot be checked in,
371     *  the provider MAY fail the request.
372     */
373    public Workspace doCheckinAll(
374            String comment,
375            CheckinFlag[] flags, Feedback feedback) throws WvcmException;
376
377    /**
378     * A description of how the merge would affect the merge target when the merge source
379     * is neither an ancestor nor a descendant of the {@link ControllableResource#CHECKED_IN}
380     * or {@link ControllableResource#CHECKED_OUT} version of the merge target.
381     */
382    public interface MergePreviewReport {
383        /**
384         * Get the merge target resource.
385         * 
386         * @return a version-controlled resource that would be
387         * updated by the merge request.
388         */
389        public ControllableResource getTarget();
390
391        /**
392         * Get the common ancestor for the merges.
393         * 
394         * @return a version that is the nearest common ancestor of all
395         * the versions to be merged.
396         */
397        public Version getCommonAncestor();
398
399        /**
400         * Get the list of versions whose controlled state is to be merged with the target.
401         * 
402         * @return a list of {@link Version} objects that identifies the versions
403         * to be merged to the specified target.
404         */
405        public ResourceList<Version> getVersionList();
406    }
407
408
409    /**
410     * Preview a merge.
411     * Because automerging of folders can affect what resources require a merge,
412     * the result from this request may not correspond exactly to the result of an actual merge.
413     * 
414     * @param sourceList a list of {@link Resource} objects that identify
415     * the versions to be merged.  See the sourceList argument for {@link #doMerge}.
416     * @param feedback the properties available in the returned proxies.
417     * @return an iterator of MergePreviewReport objects,
418     * indicating resources that have their {@link ControllableResource#MERGE_LIST}
419     * or {@link ControllableResource#AUTO_MERGE_LIST} set by a {@link #doMerge} request
420     * with {@link MergeFlag#NO_AUTO_MERGE} specified.
421     * @throws WvcmException ReasonCode:
422     *  <li>{@link ReasonCode#METHOD_NOT_SUPPORTED}:
423     *  This resource does not support this report.
424     */
425    public <T extends Resource> ResponseIterator<MergePreviewReport> doMergePreviewReport(
426            ResourceList<T> sourceList,
427            Feedback feedback)
428    throws WvcmException;
429
430    /** Boolean flags for the doMerge method */
431    public static enum MergeFlag
432    {
433        /** 
434         * Indicates whether to fork on checkout even if forking is discouraged.
435         * @see ControllableResource.CheckoutFlag#FORK_OK
436         */
437        FORK_OK("fork-ok"), //$NON-NLS-1$
438
439        /**
440         * Indicates whether to do a checkout even
441         * if there already is a reserved checkout from the currently selected
442         * version in the checkout activity.
443         * @see ControllableResource.CheckoutFlag#RESERVED
444         */
445        @SuppressWarnings("hiding") //$NON-NLS-1$
446        RESERVED("reserved"), //$NON-NLS-1$
447
448        /**
449         * Indicates whether the provider is allowed is allowed to perform automatic merges.
450         */
451        NO_AUTO_MERGE("no-auto-merge"), //$NON-NLS-1$
452
453        /**
454         * Indicates whether the provider is allowed to checkout files for merging.
455         */
456        NO_CHECKOUT("no-checkout"), //$NON-NLS-1$
457
458        /**
459         * Indicates whether a checkin will be performed if the persistent state
460         * of the new version would be identical to that of the previous
461         * version. If this flag is not set, a checkin operation on an unchanged
462         * controllable resource will uncheckout that resource.
463         */
464        CHECKIN_IDENTICAL("checkin-identical"), //$NON-NLS-1$
465
466        /**
467         * Indicates whether a stream source should be updated with the current
468         * state of the workspace if the merge succeeds.
469         */
470        UPDATE_STREAM("update-stream"); //$NON-NLS-1$
471
472        private MergeFlag(String flagName) { _flagName = flagName; }
473
474        /**
475         * Returns a string representation of this flag suitable for diagnostics.
476         */
477        @Override
478        public String toString() { return _flagName; }
479
480        /**
481         * The string form of this flag.
482         */
483        private final String _flagName;
484    }
485
486
487    /**
488     * Merge the versions specified in the <code>sourceList</code> 
489     * into the appropriate target in this {@link Workspace}.
490     * The "target" of a particular source version is the version-controlled 
491     * member of the workspace identified by this Workspace
492     * that is associated with the version history for that version.
493     * <br>If the target is checked-in, and the source version is a descendant
494     * of the target version, the target is updated to the source version.
495     * <br>If the target is checked-in, and the source version is an ancestor
496     * of the target version, the target is left unmodified.
497     * <br>If the target is checked-out, or if the target version is on a different
498     * line of descent than the source version, the target is checked out
499     * (if it is not already checked-out), and the source version is either
500     * added to the {@link #MERGE_LIST} or the {@link #AUTO_MERGE_LIST} of the target.
501     * If a source version is added to the {@link #AUTO_MERGE_LIST}, the provider must
502     * have updated the content and controlled properties of the target to contain the results of merging
503     * the content and controlled properties of the source version with the content
504     * and controlled properties of the target at the time of the merge.
505     * <p>
506     * Postconditions:
507     * <li>(merge-sources): Each of the versions in the sourceList MUST have been
508     *  merged into their target in this Workspace.  If a source has no target 
509     *  in this Workspace, it is ignored.
510     * <li>(ancestor-version): If the merge target is a version-controlled resource
511     *  whose {@link #CHECKED_IN} version or {@link #CHECKED_OUT} version is the merge source
512     *  or is a descendant of the merge source, the merge target MUST NOT have been modified by the doMerge.
513     * <li>(descendant-version): If the merge target was a checked-in version-controlled resource
514     *  whose {@link #CHECKED_IN} version was an ancestor of the merge source,
515     *  a doUpdate operation MUST have been applied to the merge target.
516     * <li>(checked-out-for-merge): If the merge target was a checked-in version-controlled resource
517     *  whose {@link #CHECKED_IN} version was neither a descendant nor an ancestor of the merge source,
518     *  a doCheckout MUST have been applied to the merge target.
519     *  All arguments that could appear in a doCheckout request MUST have been used
520     *  as arguments to the doCheckout request.  
521     * <li>(update-merge-list): If the {@link #CHECKED_OUT} version of the merge target is not equal to
522     *  or a descendant of the merge source, the merge source MUST be added to either
523     *  the {@link #MERGE_LIST} or the {@link #AUTO_MERGE_LIST} of the merge target.
524     *  The merge target MUST appear in the result.  If a merge source has been added
525     *  to the {@link #AUTO_MERGE_LIST}, the controlled state of the merge target MUST have been modified
526     *  by the provider to reflect the result of a logical merge of the merge source and the merge target.
527     *  If a merge source has been added to the {@link #MERGE_LIST}, the controlled state of the merge target
528     *  MUST NOT have been modified by the provider.  If {@link MergeFlag#NO_AUTO_MERGE} is specified in the request,
529     *  the merge source MUST NOT have been added to the {@link #AUTO_MERGE_LIST}.
530     * <li>(merge-baseline): If {@link MergeFlag#NO_AUTO_MERGE} is specified and the merge target is a configuration
531     *  whose {@link #CHECKED_OUT} baseline is neither a descendant or an ancestor
532     *  of the source baseline, then the merge baseline MUST have been
533     *  added to the {@link #MERGE_LIST} of the configuration.
534     * <li>(auto-merge-baseline): If {@link MergeFlag#NO_AUTO_MERGE} is not specified and the merge target is a configuration
535     *  whose {@link #CHECKED_OUT} baseline is neither a descendant or an ancestor
536     *  of the source baseline, then the merge baseline MUST have been
537     *  added to the {@link #AUTO_MERGE_LIST} of the configuration, and
538     *  each version of that baseline MUST have been merged into the workspace 
539     *  of that configuration.
540     * <li>(update-version-controlled-folder-members): Same semantics as {@link #doUpdate}.
541     * 
542     * @param sourceList a list of {@link Resource} objects that
543     * identifies the versions to be merged.
544     * If a member of sourceList is an activity but not a stream,
545     * each version in the {@link Activity#ACTIVITY_VERSION_LIST} is a source version.
546     * If a member of sourceList is a stream, each version in the {@link Stream#VERSION_LIST}
547     * is a source version.
548     * If a member of sourceList is a version-controlled resource,
549     * the checked-in version of the member is a source version;
550     * if that version-controlled resource is a folder, all members
551     * of that folder are considered members of the sourceList.
552     * @param flags Boolean flags for doMerge.
553     * @param feedback Specifies optional feedback to the caller.
554     * @return a new proxy for this resource, whose properties are specified by feedback.
555     * @throws WvcmException An implementation may throw a single exception on the first error encountered,
556     * or may attempt to merge all of the source versions, with any errors accumulated in the
557     * {@link WvcmException#getNestedExceptions} list.
558     * <br>ReasonCode:
559     * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}:
560     * The resource identified by the <code>activity</code> argument must be an activity.
561     * <li>{@link ReasonCode#MUST_BE_CHECKED_IN}:
562     *  A version-controlled resource in the sourceList must be checked in.
563     * <li>{@link ReasonCode#CANNOT_MERGE_CHECKOUT_NOT_ALLOWED}:
564     *  If {@link MergeFlag#NO_CHECKOUT} is specified in the request,
565     *  it MUST be possible to perform the merge without checking out the merge target.
566     *  <li>All reason codes of {@link ControllableResource#doCheckout} apply to any checkout performed by the request.
567     *  
568     */
569    public <T extends Resource> Workspace doMerge(
570            ResourceList<T> sourceList,
571            MergeFlag[] flags,
572            Feedback feedback)
573    throws WvcmException;
574
575    /**
576     * Update the state of the appropriate target in this {@link Workspace}.
577     * The "target" of a particular source version is the version-controlled 
578     * member of the workspace identified by this Workspace
579     * that is associated with the version history for that version.
580     * <p>
581     * Postconditions:
582     * <li>(update-content-and-properties): The content and controlled properties of a target
583     *  MUST be the same as that of the version specified by the source version.
584     * <li>(update-version-controlled-folder-members): If the request modified the {@link #CHECKED_IN} version
585     *  of a version-controlled folder, then the version-controlled members
586     *  of that version-controlled folder MUST have been updated.  In particular:
587     *  <br>- A version-controlled bound member MUST have been deleted if its version history
588     *    is not identified by the {@link Folder#CHILD_LIST} of the new {@link #CHECKED_IN} version.
589     *  <br>- A version-controlled bound member for a given version history
590     *    MUST have been renamed if its binding name differs from the Binding name
591     *    for that version history in the {@link Folder#CHILD_LIST} of the new {@link #CHECKED_IN} version.
592     *  <br>- A new version-controlled bound member MUST have been created when a version history
593     *    is identified by the {@link Folder#CHILD_LIST} of the {@link #CHECKED_IN} version,
594     *    but there was no member of the version-controlled folder for that version history.
595     *    If a new version-controlled member is in a workspace that already has
596     *    a version-controlled resource for that version history, then the new version-controlled member
597     *    MUST be just a binding (i.e. another name for) that existing version-controlled resource.
598     *    Otherwise, the content and controlled properties of the new version-controlled member MUST have been initialized
599     *    to be those of the version specified for that version history by the request.
600     *    If no version is specified for that version history by the request, the version selected is provider defined.
601     * <li>(set-baseline-controlled-folder-members): If the request updated the {@link #CHECKED_IN} property
602     *  of a configuration to identify a new baseline, then each version-controlled member of the {@link Configuration#ROOT_FOLDER}
603     *  of that configuration MUST have been updated so its {@link #CHECKED_IN} property identifies the
604     *  corresponding version in the {@link Baseline#VERSION_LIST} of that baseline.  In particular:
605     * <br>- A version-controlled member for a given version history MUST have been deleted
606     *  if there is no version for that version history in the {@link Baseline#VERSION_LIST} of the baseline.
607     * <br>- A version-controlled member for a given version history MUST have been renamed if its name
608     *  relative to the baseline-controlled folder is different from that of the version-controlled member
609     *  for that version history when the baseline was created.
610     * <br>- A new version-controlled member MUST have been created for each member of the {@link Baseline#VERSION_LIST} 
611     *  of the baseline for which there is no corresponding version-controlled member
612     *  in the baseline-controlled folder.  The name of that new member relative to the baseline-controlled folder is
613     *  the name of the version-controlled member for that version history when the baseline was created.
614     * <br>- A doUpdate request MUST have been applied to each version-controlled member
615     *  for a given version history whose {@link #CHECKED_IN} version is not the version
616     *  identified in the {@link Baseline#VERSION_LIST} of the baseline.
617     * <li> (update-streams): If the {@link MergeFlag#UPDATE_STREAM} is specified,
618     *  and if the merge succeeds, each stream in the sourceList is updated with
619     *  the current configuration of this workspace.
620     *  
621     * @param sourceList the list of resources specifying the versions whose target in this 
622     * workspace should be updated.  See the sourceList argument for {@link #doMerge}.
623     * @param feedback Specifies optional feedback to the caller.
624     * @return a new proxy for this resource, whose properties are specified by feedback.
625     * @throws WvcmException ReasonCode:
626     * <li>{@link ReasonCode#MUST_BE_CHECKED_IN}:
627     *  A version-controlled resource in the sourceList must be checked in.
628     * <li>{@link ReasonCode#NO_CHECKED_OUT_BASELINE_CONTROLLED_FOLDER_MEMBERS}:
629     *  If the target identifies a configuration, then all version-controlled members
630     *  of the {@link Configuration#ROOT_FOLDER} of that configuration MUST be checked-in.
631     */
632    public <T extends Resource> Workspace doUpdate(ResourceList<T> sourceList, Feedback feedback)
633    throws WvcmException;
634
635}