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, 2015.  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 access to
096         * ClearCase installed on the local machine.  Use this "local provider" to
097         * work with ClearCase dynamic and snapshot 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         * Are dynamic views version 8.0.0.0 or greater installed on this client ?
160         */
161        public boolean areDynamicViewsInstalled();
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 and all the
237         * snapshot views listed in the local snapshot view registry.
238         * <p>
239         * If the caller has registered a ProviderMangerCallback on this provider,
240         * that callback will be invoked for each view. Because these views may be
241         * hosted on different CCRC WAN servers, this gives the caller an
242         * opportunity to specify which provider should be used for each view.
243         * </p>
244         * 
245         * @param wantedProps
246         *            list of properties to retrieve for each view proxy.
247         * @return list of locally accessible views as a list of CcView proxies
248         * @see CcProviderManagerCallback
249         * @see CcProvider#registerProviderManagerCallback(CcProviderManagerCallback)
250         */
251        public ResourceList<CcView> getClientViewList(PropertyRequest wantedProps)
252            throws WvcmException;
253    
254        /**
255         * Get the list of automatic view-tags available to the logged-in OS user.
256         * This includes all view tags corresponding to views listed in the
257         * automatic view registry (typically ".ccase_avrgy" in the user's home
258         * directory).
259         * <p>
260         * If the caller has registered a ProviderMangerCallback on this provider,
261         * that callback will be invoked for each view.  Because these views may be
262         * hosted on different CCRC WAN servers, this gives the caller an opportunity to
263         * specify which provider should be used for each view.
264         * 
265         * @param wantedProps list of properties to retrieve for each view-tag proxy.
266         * @return list of locally available view-tags as a list of CcViewTag proxies
267         * @throws WvcmException
268         */
269        public ResourceList<CcViewTag> getClientAutomaticViewTagList(PropertyRequest wantedProps)
270            throws WvcmException;
271    
272        /**
273         * Get the names of all proxy types which can be protected
274         * through use of ACLs.  That is, they can be included in a policy
275         * definition.
276         */
277        public List<String> doGetProxyTypesSupportingAcls() throws WvcmException;
278    
279        /**
280         * Get the map of privileges for all proxy types which can be protected
281         * through the use of ACLs.
282         */
283        public Map<String, CcProxyTypePrivilege> doGetProxyTypePrivilegeMap() throws WvcmException;
284        
285        /**
286         * Create a proxy for a ClearCase UCM activity.
287         * @param   location  Location for UCM activity.
288         * @return  UCM activity proxy.
289         */
290        public CcActivity ccActivity(StpLocation location);
291    
292        /**
293         * Create a proxy for a ClearCase branch.
294         * @param   location  Location for branch.
295         * @return  branch proxy.
296         */
297        public CcBranch ccBranch(StpLocation location);
298    
299        /**
300         * Create a proxy for a ClearCase UCM baseline.
301         * @param   location  Location for UCM baseline.
302         * @return  UCM baseline proxy.
303         */
304        public CcBaseline ccBaseline(StpLocation location);
305    
306        /**
307         * Create a proxy for a ClearCase UCM component.
308         * @param   location  Location for UCM component.
309         * @return  UCM component proxy.
310         */
311        public CcComponent ccComponent(StpLocation location);
312    
313        /**
314         * Create a proxy for a ClearCase UCM project.
315         * @param   location  Location for UCM project.
316         * @return  UCM project proxy.
317         */
318        public CcProject ccProject(StpLocation location);
319    
320        /**
321         * Create a proxy for a ClearCase UCM project folder.
322         * @param   location  Location for UCM project folder.
323         * @return  UCM project folder proxy.
324         */
325        public CcProjectFolder ccProjectFolder(StpLocation location);
326    
327        /**
328         * Create a proxy for a ClearCase UCM stream.
329         * @param   location  Location for UCM stream.
330         * @return  UCM stream proxy.
331         */
332        public CcStream ccStream(StpLocation location);
333    
334        /**
335         * Construct a proxy for the CcDirectory (directory in a ClearCase view)
336         * specified by the given location.
337         * @param loc the location of the directory
338         * @return a new CcDirectory proxy for a directory at this Location.
339         */
340        public CcDirectory ccDirectory(StpLocation loc);
341    
342        /**
343         * Construct a proxy for the CcFile (file in a ClearCase view)
344         * specified by the given location.
345         * @param loc the location of the file.
346         * @return a new CcFile proxy for a file at this Location.
347         */
348        public CcFile ccFile(StpLocation loc);
349    
350        /**
351         * Construct a directory version proxy for the given location.
352         * @param loc the location of the directory version.
353         * @return a new proxy for a directory version at this Location.
354         */
355        public CcDirectoryVersion ccDirectoryVersion(StpLocation loc);
356    
357        /**
358         * Construct a version proxy for the given location.
359         * @param loc the location of the version.
360         * @return a new proxy for a version at this Location.
361         */
362        public CcVersion ccVersion(StpLocation loc);
363    
364        /**
365         * Construct a element proxy for the given location.
366         * @param loc the location of the element.
367         * @return a new proxy for a element at this Location.
368         */
369        public CcElement ccElement(StpLocation loc);
370    
371        /**
372         * Construct a registry region proxy for the given location.
373         * @param loc the location of the registry region
374         * @return a new proxy for the registry region at this location
375         */
376        public CcRegistryRegion ccRegistryRegion(StpLocation loc);
377        
378        /**
379         * Construct a VOB proxy for the given location.
380         * @param loc the location of the VOB.
381         * @return a new proxy for a VOB at this Location.
382         */
383        public CcVob ccVob(StpLocation loc);
384    
385        /**
386         * Construct a VOB tag proxy for the given location.
387         * @param loc the location of the VOB tag.
388         * @return a new proxy for a VOB tag at this Location.
389         */
390        public CcVobTag ccVobTag(StpLocation loc);
391    
392        /**
393         * Construct a view proxy for the given location.
394         * @param loc the location of the view.
395         * @return a new proxy for a view at this Location.
396         */
397        public CcView ccView(StpLocation loc);
398    
399        /**
400         * Construct a view tag proxy for the given location.
401         * @param loc the location of the view tag.
402         * @return a new proxy for a view tag at this Location.
403         */
404        public CcViewTag ccViewTag(StpLocation loc);
405    
406        /**
407         * Construct a storage location proxy for the given location.
408         * @param loc the location of the storage location.
409         * @return a new proxy for a storage location at this Location.
410         */
411        public CcStorageLocation ccStorageLocation(StpLocation loc);
412    
413        /**
414         * Construct a attribute type proxy for the given location.
415         * @param loc the location of the attribute type.
416         * @return a new proxy for a attribute type at this Location.
417         */
418        public CcAttributeType ccAttributeType(StpLocation loc);
419    
420        /**
421         * Construct a branch type proxy for the given location.
422         * @param loc the location of the branch type.
423         * @return a new proxy for a branch type at this Location.
424         */
425        public CcBranchType ccBranchType(StpLocation loc);
426    
427        /**
428         * Construct a element type proxy for the given location.
429         * @param loc the location of the element type.
430         * @return a new proxy for a element type at this Location.
431         */
432        public CcElementType ccElementType(StpLocation loc);
433    
434        /**
435         * Construct a hyperlink type proxy for the given location.
436         * @param loc the location of the hyperlink type.
437         * @return a new proxy for a hyperlink type at this Location.
438         */
439        public CcHyperlinkType ccHyperlinkType(StpLocation loc);
440    
441        /**
442         * Construct a label type proxy for the given location.
443         * @param loc the location of the label type.
444         * @return a new proxy for a label type at this Location.
445         */
446        public CcLabelType ccLabelType(StpLocation loc);
447    
448        /**
449         * Construct an empty CcLockInfo object for using
450         * as a property to set on a CcVobResource.
451         * @return a new lock information object
452         */
453        public CcLockInfo CcLockInfo();
454       
455        /**
456         * Construct a policy proxy for the given location.
457         * @param loc the location of the policy.
458         * @return a new proxy for a policy at this Location.
459         */
460        public CcPolicy ccPolicy(StpLocation loc);
461    
462        /**
463         * Construct a rolemap proxy for the given location.
464         * @param loc the location of the rolemap.
465         * @return a new proxy for a rolemap at this Location.
466         */
467        public CcRolemap ccRolemap(StpLocation loc);
468    
469        /**
470         * Construct a replica proxy for the given location.
471         * @param loc the location of the replica.
472         * @return a new proxy for a replica at this Location.
473         */
474        public CcReplica ccReplica(StpLocation loc);
475    
476        /**
477         * Construct a symbolic link proxy for the given location.
478         * @param loc the location of the symbolic link.
479         * @return a new proxy for a symbolic link at this Location.
480         */
481        public CcSymlink ccSymlink(StpLocation loc);
482    
483        /**
484         * Construct a reference to a task.
485         * @param uri Full URI of the task.
486         * @return a new task object.
487         */
488        @Deprecated
489        public CcTask ccTask(String uri);
490        
491        /**
492         * Construct a reference to a task.
493         * @param loc the location of the task
494         * @return a new task object.
495         */
496        public CcTask ccTask(StpLocation loc);
497        
498        /**
499         * Construct a trigger type proxy for the given location.
500         * @param loc the location of the trigger type.
501         * @return a new proxy for a trigger type at this Location.
502         */
503        public CcTriggerType ccTriggerType(StpLocation loc);
504        
505        /**
506         * Register a provider manager callback.
507         * <p>
508         * Various CM API operations invoke this callback in situations where a new
509         * provider may be required to complete an operation.  For instance, if you
510         * have local web views hosted on different CCRC WAN servers, the
511         * {@link #getClientViewList} method will invoke this callback for each view
512         * to allow your application to associate the correct provider for that view.
513         * </p>
514         * <p>
515         * Various ClearQuest/UCM Integration operations may also invoke this
516         * callback to obtain a ClearQuest provider (CqProvider) instance.
517         * </p>
518         * <p>
519         * The CM API uses a default implementation of this callback if the caller
520         * does not register another one.
521         * </p>
522         * <p>
523         * This callback is shared among all CcProvider instances, so it only needs
524         * to be set once.
525         * </p>
526         * @param callback callback
527         * @return the previously registered provider manager callback
528         * @see CcProvider#getClientViewList(javax.wvcm.PropertyRequestItem.PropertyRequest)
529         */
530        public CcProviderManagerCallback
531        registerProviderManagerCallback(CcProviderManagerCallback callback);
532        
533        /**
534         * Register a callback to process ClearPrompt interaction requests.
535         * @param callback callback
536         */
537        public void
538        registerClearPromptCallback(CcClearPromptCallback callback);
539    
540        /**
541         * Register a callback to handle SSL certificate conflicts.
542         * The callback should be registered before attempting to authenticate over
543         * a secure (SSL) HTTP connection in order to correctly handle certificate
544         * exceptions.
545         * <p>
546         * This callback is shared among all CcProvider instances, so it only needs
547         * to be set once.
548         * </p>
549         * @param callback Trust Manager callback to handle certificate
550         * @throws WvcmException 
551         */
552        public void
553        registerTrustManagerCallback(CcTrustManagerCallback callback) 
554            throws WvcmException;
555        
556        /**
557         * Register a callback to handle a FileAreaLockedException.
558         * @param callback The new callback
559         * @return The previous callback
560         */
561        public CcFileAreaLockedCallback registerCcFileAreaLockedCallback(
562                CcFileAreaLockedCallback callback) throws WvcmException;
563        
564        /**
565         * Register a callback to handling manual merges.
566         * @param callback The new callback
567         * @return The previous callback
568         */
569        public CcMergeHandlingCallback registerMergeHandlingCallback(
570                CcMergeHandlingCallback callback) throws WvcmException;
571        
572        /**
573         * Register a callback to handle state transitions of ClearQuest records. 
574         * The callback is invoked if the transition involves required 
575         * fields that the user needs to provide.
576         * @param callback the callback we're registering
577         * @return the previous registered callback
578         */
579        public CqRecordAutoTransitionCallback registerCqRecordAutoTransitionCallback(
580                CqRecordAutoTransitionCallback callback) throws WvcmException;
581        
582        /**
583         * Register a callback to handle remote view agent operations.
584         * @param callback the remote view agent callback
585         * @throws WvcmException if the callback fails to register
586         */
587        public void registerCcRemoteViewAgentCallback(
588                CcRemoteViewAgentCallback callback) throws WvcmException;
589        
590        /**
591         * Handle the manual merge using the provider's callback.
592         * @return CheckinMergeHandling specifying how the checkin 
593         *         is to be handled after the merge
594         */
595        public CheckinMergeHandling handleManualMerge(
596                CcFile file,
597                CcVersion fromVersion,
598                CcVersion toVersion) throws WvcmException;
599    
600        /**
601         * Performs a server logout and invalidates this provider's current
602         * session.  Attempting to reuse this provider will result
603         * in an attempt to create a new session using the previously 
604         * registered authentication callback.
605         */
606        public void doLogout() throws WvcmException;
607    }