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