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