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, 2008.  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         * <p>
125         * Get the default text mode for web views. This depends on two pieces
126         * of information: the {@link CcExServer#DEFAULT_VOB_LINE_TERM} property
127         * and the client OS. It is defined as follows: 
128         * </p>
129         * 
130         * <table border="1">
131         * <tr>
132         * <th>server default VOB line term</th>
133         * <th>client OS</th>
134         * <th>web view default text mode</th>
135         * </tr>
136         * <td>LF (UNIX)</td>
137         * <td>UNIX</td>
138         * <td>{@link TextMode#TRANSPARENT}</td>
139         * </tr>
140         * <tr>
141         * <td>LF (UNIX)</td>
142         * <td>Windows</td>
143         * <td>{@link TextMode#INSERT_CR}</td>
144         * </tr>
145         * <tr>
146         * <td>CR-LF (MSDOS)</td>
147         * <td>UNIX</td>
148         * <td>{@link TextMode#STRIP_CR}</td>
149         * </tr>
150         * <tr>
151         * <td>CR-LF (MSDOS)</td>
152         * <td>Windows</td>
153         * <td>{@link TextMode#TRANSPARENT}</td>
154         * </tr>
155         * <tr>
156         * <td>No default set</td>
157         * <td>Both UNIX and Windows</td>
158         * <td>{@link TextMode#TRANSPARENT}</td>
159         * </tr>
160         * </table>
161         * 
162         * @return enumeration representing the view's default text mode
163         * @throws WvcmException
164         */
165        public TextMode doGetDefaultViewTextMode() throws WvcmException;
166        
167        /**
168         * Get the list of web views belonging to the current user, and whose
169         * file areas reside on the local machine.
170         * @param wantedProps list of properties to retrieve for each web view
171         *        proxy.
172         * @return list of local web views as a list of CcView proxies
173         * @throws WvcmException
174         */
175        public ResourceList<CcView> getClientViewList(PropertyRequest wantedProps)
176            throws WvcmException;
177    
178        /**
179         * Create a proxy for a ClearCase UCM activity.
180         * @param   location  Location for UCM activity.
181         * @return  UCM activity proxy.
182         */
183        public CcActivity ccActivity(StpLocation location);
184    
185        /**
186         * Create a proxy for a ClearCase UCM baseline.
187         * @param   location  Location for UCM baseline.
188         * @return  UCM baseline proxy.
189         */
190        public CcBaseline ccBaseline(StpLocation location);
191    
192        /**
193         * Create a proxy for a ClearCase UCM component.
194         * @param   location  Location for UCM component.
195         * @return  UCM component proxy.
196         */
197        public CcComponent ccComponent(StpLocation location);
198    
199        /**
200         * Create a proxy for a ClearCase UCM project.
201         * @param   location  Location for UCM project.
202         * @return  UCM project proxy.
203         */
204        public CcProject ccProject(StpLocation location);
205    
206        /**
207         * Create a proxy for a ClearCase UCM project folder.
208         * @param   location  Location for UCM project folder.
209         * @return  UCM project folder proxy.
210         */
211        public CcProjectFolder ccProjectFolder(StpLocation location);
212    
213        /**
214         * Create a proxy for a ClearCase UCM stream.
215         * @param   location  Location for UCM stream.
216         * @return  UCM stream proxy.
217         */
218        public CcStream ccStream(StpLocation location);
219    
220        /**
221         * Construct a proxy for the CcDirectory (directory in a ClearCase view)
222         * specified by the given location.
223         * @param loc the location of the directory
224         * @return a new CcDirectory proxy for a directory at this Location.
225         */
226        public CcDirectory ccDirectory(StpLocation loc);
227    
228        /**
229         * Construct a proxy for the CcFile (file in a ClearCase view)
230         * specified by the given location.
231         * @param loc the location of the file.
232         * @return a new CcFile proxy for a file at this Location.
233         */
234        public CcFile ccFile(StpLocation loc);
235    
236        /**
237         * Construct a directory version proxy for the given location.
238         * @param loc the location of the directory version.
239         * @return a new proxy for a directory version at this Location.
240         */
241        public CcDirectoryVersion ccDirectoryVersion(StpLocation loc);
242    
243        /**
244         * Construct a version proxy for the given location.
245         * @param loc the location of the version.
246         * @return a new proxy for a version at this Location.
247         */
248        public CcVersion ccVersion(StpLocation loc);
249    
250        /**
251         * Construct a element proxy for the given location.
252         * @param loc the location of the element.
253         * @return a new proxy for a element at this Location.
254         */
255        public CcElement ccElement(StpLocation loc);
256    
257        /**
258         * Construct a registry region proxy for the given location.
259         * @param loc the location of the registry region
260         * @return a new proxy for the registry region at this location
261         */
262        public CcRegistryRegion ccRegistryRegion(StpLocation loc);
263        
264        /**
265         * Construct a VOB proxy for the given location.
266         * @param loc the location of the VOB.
267         * @return a new proxy for a VOB at this Location.
268         */
269        public CcVob ccVob(StpLocation loc);
270    
271        /**
272         * Construct a VOB tag proxy for the given location.
273         * @param loc the location of the VOB tag.
274         * @return a new proxy for a VOB tag at this Location.
275         */
276        public CcVobTag ccVobTag(StpLocation loc);
277    
278        /**
279         * Construct a view proxy for the given location.
280         * @param loc the location of the view.
281         * @return a new proxy for a view at this Location.
282         */
283        public CcView ccView(StpLocation loc);
284    
285        /**
286         * Construct a view tag proxy for the given location.
287         * @param loc the location of the view tag.
288         * @return a new proxy for a view tag at this Location.
289         */
290        public CcViewTag ccViewTag(StpLocation loc);
291    
292        /**
293         * Construct a attribute type proxy for the given location.
294         * @param loc the location of the attribute type.
295         * @return a new proxy for a attribute type at this Location.
296         */
297        public CcAttributeType ccAttributeType(StpLocation loc);
298    
299        /**
300         * Construct a branch type proxy for the given location.
301         * @param loc the location of the branch type.
302         * @return a new proxy for a branch type at this Location.
303         */
304        public CcBranchType ccBranchType(StpLocation loc);
305    
306        /**
307         * Construct a element type proxy for the given location.
308         * @param loc the location of the element type.
309         * @return a new proxy for a element type at this Location.
310         */
311        public CcElementType ccElementType(StpLocation loc);
312    
313        /**
314         * Construct a hyperlink type proxy for the given location.
315         * @param loc the location of the hyperlink type.
316         * @return a new proxy for a hyperlink type at this Location.
317         */
318        public CcHyperlinkType ccHyperlinkType(StpLocation loc);
319    
320        /**
321         * Construct a label type proxy for the given location.
322         * @param loc the location of the label type.
323         * @return a new proxy for a label type at this Location.
324         */
325        public CcLabelType ccLabelType(StpLocation loc);
326    
327        /**
328         * Construct an empty CcLockInfo object for using
329         * as a property to set on a CcVobResource.
330         * @return a new lock information object
331         */
332        public CcLockInfo CcLockInfo();
333       
334        /**
335         * Construct a replica proxy for the given location.
336         * @param loc the location of the replica.
337         * @return a new proxy for a replica at this Location.
338         */
339        public CcReplica ccReplica(StpLocation loc);
340    
341        /**
342         * Construct a symbolic link proxy for the given location.
343         * @param loc the location of the symbolic link.
344         * @return a new proxy for a symbolic link at this Location.
345         */
346        public CcSymlink ccSymlink(StpLocation loc);
347    
348        /**
349         * Construct a trigger type proxy for the given location.
350         * @param loc the location of the trigger type.
351         * @return a new proxy for a trigger type at this Location.
352         */
353        public CcTriggerType ccTriggerType(StpLocation loc);
354        
355        /**
356         * Register a callback to process ClearPrompt interaction requests.
357         * @param callback callback
358         */
359        public void
360        registerClearPromptCallback(CcClearPromptCallback callback);
361    
362        /**
363         * Register a callback to handle a FileAreaLockedException.
364         * @param callback The new callback
365         * @return The previous callback
366         */
367        public CcFileAreaLockedCallback registerCcFileAreaLockedCallback(
368                CcFileAreaLockedCallback callback) throws WvcmException;
369        
370        /**
371         * Register a callback to handling manual merges.
372         * @param callback The new callback
373         * @return The previous callback
374         */
375        public CcMergeHandlingCallback registerMergeHandlingCallback(
376                CcMergeHandlingCallback callback) throws WvcmException;
377        
378        /**
379         * Register a callback to handle state transitions of ClearQuest records. 
380         * The callback is invoked if the transition involves required 
381         * fields that the user needs to provide.
382         * @param callback the callback we're registering
383         * @return the previous registered callback
384         */
385        public CqRecordAutoTransitionCallback registerCqRecordAutoTransitionCallback(
386                CqRecordAutoTransitionCallback callback) throws WvcmException;
387        
388        /**
389         * Handle the manual merge using the provider's callback.
390         * @return CheckinMergeHandling specifying how the checkin 
391         *         is to be handled after the merge
392         */
393        public CheckinMergeHandling handleManualMerge(
394                CcFile file,
395                CcVersion fromVersion,
396                CcVersion toVersion) throws WvcmException;
397    }