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, 2009.  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    
014    package com.ibm.rational.wvcm.stp.cc;
015    
016    import java.util.List;
017    
018    import javax.wvcm.ResourceList;
019    import javax.wvcm.WorkspaceProvider;
020    import javax.wvcm.WvcmException;
021    import javax.wvcm.PropertyRequestItem.PropertyRequest;
022    import javax.wvcm.ProviderFactory.Callback.Authentication;
023    
024    import com.ibm.rational.wvcm.stp.StpLocation;
025    import com.ibm.rational.wvcm.stp.StpProvider;
026    import com.ibm.rational.wvcm.stp.cc.CcMergeHandlingCallback.CheckinMergeHandling;
027    import com.ibm.rational.wvcm.stp.cc.CcView.TextMode;
028    import com.ibm.rational.wvcm.stp.ccex.CcExServer;
029    
030    /**
031     * A ClearCase-specific extension of the javax.wvcm.Provider interface.
032     * <p>
033     * The CcProvider interface contains factory methods for constructing proxies
034     * for various ClearCase-specific resources. Note that there are many resource
035     * types where a ClearCase-specific interface exists for a standard WVCM
036     * interface.  For instance, CcFile is the ClearCase specialization of
037     * javax.wvcm.ControllableResource.
038     * </p>
039     * <p>
040     * The CcProvider interface also contains methods for listing client-side
041     * and server-side ClearCase resources:
042     * <bl>
043     * <li>{@link #getClientViewList} lists the web views
044     * available on the local machine
045     * </li>
046     * <li>{@link #doGetDefaultCcRegistryRegion} gets the default
047     * ClearCase registry region, which in turn has properties representing the
048     * ClearCase VOBs and views in that region.
049     * </li>
050     * </bl>
051     * </p>
052     */
053    public interface CcProvider 
054        extends StpProvider, WorkspaceProvider
055    {
056        /**
057         * The name of a CcProvider class whose instances also provide access to a
058         * CcProvider object. Pass this name to ProviderFactory.createProvider to
059         * obtain an object that implements this interface and provides access to an
060         * implementation of CcProvider interface.
061         * 
062         * @see com.ibm.rational.wvcm.stp.ccex.CcExProvider#NETWORK_PROVIDERS
063         * @deprecated Use
064         *             com.ibm.rational.wvcm.stp.ccex.CcExProvider#NETWORK_PROVIDERS
065         */
066        String PROVIDER_CLASS =
067            "com.ibm.rational.stp.client.internal.cc.CcSubproviderImpl";
068    
069        /**
070         * The name of a CcProvider class whose instances provide only support for
071         * ClearCase via a server. Pass this name to ProviderFactory.createProvider
072         * to obtain an object that implements just this interface.
073         */
074        String CC_ONLY_PROVIDER_CLASS =
075            "com.ibm.rational.stp.client.internal.cc.CcOnlyProviderImpl";
076    
077        /**
078         * An extension of ProviderFactory.Callback that client call-backs can
079         * return to provide a Primary Group or Group List for a ClearCase login
080         */
081        public interface CcAuthentication extends Authentication {
082    
083            /**
084             * <p>ClearCase checks the user's "primary group" to determine whether
085             * the user can peform certain operations in a given VOB, such as
086             * creating a new CC element.
087             * </p>
088             * <p>On Windows operating systems, the user's primary group cannot be
089             * reliably determined, so it must be set explicitly here.
090             * </p>
091             * <p>On Unix, this setting may be used to override the user's primary
092             * group as specified in the /etc/password file or equivalent.
093             * </p>
094             * @return The primary group name to use performing ClearCase operations,
095             *         or <code>null</code> to use the default primary group
096             */
097            String getPrimaryGroupName();
098    
099            /**
100             * <p>ClearCase checks the user's group list (the list of OS groups
101             * to which the user belongs) to determine whether the user can peform
102             * certain operations in a given VOB.
103             * </p>
104             * <p>If the user belongs to more than 32 groups, in certain situations
105             * ClearCase may ignore some of those groups, causing the operation to
106             * fail unnecessarily.  In this case, use this setting to define which
107             * groups (up to 32) ClearCase should use.
108             * </p>
109             * @return The group list to use when performing ClearCase operations,
110             *         or empty list to use the default group list
111             */
112            List<String> getGroupList();
113        }
114        
115        /**
116         * Get the server's default ClearCase registry region.
117         * @param wantedProps list of properties to be returned with registry region proxy
118         * @return proxy for server's default registry region.
119         * @throws WvcmException
120         */
121        public CcRegistryRegion doGetDefaultCcRegistryRegion(PropertyRequest wantedProps) throws WvcmException;
122    
123        /**
124         * @return server's version, as a string.
125         * @throws WvcmException
126         */
127        public String doGetServerVersionString() throws WvcmException;
128    
129        /**
130         * <p>
131         * Get the default text mode for web views. This depends on two pieces
132         * of information: the {@link CcExServer#DEFAULT_VOB_LINE_TERM} property
133         * and the client OS. It is defined as follows: 
134         * </p>
135         * 
136         * <table border="1">
137         * <tr>
138         * <th>server default VOB line term</th>
139         * <th>client OS</th>
140         * <th>web view default text mode</th>
141         * </tr>
142         * <td>LF (UNIX)</td>
143         * <td>UNIX</td>
144         * <td>{@link TextMode#TRANSPARENT}</td>
145         * </tr>
146         * <tr>
147         * <td>LF (UNIX)</td>
148         * <td>Windows</td>
149         * <td>{@link TextMode#INSERT_CR}</td>
150         * </tr>
151         * <tr>
152         * <td>CR-LF (MSDOS)</td>
153         * <td>UNIX</td>
154         * <td>{@link TextMode#STRIP_CR}</td>
155         * </tr>
156         * <tr>
157         * <td>CR-LF (MSDOS)</td>
158         * <td>Windows</td>
159         * <td>{@link TextMode#TRANSPARENT}</td>
160         * </tr>
161         * <tr>
162         * <td>No default set</td>
163         * <td>Both UNIX and Windows</td>
164         * <td>{@link TextMode#TRANSPARENT}</td>
165         * </tr>
166         * </table>
167         * 
168         * @return enumeration representing the view's default text mode
169         * @throws WvcmException
170         */
171        public TextMode doGetDefaultViewTextMode() throws WvcmException;
172        
173        /**
174         * Get the list of web views belonging to the current user, and whose
175         * file areas reside on the local machine.
176         * @param wantedProps list of properties to retrieve for each web view
177         *        proxy.
178         * @return list of local web views as a list of CcView proxies
179         * @throws WvcmException
180         */
181        public ResourceList<CcView> getClientViewList(PropertyRequest wantedProps)
182            throws WvcmException;
183    
184        /**
185         * Create a proxy for a ClearCase UCM activity.
186         * @param   location  Location for UCM activity.
187         * @return  UCM activity proxy.
188         */
189        public CcActivity ccActivity(StpLocation location);
190    
191        /**
192         * Create a proxy for a ClearCase branch.
193         * @param   location  Location for branch.
194         * @return  branch proxy.
195         */
196        public CcBranch ccBranch(StpLocation location);
197    
198        /**
199         * Create a proxy for a ClearCase UCM baseline.
200         * @param   location  Location for UCM baseline.
201         * @return  UCM baseline proxy.
202         */
203        public CcBaseline ccBaseline(StpLocation location);
204    
205        /**
206         * Create a proxy for a ClearCase UCM component.
207         * @param   location  Location for UCM component.
208         * @return  UCM component proxy.
209         */
210        public CcComponent ccComponent(StpLocation location);
211    
212        /**
213         * Create a proxy for a ClearCase UCM project.
214         * @param   location  Location for UCM project.
215         * @return  UCM project proxy.
216         */
217        public CcProject ccProject(StpLocation location);
218    
219        /**
220         * Create a proxy for a ClearCase UCM project folder.
221         * @param   location  Location for UCM project folder.
222         * @return  UCM project folder proxy.
223         */
224        public CcProjectFolder ccProjectFolder(StpLocation location);
225    
226        /**
227         * Create a proxy for a ClearCase UCM stream.
228         * @param   location  Location for UCM stream.
229         * @return  UCM stream proxy.
230         */
231        public CcStream ccStream(StpLocation location);
232    
233        /**
234         * Construct a proxy for the CcDirectory (directory in a ClearCase view)
235         * specified by the given location.
236         * @param loc the location of the directory
237         * @return a new CcDirectory proxy for a directory at this Location.
238         */
239        public CcDirectory ccDirectory(StpLocation loc);
240    
241        /**
242         * Construct a proxy for the CcFile (file in a ClearCase view)
243         * specified by the given location.
244         * @param loc the location of the file.
245         * @return a new CcFile proxy for a file at this Location.
246         */
247        public CcFile ccFile(StpLocation loc);
248    
249        /**
250         * Construct a directory version proxy for the given location.
251         * @param loc the location of the directory version.
252         * @return a new proxy for a directory version at this Location.
253         */
254        public CcDirectoryVersion ccDirectoryVersion(StpLocation loc);
255    
256        /**
257         * Construct a version proxy for the given location.
258         * @param loc the location of the version.
259         * @return a new proxy for a version at this Location.
260         */
261        public CcVersion ccVersion(StpLocation loc);
262    
263        /**
264         * Construct a element proxy for the given location.
265         * @param loc the location of the element.
266         * @return a new proxy for a element at this Location.
267         */
268        public CcElement ccElement(StpLocation loc);
269    
270        /**
271         * Construct a registry region proxy for the given location.
272         * @param loc the location of the registry region
273         * @return a new proxy for the registry region at this location
274         */
275        public CcRegistryRegion ccRegistryRegion(StpLocation loc);
276        
277        /**
278         * Construct a VOB proxy for the given location.
279         * @param loc the location of the VOB.
280         * @return a new proxy for a VOB at this Location.
281         */
282        public CcVob ccVob(StpLocation loc);
283    
284        /**
285         * Construct a VOB tag proxy for the given location.
286         * @param loc the location of the VOB tag.
287         * @return a new proxy for a VOB tag at this Location.
288         */
289        public CcVobTag ccVobTag(StpLocation loc);
290    
291        /**
292         * Construct a view proxy for the given location.
293         * @param loc the location of the view.
294         * @return a new proxy for a view at this Location.
295         */
296        public CcView ccView(StpLocation loc);
297    
298        /**
299         * Construct a view tag proxy for the given location.
300         * @param loc the location of the view tag.
301         * @return a new proxy for a view tag at this Location.
302         */
303        public CcViewTag ccViewTag(StpLocation loc);
304    
305        /**
306         * Construct a attribute type proxy for the given location.
307         * @param loc the location of the attribute type.
308         * @return a new proxy for a attribute type at this Location.
309         */
310        public CcAttributeType ccAttributeType(StpLocation loc);
311    
312        /**
313         * Construct a branch type proxy for the given location.
314         * @param loc the location of the branch type.
315         * @return a new proxy for a branch type at this Location.
316         */
317        public CcBranchType ccBranchType(StpLocation loc);
318    
319        /**
320         * Construct a element type proxy for the given location.
321         * @param loc the location of the element type.
322         * @return a new proxy for a element type at this Location.
323         */
324        public CcElementType ccElementType(StpLocation loc);
325    
326        /**
327         * Construct a hyperlink type proxy for the given location.
328         * @param loc the location of the hyperlink type.
329         * @return a new proxy for a hyperlink type at this Location.
330         */
331        public CcHyperlinkType ccHyperlinkType(StpLocation loc);
332    
333        /**
334         * Construct a label type proxy for the given location.
335         * @param loc the location of the label type.
336         * @return a new proxy for a label type at this Location.
337         */
338        public CcLabelType ccLabelType(StpLocation loc);
339    
340        /**
341         * Construct an empty CcLockInfo object for using
342         * as a property to set on a CcVobResource.
343         * @return a new lock information object
344         */
345        public CcLockInfo CcLockInfo();
346       
347        /**
348         * Construct a replica proxy for the given location.
349         * @param loc the location of the replica.
350         * @return a new proxy for a replica at this Location.
351         */
352        public CcReplica ccReplica(StpLocation loc);
353    
354        /**
355         * Construct a symbolic link proxy for the given location.
356         * @param loc the location of the symbolic link.
357         * @return a new proxy for a symbolic link at this Location.
358         */
359        public CcSymlink ccSymlink(StpLocation loc);
360    
361        /**
362         * Construct a trigger type proxy for the given location.
363         * @param loc the location of the trigger type.
364         * @return a new proxy for a trigger type at this Location.
365         */
366        public CcTriggerType ccTriggerType(StpLocation loc);
367        
368        /**
369         * Register a callback to process ClearPrompt interaction requests.
370         * @param callback callback
371         */
372        public void
373        registerClearPromptCallback(CcClearPromptCallback callback);
374    
375        /**
376         * Register a callback to handle a FileAreaLockedException.
377         * @param callback The new callback
378         * @return The previous callback
379         */
380        public CcFileAreaLockedCallback registerCcFileAreaLockedCallback(
381                CcFileAreaLockedCallback callback) throws WvcmException;
382        
383        /**
384         * Register a callback to handling manual merges.
385         * @param callback The new callback
386         * @return The previous callback
387         */
388        public CcMergeHandlingCallback registerMergeHandlingCallback(
389                CcMergeHandlingCallback callback) throws WvcmException;
390        
391        /**
392         * Register a callback to handle state transitions of ClearQuest records. 
393         * The callback is invoked if the transition involves required 
394         * fields that the user needs to provide.
395         * @param callback the callback we're registering
396         * @return the previous registered callback
397         */
398        public CqRecordAutoTransitionCallback registerCqRecordAutoTransitionCallback(
399                CqRecordAutoTransitionCallback callback) throws WvcmException;
400        
401        /**
402         * Handle the manual merge using the provider's callback.
403         * @return CheckinMergeHandling specifying how the checkin 
404         *         is to be handled after the merge
405         */
406        public CheckinMergeHandling handleManualMerge(
407                CcFile file,
408                CcVersion fromVersion,
409                CcVersion toVersion) throws WvcmException;
410    }