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, 2015. 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 access to 096 * ClearCase installed on the local machine. Use this "local provider" to 097 * work with ClearCase dynamic and snapshot 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 * Are dynamic views version 8.0.0.0 or greater installed on this client ? 160 */ 161 public boolean areDynamicViewsInstalled(); 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 and all the 237 * snapshot views listed in the local snapshot view registry. 238 * <p> 239 * If the caller has registered a ProviderMangerCallback on this provider, 240 * that callback will be invoked for each view. Because these views may be 241 * hosted on different CCRC WAN servers, this gives the caller an 242 * opportunity to specify which provider should be used for each view. 243 * </p> 244 * 245 * @param wantedProps 246 * list of properties to retrieve for each view proxy. 247 * @return list of locally accessible views as a list of CcView proxies 248 * @see CcProviderManagerCallback 249 * @see CcProvider#registerProviderManagerCallback(CcProviderManagerCallback) 250 */ 251 public ResourceList<CcView> getClientViewList(PropertyRequest wantedProps) 252 throws WvcmException; 253 254 /** 255 * Get the list of automatic view-tags available to the logged-in OS user. 256 * This includes all view tags corresponding to views listed in the 257 * automatic view registry (typically ".ccase_avrgy" in the user's home 258 * directory). 259 * <p> 260 * If the caller has registered a ProviderMangerCallback on this provider, 261 * that callback will be invoked for each view. Because these views may be 262 * hosted on different CCRC WAN servers, this gives the caller an opportunity to 263 * specify which provider should be used for each view. 264 * 265 * @param wantedProps list of properties to retrieve for each view-tag proxy. 266 * @return list of locally available view-tags as a list of CcViewTag proxies 267 * @throws WvcmException 268 */ 269 public ResourceList<CcViewTag> getClientAutomaticViewTagList(PropertyRequest wantedProps) 270 throws WvcmException; 271 272 /** 273 * Get the names of all proxy types which can be protected 274 * through use of ACLs. That is, they can be included in a policy 275 * definition. 276 */ 277 public List<String> doGetProxyTypesSupportingAcls() throws WvcmException; 278 279 /** 280 * Get the map of privileges for all proxy types which can be protected 281 * through the use of ACLs. 282 */ 283 public Map<String, CcProxyTypePrivilege> doGetProxyTypePrivilegeMap() throws WvcmException; 284 285 /** 286 * Create a proxy for a ClearCase UCM activity. 287 * @param location Location for UCM activity. 288 * @return UCM activity proxy. 289 */ 290 public CcActivity ccActivity(StpLocation location); 291 292 /** 293 * Create a proxy for a ClearCase branch. 294 * @param location Location for branch. 295 * @return branch proxy. 296 */ 297 public CcBranch ccBranch(StpLocation location); 298 299 /** 300 * Create a proxy for a ClearCase UCM baseline. 301 * @param location Location for UCM baseline. 302 * @return UCM baseline proxy. 303 */ 304 public CcBaseline ccBaseline(StpLocation location); 305 306 /** 307 * Create a proxy for a ClearCase UCM component. 308 * @param location Location for UCM component. 309 * @return UCM component proxy. 310 */ 311 public CcComponent ccComponent(StpLocation location); 312 313 /** 314 * Create a proxy for a ClearCase UCM project. 315 * @param location Location for UCM project. 316 * @return UCM project proxy. 317 */ 318 public CcProject ccProject(StpLocation location); 319 320 /** 321 * Create a proxy for a ClearCase UCM project folder. 322 * @param location Location for UCM project folder. 323 * @return UCM project folder proxy. 324 */ 325 public CcProjectFolder ccProjectFolder(StpLocation location); 326 327 /** 328 * Create a proxy for a ClearCase UCM stream. 329 * @param location Location for UCM stream. 330 * @return UCM stream proxy. 331 */ 332 public CcStream ccStream(StpLocation location); 333 334 /** 335 * Construct a proxy for the CcDirectory (directory in a ClearCase view) 336 * specified by the given location. 337 * @param loc the location of the directory 338 * @return a new CcDirectory proxy for a directory at this Location. 339 */ 340 public CcDirectory ccDirectory(StpLocation loc); 341 342 /** 343 * Construct a proxy for the CcFile (file in a ClearCase view) 344 * specified by the given location. 345 * @param loc the location of the file. 346 * @return a new CcFile proxy for a file at this Location. 347 */ 348 public CcFile ccFile(StpLocation loc); 349 350 /** 351 * Construct a directory version proxy for the given location. 352 * @param loc the location of the directory version. 353 * @return a new proxy for a directory version at this Location. 354 */ 355 public CcDirectoryVersion ccDirectoryVersion(StpLocation loc); 356 357 /** 358 * Construct a version proxy for the given location. 359 * @param loc the location of the version. 360 * @return a new proxy for a version at this Location. 361 */ 362 public CcVersion ccVersion(StpLocation loc); 363 364 /** 365 * Construct a element proxy for the given location. 366 * @param loc the location of the element. 367 * @return a new proxy for a element at this Location. 368 */ 369 public CcElement ccElement(StpLocation loc); 370 371 /** 372 * Construct a registry region proxy for the given location. 373 * @param loc the location of the registry region 374 * @return a new proxy for the registry region at this location 375 */ 376 public CcRegistryRegion ccRegistryRegion(StpLocation loc); 377 378 /** 379 * Construct a VOB proxy for the given location. 380 * @param loc the location of the VOB. 381 * @return a new proxy for a VOB at this Location. 382 */ 383 public CcVob ccVob(StpLocation loc); 384 385 /** 386 * Construct a VOB tag proxy for the given location. 387 * @param loc the location of the VOB tag. 388 * @return a new proxy for a VOB tag at this Location. 389 */ 390 public CcVobTag ccVobTag(StpLocation loc); 391 392 /** 393 * Construct a view proxy for the given location. 394 * @param loc the location of the view. 395 * @return a new proxy for a view at this Location. 396 */ 397 public CcView ccView(StpLocation loc); 398 399 /** 400 * Construct a view tag proxy for the given location. 401 * @param loc the location of the view tag. 402 * @return a new proxy for a view tag at this Location. 403 */ 404 public CcViewTag ccViewTag(StpLocation loc); 405 406 /** 407 * Construct a storage location proxy for the given location. 408 * @param loc the location of the storage location. 409 * @return a new proxy for a storage location at this Location. 410 */ 411 public CcStorageLocation ccStorageLocation(StpLocation loc); 412 413 /** 414 * Construct a attribute type proxy for the given location. 415 * @param loc the location of the attribute type. 416 * @return a new proxy for a attribute type at this Location. 417 */ 418 public CcAttributeType ccAttributeType(StpLocation loc); 419 420 /** 421 * Construct a branch type proxy for the given location. 422 * @param loc the location of the branch type. 423 * @return a new proxy for a branch type at this Location. 424 */ 425 public CcBranchType ccBranchType(StpLocation loc); 426 427 /** 428 * Construct a element type proxy for the given location. 429 * @param loc the location of the element type. 430 * @return a new proxy for a element type at this Location. 431 */ 432 public CcElementType ccElementType(StpLocation loc); 433 434 /** 435 * Construct a hyperlink type proxy for the given location. 436 * @param loc the location of the hyperlink type. 437 * @return a new proxy for a hyperlink type at this Location. 438 */ 439 public CcHyperlinkType ccHyperlinkType(StpLocation loc); 440 441 /** 442 * Construct a label type proxy for the given location. 443 * @param loc the location of the label type. 444 * @return a new proxy for a label type at this Location. 445 */ 446 public CcLabelType ccLabelType(StpLocation loc); 447 448 /** 449 * Construct an empty CcLockInfo object for using 450 * as a property to set on a CcVobResource. 451 * @return a new lock information object 452 */ 453 public CcLockInfo CcLockInfo(); 454 455 /** 456 * Construct a policy proxy for the given location. 457 * @param loc the location of the policy. 458 * @return a new proxy for a policy at this Location. 459 */ 460 public CcPolicy ccPolicy(StpLocation loc); 461 462 /** 463 * Construct a rolemap proxy for the given location. 464 * @param loc the location of the rolemap. 465 * @return a new proxy for a rolemap at this Location. 466 */ 467 public CcRolemap ccRolemap(StpLocation loc); 468 469 /** 470 * Construct a replica proxy for the given location. 471 * @param loc the location of the replica. 472 * @return a new proxy for a replica at this Location. 473 */ 474 public CcReplica ccReplica(StpLocation loc); 475 476 /** 477 * Construct a symbolic link proxy for the given location. 478 * @param loc the location of the symbolic link. 479 * @return a new proxy for a symbolic link at this Location. 480 */ 481 public CcSymlink ccSymlink(StpLocation loc); 482 483 /** 484 * Construct a reference to a task. 485 * @param uri Full URI of the task. 486 * @return a new task object. 487 */ 488 @Deprecated 489 public CcTask ccTask(String uri); 490 491 /** 492 * Construct a reference to a task. 493 * @param loc the location of the task 494 * @return a new task object. 495 */ 496 public CcTask ccTask(StpLocation loc); 497 498 /** 499 * Construct a trigger type proxy for the given location. 500 * @param loc the location of the trigger type. 501 * @return a new proxy for a trigger type at this Location. 502 */ 503 public CcTriggerType ccTriggerType(StpLocation loc); 504 505 /** 506 * Register a provider manager callback. 507 * <p> 508 * Various CM API operations invoke this callback in situations where a new 509 * provider may be required to complete an operation. For instance, if you 510 * have local web views hosted on different CCRC WAN servers, the 511 * {@link #getClientViewList} method will invoke this callback for each view 512 * to allow your application to associate the correct provider for that view. 513 * </p> 514 * <p> 515 * Various ClearQuest/UCM Integration operations may also invoke this 516 * callback to obtain a ClearQuest provider (CqProvider) instance. 517 * </p> 518 * <p> 519 * The CM API uses a default implementation of this callback if the caller 520 * does not register another one. 521 * </p> 522 * <p> 523 * This callback is shared among all CcProvider instances, so it only needs 524 * to be set once. 525 * </p> 526 * @param callback callback 527 * @return the previously registered provider manager callback 528 * @see CcProvider#getClientViewList(javax.wvcm.PropertyRequestItem.PropertyRequest) 529 */ 530 public CcProviderManagerCallback 531 registerProviderManagerCallback(CcProviderManagerCallback callback); 532 533 /** 534 * Register a callback to process ClearPrompt interaction requests. 535 * @param callback callback 536 */ 537 public void 538 registerClearPromptCallback(CcClearPromptCallback callback); 539 540 /** 541 * Register a callback to handle SSL certificate conflicts. 542 * The callback should be registered before attempting to authenticate over 543 * a secure (SSL) HTTP connection in order to correctly handle certificate 544 * exceptions. 545 * <p> 546 * This callback is shared among all CcProvider instances, so it only needs 547 * to be set once. 548 * </p> 549 * @param callback Trust Manager callback to handle certificate 550 * @throws WvcmException 551 */ 552 public void 553 registerTrustManagerCallback(CcTrustManagerCallback callback) 554 throws WvcmException; 555 556 /** 557 * Register a callback to handle a FileAreaLockedException. 558 * @param callback The new callback 559 * @return The previous callback 560 */ 561 public CcFileAreaLockedCallback registerCcFileAreaLockedCallback( 562 CcFileAreaLockedCallback callback) throws WvcmException; 563 564 /** 565 * Register a callback to handling manual merges. 566 * @param callback The new callback 567 * @return The previous callback 568 */ 569 public CcMergeHandlingCallback registerMergeHandlingCallback( 570 CcMergeHandlingCallback callback) throws WvcmException; 571 572 /** 573 * Register a callback to handle state transitions of ClearQuest records. 574 * The callback is invoked if the transition involves required 575 * fields that the user needs to provide. 576 * @param callback the callback we're registering 577 * @return the previous registered callback 578 */ 579 public CqRecordAutoTransitionCallback registerCqRecordAutoTransitionCallback( 580 CqRecordAutoTransitionCallback callback) throws WvcmException; 581 582 /** 583 * Register a callback to handle remote view agent operations. 584 * @param callback the remote view agent callback 585 * @throws WvcmException if the callback fails to register 586 */ 587 public void registerCcRemoteViewAgentCallback( 588 CcRemoteViewAgentCallback callback) throws WvcmException; 589 590 /** 591 * Handle the manual merge using the provider's callback. 592 * @return CheckinMergeHandling specifying how the checkin 593 * is to be handled after the merge 594 */ 595 public CheckinMergeHandling handleManualMerge( 596 CcFile file, 597 CcVersion fromVersion, 598 CcVersion toVersion) throws WvcmException; 599 600 /** 601 * Performs a server logout and invalidates this provider's current 602 * session. Attempting to reuse this provider will result 603 * in an attempt to create a new session using the previously 604 * registered authentication callback. 605 */ 606 public void doLogout() throws WvcmException; 607 }