001    /*
002     * file CcProvider.java
003     *
004     * Licensed Materials - Property of IBM
005     * Restricted Materials of IBM
006     * 
007     * com.ibm.rational.wvcm.stp.cc.CcProvider
008     *
009     * © 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    package com.ibm.rational.wvcm.stp.cc;
014    
015    import java.util.List;
016    
017    import javax.wvcm.PropertyRequestItem.PropertyRequest;
018    import javax.wvcm.ProviderFactory;
019    import javax.wvcm.ProviderFactory.Callback.Authentication;
020    import javax.wvcm.ResourceList;
021    import javax.wvcm.WorkspaceProvider;
022    import javax.wvcm.WvcmException;
023    
024    import com.ibm.rational.wvcm.stp.StpLocation;
025    import com.ibm.rational.wvcm.stp.StpProvider;
026    import com.ibm.rational.wvcm.stp.cc.CcMergeHandlingCallback.CheckinMergeHandling;
027    import com.ibm.rational.wvcm.stp.cc.CcView.TextMode;
028    
029    /**
030     * CcProvider is a ClearCase-specific extension of the generic
031     * javax.wvcm.Provider interface and the Rational-specific
032     * com.ibm.rational.wvcm.stp.StpProvider interface.
033     * <p>
034     * A CcProvider instance represents an individual user session with
035     * ClearCase on a particular remote CCRC WAN server or with ClearCase on the
036     * local machine.
037     * </p>
038     * <p>
039     * In addition to the methods defined by its superinterfaces, the CcProvider
040     * interface defines:
041     * <bl> 
042     * <li>Factory methods for constructing proxies
043     * for various ClearCase-specific resources. Note that there are many resource
044     * types where a ClearCase-specific interface exists for a standard WVCM
045     * interface.  For instance, CcFile is the ClearCase specialization of
046     * javax.wvcm.ControllableResource.
047     * </li>
048     * <li>Methods to register callbacks to notify your application of various
049     * ClearCase-related events - "file area lock" exceptions, HTTP SSL certificate
050     * exceptions, clearprompt events, etc.
051     * </li>
052     * <li>
053     * Methods to get information about the ClearCase environment - the default
054     * ClearCase registry region, whether MVFS is installed on the local machine, etc.
055     * </li>
056     * <li>
057     * Methods for listing locally available ClearCase resources, e.g., 
058     * {@link #getClientViewList}.
059     * </bl>
060     * </p>
061     * <p>
062     * NOTE: Starting in the 8.0 release, CM API providers can no
063     * longer support both CC and CQ operations in the same provider instance.
064     * In 7.1.x releases, a unified CM Server processed both CC and CQ operations.
065     * In 8.0, there are separate CC and CQ servers, and so you must instantiate
066     * a CqProvider to perform CQ operations and a CcProvider for CC operations.
067     * </p>
068     */
069    public interface CcProvider 
070        extends StpProvider, WorkspaceProvider
071    {
072        /**
073         * <p>The name of a CcProvider class whose instances support ClearCase access
074         * via an HTTP connection to a remote CCRC WAN server.  Use this
075         * "network provider" to work with ClearCase web views hosted on a
076         * particular server.
077         * </p>
078         * <p>Pass this name to <code>ProviderFactory.createProvider()</code> and cast
079         * the resulting <code>Provider</code> instance to <code>CcProvider</code>
080         * to access ClearCase-specific methods:
081         * <pre>
082         * CcProvider provider =
083         *     (CcProvider) ProviderFactory.createProvider(
084         *         CcProvider.NETWORK_PROVIDER_CLASS, ...);
085         * </pre>
086         * </p>
087         * @see ProviderFactory#createProvider(String, javax.wvcm.ProviderFactory.Callback)
088         */
089        String NETWORK_PROVIDER_CLASS =
090            "com.ibm.rational.stp.client.internal.cc.CcNetworkProviderImpl";
091    
092        /**
093         * <p>The name of a CcProvider class whose instances support direct acess to
094         * ClearCase installed on the local machine.  Use this "local provider" to
095         * work with ClearCase dynamic views on the local machine.
096         * </p>
097         * <p>Pass this name to <code>ProviderFactory.createProvider()</code> and cast
098         * the resulting <code>Provider</code> instance to <code>CcProvider</code>
099         * to access ClearCase-specific methods:
100         * <pre>
101         * CcProvider provider =
102         *     (CcProvider) ProviderFactory.createProvider(
103         *         CcProvider.LOCAL_PROVIDER_CLASS, ...);
104         * </pre>
105         * </p>
106         * @see ProviderFactory#createProvider(String, javax.wvcm.ProviderFactory.Callback)
107         */
108        String LOCAL_PROVIDER_CLASS =
109            "com.ibm.rational.stp.client.internal.cc.CcLocalProviderImpl";
110    
111        /**
112         * An extension of ProviderFactory.Callback that client call-backs can
113         * return to provide a Primary Group or Group List for a ClearCase login
114         */
115        public interface CcAuthentication extends Authentication {
116    
117            /**
118             * <p>ClearCase checks the user's "primary group" to determine whether
119             * the user can peform certain operations in a given VOB, such as
120             * creating a new CC element.
121             * </p>
122             * <p>On Windows operating systems, the user's primary group cannot be
123             * reliably determined, so it must be set explicitly here.
124             * </p>
125             * <p>On Unix, this setting may be used to override the user's primary
126             * group as specified in the /etc/password file or equivalent.
127             * </p>
128             * @return The primary group name to use performing ClearCase operations,
129             *         or <code>null</code> to use the default primary group
130             */
131            String getPrimaryGroupName();
132    
133            /**
134             * <p>ClearCase checks the user's group list (the list of OS groups
135             * to which the user belongs) to determine whether the user can peform
136             * certain operations in a given VOB.
137             * </p>
138             * <p>If the user belongs to more than 32 groups, in certain situations
139             * ClearCase may ignore some of those groups, causing the operation to
140             * fail unnecessarily.  In this case, use this setting to define which
141             * groups (up to 32) ClearCase should use.
142             * </p>
143             * @return The group list to use when performing ClearCase operations,
144             *         or empty list to use the default group list
145             */
146            List<String> getGroupList();
147        }
148    
149        /**
150         * Is this a local provider, as opposed to a network provider?
151         * @see CcProvider#LOCAL_PROVIDER_CLASS
152         * @see CcProvider#NETWORK_PROVIDER_CLASS
153         */
154        public boolean isLocalProvider();
155        
156        /**
157         * Is ClearCase with MVFS version 8.0.0.0 or greater installed on this client?
158         */
159        public boolean isMVFSInstalledLocally();
160        
161        /**
162         * Get the server's default ClearCase registry region.
163         * @param wantedProps list of properties to be returned with registry region proxy
164         * @return proxy for server's default registry region.
165         * @throws WvcmException
166         */
167        public CcRegistryRegion doGetDefaultCcRegistryRegion(PropertyRequest wantedProps) throws WvcmException;
168    
169        /**
170         * @return server's version, as a string.
171         * @throws WvcmException
172         */
173        public String doGetServerVersionString() throws WvcmException;
174    
175        /**
176         * <p>
177         * Get the default text mode for web views. This depends on two pieces
178         * of information: the CCRC WAN server's default VOB line termination
179         * setting and the client OS. It is defined as follows: 
180         * </p>
181         * 
182         * <table border="1">
183         * <tr>
184         * <th>server default VOB line term</th>
185         * <th>client OS</th>
186         * <th>web view default text mode</th>
187         * </tr>
188         * <td>LF (UNIX)</td>
189         * <td>UNIX</td>
190         * <td>{@link TextMode#TRANSPARENT}</td>
191         * </tr>
192         * <tr>
193         * <td>LF (UNIX)</td>
194         * <td>Windows</td>
195         * <td>{@link TextMode#INSERT_CR}</td>
196         * </tr>
197         * <tr>
198         * <td>CR-LF (MSDOS)</td>
199         * <td>UNIX</td>
200         * <td>{@link TextMode#STRIP_CR}</td>
201         * </tr>
202         * <tr>
203         * <td>CR-LF (MSDOS)</td>
204         * <td>Windows</td>
205         * <td>{@link TextMode#TRANSPARENT}</td>
206         * </tr>
207         * <tr>
208         * <td>No default set</td>
209         * <td>Both UNIX and Windows</td>
210         * <td>{@link TextMode#TRANSPARENT}</td>
211         * </tr>
212         * </table>
213         * 
214         * @return enumeration representing the view's default text mode
215         * @throws WvcmException
216         */
217        public TextMode doGetDefaultViewTextMode() throws WvcmException;
218    
219        /**
220         * Get the list of views that are accessible on the local machine.
221         * This includes all web views listed in the local web view registry
222         * (typically ".ccase_wvreg" in the user's home directory).
223         * In addition, if this provider is a local provider (LOCAL_PROVIDER_CLASS),
224         * the list includes any dynamic views currently running on this machine.
225         * <p>
226         * If the caller has registered a ProviderMangerCallback on this provider,
227         * that callback will be invoked for each view.  Because these views may be
228         * hosted on different CCRC WAN servers, this gives the caller an opportunity to
229         * specify which provider should be used for each view.
230         * </p>
231         * @param wantedProps list of properties to retrieve for each view proxy.
232         * @return list of locally accessible views as a list of CcView proxies
233         * @see CcProviderManagerCallback
234         * @see CcProvider#registerProviderManagerCallback(CcProviderManagerCallback)
235         */
236        public ResourceList<CcView> getClientViewList(PropertyRequest wantedProps)
237            throws WvcmException;
238    
239        /**
240         * Create a proxy for a ClearCase UCM activity.
241         * @param   location  Location for UCM activity.
242         * @return  UCM activity proxy.
243         */
244        public CcActivity ccActivity(StpLocation location);
245    
246        /**
247         * Create a proxy for a ClearCase branch.
248         * @param   location  Location for branch.
249         * @return  branch proxy.
250         */
251        public CcBranch ccBranch(StpLocation location);
252    
253        /**
254         * Create a proxy for a ClearCase UCM baseline.
255         * @param   location  Location for UCM baseline.
256         * @return  UCM baseline proxy.
257         */
258        public CcBaseline ccBaseline(StpLocation location);
259    
260        /**
261         * Create a proxy for a ClearCase UCM component.
262         * @param   location  Location for UCM component.
263         * @return  UCM component proxy.
264         */
265        public CcComponent ccComponent(StpLocation location);
266    
267        /**
268         * Create a proxy for a ClearCase UCM project.
269         * @param   location  Location for UCM project.
270         * @return  UCM project proxy.
271         */
272        public CcProject ccProject(StpLocation location);
273    
274        /**
275         * Create a proxy for a ClearCase UCM project folder.
276         * @param   location  Location for UCM project folder.
277         * @return  UCM project folder proxy.
278         */
279        public CcProjectFolder ccProjectFolder(StpLocation location);
280    
281        /**
282         * Create a proxy for a ClearCase UCM stream.
283         * @param   location  Location for UCM stream.
284         * @return  UCM stream proxy.
285         */
286        public CcStream ccStream(StpLocation location);
287    
288        /**
289         * Construct a proxy for the CcDirectory (directory in a ClearCase view)
290         * specified by the given location.
291         * @param loc the location of the directory
292         * @return a new CcDirectory proxy for a directory at this Location.
293         */
294        public CcDirectory ccDirectory(StpLocation loc);
295    
296        /**
297         * Construct a proxy for the CcFile (file in a ClearCase view)
298         * specified by the given location.
299         * @param loc the location of the file.
300         * @return a new CcFile proxy for a file at this Location.
301         */
302        public CcFile ccFile(StpLocation loc);
303    
304        /**
305         * Construct a directory version proxy for the given location.
306         * @param loc the location of the directory version.
307         * @return a new proxy for a directory version at this Location.
308         */
309        public CcDirectoryVersion ccDirectoryVersion(StpLocation loc);
310    
311        /**
312         * Construct a version proxy for the given location.
313         * @param loc the location of the version.
314         * @return a new proxy for a version at this Location.
315         */
316        public CcVersion ccVersion(StpLocation loc);
317    
318        /**
319         * Construct a element proxy for the given location.
320         * @param loc the location of the element.
321         * @return a new proxy for a element at this Location.
322         */
323        public CcElement ccElement(StpLocation loc);
324    
325        /**
326         * Construct a registry region proxy for the given location.
327         * @param loc the location of the registry region
328         * @return a new proxy for the registry region at this location
329         */
330        public CcRegistryRegion ccRegistryRegion(StpLocation loc);
331        
332        /**
333         * Construct a VOB proxy for the given location.
334         * @param loc the location of the VOB.
335         * @return a new proxy for a VOB at this Location.
336         */
337        public CcVob ccVob(StpLocation loc);
338    
339        /**
340         * Construct a VOB tag proxy for the given location.
341         * @param loc the location of the VOB tag.
342         * @return a new proxy for a VOB tag at this Location.
343         */
344        public CcVobTag ccVobTag(StpLocation loc);
345    
346        /**
347         * Construct a view proxy for the given location.
348         * @param loc the location of the view.
349         * @return a new proxy for a view at this Location.
350         */
351        public CcView ccView(StpLocation loc);
352    
353        /**
354         * Construct a view tag proxy for the given location.
355         * @param loc the location of the view tag.
356         * @return a new proxy for a view tag at this Location.
357         */
358        public CcViewTag ccViewTag(StpLocation loc);
359    
360        /**
361         * Construct a storage location proxy for the given location.
362         * @param loc the location of the storage location.
363         * @return a new proxy for a storage location at this Location.
364         */
365        public CcStorageLocation ccStorageLocation(StpLocation loc);
366    
367        /**
368         * Construct a attribute type proxy for the given location.
369         * @param loc the location of the attribute type.
370         * @return a new proxy for a attribute type at this Location.
371         */
372        public CcAttributeType ccAttributeType(StpLocation loc);
373    
374        /**
375         * Construct a branch type proxy for the given location.
376         * @param loc the location of the branch type.
377         * @return a new proxy for a branch type at this Location.
378         */
379        public CcBranchType ccBranchType(StpLocation loc);
380    
381        /**
382         * Construct a element type proxy for the given location.
383         * @param loc the location of the element type.
384         * @return a new proxy for a element type at this Location.
385         */
386        public CcElementType ccElementType(StpLocation loc);
387    
388        /**
389         * Construct a hyperlink type proxy for the given location.
390         * @param loc the location of the hyperlink type.
391         * @return a new proxy for a hyperlink type at this Location.
392         */
393        public CcHyperlinkType ccHyperlinkType(StpLocation loc);
394    
395        /**
396         * Construct a label type proxy for the given location.
397         * @param loc the location of the label type.
398         * @return a new proxy for a label type at this Location.
399         */
400        public CcLabelType ccLabelType(StpLocation loc);
401    
402        /**
403         * Construct an empty CcLockInfo object for using
404         * as a property to set on a CcVobResource.
405         * @return a new lock information object
406         */
407        public CcLockInfo CcLockInfo();
408       
409        /**
410         * Construct a replica proxy for the given location.
411         * @param loc the location of the replica.
412         * @return a new proxy for a replica at this Location.
413         */
414        public CcReplica ccReplica(StpLocation loc);
415    
416        /**
417         * Construct a symbolic link proxy for the given location.
418         * @param loc the location of the symbolic link.
419         * @return a new proxy for a symbolic link at this Location.
420         */
421        public CcSymlink ccSymlink(StpLocation loc);
422    
423        /**
424         * Construct a reference to a task.
425         * @param uri Full URI of the task.
426         * @return a new task object.
427         */
428        public CcTask ccTask(String uri);
429        
430        /**
431         * Construct a trigger type proxy for the given location.
432         * @param loc the location of the trigger type.
433         * @return a new proxy for a trigger type at this Location.
434         */
435        public CcTriggerType ccTriggerType(StpLocation loc);
436        
437        /**
438         * Register a provider manager callback.
439         * <p>
440         * Various CM API operations invoke this callback in situations where a new
441         * provider may be required to complete an operation.  For instance, if you
442         * have local web views hosted on different CCRC WAN servers, the
443         * {@link #getClientViewList} method will invoke this callback for each view
444         * to allow your application to associate the correct provider for that view.
445         * </p>
446         * <p>
447         * Various ClearQuest/UCM Integration operations may also invoke this
448         * callback to obtain a ClearQuest provider (CqProvider) instance.
449         * </p>
450         * <p>
451         * The CM API uses a default implementation of this callback if the caller
452         * does not register another one.
453         * </p>
454         * <p>
455         * This callback is shared among all CcProvider instances, so it only needs
456         * to be set once.
457         * </p>
458         * @param callback callback
459         * @return the previously registered provider manager callback
460         * @see CcProvider#getClientViewList(javax.wvcm.PropertyRequestItem.PropertyRequest)
461         */
462        public CcProviderManagerCallback
463        registerProviderManagerCallback(CcProviderManagerCallback callback);
464        
465        /**
466         * Register a callback to process ClearPrompt interaction requests.
467         * @param callback callback
468         */
469        public void
470        registerClearPromptCallback(CcClearPromptCallback callback);
471    
472        /**
473         * Register a callback to handle SSL certificate conflicts.
474         * The callback should be registered before attempting to authenticate over
475         * a secure (SSL) HTTP connection in order to correctly handle certificate
476         * exceptions.
477         * <p>
478         * This callback is shared among all CcProvider instances, so it only needs
479         * to be set once.
480         * </p>
481         * @param callback Trust Manager callback to handle certificate
482         * @throws WvcmException 
483         */
484        public void
485        registerTrustManagerCallback(CcTrustManagerCallback callback) 
486            throws WvcmException;
487        
488        /**
489         * Register a callback to handle a FileAreaLockedException.
490         * @param callback The new callback
491         * @return The previous callback
492         */
493        public CcFileAreaLockedCallback registerCcFileAreaLockedCallback(
494                CcFileAreaLockedCallback callback) throws WvcmException;
495        
496        /**
497         * Register a callback to handling manual merges.
498         * @param callback The new callback
499         * @return The previous callback
500         */
501        public CcMergeHandlingCallback registerMergeHandlingCallback(
502                CcMergeHandlingCallback callback) throws WvcmException;
503        
504        /**
505         * Register a callback to handle state transitions of ClearQuest records. 
506         * The callback is invoked if the transition involves required 
507         * fields that the user needs to provide.
508         * @param callback the callback we're registering
509         * @return the previous registered callback
510         */
511        public CqRecordAutoTransitionCallback registerCqRecordAutoTransitionCallback(
512                CqRecordAutoTransitionCallback callback) throws WvcmException;
513        
514        /**
515         * Handle the manual merge using the provider's callback.
516         * @return CheckinMergeHandling specifying how the checkin 
517         *         is to be handled after the merge
518         */
519        public CheckinMergeHandling handleManualMerge(
520                CcFile file,
521                CcVersion fromVersion,
522                CcVersion toVersion) throws WvcmException;
523    }