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