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 }