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