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