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