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, 2016. 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 */ 013package com.ibm.rational.wvcm.stp.cc; 014 015import java.util.List; 016import java.util.Map; 017 018import javax.wvcm.PropertyRequestItem.PropertyRequest; 019import javax.wvcm.ProviderFactory; 020import javax.wvcm.ProviderFactory.Callback.Authentication; 021import javax.wvcm.ResourceList; 022import javax.wvcm.WorkspaceProvider; 023import javax.wvcm.WvcmException; 024 025import com.ibm.rational.wvcm.stp.StpLocation; 026import com.ibm.rational.wvcm.stp.StpProvider; 027import com.ibm.rational.wvcm.stp.cc.CcMergeHandlingCallback.CheckinMergeHandling; 028import com.ibm.rational.wvcm.stp.cc.CcView.TextMode; 029import 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 */ 071public 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 public interface CertificateAuthentication extends CcAuthentication { 153 154 } 155 156 /** 157 * Is this a local provider, as opposed to a network provider? 158 * @see CcProvider#LOCAL_PROVIDER_CLASS 159 * @see CcProvider#NETWORK_PROVIDER_CLASS 160 */ 161 public boolean isLocalProvider(); 162 163 /** 164 * Are dynamic views version 8.0.0.0 or greater installed on this client ? 165 */ 166 public boolean areDynamicViewsInstalled(); 167 168 /** 169 * Returns the list of view types supported by this provider 170 * 171 * @return the list of supported view types, or an empty list 172 * @throws WvcmException 173 */ 174 public List<ViewType> getSupportedViewTypeList() throws WvcmException; 175 176 /** 177 * Get the server's default ClearCase registry region. 178 * @param wantedProps list of properties to be returned with registry region proxy 179 * @return proxy for server's default registry region. 180 * @throws WvcmException 181 */ 182 public CcRegistryRegion doGetDefaultCcRegistryRegion(PropertyRequest wantedProps) throws WvcmException; 183 184 /** 185 * @return server's version, as a string. 186 * @throws WvcmException 187 */ 188 public String doGetServerVersionString() throws WvcmException; 189 190 /** 191 * <p> 192 * Get the default text mode for web views. This depends on two pieces 193 * of information: the CCRC WAN server's default VOB line termination 194 * setting and the client OS. It is defined as follows: 195 * </p> 196 * 197 * <table border="1"> 198 * <tr> 199 * <th>server default VOB line term</th> 200 * <th>client OS</th> 201 * <th>web view default text mode</th> 202 * </tr> 203 * <td>LF (UNIX)</td> 204 * <td>UNIX</td> 205 * <td>{@link TextMode#TRANSPARENT}</td> 206 * </tr> 207 * <tr> 208 * <td>LF (UNIX)</td> 209 * <td>Windows</td> 210 * <td>{@link TextMode#INSERT_CR}</td> 211 * </tr> 212 * <tr> 213 * <td>CR-LF (MSDOS)</td> 214 * <td>UNIX</td> 215 * <td>{@link TextMode#STRIP_CR}</td> 216 * </tr> 217 * <tr> 218 * <td>CR-LF (MSDOS)</td> 219 * <td>Windows</td> 220 * <td>{@link TextMode#TRANSPARENT}</td> 221 * </tr> 222 * <tr> 223 * <td>No default set</td> 224 * <td>Both UNIX and Windows</td> 225 * <td>{@link TextMode#TRANSPARENT}</td> 226 * </tr> 227 * </table> 228 * 229 * @return enumeration representing the view's default text mode 230 * @throws WvcmException 231 */ 232 public TextMode doGetDefaultViewTextMode() throws WvcmException; 233 234 /** 235 * Get the list of views that are accessible on the local machine. This 236 * includes all web views listed in the local web view registry (typically 237 * ".ccase_wvreg" in the user's home directory). It includes all automatic 238 * views listed in the local automatic view registry (typically 239 * ".ccase_avrgy" in the user's home directory. In addition, if this 240 * provider is a local provider (LOCAL_PROVIDER_CLASS), the list includes 241 * any dynamic views currently running on this machine and all the 242 * snapshot views listed in the local snapshot view registry. 243 * <p> 244 * If the caller has registered a ProviderMangerCallback on this provider, 245 * that callback will be invoked for each view. Because these views may be 246 * hosted on different CCRC WAN servers, this gives the caller an 247 * opportunity to specify which provider should be used for each view. 248 * </p> 249 * 250 * @param wantedProps 251 * list of properties to retrieve for each view proxy. 252 * @return list of locally accessible views as a list of CcView proxies 253 * @see CcProviderManagerCallback 254 * @see CcProvider#registerProviderManagerCallback(CcProviderManagerCallback) 255 */ 256 public ResourceList<CcView> getClientViewList(PropertyRequest wantedProps) 257 throws WvcmException; 258 259 /** 260 * Get the list of automatic view-tags available to the logged-in OS user. 261 * This includes all view tags corresponding to views listed in the 262 * automatic view registry (typically ".ccase_avrgy" in the user's home 263 * directory). 264 * <p> 265 * If the caller has registered a ProviderMangerCallback on this provider, 266 * that callback will be invoked for each view. Because these views may be 267 * hosted on different CCRC WAN servers, this gives the caller an opportunity to 268 * specify which provider should be used for each view. 269 * 270 * @param wantedProps list of properties to retrieve for each view-tag proxy. 271 * @return list of locally available view-tags as a list of CcViewTag proxies 272 * @throws WvcmException 273 */ 274 public ResourceList<CcViewTag> getClientAutomaticViewTagList(PropertyRequest wantedProps) 275 throws WvcmException; 276 277 /** 278 * Get the list of views owned by the logged-in OS user. This includes all 279 * web views listed in the local web view registry (typically ".ccase_wvreg" 280 * in the user's home directory). It includes all automatic views listed in 281 * the local automatic view registry (typically ".ccase_avrgy" in the user's 282 * home directory. In addition, if this provider is a local provider 283 * (LOCAL_PROVIDER_CLASS), the list includes all dynamic views currently 284 * running on this machine and owned by the current user and all 285 * snapshot views listed in the local snapshot view registry. 286 * <p> 287 * If the caller has registered a ProviderMangerCallback on this provider, 288 * that callback will be invoked for each view. Because these views may be 289 * hosted on different CCRC WAN servers, this gives the caller an 290 * opportunity to specify which provider should be used for each view. 291 * </p> 292 * 293 * @param wantedProps 294 * list of properties to retrieve for each view proxy. 295 * @return list of locally accessible views for the logged-in OS user, 296 * as a list of CcView proxies 297 * @see CcProviderManagerCallback 298 * @see CcProvider#registerProviderManagerCallback(CcProviderManagerCallback) 299 */ 300 public ResourceList<CcView> getCurrentUserClientViewList(PropertyRequest wantedProps) 301 throws WvcmException; 302 303 /** 304 * Get the names of all proxy types which can be protected 305 * through use of ACLs. That is, they can be included in a policy 306 * definition. 307 */ 308 public List<String> doGetProxyTypesSupportingAcls() throws WvcmException; 309 310 /** 311 * Get the map of privileges for all proxy types which can be protected 312 * through the use of ACLs. 313 */ 314 public Map<String, CcProxyTypePrivilege> doGetProxyTypePrivilegeMap() throws WvcmException; 315 316 /** 317 * Create a proxy for a ClearCase UCM activity. 318 * @param location Location for UCM activity. 319 * @return UCM activity proxy. 320 */ 321 public CcActivity ccActivity(StpLocation location); 322 323 /** 324 * Create a proxy for a ClearCase branch. 325 * @param location Location for branch. 326 * @return branch proxy. 327 */ 328 public CcBranch ccBranch(StpLocation location); 329 330 /** 331 * Create a proxy for a ClearCase UCM baseline. 332 * @param location Location for UCM baseline. 333 * @return UCM baseline proxy. 334 */ 335 public CcBaseline ccBaseline(StpLocation location); 336 337 /** 338 * Create a proxy for a ClearCase UCM component. 339 * @param location Location for UCM component. 340 * @return UCM component proxy. 341 */ 342 public CcComponent ccComponent(StpLocation location); 343 344 /** 345 * Create a proxy for a ClearCase UCM project. 346 * @param location Location for UCM project. 347 * @return UCM project proxy. 348 */ 349 public CcProject ccProject(StpLocation location); 350 351 /** 352 * Create a proxy for a ClearCase UCM project folder. 353 * @param location Location for UCM project folder. 354 * @return UCM project folder proxy. 355 */ 356 public CcProjectFolder ccProjectFolder(StpLocation location); 357 358 /** 359 * Create a proxy for a ClearCase UCM stream. 360 * @param location Location for UCM stream. 361 * @return UCM stream proxy. 362 */ 363 public CcStream ccStream(StpLocation location); 364 365 /** 366 * Construct a proxy for the CcDirectory (directory in a ClearCase view) 367 * specified by the given location. 368 * @param loc the location of the directory 369 * @return a new CcDirectory proxy for a directory at this Location. 370 */ 371 public CcDirectory ccDirectory(StpLocation loc); 372 373 /** 374 * Construct a proxy for the CcFile (file in a ClearCase view) 375 * specified by the given location. 376 * @param loc the location of the file. 377 * @return a new CcFile proxy for a file at this Location. 378 */ 379 public CcFile ccFile(StpLocation loc); 380 381 /** 382 * Construct a directory version proxy for the given location. 383 * @param loc the location of the directory version. 384 * @return a new proxy for a directory version at this Location. 385 */ 386 public CcDirectoryVersion ccDirectoryVersion(StpLocation loc); 387 388 /** 389 * Construct a version proxy for the given location. 390 * @param loc the location of the version. 391 * @return a new proxy for a version at this Location. 392 */ 393 public CcVersion ccVersion(StpLocation loc); 394 395 /** 396 * Construct a element proxy for the given location. 397 * @param loc the location of the element. 398 * @return a new proxy for a element at this Location. 399 */ 400 public CcElement ccElement(StpLocation loc); 401 402 /** 403 * Construct a registry region proxy for the given location. 404 * @param loc the location of the registry region 405 * @return a new proxy for the registry region at this location 406 */ 407 public CcRegistryRegion ccRegistryRegion(StpLocation loc); 408 409 /** 410 * Construct a VOB proxy for the given location. 411 * @param loc the location of the VOB. 412 * @return a new proxy for a VOB at this Location. 413 */ 414 public CcVob ccVob(StpLocation loc); 415 416 /** 417 * Construct a VOB tag proxy for the given location. 418 * @param loc the location of the VOB tag. 419 * @return a new proxy for a VOB tag at this Location. 420 */ 421 public CcVobTag ccVobTag(StpLocation loc); 422 423 /** 424 * Construct a view proxy for the given location. 425 * @param loc the location of the view. 426 * @return a new proxy for a view at this Location. 427 */ 428 public CcView ccView(StpLocation loc); 429 430 /** 431 * Construct a view tag proxy for the given location. 432 * @param loc the location of the view tag. 433 * @return a new proxy for a view tag at this Location. 434 */ 435 public CcViewTag ccViewTag(StpLocation loc); 436 437 /** 438 * Construct a storage location proxy for the given location. 439 * @param loc the location of the storage location. 440 * @return a new proxy for a storage location at this Location. 441 */ 442 public CcStorageLocation ccStorageLocation(StpLocation loc); 443 444 /** 445 * Construct a attribute type proxy for the given location. 446 * @param loc the location of the attribute type. 447 * @return a new proxy for a attribute type at this Location. 448 */ 449 public CcAttributeType ccAttributeType(StpLocation loc); 450 451 /** 452 * Construct a branch type proxy for the given location. 453 * @param loc the location of the branch type. 454 * @return a new proxy for a branch type at this Location. 455 */ 456 public CcBranchType ccBranchType(StpLocation loc); 457 458 /** 459 * Construct a element type proxy for the given location. 460 * @param loc the location of the element type. 461 * @return a new proxy for a element type at this Location. 462 */ 463 public CcElementType ccElementType(StpLocation loc); 464 465 /** 466 * Construct a hyperlink type proxy for the given location. 467 * @param loc the location of the hyperlink type. 468 * @return a new proxy for a hyperlink type at this Location. 469 */ 470 public CcHyperlinkType ccHyperlinkType(StpLocation loc); 471 472 /** 473 * Construct a label type proxy for the given location. 474 * @param loc the location of the label type. 475 * @return a new proxy for a label type at this Location. 476 */ 477 public CcLabelType ccLabelType(StpLocation loc); 478 479 /** 480 * Construct an empty CcLockInfo object for using 481 * as a property to set on a CcVobResource. 482 * @return a new lock information object 483 */ 484 public CcLockInfo CcLockInfo(); 485 486 /** 487 * Construct a policy proxy for the given location. 488 * @param loc the location of the policy. 489 * @return a new proxy for a policy at this Location. 490 */ 491 public CcPolicy ccPolicy(StpLocation loc); 492 493 /** 494 * Construct a rolemap proxy for the given location. 495 * @param loc the location of the rolemap. 496 * @return a new proxy for a rolemap at this Location. 497 */ 498 public CcRolemap ccRolemap(StpLocation loc); 499 500 /** 501 * Construct a replica proxy for the given location. 502 * @param loc the location of the replica. 503 * @return a new proxy for a replica at this Location. 504 */ 505 public CcReplica ccReplica(StpLocation loc); 506 507 /** 508 * Construct a symbolic link proxy for the given location. 509 * @param loc the location of the symbolic link. 510 * @return a new proxy for a symbolic link at this Location. 511 */ 512 public CcSymlink ccSymlink(StpLocation loc); 513 514 /** 515 * Construct a reference to a task. 516 * @param uri Full URI of the task. 517 * @return a new task object. 518 */ 519 @Deprecated 520 public CcTask ccTask(String uri); 521 522 /** 523 * Construct a reference to a task. 524 * @param loc the location of the task 525 * @return a new task object. 526 */ 527 public CcTask ccTask(StpLocation loc); 528 529 /** 530 * Construct a trigger type proxy for the given location. 531 * @param loc the location of the trigger type. 532 * @return a new proxy for a trigger type at this Location. 533 */ 534 public CcTriggerType ccTriggerType(StpLocation loc); 535 536 /** 537 * Register a provider manager callback. 538 * <p> 539 * Various CM API operations invoke this callback in situations where a new 540 * provider may be required to complete an operation. For instance, if you 541 * have local web views hosted on different CCRC WAN servers, the 542 * {@link #getClientViewList} method will invoke this callback for each view 543 * to allow your application to associate the correct provider for that view. 544 * </p> 545 * <p> 546 * Various ClearQuest/UCM Integration operations may also invoke this 547 * callback to obtain a ClearQuest provider (CqProvider) instance. 548 * </p> 549 * <p> 550 * The CM API uses a default implementation of this callback if the caller 551 * does not register another one. 552 * </p> 553 * <p> 554 * This callback is shared among all CcProvider instances, so it only needs 555 * to be set once. 556 * </p> 557 * @param callback callback 558 * @return the previously registered provider manager callback 559 * @see CcProvider#getClientViewList(javax.wvcm.PropertyRequestItem.PropertyRequest) 560 */ 561 public CcProviderManagerCallback 562 registerProviderManagerCallback(CcProviderManagerCallback callback); 563 564 /** 565 * Register a callback to process ClearPrompt interaction requests. 566 * @param callback callback 567 */ 568 public void 569 registerClearPromptCallback(CcClearPromptCallback callback); 570 571 /** 572 * Register a callback to handle SSL certificate conflicts. 573 * The callback should be registered before attempting to authenticate over 574 * a secure (SSL) HTTP connection in order to correctly handle certificate 575 * exceptions. 576 * <p> 577 * This callback is shared among all CcProvider instances, so it only needs 578 * to be set once. 579 * </p> 580 * @param callback Trust Manager callback to handle certificate 581 * @throws WvcmException 582 */ 583 public void 584 registerTrustManagerCallback(CcTrustManagerCallback callback) 585 throws WvcmException; 586 587 /** 588 * Register a callback to handle a FileAreaLockedException. 589 * @param callback The new callback 590 * @return The previous callback 591 */ 592 public CcFileAreaLockedCallback registerCcFileAreaLockedCallback( 593 CcFileAreaLockedCallback callback) throws WvcmException; 594 595 /** 596 * Register a callback to handling manual merges. 597 * @param callback The new callback 598 * @return The previous callback 599 */ 600 public CcMergeHandlingCallback registerMergeHandlingCallback( 601 CcMergeHandlingCallback callback) throws WvcmException; 602 603 /** 604 * Register a callback to handle state transitions of ClearQuest records. 605 * The callback is invoked if the transition involves required 606 * fields that the user needs to provide. 607 * @param callback the callback we're registering 608 * @return the previous registered callback 609 */ 610 public CqRecordAutoTransitionCallback registerCqRecordAutoTransitionCallback( 611 CqRecordAutoTransitionCallback callback) throws WvcmException; 612 613 /** 614 * Register a callback to handle remote view agent operations. 615 * @param callback the remote view agent callback 616 * @throws WvcmException if the callback fails to register 617 */ 618 public void registerCcRemoteViewAgentCallback( 619 CcRemoteViewAgentCallback callback) throws WvcmException; 620 621 /** 622 * Handle the manual merge using the provider's callback. 623 * @return CheckinMergeHandling specifying how the checkin 624 * is to be handled after the merge 625 */ 626 public CheckinMergeHandling handleManualMerge( 627 CcFile file, 628 CcVersion fromVersion, 629 CcVersion toVersion) throws WvcmException; 630 631 /** 632 * Performs a server logout and invalidates this provider's current 633 * session. Attempting to reuse this provider will result 634 * in an attempt to create a new session using the previously 635 * registered authentication callback. 636 */ 637 public void doLogout() throws WvcmException; 638}