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, 2016.  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 */
013package com.ibm.rational.wvcm.stp.cc;
014
015import java.util.List;
016import java.util.Map;
017
018import javax.wvcm.PropertyRequestItem.PropertyRequest;
019import javax.wvcm.ProviderFactory;
020import javax.wvcm.ProviderFactory.Callback.Authentication;
021import javax.wvcm.ResourceList;
022import javax.wvcm.WorkspaceProvider;
023import javax.wvcm.WvcmException;
024
025import com.ibm.rational.wvcm.stp.StpLocation;
026import com.ibm.rational.wvcm.stp.StpProvider;
027import com.ibm.rational.wvcm.stp.cc.CcMergeHandlingCallback.CheckinMergeHandling;
028import com.ibm.rational.wvcm.stp.cc.CcView.TextMode;
029import 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 */
071public 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    public interface CertificateAuthentication extends CcAuthentication {
153        
154    }
155
156    /**
157     * Is this a local provider, as opposed to a network provider?
158     * @see CcProvider#LOCAL_PROVIDER_CLASS
159     * @see CcProvider#NETWORK_PROVIDER_CLASS
160     */
161    public boolean isLocalProvider();
162    
163    /**
164     * Are dynamic views version 8.0.0.0 or greater installed on this client ?
165     */
166    public boolean areDynamicViewsInstalled();
167    
168    /**
169     * Returns the list of view types supported by this provider
170     *
171     * @return the list of supported view types, or an empty list
172     * @throws WvcmException
173     */
174    public List<ViewType> getSupportedViewTypeList() throws WvcmException;
175    
176    /**
177     * Get the server's default ClearCase registry region.
178     * @param wantedProps list of properties to be returned with registry region proxy
179     * @return proxy for server's default registry region.
180     * @throws WvcmException
181     */
182    public CcRegistryRegion doGetDefaultCcRegistryRegion(PropertyRequest wantedProps) throws WvcmException;
183
184    /**
185     * @return server's version, as a string.
186     * @throws WvcmException
187     */
188    public String doGetServerVersionString() throws WvcmException;
189
190    /**
191     * <p>
192     * Get the default text mode for web views. This depends on two pieces
193     * of information: the CCRC WAN server's default VOB line termination
194     * setting and the client OS. It is defined as follows: 
195     * </p>
196     * 
197     * <table border="1">
198     * <tr>
199     * <th>server default VOB line term</th>
200     * <th>client OS</th>
201     * <th>web view default text mode</th>
202     * </tr>
203     * <td>LF (UNIX)</td>
204     * <td>UNIX</td>
205     * <td>{@link TextMode#TRANSPARENT}</td>
206     * </tr>
207     * <tr>
208     * <td>LF (UNIX)</td>
209     * <td>Windows</td>
210     * <td>{@link TextMode#INSERT_CR}</td>
211     * </tr>
212     * <tr>
213     * <td>CR-LF (MSDOS)</td>
214     * <td>UNIX</td>
215     * <td>{@link TextMode#STRIP_CR}</td>
216     * </tr>
217     * <tr>
218     * <td>CR-LF (MSDOS)</td>
219     * <td>Windows</td>
220     * <td>{@link TextMode#TRANSPARENT}</td>
221     * </tr>
222     * <tr>
223     * <td>No default set</td>
224     * <td>Both UNIX and Windows</td>
225     * <td>{@link TextMode#TRANSPARENT}</td>
226     * </tr>
227     * </table>
228     * 
229     * @return enumeration representing the view's default text mode
230     * @throws WvcmException
231     */
232    public TextMode doGetDefaultViewTextMode() throws WvcmException;
233
234    /**
235     * Get the list of views that are accessible on the local machine. This
236     * includes all web views listed in the local web view registry (typically
237     * ".ccase_wvreg" in the user's home directory). It includes all automatic
238     * views listed in the local automatic view registry (typically
239     * ".ccase_avrgy" in the user's home directory. In addition, if this
240     * provider is a local provider (LOCAL_PROVIDER_CLASS), the list includes
241     * any dynamic views currently running on this machine and all the
242     * snapshot views listed in the local snapshot view registry.
243     * <p>
244     * If the caller has registered a ProviderMangerCallback on this provider,
245     * that callback will be invoked for each view. Because these views may be
246     * hosted on different CCRC WAN servers, this gives the caller an
247     * opportunity to specify which provider should be used for each view.
248     * </p>
249     * 
250     * @param wantedProps
251     *            list of properties to retrieve for each view proxy.
252     * @return list of locally accessible views as a list of CcView proxies
253     * @see CcProviderManagerCallback
254     * @see CcProvider#registerProviderManagerCallback(CcProviderManagerCallback)
255     */
256    public ResourceList<CcView> getClientViewList(PropertyRequest wantedProps)
257        throws WvcmException;
258
259    /**
260     * Get the list of automatic view-tags available to the logged-in OS user.
261     * This includes all view tags corresponding to views listed in the
262     * automatic view registry (typically ".ccase_avrgy" in the user's home
263     * directory).
264     * <p>
265     * If the caller has registered a ProviderMangerCallback on this provider,
266     * that callback will be invoked for each view.  Because these views may be
267     * hosted on different CCRC WAN servers, this gives the caller an opportunity to
268     * specify which provider should be used for each view.
269     * 
270     * @param wantedProps list of properties to retrieve for each view-tag proxy.
271     * @return list of locally available view-tags as a list of CcViewTag proxies
272     * @throws WvcmException
273     */
274    public ResourceList<CcViewTag> getClientAutomaticViewTagList(PropertyRequest wantedProps)
275        throws WvcmException;
276
277    /**
278     * Get the list of views owned by the logged-in OS user. This includes all
279     * web views listed in the local web view registry (typically ".ccase_wvreg"
280     * in the user's home directory). It includes all automatic views listed in
281     * the local automatic view registry (typically ".ccase_avrgy" in the user's
282     * home directory. In addition, if this provider is a local provider
283     * (LOCAL_PROVIDER_CLASS), the list includes all dynamic views currently
284     * running on this machine and owned by the current user and all
285     * snapshot views listed in the local snapshot view registry.
286     * <p>
287     * If the caller has registered a ProviderMangerCallback on this provider,
288     * that callback will be invoked for each view. Because these views may be
289     * hosted on different CCRC WAN servers, this gives the caller an
290     * opportunity to specify which provider should be used for each view.
291     * </p>
292     * 
293     * @param wantedProps
294     *            list of properties to retrieve for each view proxy.
295     * @return list of locally accessible views for the logged-in OS user,
296     *         as a list of CcView proxies
297     * @see CcProviderManagerCallback
298     * @see CcProvider#registerProviderManagerCallback(CcProviderManagerCallback)
299     */
300    public ResourceList<CcView> getCurrentUserClientViewList(PropertyRequest wantedProps)
301        throws WvcmException;
302    
303    /**
304     * Get the names of all proxy types which can be protected
305     * through use of ACLs.  That is, they can be included in a policy
306     * definition.
307     */
308    public List<String> doGetProxyTypesSupportingAcls() throws WvcmException;
309
310    /**
311     * Get the map of privileges for all proxy types which can be protected
312     * through the use of ACLs.
313     */
314    public Map<String, CcProxyTypePrivilege> doGetProxyTypePrivilegeMap() throws WvcmException;
315    
316    /**
317     * Create a proxy for a ClearCase UCM activity.
318     * @param   location  Location for UCM activity.
319     * @return  UCM activity proxy.
320     */
321    public CcActivity ccActivity(StpLocation location);
322
323    /**
324     * Create a proxy for a ClearCase branch.
325     * @param   location  Location for branch.
326     * @return  branch proxy.
327     */
328    public CcBranch ccBranch(StpLocation location);
329
330    /**
331     * Create a proxy for a ClearCase UCM baseline.
332     * @param   location  Location for UCM baseline.
333     * @return  UCM baseline proxy.
334     */
335    public CcBaseline ccBaseline(StpLocation location);
336
337    /**
338     * Create a proxy for a ClearCase UCM component.
339     * @param   location  Location for UCM component.
340     * @return  UCM component proxy.
341     */
342    public CcComponent ccComponent(StpLocation location);
343
344    /**
345     * Create a proxy for a ClearCase UCM project.
346     * @param   location  Location for UCM project.
347     * @return  UCM project proxy.
348     */
349    public CcProject ccProject(StpLocation location);
350
351    /**
352     * Create a proxy for a ClearCase UCM project folder.
353     * @param   location  Location for UCM project folder.
354     * @return  UCM project folder proxy.
355     */
356    public CcProjectFolder ccProjectFolder(StpLocation location);
357
358    /**
359     * Create a proxy for a ClearCase UCM stream.
360     * @param   location  Location for UCM stream.
361     * @return  UCM stream proxy.
362     */
363    public CcStream ccStream(StpLocation location);
364
365    /**
366     * Construct a proxy for the CcDirectory (directory in a ClearCase view)
367     * specified by the given location.
368     * @param loc the location of the directory
369     * @return a new CcDirectory proxy for a directory at this Location.
370     */
371    public CcDirectory ccDirectory(StpLocation loc);
372
373    /**
374     * Construct a proxy for the CcFile (file in a ClearCase view)
375     * specified by the given location.
376     * @param loc the location of the file.
377     * @return a new CcFile proxy for a file at this Location.
378     */
379    public CcFile ccFile(StpLocation loc);
380
381    /**
382     * Construct a directory version proxy for the given location.
383     * @param loc the location of the directory version.
384     * @return a new proxy for a directory version at this Location.
385     */
386    public CcDirectoryVersion ccDirectoryVersion(StpLocation loc);
387
388    /**
389     * Construct a version proxy for the given location.
390     * @param loc the location of the version.
391     * @return a new proxy for a version at this Location.
392     */
393    public CcVersion ccVersion(StpLocation loc);
394
395    /**
396     * Construct a element proxy for the given location.
397     * @param loc the location of the element.
398     * @return a new proxy for a element at this Location.
399     */
400    public CcElement ccElement(StpLocation loc);
401
402    /**
403     * Construct a registry region proxy for the given location.
404     * @param loc the location of the registry region
405     * @return a new proxy for the registry region at this location
406     */
407    public CcRegistryRegion ccRegistryRegion(StpLocation loc);
408    
409    /**
410     * Construct a VOB proxy for the given location.
411     * @param loc the location of the VOB.
412     * @return a new proxy for a VOB at this Location.
413     */
414    public CcVob ccVob(StpLocation loc);
415
416    /**
417     * Construct a VOB tag proxy for the given location.
418     * @param loc the location of the VOB tag.
419     * @return a new proxy for a VOB tag at this Location.
420     */
421    public CcVobTag ccVobTag(StpLocation loc);
422
423    /**
424     * Construct a view proxy for the given location.
425     * @param loc the location of the view.
426     * @return a new proxy for a view at this Location.
427     */
428    public CcView ccView(StpLocation loc);
429
430    /**
431     * Construct a view tag proxy for the given location.
432     * @param loc the location of the view tag.
433     * @return a new proxy for a view tag at this Location.
434     */
435    public CcViewTag ccViewTag(StpLocation loc);
436
437    /**
438     * Construct a storage location proxy for the given location.
439     * @param loc the location of the storage location.
440     * @return a new proxy for a storage location at this Location.
441     */
442    public CcStorageLocation ccStorageLocation(StpLocation loc);
443
444    /**
445     * Construct a attribute type proxy for the given location.
446     * @param loc the location of the attribute type.
447     * @return a new proxy for a attribute type at this Location.
448     */
449    public CcAttributeType ccAttributeType(StpLocation loc);
450
451    /**
452     * Construct a branch type proxy for the given location.
453     * @param loc the location of the branch type.
454     * @return a new proxy for a branch type at this Location.
455     */
456    public CcBranchType ccBranchType(StpLocation loc);
457
458    /**
459     * Construct a element type proxy for the given location.
460     * @param loc the location of the element type.
461     * @return a new proxy for a element type at this Location.
462     */
463    public CcElementType ccElementType(StpLocation loc);
464
465    /**
466     * Construct a hyperlink type proxy for the given location.
467     * @param loc the location of the hyperlink type.
468     * @return a new proxy for a hyperlink type at this Location.
469     */
470    public CcHyperlinkType ccHyperlinkType(StpLocation loc);
471
472    /**
473     * Construct a label type proxy for the given location.
474     * @param loc the location of the label type.
475     * @return a new proxy for a label type at this Location.
476     */
477    public CcLabelType ccLabelType(StpLocation loc);
478
479    /**
480     * Construct an empty CcLockInfo object for using
481     * as a property to set on a CcVobResource.
482     * @return a new lock information object
483     */
484    public CcLockInfo CcLockInfo();
485   
486    /**
487     * Construct a policy proxy for the given location.
488     * @param loc the location of the policy.
489     * @return a new proxy for a policy at this Location.
490     */
491    public CcPolicy ccPolicy(StpLocation loc);
492
493    /**
494     * Construct a rolemap proxy for the given location.
495     * @param loc the location of the rolemap.
496     * @return a new proxy for a rolemap at this Location.
497     */
498    public CcRolemap ccRolemap(StpLocation loc);
499
500    /**
501     * Construct a replica proxy for the given location.
502     * @param loc the location of the replica.
503     * @return a new proxy for a replica at this Location.
504     */
505    public CcReplica ccReplica(StpLocation loc);
506
507    /**
508     * Construct a symbolic link proxy for the given location.
509     * @param loc the location of the symbolic link.
510     * @return a new proxy for a symbolic link at this Location.
511     */
512    public CcSymlink ccSymlink(StpLocation loc);
513
514    /**
515     * Construct a reference to a task.
516     * @param uri Full URI of the task.
517     * @return a new task object.
518     */
519    @Deprecated
520    public CcTask ccTask(String uri);
521    
522    /**
523     * Construct a reference to a task.
524     * @param loc the location of the task
525     * @return a new task object.
526     */
527    public CcTask ccTask(StpLocation loc);
528    
529    /**
530     * Construct a trigger type proxy for the given location.
531     * @param loc the location of the trigger type.
532     * @return a new proxy for a trigger type at this Location.
533     */
534    public CcTriggerType ccTriggerType(StpLocation loc);
535    
536    /**
537     * Register a provider manager callback.
538     * <p>
539     * Various CM API operations invoke this callback in situations where a new
540     * provider may be required to complete an operation.  For instance, if you
541     * have local web views hosted on different CCRC WAN servers, the
542     * {@link #getClientViewList} method will invoke this callback for each view
543     * to allow your application to associate the correct provider for that view.
544     * </p>
545     * <p>
546     * Various ClearQuest/UCM Integration operations may also invoke this
547     * callback to obtain a ClearQuest provider (CqProvider) instance.
548     * </p>
549     * <p>
550     * The CM API uses a default implementation of this callback if the caller
551     * does not register another one.
552     * </p>
553     * <p>
554     * This callback is shared among all CcProvider instances, so it only needs
555     * to be set once.
556     * </p>
557     * @param callback callback
558     * @return the previously registered provider manager callback
559     * @see CcProvider#getClientViewList(javax.wvcm.PropertyRequestItem.PropertyRequest)
560     */
561    public CcProviderManagerCallback
562    registerProviderManagerCallback(CcProviderManagerCallback callback);
563    
564    /**
565     * Register a callback to process ClearPrompt interaction requests.
566     * @param callback callback
567     */
568    public void
569    registerClearPromptCallback(CcClearPromptCallback callback);
570
571    /**
572     * Register a callback to handle SSL certificate conflicts.
573     * The callback should be registered before attempting to authenticate over
574     * a secure (SSL) HTTP connection in order to correctly handle certificate
575     * exceptions.
576     * <p>
577     * This callback is shared among all CcProvider instances, so it only needs
578     * to be set once.
579     * </p>
580     * @param callback Trust Manager callback to handle certificate
581     * @throws WvcmException 
582     */
583    public void
584    registerTrustManagerCallback(CcTrustManagerCallback callback) 
585        throws WvcmException;
586    
587    /**
588     * Register a callback to handle a FileAreaLockedException.
589     * @param callback The new callback
590     * @return The previous callback
591     */
592    public CcFileAreaLockedCallback registerCcFileAreaLockedCallback(
593            CcFileAreaLockedCallback callback) throws WvcmException;
594    
595    /**
596     * Register a callback to handling manual merges.
597     * @param callback The new callback
598     * @return The previous callback
599     */
600    public CcMergeHandlingCallback registerMergeHandlingCallback(
601            CcMergeHandlingCallback callback) throws WvcmException;
602    
603    /**
604     * Register a callback to handle state transitions of ClearQuest records. 
605     * The callback is invoked if the transition involves required 
606     * fields that the user needs to provide.
607     * @param callback the callback we're registering
608     * @return the previous registered callback
609     */
610    public CqRecordAutoTransitionCallback registerCqRecordAutoTransitionCallback(
611            CqRecordAutoTransitionCallback callback) throws WvcmException;
612    
613    /**
614     * Register a callback to handle remote view agent operations.
615     * @param callback the remote view agent callback
616     * @throws WvcmException if the callback fails to register
617     */
618    public void registerCcRemoteViewAgentCallback(
619            CcRemoteViewAgentCallback callback) throws WvcmException;
620    
621    /**
622     * Handle the manual merge using the provider's callback.
623     * @return CheckinMergeHandling specifying how the checkin 
624     *         is to be handled after the merge
625     */
626    public CheckinMergeHandling handleManualMerge(
627            CcFile file,
628            CcVersion fromVersion,
629            CcVersion toVersion) throws WvcmException;
630
631    /**
632     * Performs a server logout and invalidates this provider's current
633     * session.  Attempting to reuse this provider will result
634     * in an attempt to create a new session using the previously 
635     * registered authentication callback.
636     */
637    public void doLogout() throws WvcmException;
638}