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    * © Copyright IBM Corporation 2004, 2008.  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.Map;
020    
021    import javax.wvcm.Feedback;
022    import javax.wvcm.Resource;
023    import javax.wvcm.Stream;
024    import javax.wvcm.WvcmException;
025    import javax.wvcm.PropertyNameList.PropertyName;
026    
027    import com.ibm.rational.wvcm.stp.StpActivity;
028    import com.ibm.rational.wvcm.stp.cc.CcFileAreaLockedCallback.CcFileAreaLockInfo;
029    import com.ibm.rational.wvcm.stpex.StpExEnumeration;
030    
031    /**
032     * <p>A proxy for a ClearCase view.  ClearCase "view" and WVCM "workspace"
033     * are equivalent terms for the same type of resource. 
034     * </p>
035     * <p>In this release, only ClearCase CCRC web views are supported.
036     * ClearCase dynamic and snapshot views are not currently supported.
037     * </p>
038     */
039    public interface CcView 
040        extends CcDirectory, javax.wvcm.Workspace
041    {
042        /** Values for view text mode */
043        enum TextMode implements StpExEnumeration {
044            
045            /**
046             * A transparent interop text mode. The line terminator for text files 
047             * is a single <code>NL</code> character. The view does not transform 
048             * text file line terminators in any way. This is the default text mode 
049             * if no value is set upon view creation.
050             */
051            TRANSPARENT("transparent"),
052            
053            /**
054             * An insert_cr interop text mode. The view converts <code>NL</code> line 
055             * terminators to the <code>CR NL</code> sequence when reading from a VOB,
056             * and <code>CR NL</code> line terminators to single <code>NL</code>
057             * characters when writing to the VOB.
058             */
059            INSERT_CR("insert-cr"),
060            
061            /**
062             * An nl_to_cr interop text mode. The view converts <code>NL</code> line
063             * terminators to <code>CR</code> characters when reading from a VOB, and
064             * <code>CR</code> line terminators to single <code>NL</code> characters
065             * wehn writing to the VOB.
066             */
067            NL_TO_CR("nl-to-cr"),
068            
069            /**
070             * A strip_cr interop text mode. The view converts <code>CR NL</code> line 
071             * terminators to <code>NL</code> when reading from a VOB, and <code>NL</code> 
072             * line terminators back to the <code>CR NL</code> sequence when writing to the VOB.
073             */
074            STRIP_CR("strip-cr");
075            
076            private String m_name;
077    
078            private TextMode(String name) { m_name = name; }
079    
080            /* (non-Javadoc)
081             * @see java.lang.Object#toString()
082             */
083            public String toString() { return m_name; }
084        }
085        
086        /** Flags for the <code>doSynchronizeFileAreaDb</code> method */
087        enum SynchronizeFileAreaDbFlag implements StpExEnumeration {
088            
089            /**
090             * Synchronize the view's client-side vob database with the
091             * correct information from the server. Specifying this flag
092             * requires a server connection.
093             */
094            FILE_AREA_VOB_DB("file-area-vob-db"),
095            
096            /**
097             * Synchronize the view's client-side modified files database
098             * so that it correctly reflects files that have been modified
099             * as a result of checkouts or hijacks. Specifying this flag
100             * does <i>not</i> require a server connection.
101             */
102            FILE_AREA_MODIFIED_FILES_DB("file-area-modified-files-db");
103        
104            private String m_name;
105    
106            private SynchronizeFileAreaDbFlag(String name) { m_name = name; }
107    
108            /* (non-Javadoc)
109             * @see java.lang.Object#toString()
110             */
111            public String toString() { return m_name; }
112        }
113        
114        /**
115         *<p>
116         * Binds a CcActivity proxy to a CqRecord proxy without making the
117         * activity the current one for this view.
118         * </p>
119         * <p>
120         * NOTE: Unlike most API methods, the optional property request will be executed
121         * on the returned StpActivity, not the CcView proxy on which the method
122         * was invoked.
123         * </p>
124         * 
125         * <code>act</code> can either be a CcActivity proxy or a CqRecord proxy.
126         * <p>
127         * If <code>act</code> is a CcActivity proxy and the associated project is
128         * not CQ enabled, this operation simply executes the provided property
129         * request -- if any.  If the project is CQ enabled, it additionally validates
130         * that the bound CQ record is in an active state.
131         * </p>
132         * <p>
133         * If <code>act</code> is a CqRecord proxy, this operation is more
134         * involved.  First, <code>act</code> is automatically transitioned to an
135         * active state.  If this transition involves required fields, the caller
136         * may be prompted to provide values for those fields.  Next a CcActivity 
137         * resource is created in this view's stream and is bound to
138         * <code>act</code>.  
139         * </p>
140         * @param act the activity to work on - either a CqRecord or CcActivity
141         * @param feedback optional property request
142         * @return new proxy for the StpActivity, with requested properties
143         * @see javax.wvcm.Workspace#CURRENT_ACTIVITY
144         * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CC_ACTIVITY
145         * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CQ_RECORD
146         */
147        public StpActivity doBindActivity(StpActivity act, Feedback feedback) throws WvcmException;
148    
149        /**
150         * <p>Create a new ClearCase web view based on this CcView proxy.
151         * </p>
152         * <p>
153         * Preconditions:
154         * </p>
155         * <ul>
156         * <li>This proxy must have a file-based location representing the desired
157         * path of the root directory of the file area on the local machine.
158         * The directory must not yet exist.</li>
159         * <li>The location's leaf name (the directory name) will be used as
160         * the view tag of the new view.  A view having that view-tag must not
161         * already exist.</li>
162         * <li>To create a view associated with a UCM stream, specify that stream
163         * by setting this view proxy's STREAM property.</li>
164         * </ul>
165         * <p>
166         * Postconditions:
167         * </p>
168         * <ul>
169         * <li>A ClearCase web view is created, with the view tag
170         * and local file area as described above.</li>
171         * <li>If the view proxy's STREAM property was set, the view will be
172         * associated with that stream.</li>
173         * <li>If the view proxy's VIEW_TAG_STRING property was set, the view will
174         * be assigned that tag.  Otherwise, the file area's root directory name
175         * will be used.</li>
176         * </ul>
177         * @throws WvcmException if the preconditions are not met, or if there is an
178         * error creating the view. 
179         */
180        public CcView doCreateCcWebView(Feedback feedback) throws WvcmException;
181    
182        /**
183         * <p>Upgrade this web view's file area.</p>
184         * <p>Preconditions:</p>
185         * <ul>
186         * <li>This web view's file area schema version must be older than the
187         * version supported by the currently running CM API file area management
188         * code.
189         * </li>
190         * </ul>
191         * <p>Postconditions:</p>
192         * <ul>
193         * <li>This web view's file area schema will be upgraded to the currently
194         * supported version.</li>
195         * </ul>
196         * <p>This operation has no effect on non-web views, and on web views that
197         * are already compatible.
198         * </p>
199         * @throws WvcmException if the preconditions are not met, or if there is an
200         * error upgrading the file area. 
201         */
202        public CcView doUpgradeFileArea(Feedback feedback) throws WvcmException;
203    
204        /**
205         * Work on the specified activity in this CC view.
206         * <code>act</code> can either be a CcActivity proxy or a CqRecord proxy.
207         * <p>
208         * If <code>act</code> is a CcActivity proxy and the associated project is
209         * not CQ enabled, this operation simply makes it the current activity 
210         * in this view.  If the project is CQ enabled, it additionally validates 
211         * that the bound CQ record is in an active state.
212         * </p>
213         * <p>
214         * If <code>act</code> is a CqRecord proxy, this operation is more
215         * involved.  First, <code>act</code> is automatically transitioned to an
216         * active state.  If this transition involves required fields, the caller
217         * may be prompted to provide values for those fields.  Next a CcActivity 
218         * resource is created in this view's stream and is bound to
219         * <code>act</code>.  Finally, it makes the new CC activity resource the
220         * current activity in this view.
221         * </p>
222         * @param act the activity to work on - either a CqRecord or CcActivity
223         * @param feedback optional property request
224         * @return new proxy for this view, with requested properties
225         * @see javax.wvcm.Workspace#CURRENT_ACTIVITY
226         * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CC_ACTIVITY
227         * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CQ_RECORD
228         */
229        public CcView doWorkOnActivity(StpActivity act, Feedback feedback) throws WvcmException;
230    
231        /**
232         * <p>
233         * Transitions the specified activity to the default completed state.
234         * <code>act</code> can either be a CcActivity proxy or a CqRecord proxy.
235         * </p>
236         * <p>
237         * NOTE: Unlike most API methods, the optional property request will be executed
238         * on the returned StpActivity, not the CcView proxy on which the method
239         * was invoked.
240         * </p>
241         * <p>Preconditions:</p>
242         * <ul>
243         * <li><code>act</code> is a bound CqRecord/CcActivity pair in a CQ-enabled
244         * context.</li>
245         * </ul>
246         * <p>Postconditions:</p>
247         * <ul>
248         * <li>If <code>act</code>'s CcActivity has checkouts, the operation is
249         * cancelled and there is no change to the activity.</li>
250         * <li>Transitions <code>act</code>'s CqRecord to the default completed state. 
251         * If this transition involves required fields, the caller may be prompted 
252         * to provide values for those fields.</li>
253         * <li>Unsets <code>act</code>'s CcActivity from all views'
254         * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} property.</li>
255         * </ul>
256         * @param act the activity to finish
257         * @param feedback optional property request for the activity
258         * @return new proxy for the activity, with requested properties
259         * @throws WvcmException if the preconditions are not met.
260         */
261        public StpActivity doFinishActivity(StpActivity act, Feedback feedback) 
262            throws WvcmException;
263    
264        /**
265         * <p>
266         * Synchronize this file area's local databases to accurately reflect the 
267         * current state of the file area. The databases available to synchronize are:
268         * </p>
269         * <ul>
270         * <li>VOB database: This contains the loaded vobs in the view. A server connection
271         * is required to synchronize this database.</li>
272         * <li>Modified files database: This contains the checkouts and hijacks in the view.
273         * A server connection <i>not</i> required to synchronize this database.</li>
274         * </ul>
275         * @param flags array of flags which specify the databases to synchronize.
276         * @param feedback optional property request for the view
277         * @return A new proxy for this resource, whose properties are specified by feedback.
278         * @throws WvcmException
279         */
280        public CcView doSynchronizeFileAreaDb(SynchronizeFileAreaDbFlag[] flags, Feedback feedback) 
281            throws WvcmException;
282    
283        /**
284         * Register this local web view's file area in the local file area registry.
285         * Web views are registered automatically when created, but may need to be
286         * re-registered if the registry is accidentally deleted, etc.
287         */
288        public void registerFileArea() throws WvcmException;
289    
290        /**
291         * Remove this local web view's file area from the local file area registry.
292         * Once removed, this view will no longer show up when listing local views.
293         * @see com.ibm.rational.wvcm.stp.cc.CcProvider#getClientViewList(javax.wvcm.PropertyRequestItem.PropertyRequest)
294         */
295        public void unregisterFileArea() throws WvcmException;
296    
297        /**
298         * If this is a local web view, the URL of the CM Server where this
299         * view's view database resides.
300         */
301        PropertyName<String> SERVER_URL =
302            new PropertyName<String>(PROPERTY_NAMESPACE, "server-url");
303       
304        /**
305         * Get the value of this proxy's {@link #SERVER_URL} property.
306         * @return this view's server URL
307         * @throws WvcmException if this proxy doesn't define a value for this property.
308         */
309        public String getServerUrl() throws WvcmException;
310    
311        /**
312         * Change the URL used to connect to the CM server on which this web view resides.
313         * Note: Web views cannot be moved from one CM server to another.
314         * Use this method only to change the server URL, not to try to connect to
315         * a different server.
316         * <p>
317         * This may be necessary if, for example:
318         * <ul>
319         * <li>The CM server administrator changes the CM server's port number</li>
320         * <li>The client needs a secure HTTP connection to the CM server:
321         *     "https://..." instead of "http://..."</li>
322         * <li>The CM server is moved to a different internet subdomain</li>
323         * </ul>
324         * @param updatedUrl the updated URL of this web view's CM server
325         * @throws WvcmException
326         */
327        public void updateServerUrl(String updatedUrl) throws WvcmException;
328    
329        /**
330         * This view's view tag as a string.
331         */
332        PropertyName<String> VIEW_TAG_STRING =
333            new PropertyName<String>(PROPERTY_NAMESPACE, "view-tag-string");
334      
335        /**
336         * Get the value of this proxy's {@link #VIEW_TAG_STRING} property.
337         * @return this view's view tag
338         * @throws WvcmException if this proxy doesn't define a value for this property.
339         */
340        public String getViewTagString() throws WvcmException;
341    
342        /**
343         * Set the value of this view's {@link #VIEW_TAG_STRING} property.
344         * This property may only be set at view creation time.
345         * @param viewTag the view tag for the new view
346         */
347        void setViewTagString(String viewTag);
348       
349        /**
350         * This view's view tag as a {@link CcViewTag} resource.
351         */
352        PropertyName<CcViewTag> VIEW_TAG =
353            new PropertyName<CcViewTag>(PROPERTY_NAMESPACE, "view-tag");
354       
355        /**
356         * Get the value of this proxy's {@link #VIEW_TAG} property.
357         * @return this view's view tag
358         * @throws WvcmException if this proxy doesn't define a value for this property.
359         */
360        public CcViewTag getViewTag() throws WvcmException;
361       
362        /**
363         * Whereas a CcView resource's {@link javax.wvcm.Folder#CHILD_MAP} property
364         * returns the root directories of <i>all</i> VOBs, LOADED_CHILD_MAP only
365         * returns the root directories of VOBs that are partially or fully loaded
366         * in this view. 
367         */
368        PropertyName<Map<String,Resource>> LOADED_CHILD_MAP =
369            new PropertyName<Map<String,Resource>>(PROPERTY_NAMESPACE, "loaded-child-map");
370       
371        /**
372         * Get the value of this proxy's {@link #LOADED_CHILD_MAP} property.
373         * @return this view's loaded child map
374         * @throws WvcmException if this proxy doesn't define a value for this property.
375         */
376        public Map<String,Resource> getLoadedChildMap() throws WvcmException;
377    
378        /**
379         * This view's file area root directory on the local machine.
380         * The value of this property will be null if this is not a web view,
381         * or if it does not have a file area on the local machine.
382         */
383        PropertyName<File> FILE_AREA_ROOT_DIRECTORY =
384            new PropertyName<File>(PROPERTY_NAMESPACE, "file-area-root-directory");
385       
386        /**
387         * Returns the value of the {@link #FILE_AREA_ROOT_DIRECTORY} property.
388         * @return This view's copy area root directory, or null if it has
389         *         no copy area on the local machine
390         * @throws WvcmException if this property is not defined by this proxy.
391         */
392        public File getFileAreaRootDirectory() throws WvcmException;
393    
394        /**
395         * Is this view's local file area schema version older than the version
396         * supported by the running CM API file management code? If so, the file
397         * area needs to be upgraded before it can be used.
398         * 
399         * @see com.ibm.rational.wvcm.stp.cc.CcView#doUpgradeFileArea(Feedback)
400         */
401        PropertyName<Boolean> FILE_AREA_NEEDS_UPGRADE =
402            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "file-area-needs-upgrade");
403       
404        /**
405         * Get the value of this view's {@link #FILE_AREA_NEEDS_UPGRADE} property.
406         * @return true if this view's local file area needs upgrading; false otherwise.
407         * @throws WvcmException if this property is not defined by this proxy.
408         */
409        boolean getFileAreaNeedsUpgrade() throws WvcmException;
410       
411        /**
412         * Is this view associated with a UCM stream?.
413         */
414        PropertyName<Boolean> IS_UCM_VIEW =
415            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-ucm-view");
416       
417        /**
418         * Get the value of this view's {@link #IS_UCM_VIEW} property.
419         * @return true if this view represents a UCM view; false otherwise.
420         * @throws WvcmException if this property is not defined by this proxy.
421         */
422        boolean getIsUcmView() throws WvcmException;
423       
424        /**
425         * This view's config spec.
426         */
427        PropertyName<CcConfigSpec> CONFIG_SPEC =
428            new PropertyName<CcConfigSpec>(PROPERTY_NAMESPACE, "config-spec");
429        
430        /**
431         * Get the value of this view's {@link #CONFIG_SPEC} property.
432         * @return this view's config spec as a CcConfigSpec instance
433         */
434        CcConfigSpec getConfigSpec() throws WvcmException;
435    
436        /**
437         * Set the value of this view's {@link #CONFIG_SPEC} property.
438         * @param configSpec the new config spec for this view
439         */
440        void setConfigSpec(CcConfigSpec configSpec);
441        
442        /**
443         * The text mode of the view. The text mode specifies the line
444         * terminator sequence for text files in the view. If no value is
445         * set upon view creation, defaults to {@link TextMode#TRANSPARENT}.
446         */
447        PropertyName<TextMode> TEXT_MODE =
448            new PropertyName<TextMode>(PROPERTY_NAMESPACE, "text-mode");
449        
450        /**
451         * Get the value of this view's {@link #TEXT_MODE} property.
452         * @return enumeration value representing this view's text mode.
453         * @throws WvcmException if this proxy doesn't define a value for this property.
454         */
455        TextMode getTextMode() throws WvcmException;
456        
457        /**
458         * Set the value of this view's {@link #TEXT_MODE} property. This
459         * property may only be set at view creation time.
460         * @param textMode the text mode of the view.
461         */
462        void setTextMode(TextMode textMode);
463        
464        /**
465         * Break a file area lock on this view with the given lock info.
466         * @param lockInfo information about the lock
467         * @return true if the lock was broken; false otherwise
468         * @throws WvcmException if a problem occurred breaking the lock
469         */
470        boolean breakFileAreaLock(CcFileAreaLockInfo lockInfo) throws WvcmException;
471        
472        /**
473         * CcViewAccessInfo object contains the supported view access properties.
474         */
475        public static final PropertyName<CcViewAccessInfo> VIEW_ACCESS_INFO =
476            new PropertyName<CcViewAccessInfo>(PROPERTY_NAMESPACE, "view-access-info");
477    
478        /**
479         * Returns the value of this proxy's {@link #VIEW_ACCESS_INFO} property.
480         * 
481         * @return the CcViewAccessInfo object.
482         * @throws WvcmException
483         *             if this proxy doesn't define a value for this property.
484         */
485        public CcViewAccessInfo getViewAccessInfo() throws WvcmException;
486    
487        /**
488         * <p>
489         * The permissions applied to this resource.
490         * </p>
491         */
492        public static final PropertyName<CcPermissions> PERMISSIONS =
493            new PropertyName<CcPermissions>(PROPERTY_NAMESPACE, "cc-permissions");
494        
495        /**
496         * Returns the value of this proxy's {@link #PERMISSIONS} property.
497         * 
498         * @return A permissions object from which specific permissions 
499         *         information can be extracted.
500         * @throws WvcmException
501         *             if this proxy doesn't define a value for this property.
502         */
503        public CcPermissions getPermissions() throws WvcmException;
504    
505        /**
506         * Does this view have non-shareable derived objects?
507         */
508        public static final PropertyName<Boolean> IS_EXPRESS =
509            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-express");
510        
511        /**
512         * Returns the value of this proxy's {@link #IS_EXPRESS} property.
513         * 
514         * @return true if this view has non-shareable DOs; false otherwise.
515         * @throws WvcmException
516         *             if this proxy doesn't define a value for this property.
517         */
518        public Boolean getIsExpress() throws WvcmException;
519    
520        /**
521         * Are this view's permissions valid?
522         */
523        public static final PropertyName<Boolean> ARE_PERMISSIONS_VALID =
524            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "are-permissions-valid");
525        
526        /**
527         * Returns the value of this proxy's {@link #ARE_PERMISSIONS_VALID} property.
528         * 
529         * @return true if this view's permissions are valid; false otherwise.
530         * @throws WvcmException
531         *             if this proxy doesn't define a value for this property.
532         */
533        public Boolean getArePermissionsValid() throws WvcmException;
534    
535        /**
536         * Is this view read-only?
537         */
538        public static final PropertyName<Boolean> IS_READ_ONLY =
539            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-read-only");
540        
541        /**
542         * Returns the value of this proxy's {@link #IS_READ_ONLY} property.
543         * 
544         * @return true if this view is read-only; false otherwise.
545         * @throws WvcmException
546         *             if this proxy doesn't define a value for this property.
547         */
548        public Boolean getIsReadOnly() throws WvcmException;
549        
550         /**
551         * Set the {@link #STREAM} property.
552         * 
553         * @param stream the {@link Stream} object that
554         * identifies the {@link #STREAM} for this Workspace.
555         * @see #getStream
556         */
557        public void setStream(Stream stream);
558    }