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