001    /*
002    * file CcView.java
003    *
004    * Licensed Materials - Property of IBM
005    * Restricted Materials of IBM
006    * 
007    * com.ibm.rational.wvcm.stp.cc.CcView
008    *
009    * (C) Copyright IBM Corporation 2004, 2011.  All Rights Reserved. 
010    * Note to U.S. Government Users Restricted Rights:  Use, duplication or  
011    * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp. 
012    */
013    
014    package com.ibm.rational.wvcm.stp.cc;
015    
016    import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017    
018    import java.io.File;
019    import java.util.List;
020    import java.util.Map;
021    
022    import javax.wvcm.Feedback;
023    import javax.wvcm.Resource;
024    import javax.wvcm.ResourceList;
025    import javax.wvcm.Stream;
026    import javax.wvcm.WvcmException;
027    import javax.wvcm.PropertyNameList.PropertyName;
028    
029    import com.ibm.rational.wvcm.stp.StpActivity;
030    import com.ibm.rational.wvcm.stp.cc.CcFileAreaLockedCallback.CcFileAreaLockInfo;
031    import com.ibm.rational.wvcm.stp.cc.CcViewTag.ViewType;
032    import com.ibm.rational.wvcm.stpex.StpExEnumeration;
033    
034    /**
035     * <p>A proxy for a ClearCase view.  ClearCase "view" and WVCM "workspace"
036     * are equivalent terms for the same type of resource. 
037     * </p>
038     * <p>As of the ClearCase 8.0 release, CM API supports web views and dynamic
039     * views.  ClearCase snapshot views are not currently supported.
040     * </p>
041     */
042    public interface CcView 
043        extends CcDirectory, javax.wvcm.Workspace
044    {
045        /** Values for view text mode */
046        enum TextMode implements StpExEnumeration {
047            
048            /**
049             * A transparent interop text mode. The line terminator for text files 
050             * is a single <code>NL</code> character. The view does not transform 
051             * text file line terminators in any way. This is the default text mode 
052             * if no value is set upon view creation.
053             */
054            TRANSPARENT("transparent"),
055            
056            /**
057             * An insert_cr interop text mode. The view converts <code>NL</code> line 
058             * terminators to the <code>CR NL</code> sequence when reading from a VOB,
059             * and <code>CR NL</code> line terminators to single <code>NL</code>
060             * characters when writing to the VOB.
061             */
062            INSERT_CR("insert_cr"),
063            
064            /**
065             * An nl_to_cr interop text mode. The view converts <code>NL</code> line
066             * terminators to <code>CR</code> characters when reading from a VOB, and
067             * <code>CR</code> line terminators to single <code>NL</code> characters
068             * wehn writing to the VOB.
069             */
070            NL_TO_CR("cvt_nl_to_cr"),
071            
072            /**
073             * A strip_cr interop text mode. The view converts <code>CR NL</code> line 
074             * terminators to <code>NL</code> when reading from a VOB, and <code>NL</code> 
075             * line terminators back to the <code>CR NL</code> sequence when writing to the VOB.
076             */
077            STRIP_CR("strip_cr");
078            
079            private String m_name;
080    
081            private TextMode(String name) { m_name = name; }
082    
083            /* (non-Javadoc)
084             * @see java.lang.Object#toString()
085             */
086            public String toString() { return m_name; }
087        }
088        
089        /** Flags for the <code>doSynchronizeFileAreaDb</code> method */
090        enum SynchronizeFileAreaDbFlag implements StpExEnumeration {
091            
092            /**
093             * Synchronize the web view's client-side vob database with the
094             * correct information from the server. Specifying this flag
095             * requires a server connection.
096             */
097            FILE_AREA_VOB_DB("file-area-vob-db"),
098            
099            /**
100             * Synchronize the web view's client-side modified files database
101             * so that it correctly reflects files that have been modified
102             * as a result of checkouts or hijacks. Specifying this flag
103             * does <i>not</i> require a server connection.
104             */
105            FILE_AREA_MODIFIED_FILES_DB("file-area-modified-files-db");
106        
107            private String m_name;
108    
109            private SynchronizeFileAreaDbFlag(String name) { m_name = name; }
110    
111            /* (non-Javadoc)
112             * @see java.lang.Object#toString()
113             */
114            public String toString() { return m_name; }
115        }
116        
117        /** Flags for the doFindMergeCandidates methods */
118        enum FindmergeFlag {
119            
120            /**
121             * Just search the directory itself when searching for merge candidates,
122             * do not search the child elements
123             */
124            DIRECTORY_ONLY,        
125            
126            /**
127             * Follow VOB symbolic links when searching for merge candidates
128             */
129            FOLLOW_SYMLINKS                
130        }
131        
132        /**
133         *<p>
134         * Binds a CcActivity proxy to a CqRecord proxy without making the
135         * activity the current one for this view.
136         * </p>
137         * <p>
138         * NOTE: Unlike most API methods, the optional property request will be executed
139         * on the returned StpActivity, not the CcView proxy on which the method
140         * was invoked.
141         * </p>
142         * 
143         * <code>act</code> can either be a CcActivity proxy or a CqRecord proxy.
144         * <p>
145         * If <code>act</code> is a CcActivity proxy and the associated project is
146         * not CQ enabled, this operation simply executes the provided property
147         * request -- if any.  If the project is CQ enabled, it additionally validates
148         * that the bound CQ record is in an active state.
149         * </p>
150         * <p>
151         * If <code>act</code> is a CqRecord proxy, this operation is more
152         * involved.  First, <code>act</code> is automatically transitioned to an
153         * active state.  If this transition involves required fields, the caller
154         * may be prompted to provide values for those fields.  Next a CcActivity 
155         * resource is created in this view's stream and is bound to
156         * <code>act</code>.  
157         * </p>
158         * @param act the activity to work on - either a CqRecord or CcActivity
159         * @param feedback optional property request
160         * @return new proxy for the StpActivity, with requested properties
161         * @see javax.wvcm.Workspace#CURRENT_ACTIVITY
162         * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CC_ACTIVITY
163         * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CQ_RECORD
164         */
165        public StpActivity doBindActivity(StpActivity act, Feedback feedback) throws WvcmException;
166    
167        /**
168         * <p>Create a new ClearCase web view based on this CcView proxy.
169         * </p>
170         * <p>
171         * Preconditions:
172         * </p>
173         * <ul>
174         * <li>This proxy must have a file-based location representing the desired
175         * path of the root directory of the file area on the local machine.
176         * The directory must not yet exist.</li>
177         * <li>The location's leaf name (the directory name) will be used as
178         * the view tag of the new view.  A view having that view-tag must not
179         * already exist.</li>
180         * <li>To create a view associated with a UCM stream, specify that stream
181         * by setting this view proxy's STREAM property.</li>
182         * </ul>
183         * <p>
184         * Postconditions:
185         * </p>
186         * <ul>
187         * <li>A ClearCase web view is created, with the view tag
188         * and local file area as described above.</li>
189         * <li>If the view proxy's STREAM property was set, the view will be
190         * associated with that stream.</li>
191         * <li>If the view proxy's VIEW_TAG_STRING property was set, the view will
192         * be assigned that tag.  Otherwise, the file area's root directory name
193         * will be used.</li>
194         * </ul>
195         * @throws WvcmException if the preconditions are not met, or if there is an
196         * error creating the view. 
197         */
198        public CcView doCreateCcWebView(Feedback feedback) throws WvcmException;
199    
200        /**
201         * <p>Create a new ClearCase dynamic view based on this CcView proxy.
202         * </p>
203         * <p>
204         * Preconditions:
205         * </p>
206         * <ul>
207         * <li>The view proxy's VIEW_TAG_STRING property must be set
208         * to the desired view tag of the new view.  A view having that view 
209         * tag must not already exist.</li>
210         * <li>The view proxy's VIEW_STORAGE_PATH property must be set
211         * to the desired storage path for the new view unless a storage location
212         * is being used.
213         * <li>If a storage location is desired, rather than an explicit path.
214         * then the VIEW_STORAGE_LOCATION property must be set to that storage
215         * location.
216         * <li>To create a view associated with a UCM stream, specify that stream
217         * by setting this view proxy's STREAM property.</li>
218         * <li>The proxy's location is ignored for creation.</li>
219         * </ul>
220         * <p>
221         * Postconditions:
222         * </p>
223         * <ul>
224         * <li>A ClearCase dynamic view is created, with the view tag
225         * and storage path as described above.</li>
226         * <li>If the view proxy's STREAM property was set, the view will be
227         * associated with that stream.</li>
228         * 
229         * </ul>
230         * @throws WvcmException if the preconditions are not met, or if there is an
231         * error creating the view. 
232         */
233        public CcView doCreateCcDynamicView(Feedback feedback) throws WvcmException;
234        
235        /**
236         * <p>The rebase command reconfigures a stream by adding, dropping, or 
237         * replacing one or more of the stream's foundation baselines. The file and
238         * directory versions selected by those new baselines (and thus their 
239         * associated activities) then become visible in the stream's views.
240         * </p>
241         * <p>
242         * Preconditions:
243         * </p>
244         * <ul>
245         * <li>The baseline is not from the stream that is being rebased.</li>
246         * <li>The baseline is labeled. Baselines created by deliver operations are
247         * not labeled by default.</li>
248         * <li>Another rebase operation is not in progress.</li>
249         * <li>A deliver operation is not in progress.</li>
250         * </ul>
251         * Additional rules apply to integration streams and development
252         * streams in selecting a baseline:
253         * <ul>
254         * <li>An integration stream can be rebased only to a baseline created in 
255         * another project or to an imported or initial baseline of that project.</li>
256         * <li>A development stream can be rebased to a baseline that meets one 
257         * of the following criteria:
258         *      <ul>
259         *      <li>The baseline was created in its parent stream.</li>
260         *      <li>The baseline is in its parent stream's foundation.</li>
261         *      <li>The baseline is an ancestor of the development stream's parent
262         *       foundation baseline and created on the same stream as the parent's
263         *       foundation baseline.</li>
264         *      <li>The baseline was created in a stream other than its parent 
265         *       stream and is contained in its parent stream. A baseline is 
266         *       contained in another baseline if all changes in the first baseline
267         *       are included in the second baseline.</li> 
268         *      </ul>
269         * </li>
270         * </ul>
271         * <p>
272         * Postconditions:
273         * </p>
274         * <ul>
275         * <li>A rebase is started on the specified view. Use one of the other 
276         * methods to resume, complete, or cancel the rebase.</li>
277         * <li>The activity is set to the rebase activity.</li>
278         * <li>If <code>baselineList</code> is specified and those baselines meet 
279         * the preconditions above, the rebase will be started to those baselines.</li>
280         * <li>If <code>baselineList</code> is not specified, the rebase will be 
281         * started to the source stream's recommended baselines.</li>
282         * <li>If <code>doAutoMerge</code> is true, elements needing merge will 
283         * attempt to automatically merge on the server.</li> 
284         * </ul>
285         * 
286         * @param baselineList optional list of baselines to include
287         * @param doAutoMerge tells the rebase operation to attempt auto merges
288         * @param integrationListener optional listener to get feedback on operation
289         * @param updateListener optional listener to get feedback on view update 
290         * changes
291         * @param feedback optional property request
292         * @return new proxy to the view with requested properties
293         * 
294         * @throws WvcmException if there is an error starting the rebase operation
295         */
296        public CcView doStartRebase(
297                List<CcBaseline> baselineList,
298                boolean doAutoMerge,
299                CcListener integrationListener,
300                CcListener updateListener,
301                Feedback feedback) throws WvcmException;
302        
303        /**
304         * <p>
305         * Restarts a rebase operation from the point at which it has been 
306         * suspended. A rebase operation can be interrupted or when it encounters an
307         * external error or condition that requires more information. However, you
308         * cannot resume a rebase operation that has been successfully halted with
309         * the <code>CcView.doCancelRebase()</code> operation.
310         * </p>
311         * 
312         * @param doAutoMerge tells the rebase operation to attempt auto merges
313         * @param integrationListener optional listener to get feedback on operation
314         * @param updateListener optional listener to get feedback on view update 
315         * changes
316         * @param feedback optional property request
317         * @return new proxy to the view with requested properties
318         * @throws WvcmException if there is an error resuming the rebase operation
319         */
320        public CcView doResumeRebase(
321                boolean doAutoMerge,
322                CcListener integrationListener,
323                CcListener updateListener,
324                Feedback feedback) throws WvcmException;
325        
326    
327        /**
328         * <p>
329         * Completes a rebase operation taking the following actions:
330         * </p>
331         * <ul>
332         * <li>Resumes the rebase operation</li>
333         * <li>Verifies that needed merges were made</li>
334         * <li>Checks in any versions that are checked out</li>
335         * <li>Records changes in the change set for the rebase activity</li>
336         * </ul>
337         * 
338         * @param integrationListener optional listener to get feedback on operation
339         * @param updateListener optional listener to get feedback on view update 
340         * changes
341         * @param feedback optional property request
342         * @return new proxy to the view with requested properties
343         * @throws WvcmException if there is an error completing the 
344         * rebase operation
345         */
346        public CcView doCompleteRebase(
347                CcListener integrationListener, 
348                CcListener updateListener,            
349                Feedback feedback) throws WvcmException;      
350        
351        /**
352         * <p>
353         * Cancels a rebase operation and restores the stream's previous 
354         * configuration. Deletes the integration activity and any 
355         * versions created by the rebase operation that are not yet checked in. 
356         * </p>
357         * <p>
358         * Preconditions:
359         * </p>
360         * <ul>
361         * <li>None of the versions created in the integration activity can be
362         * checked in.</li>
363         * </ul>
364         * 
365         * @param integrationListener optional listener to get feedback on operation
366         * @param updateListener optional listener to get feedback on view update 
367         * changes
368         * @param feedback optional property request
369         * @return new proxy to the view with requested properties
370         * @throws WvcmException if there is an error canceling the 
371         * rebase operation
372         */
373        public CcView doCancelRebase(
374                CcListener integrationListener, 
375                CcListener updateListener,            
376                Feedback feedback) throws WvcmException;    
377    
378        /**
379         * <p>
380         * The deliver command lets you deliver work from a source stream to a 
381         * target stream in the same or a different project. This method delivers
382         * all activities in the stream that have changed since the last deliver 
383         * operation from the stream. The target stream is determined by the 
384         * <code>CcView</code> integration view passed to this method.
385         * </p>
386         * <p>
387         * Preconditions:
388         * </p>
389         * <ul>
390         * <li>A deliver operation is not currently in progress.</li>
391         * <li>A rebase operation is not currently in progress.</li>
392         * <li>The checkout states must match the project's UCM policies.</li>
393         * <li>Delivering to a non-default target stream is subject to 
394         * restrictions. Refer to the ClearCase cleartool deliver man page
395         * for details.</li>
396         * </ul>
397         * <p>
398         * Postconditions:
399         * </p>
400         * <ul>
401         * <li>A deliver is started on the specified view. Use one of the other 
402         * deliver methods to resume, complete, or cancel the deliver.</li>
403         * <li>The deliver operation creates a UCM integration activity and sets 
404         * it as the current activity in the integration view. This activity 
405         * records the change set for the deliver operation.</li>
406         * </ul>
407         * 
408         * @param integrationView the target view to deliver to
409         * @param doAutoMerge tells the deliver operation to attempt auto merges
410         * @param integrationListener optional listener to get feedback on operation
411         * @param feedback optional property request
412         * @return new proxy to the view with requested properties
413         * @throws WvcmException if there is an error starting the deliver operation
414         */
415        public CcView doStartDeliver(
416                CcView integrationView, 
417                boolean doAutoMerge,
418                CcListener integrationListener, 
419                Feedback feedback) throws WvcmException;    
420      
421        /**
422         * <p>
423         * Deliver the specified baselines from the source stream associated with 
424         * this view to the target stream associated with the specified integration 
425         * view. A development stream can deliver activities or baselines, but an
426         * integration stream can deliver only baselines. Refer to the ClearCase
427         * cleartool deliver man page for more details.
428         * </p>
429         * <p>
430         * Preconditions:
431         * </p>
432         * <ul>
433         * <li>A deliver operation is not currently in progress.</li>
434         * <li>A rebase operation is not currently in progress.</li>
435         * <li>The checkout states must match the project's UCM policies.</li>
436         * <li>Delivering to a non-default target stream is subject to 
437         * restrictions. Refer to the ClearCase cleartool deliver man page
438         * for details.</li>
439         * </ul>
440         * <p>
441         * Postconditions:
442         * </p>
443         * <ul>
444         * <li>A deliver is started on the specified view. Use one of the other 
445         * deliver methods to resume, complete, or cancel the deliver.</li>
446         * <li>The deliver operation creates a UCM integration activity and sets 
447         * it as the current activity in the integration view. This activity 
448         * records the change set for the deliver operation.</li>
449         * </ul>
450         * 
451         * @param integrationView the target view to deliver to
452         * @param baselineList list of baselines to deliver
453         * @param doAutoMerge tells the deliver operation to attempt auto merges
454         * @param integrationListener optional listener to get feedback on operation
455         * @param feedback optional property request
456         * @return new proxy to the view with requested properties
457         * @throws WvcmException if there is an error starting the deliver operation
458         */
459        public CcView doStartDeliverBaselines(            
460                CcView integrationView,
461                ResourceList<CcBaseline> baselineList,
462                boolean doAutoMerge,
463                CcListener integrationListener, 
464                Feedback feedback) throws WvcmException; 
465        
466        /**
467         * <p>
468         * Deliver the specified activities from the source stream associated with 
469         * this view to the target stream associated with the specified integration 
470         * view. The list of activities must be self-consistent: the 
471         * activities specified must not depend on the inclusion of any unspecified 
472         * activities. Refer to the ClearCase cleartool deliver man page for more
473         * details.
474         * </p>
475         * <p>
476         * Preconditions:
477         * </p>
478         * <ul>
479         * <li>A deliver operation is not currently in progress.</li>
480         * <li>A rebase operation is not currently in progress.</li>
481         * <li>The list of activities must be self-consistent.</li>
482         * <li>The checkout states must match the project's UCM policies.</li>
483         * <li>Delivering to a non-default target stream is subject to 
484         * restrictions. Refer to the ClearCase cleartool deliver man page
485         * for details.</li>
486         * </ul>
487         * <p>
488         * Postconditions:
489         * </p>
490         * <ul>
491         * <li>A deliver is started on the specified view. Use one of the other 
492         * deliver methods to resume, complete, or cancel the deliver.</li>
493         * <li>The deliver operation creates a UCM integration activity and sets 
494         * it as the current activity in the integration view. This activity 
495         * records the change set for the deliver operation.</li>
496         * </ul>
497         * 
498         * @param integrationView the target view to deliver to
499         * @param activityList optional list of activities to deliver
500         * @param doAutoMerge tells the deliver operation to attempt auto merges
501         * @param integrationListener optional listener to get feedback on operation
502         * @param feedback optional property request
503         * @return new proxy to the view with requested properties
504         * @throws WvcmException if there is an error starting the deliver operation
505         * 
506         */
507        public CcView doStartDeliverActivities(            
508                CcView integrationView,
509                ResourceList<CcActivity> activityList,
510                boolean doAutoMerge,
511                CcListener integrationListener, 
512                Feedback feedback) throws WvcmException;   
513        
514        /**
515         * <p>
516         * In a MultiSite configuration where a team of developers works at a 
517         * remote site, the project's integration stream may be mastered at a 
518         * different replica than the developers' development streams. In this 
519         * situation, the developers cannot complete deliver operations to the 
520         * integration stream. When such a stream mastership situation is 
521         * detected, the deliver operation starts but no versions are merged. 
522         * Instead, the deliver operation is left in a posted state. You must 
523         * periodically find and complete posted deliver operations. The post 
524         * deliver command lets you do such the delivery work from a source 
525         * stream to a target stream in the same or a different project. This 
526         * method delivers all activities in the stream that have changed since 
527         * the last deliver operation from the stream. The target stream is 
528         * determined by the <code>Stream</code> targetStream passed to this 
529         * method.
530         * </p>
531         * <p>
532         * Preconditions:
533         * </p>
534         * <ul>
535         * <li>A deliver operation is not currently in progress.</li>
536         * <li>A rebase operation is not currently in progress.</li>
537         * <li>The checkout states must match the project's UCM policies.</li>
538         * <li>Delivering to a non-default target stream is subject to 
539         * restrictions. Refer to the ClearCase cleartool deliver man page
540         * for details.</li>
541         * </ul>
542         * <p>
543         * Postconditions:
544         * </p>
545         * <ul>
546         * <li>A deliver is started but no versions are merged. Instead, the 
547         * deliver operation is left in a posted state. You must periodically find
548         * and complete posted deliver operations.</li>
549         * </ul>
550         * 
551         * @param targetStream the target stream to deliver to
552         * @param integrationListener optional listener to get feedback on operation
553         * @param feedback optional property request
554         * @return new proxy to the view with requested properties
555         * @throws WvcmException if there is an error starting the deliver operation
556         */
557        public CcView doStartPostDeliver(
558                Stream targetStream, 
559                CcListener integrationListener, 
560                Feedback feedback) throws WvcmException;    
561      
562        /**
563         * <p>
564         * Post deliver the specified baselines from the source stream associated 
565         * with this view to the target stream. A development stream can deliver 
566         * activities or baselines, but an integration stream can deliver only 
567         * baselines. Refer to the ClearCase cleartool deliver man page for more 
568         * details.
569         * </p>
570         * <p>
571         * Preconditions:
572         * </p>
573         * <ul>
574         * <li>A deliver operation is not currently in progress.</li>
575         * <li>A rebase operation is not currently in progress.</li>
576         * <li>The checkout states must match the project's UCM policies.</li>
577         * <li>Delivering to a non-default target stream is subject to 
578         * restrictions. Refer to the ClearCase cleartool deliver man page
579         * for details.</li>
580         * </ul>
581         * <p>
582         * Postconditions:
583         * </p>
584         * <ul>
585         * <li>A deliver is started but no versions are merged. Instead, the 
586         * deliver operation is left in a posted state. You must periodically find
587         * and complete posted deliver operations.</li>
588         * </ul>
589         * 
590         * @param targetStream the target stream to deliver to
591         * @param baselineList list of baselines to deliver
592         * @param integrationListener optional listener to get feedback on operation
593         * @param feedback optional property request
594         * @return new proxy to the view with requested properties
595         * @throws WvcmException if there is an error starting the deliver operation
596         */
597        public CcView doStartPostDeliverBaselines(            
598                Stream targetStream, 
599                ResourceList<CcBaseline> baselineList,
600                CcListener integrationListener, 
601                Feedback feedback) throws WvcmException; 
602        
603        /**
604         * <p>
605         * Post deliver the specified activities from the source stream associated 
606         * with this view to the target stream associated with the specified 
607         * integration view. The list of activities must be self-consistent: the 
608         * activities specified must not depend on the inclusion of any unspecified 
609         * activities. Refer to the ClearCase cleartool deliver man page for more
610         * details.
611         * </p>
612         * <p>
613         * Preconditions:
614         * </p>
615         * <ul>
616         * <li>A deliver operation is not currently in progress.</li>
617         * <li>A rebase operation is not currently in progress.</li>
618         * <li>The list of activities must be self-consistent.</li>
619         * <li>The checkout states must match the project's UCM policies.</li>
620         * <li>Delivering to a non-default target stream is subject to 
621         * restrictions. Refer to the ClearCase cleartool deliver man page
622         * for details.</li>
623         * </ul>
624         * <p>
625         * Postconditions:
626         * </p>
627         * <ul>
628         * <li>A deliver is started but no versions are merged. Instead, the 
629         * deliver operation is left in a posted state. You must periodically find
630         * and complete posted deliver operations.</li>
631         * </ul>
632         * 
633         * @param targetStream the target stream to deliver to
634         * @param activityList optional list of activities to deliver
635         * @param integrationListener optional listener to get feedback on operation
636         * @param feedback optional property request
637         * @return new proxy to the view with requested properties
638         * @throws WvcmException if there is an error starting the deliver operation
639         * 
640         */
641        public CcView doStartPostDeliverActivities(            
642                Stream targetStream, 
643                ResourceList<CcActivity> activityList,
644                CcListener integrationListener, 
645                Feedback feedback) throws WvcmException;  
646        
647        /**
648         * <p>
649         * Resumes a deliver operation from the point at which it was suspended. 
650         * </p>
651         * 
652         * @param integrationView the target view to deliver to
653         * @param integrationListener optional listener to get feedback on operation
654         * @param feedback optional property request
655         * @return new proxy to the view with requested properties
656         * @throws WvcmException if there is an error resuming the deliver operation
657         */    
658        public CcView doResumeDeliver(
659                CcView integrationView,
660                CcListener integrationListener,
661                Feedback feedback) throws WvcmException;    
662    
663        /**
664         * <p>
665         * Resets a deliver operation in progress to use the new integration view 
666         * </p>
667         * 
668         * @param integrationView the new integration view
669         * @param integrationListener optional listener to get feedback on operation
670         * @param feedback optional property request
671         * @return new proxy to the view with requested properties
672         * @throws WvcmException if there is an error resuming the deliver operation
673         */     
674        public CcView doResetDeliver(
675                CcView integrationView,
676                CcListener integrationListener,
677                Feedback feedback) throws WvcmException;    
678    
679        /**
680         * <p>
681         * Complete in-progress deliver operation taking the following actions:
682         * </p>
683         * <ul>
684         * <li>Verify that all versions in the integration view have been 
685         * successfully merged and that merge conflicts have been resolved.</li>
686         * <li>Check in resulting versions in the integration view.</li>
687         * <li>Unset the integration activity in the integration view.</li>
688         * </ul>
689         * <p>  
690         * If unresolved merge conflicts exist, the deliver operation is suspended.
691         * </p>
692         * 
693         * @param integrationView the target view to deliver to
694         * @param integrationListener optional listener to get feedback on operation
695         * @param mergeElements optional list of client maintained 
696         * <code>CcMergeElement</code>s to allow the operation to cancel any 
697         * checkouts
698         * @param feedback optional property request
699         * @return new proxy to the view with requested properties
700         * @throws WvcmException if there is an error completing the deliver
701         * operation
702         */      
703        public CcView doCompleteDeliver(
704                CcView integrationView,
705                CcListener integrationListener,
706                CcMergeElement[] mergeElements,
707                Feedback feedback) throws WvcmException;
708        
709        /**
710         * <p>
711         * Halt a deliver operation in progress, returning the source and 
712         * destination streams to their states before the deliver operation began. 
713         * Note: This method cannot cancel a deliver operation after the completion
714         * phase has begun. See ClearCase cleartool deliver man page for details.
715         * </p>
716         * 
717         * @param integrationView the target view to deliver to
718         * @param integrationListener optional listener to get feedback on operation
719         * @param mergeElements optional list of client maintained 
720         * <code>CcMergeElement</code>s to allow the operation to cancel any 
721         * checkouts
722         * @param feedback optional property request
723         * @return new proxy to the view with requested properties
724         * @throws WvcmException if there is an error cancelling the deliver 
725         * operation
726         */
727        public CcView doCancelDeliver(
728                CcView integrationView,
729                CcListener integrationListener,
730                CcMergeElement[] mergeElements,
731                Feedback feedback) throws WvcmException;
732        
733        /**
734         * <p>
735         * Runs findmerge command in this view. Searches the specified elements for merge candidates using
736         * the specified VOB resource as a search criteria. The VOB resource can be either a branch type, or
737         * a label type, or a version. Flags further define the search criteria. 
738         * Found merge candidates are returned through the listener.
739         * </p> 
740         * 
741         * @param listener optional listener to get feedback on operation. 
742         * Note: although a listener is not required, that is the only way for a consumer of this method 
743         * to receive the results of the findmerge operation.
744         * @param flags array of flags which specify the behavior of the operation
745         * @param fromVobResource VOB resource to use as a search criteria; Legal argument types include
746         * CcBranchType, CcLabelType and CcVersion
747         * @param feedback optional property request
748         * @return new proxy to the view with requested properties
749         * @throws WvcmException if there is an error completing the findmerge operation 
750         *
751         * @return new proxy to the view with requested properties
752         * @throws WvcmException
753         */
754        public CcView doFindMergeCandidates(
755                CcFindmergeListener listener,
756                FindmergeFlag []flags,
757                CcVobResource fromVobResource,
758                List<CcFile> elements,
759                Feedback feedback) throws WvcmException;
760        
761        /**
762         * <p>
763         * Runs findmerge command in this view. The specified activities are used as the search criteria.
764         * Flags further define the search criteria. Found merge candidates are returned through the listener.
765         *
766         * </p> 
767         * 
768         * @param listener optional listener to get feedback on operation. 
769         * Note: although a listener is not required, that is the only way for a consumer of this method 
770         * to receive the results of the findmerge operation.
771         * @param flags array of flags which specify the behavior of the operation
772         * @param activities list of activities whose change sets to search for merge candidates
773         * @param feedback optional property request
774         * @return new proxy to the view with requested properties
775         * @throws WvcmException if there is an error completing the findmerge operation 
776         *
777         */
778        public CcView doFindMergeCandidatesFromChangeSets(
779                CcFindmergeListener listener,
780                FindmergeFlag []flags,
781                List<CcActivity> activities,
782                Feedback feedback) throws WvcmException;
783        
784        /**
785         * <p>Upgrade this web view's file area.</p>
786         * <p>Preconditions:</p>
787         * <ul>
788         * <li>This web view's file area schema version must be older than the
789         * version supported by the currently running CM API file area management
790         * code.
791         * </li>
792         * </ul>
793         * <p>Postconditions:</p>
794         * <ul>
795         * <li>This web view's file area schema will be upgraded to the currently
796         * supported version.</li>
797         * </ul>
798         * <p>This operation has no effect on non-web views, and on web views that
799         * are already compatible.
800         * </p>
801         * @throws WvcmException if the preconditions are not met, or if there is an
802         * error upgrading the file area. 
803         */
804        public CcView doUpgradeFileArea(Feedback feedback) throws WvcmException;
805    
806        /**
807         * Work on the specified activity in this CC view.
808         * <code>act</code> can either be a CcActivity proxy or a CqRecord proxy.
809         * <p>
810         * If <code>act</code> is a CcActivity proxy and the associated project is
811         * not CQ enabled, this operation simply makes it the current activity 
812         * in this view.  If the project is CQ enabled, it additionally validates 
813         * that the bound CQ record is in an active state.
814         * </p>
815         * <p>
816         * If <code>act</code> is a CqRecord proxy, this operation is more
817         * involved.  First, <code>act</code> is automatically transitioned to an
818         * active state.  If this transition involves required fields, the caller
819         * may be prompted to provide values for those fields.  Next a CcActivity 
820         * resource is created in this view's stream and is bound to
821         * <code>act</code>.  Finally, it makes the new CC activity resource the
822         * current activity in this view.
823         * </p>
824         * @param act the activity to work on - either a CqRecord or CcActivity
825         * @param feedback optional property request
826         * @return new proxy for this view, with requested properties
827         * @see javax.wvcm.Workspace#CURRENT_ACTIVITY
828         * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CC_ACTIVITY
829         * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CQ_RECORD
830         */
831        public CcView doWorkOnActivity(StpActivity act, Feedback feedback) throws WvcmException;
832    
833        /**
834         * <p>
835         * Transitions the specified activity to the default completed state.
836         * <code>act</code> can either be a CcActivity proxy or a CqRecord proxy.
837         * </p>
838         * <p>
839         * NOTE: Unlike most API methods, the optional property request will be executed
840         * on the returned StpActivity, not the CcView proxy on which the method
841         * was invoked.
842         * </p>
843         * <p>Preconditions:</p>
844         * <ul>
845         * <li><code>act</code> is a bound CqRecord/CcActivity pair in a CQ-enabled
846         * context.</li>
847         * </ul>
848         * <p>Postconditions:</p>
849         * <ul>
850         * <li>If <code>act</code>'s CcActivity has checkouts, the operation is
851         * cancelled and there is no change to the activity.</li>
852         * <li>Transitions <code>act</code>'s CqRecord to the default completed state. 
853         * If this transition involves required fields, the caller may be prompted 
854         * to provide values for those fields.</li>
855         * <li>Unsets <code>act</code>'s CcActivity from all views'
856         * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} property.</li>
857         * </ul>
858         * @param act the activity to finish
859         * @param feedback optional property request for the activity
860         * @return new proxy for the activity, with requested properties
861         * @throws WvcmException if the preconditions are not met.
862         */
863        public StpActivity doFinishActivity(StpActivity act, Feedback feedback) 
864            throws WvcmException;
865    
866        /**
867         * <p>
868         * Synchronize this web view file area's local databases to accurately reflect the 
869         * current state of the file area. The databases available to synchronize are:
870         * </p>
871         * <ul>
872         * <li>VOB database: This contains the loaded vobs in the web view. A server connection
873         * is required to synchronize this database.</li>
874         * <li>Modified files database: This contains the checkouts and hijacks in the web view.
875         * A server connection <i>not</i> required to synchronize this database.</li>
876         * </ul>
877         * @param flags array of flags which specify the databases to synchronize.
878         * @param feedback optional property request for the view
879         * @return A new proxy for this resource, whose properties are specified by feedback.
880         * @throws WvcmException
881         */
882        public CcView doSynchronizeFileAreaDb(SynchronizeFileAreaDbFlag[] flags, Feedback feedback) 
883            throws WvcmException;
884    
885        /**
886         * Register this local web view's file area in the local file area registry.
887         * Web views are registered automatically when created, but may need to be
888         * re-registered if the registry is accidentally deleted, etc.
889         */
890        public void registerFileArea() throws WvcmException;
891    
892        /**
893         * Remove this local web view's file area from the local file area registry.
894         * Once removed, this view will no longer show up when listing local views.
895         * @see com.ibm.rational.wvcm.stp.cc.CcProvider#getClientViewList(javax.wvcm.PropertyRequestItem.PropertyRequest)
896         */
897        public void unregisterFileArea() throws WvcmException;
898    
899        /**
900         * If this is a local web view, the URL of the CCRC WAN server where this
901         * web view's view database resides.
902         */
903        PropertyName<String> SERVER_URL =
904            new PropertyName<String>(PROPERTY_NAMESPACE, "server-url");
905       
906        /**
907         * Get the value of this proxy's {@link #SERVER_URL} property.
908         * @return this view's server URL
909         * @throws WvcmException if this proxy doesn't define a value for this property.
910         */
911        public String getServerUrl() throws WvcmException;
912    
913        /**
914         * Change the URL used to connect to the CCRC WAN server on which this web view resides.
915         * Note: Web views cannot be moved from one CCRC WAN server to another.
916         * Use this method only to change the server URL, not to try to connect to
917         * a different server.
918         * <p>
919         * This may be necessary if, for example:
920         * <ul>
921         * <li>The CCRC WAN server administrator changes the CCRC WAN server's port number</li>
922         * <li>The client needs a secure HTTP connection to the CCRC WAN server:
923         *     "https://..." instead of "http://..."</li>
924         * <li>The CCRC WAN server is moved to a different internet subdomain</li>
925         * </ul>
926         * @param updatedUrl the updated URL of this web view's CCRC WAN server
927         * @throws WvcmException
928         */
929        public void updateServerUrl(String updatedUrl) throws WvcmException;
930    
931        /**
932         * This view's uuid as a string.
933         */
934        PropertyName<String> VIEW_UUID_STRING =
935            new PropertyName<String>(PROPERTY_NAMESPACE, "view-uuid-string");
936      
937        /**
938         * Get the value of this proxy's {@link #VIEW_UUID_STRING} property.
939         * @return this view's uuid
940         * @throws WvcmException if this proxy doesn't define a value for this property.
941         */
942        public String getViewUuidString() throws WvcmException;
943        
944        /**
945         * This view's view tag as a string.
946         */
947        PropertyName<String> VIEW_TAG_STRING =
948            new PropertyName<String>(PROPERTY_NAMESPACE, "view-tag-string");
949      
950        /**
951         * Get the value of this proxy's {@link #VIEW_TAG_STRING} property.
952         * @return this view's view tag
953         * @throws WvcmException if this proxy doesn't define a value for this property.
954         */
955        public String getViewTagString() throws WvcmException;
956    
957        /**
958         * Set the value of this view's {@link #VIEW_TAG_STRING} property.
959         * This property may only be set at view creation time.
960         * @param viewTag the view tag for the new view
961         */
962        void setViewTagString(String viewTag);
963       
964        /**
965         * This view's view tag as a {@link CcViewTag} resource.
966         */
967        PropertyName<CcViewTag> VIEW_TAG =
968            new PropertyName<CcViewTag>(PROPERTY_NAMESPACE, "view-tag");
969       
970        /**
971         * Get the value of this proxy's {@link #VIEW_TAG} property.
972         * @return this view's view tag
973         * @throws WvcmException if this proxy doesn't define a value for this property.
974         */
975        public CcViewTag getViewTag() throws WvcmException;
976       
977        /** Kind of view to which this tag refers */
978        PropertyName<ViewType> VIEW_TYPE =
979            new PropertyName<ViewType>(PROPERTY_NAMESPACE,
980                                       "view-view-type");
981        
982        /**
983         * Returns the value  of this proxy's {@link #VIEW_TYPE} property.
984         * 
985         * @return Kind of view this tag refers to.
986         * @throws WvcmException
987         *             if this proxy doesn't define a value for this property.
988         */
989        ViewType getViewType() throws WvcmException;
990        
991        /**
992         * Whereas a CcView resource's {@link javax.wvcm.Folder#CHILD_MAP} property
993         * returns the root directories of <i>all</i> VOBs, LOADED_CHILD_MAP only
994         * returns the root directories of VOBs that are partially or fully loaded
995         * in this view (if this is a web view) or mounted (if this is a dynamic view).
996         */
997        PropertyName<Map<String,Resource>> LOADED_CHILD_MAP =
998            new PropertyName<Map<String,Resource>>(PROPERTY_NAMESPACE, "loaded-child-map");
999       
1000        /**
1001         * Get the value of this proxy's {@link #LOADED_CHILD_MAP} property.
1002         * @return this view's loaded child map
1003         * @throws WvcmException if this proxy doesn't define a value for this property.
1004         */
1005        public Map<String,Resource> getLoadedChildMap() throws WvcmException;
1006    
1007        /**
1008         * This web view's file area root directory on the local machine.
1009         * The value of this property will be null if it does not have 
1010         * a file area on the local machine.
1011         * Only supported for web views.
1012         */
1013        PropertyName<File> FILE_AREA_ROOT_DIRECTORY =
1014            new PropertyName<File>(PROPERTY_NAMESPACE, "file-area-root-directory");
1015       
1016        /**
1017         * Returns the value of the {@link #FILE_AREA_ROOT_DIRECTORY} property.
1018         * @return This view's copy area root directory, or null if it has
1019         *         no copy area on the local machine
1020         * @throws WvcmException if this property is not defined by this proxy.
1021         */
1022        public File getFileAreaRootDirectory() throws WvcmException;
1023    
1024        /**
1025         * Is this web view's local file area schema version older than the version
1026         * supported by the running CM API file management code? If so, the file
1027         * area needs to be upgraded before it can be used.
1028         * 
1029         * @see com.ibm.rational.wvcm.stp.cc.CcView#doUpgradeFileArea(Feedback)
1030         */
1031        PropertyName<Boolean> FILE_AREA_NEEDS_UPGRADE =
1032            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "file-area-needs-upgrade");
1033       
1034        /**
1035         * Get the value of this view's {@link #FILE_AREA_NEEDS_UPGRADE} property.
1036         * @return true if this view's local file area needs upgrading; false otherwise.
1037         * @throws WvcmException if this property is not defined by this proxy.
1038         */
1039        boolean getFileAreaNeedsUpgrade() throws WvcmException;
1040       
1041        /**
1042         * Is this view associated with a UCM stream?.
1043         */
1044        PropertyName<Boolean> IS_UCM_VIEW =
1045            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-ucm-view");
1046       
1047        /**
1048         * Get the value of this view's {@link #IS_UCM_VIEW} property.
1049         * @return true if this view represents a UCM view; false otherwise.
1050         * @throws WvcmException if this property is not defined by this proxy.
1051         */
1052        boolean getIsUcmView() throws WvcmException;
1053       
1054        /**
1055         * This view's config spec.
1056         */
1057        PropertyName<CcConfigSpec> CONFIG_SPEC =
1058            new PropertyName<CcConfigSpec>(PROPERTY_NAMESPACE, "config-spec");
1059        
1060        /**
1061         * Get the value of this view's {@link #CONFIG_SPEC} property.
1062         * @return this view's config spec as a CcConfigSpec instance
1063         */
1064        CcConfigSpec getConfigSpec() throws WvcmException;
1065    
1066        /**
1067         * Set the value of this view's {@link #CONFIG_SPEC} property.
1068         * @param configSpec the new config spec for this view
1069         */
1070        void setConfigSpec(CcConfigSpec configSpec);
1071        
1072        /**
1073         * Network region in which the dynamic view is registered.
1074         * Not supported for other view types.
1075         * This is a write only property; to determine the region for
1076         * an existing view, use the CcViewTag.REGISTRY_REGION property.
1077         */
1078        PropertyName<CcRegistryRegion> REGION =
1079            new PropertyName<CcRegistryRegion>(PROPERTY_NAMESPACE, "view-region");
1080        
1081        /**
1082         * Set the value of this view's {@link #REGION} property. This
1083         * property may only be set at view creation time.
1084         * This is a write only property.
1085         * If unspecified, the local host's network region will be used.
1086         * @param region network region in which to register the view
1087         */
1088        void setRegion(CcRegistryRegion region);
1089    
1090        /**
1091         * Should derived objects created in this view be shared and made
1092         * available for winkin by other views?
1093         * (Dynamic views only, not supported for other view types.)
1094         */
1095        PropertyName<Boolean> SHARE_DERIVED_OBJECTS =
1096            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "shared-dos");
1097        
1098        /**
1099         * Get the value of this view's {@link #SHARE_DERIVED_OBJECTS} property.
1100         * @return true if view creates shared derived objects, false otherwise
1101         */
1102        Boolean getShareDerivedObjects() throws WvcmException;
1103    
1104        /**
1105         * Set the value of this view's {@link #SHARE_DERIVED_OBJECTS} property. This
1106         * property may only be set at view creation time.
1107         * If unspecified, site-wide default is used.
1108         * If unspecified and no site-wide default, derived objects will be shared.
1109         * @param shareDerivedObjects true to make derived objects available for winkin
1110         * by other views, otherwise false
1111         */
1112        void setShareDerivedObjects(Boolean shareDerivedObjects);
1113        
1114        /**
1115         * The text mode of the view. The text mode specifies the line
1116         * terminator sequence for text files in the view. If no value is
1117         * set upon view creation, defaults to {@link TextMode#TRANSPARENT}.
1118         */
1119        PropertyName<TextMode> TEXT_MODE =
1120            new PropertyName<TextMode>(PROPERTY_NAMESPACE, "text-mode");
1121        
1122        /**
1123         * Get the value of this view's {@link #TEXT_MODE} property.
1124         * @return enumeration value representing this view's text mode.
1125         * @throws WvcmException if this proxy doesn't define a value for this property.
1126         */
1127        TextMode getTextMode() throws WvcmException;
1128        
1129        /**
1130         * Set the value of this view's {@link #TEXT_MODE} property. This
1131         * property may only be set at view creation time.
1132         * @param textMode the text mode of the view.
1133         */
1134        void setTextMode(TextMode textMode);
1135        
1136        /**
1137         * Break a file area lock on this web view with the given lock info.
1138         * @param lockInfo information about the lock
1139         * @return true if the lock was broken; false otherwise
1140         * @throws WvcmException if a problem occurred breaking the lock
1141         */
1142        boolean breakFileAreaLock(CcFileAreaLockInfo lockInfo) throws WvcmException;
1143        
1144        /**
1145         * CcViewAccessInfo object contains the supported view access properties.
1146         */
1147        public static final PropertyName<CcViewAccessInfo> VIEW_ACCESS_INFO =
1148            new PropertyName<CcViewAccessInfo>(PROPERTY_NAMESPACE, "view-access-info");
1149    
1150        /**
1151         * Returns the value of this proxy's {@link #VIEW_ACCESS_INFO} property.
1152         * 
1153         * @return the CcViewAccessInfo object.
1154         * @throws WvcmException
1155         *             if this proxy doesn't define a value for this property.
1156         */
1157        public CcViewAccessInfo getViewAccessInfo() throws WvcmException;
1158    
1159        /**
1160         * The storage location for a dynamic view, not supported for other
1161         * view types.
1162         */
1163        public static final PropertyName<CcStorageLocation> VIEW_STORAGE_LOCATION =
1164            new PropertyName<CcStorageLocation>(PROPERTY_NAMESPACE, "view-stgloc");
1165        
1166        /**
1167         * Set the value of this view's {@link #VIEW_STORAGE_LOCATION} property.
1168         * This property may only be set at view creation time.
1169         * It is a write-only property.
1170         * @param viewStorageLocation the storage location for the new view
1171         */
1172        void setViewStorageLocation(CcStorageLocation viewStorageLocation);
1173    
1174        /**
1175         * The storage path for a dynamic view, not supported for other
1176         * view types.
1177         */
1178        public static final PropertyName<String> VIEW_STORAGE_PATH =
1179            new PropertyName<String>(PROPERTY_NAMESPACE, "view-storage-path");
1180        
1181        /**
1182         * Returns the value of this proxy's {@link #VIEW_STORAGE_PATH} property.
1183         * 
1184         * @return path to the view storage
1185         * @throws WvcmException
1186         *             if this proxy doesn't define a value for this property.
1187         */
1188        public String getViewStoragePath() throws WvcmException;
1189       
1190        /**
1191         * Set the value of this view's {@link #VIEW_STORAGE_PATH} property.
1192         * This property may only be set at view creation time.
1193         * @param viewStoragePath the storage path for the new view
1194         */
1195        void setViewStoragePath(String viewStoragePath);
1196          
1197        /**
1198         * <p>
1199         * The permissions applied to this resource.
1200         * </p>
1201         */
1202        public static final PropertyName<CcPermissions> PERMISSIONS =
1203            new PropertyName<CcPermissions>(PROPERTY_NAMESPACE, "cc-permissions");
1204        
1205        /**
1206         * Returns the value of this proxy's {@link #PERMISSIONS} property.
1207         * 
1208         * @return A permissions object from which specific permissions 
1209         *         information can be extracted.
1210         * @throws WvcmException
1211         *             if this proxy doesn't define a value for this property.
1212         */
1213        public CcPermissions getPermissions() throws WvcmException;
1214    
1215        /**
1216         * Does this view have non-shareable derived objects?
1217         * This property is supported for dynamic views only.
1218         */
1219        public static final PropertyName<Boolean> IS_EXPRESS =
1220            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-express");
1221        
1222        /**
1223         * Returns the value of this proxy's {@link #IS_EXPRESS} property.
1224         * 
1225         * @return true if this view has non-shareable DOs; false otherwise.
1226         * @throws WvcmException
1227         *             if this proxy doesn't define a value for this property.
1228         */
1229        public Boolean getIsExpress() throws WvcmException;
1230    
1231        /**
1232         * Are this view's permissions valid?
1233         */
1234        public static final PropertyName<Boolean> ARE_PERMISSIONS_VALID =
1235            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "are-permissions-valid");
1236        
1237        /**
1238         * Returns the value of this proxy's {@link #ARE_PERMISSIONS_VALID} property.
1239         * 
1240         * @return true if this view's permissions are valid; false otherwise.
1241         * @throws WvcmException
1242         *             if this proxy doesn't define a value for this property.
1243         */
1244        public Boolean getArePermissionsValid() throws WvcmException;
1245    
1246        /**
1247         * Is this view read-only?
1248         */
1249        public static final PropertyName<Boolean> IS_READ_ONLY =
1250            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-read-only");
1251        
1252        /**
1253         * Returns the value of this proxy's {@link #IS_READ_ONLY} property.
1254         * 
1255         * @return true if this view is read-only; false otherwise.
1256         * @throws WvcmException
1257         *             if this proxy doesn't define a value for this property.
1258         */
1259        public Boolean getIsReadOnly() throws WvcmException;
1260        
1261         /**
1262         * Set the {@link #STREAM} property.
1263         * 
1264         * @param stream the {@link Stream} object that
1265         * identifies the {@link #STREAM} for this Workspace.
1266         * @see #getStream
1267         */
1268        public void setStream(Stream stream);
1269    
1270    }