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