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