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