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, 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 }