001 /* 002 * file StpProvider.java 003 * 004 * Licensed Materials - Property of IBM 005 * Restricted Materials of IBM 006 * 007 * com.ibm.rational.wvcm.stp.StpProvider 008 * 009 * (C) Copyright IBM Corporation 2004, 2008. 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 014 package com.ibm.rational.wvcm.stp; 015 016 import java.io.File; 017 import java.util.Date; 018 import java.util.Locale; 019 import java.util.Map; 020 import java.util.TimeZone; 021 022 import javax.wvcm.PropertyNameList.PropertyName; 023 import javax.wvcm.ProviderFactory.Callback; 024 import javax.wvcm.ProviderFactory.Callback.Authentication; 025 import javax.wvcm.Resource; 026 import javax.wvcm.ResourceList; 027 import javax.wvcm.WvcmException; 028 029 import com.ibm.rational.wvcm.stp.StpAccessControlEntry.AccessRight; 030 import com.ibm.rational.wvcm.stp.StpException.StpReasonCode; 031 import com.ibm.rational.wvcm.stp.cc.CcProvider; 032 import com.ibm.rational.wvcm.stp.cq.CqProvider; 033 import com.ibm.rational.wvcm.stpex.StpExEnumeration; 034 import com.ibm.rational.wvcm.stpex.annotation.RpcEnum; 035 036 037 /** 038 * StpProvider is an extension to the WVCM {@link javax.wvcm.Provider Provider} 039 * interface. It defines additional features supported by providers of this API 040 * that are common to both the ClearCase and ClearQuest domains. The StpProvider 041 * implementation <i>classes</i> that are available for instantiation are named 042 * by the String fields of this interface and its extensions and must be 043 * instantiated using the WVCM 044 * {@link javax.wvcm.ProviderFactory ProviderFactory} class. 045 * 046 * <p> 047 * For more flexible deployment of the API implementation, this library is 048 * partitioned into two domain-specific subcomponents or <i>subproviders</i>. 049 * There is at least one subprovider for each {@link StpProvider.Domain}. If 050 * access to a given domain is available along multiple paths--e.g., locally or 051 * via WAN--there will likely be one subprovider for each different access 052 * method. The services of a single subprovider interface will be available only 053 * if its subprovider class can be instantiated and such a subprovider can be 054 * instantiated only if the Rational product underlying the subprovider's domain 055 * has been properly installed and licensed. Each subprovider is autonomous, 056 * however, and this provider can be instantiated as long as at least one of its 057 * subproviders can be instantiated. If a client needs to know which domains are 058 * supported by an instance of this provider, it may use the 059 * {@link #isSupported(com.ibm.rational.wvcm.stp.StpProvider.Domain) isSupported} 060 * method to discover this and use {@link #getInstantiationErrors()} for more 061 * information why a subprovider failed to instantiated. 062 * </p> 063 * 064 * <p> 065 * {@link javax.wvcm.ProviderFactory#createProvider(String, 066 * javax.wvcm.ProviderFactory.Callback) ProviderFactory.createProvider} may be 067 * invoked with a non-<b>null</b> Callback object from which an {@link 068 * javax.wvcm.ProviderFactory.Callback.Authentication Authentication} object can 069 * be obtained for each authentication realm visited by the provider. The 070 * <b>realmId</b> provided to the 071 * {@link javax.wvcm.ProviderFactory.Callback#getAuthentication getAuthentication} 072 * method tells the user what credentials to provide. For ClearQuest, the realm 073 * identifier is the database set name (also known as the schema repository, 074 * master database, profile, or connection name); for ClearCase, the realm 075 * identifier is the URL for the server. 076 * </p> 077 * <p> 078 * This interface defines {@link StpCallback}, which extends 079 * {@link javax.wvcm.ProviderFactory.Callback} to allow the library to provide 080 * more information to the client's callback object when it is asked for 081 * credentials. 082 * </p> 083 * If no Callback instance is made available to the provider, operations that 084 * require an authenticated identity will fail unless the client has already 085 * provided an Authentication object to the provider via the 086 * {@link #setAuthentication(com.ibm.rational.wvcm.stp.StpProvider.Domain, String, javax.wvcm.ProviderFactory.Callback.Authentication, boolean) setAuthentication} 087 * method 088 * <p> 089 * Some subproviders require the client to tell them the URL for their 090 * associated server. That is accomplished using the 091 * {@link #setServerUrl(String) setServerUrl} method following Provider 092 * construction. Setting a server URL does not result in any validation that the 093 * server is accessible. A client must perform some operation (e.g., 094 * {@link javax.wvcm.Resource#doReadProperties(javax.wvcm.Feedback)}) to 095 * attempt to use, and hence check, a server URL. An attempt to create a 096 * Location associated with such a subprovider will fail if the server URL has 097 * not yet been specified. The server URL associated with a subprovider cannot 098 * be changed once it has been set via {@link #setServerUrl}. A new StpProvider 099 * instance must be created to reference a different server. 100 * </p> 101 * 102 * <p> 103 * When a Provider is instantiated via the ProviderFactory, a new, independent 104 * sequence of server interactions is started for a single user. The user of the 105 * provider is identified by the {@link javax.wvcm.ProviderFactory.Callback 106 * Callback} instance passed through the ProviderFactory to the Provider 107 * instance. 108 * </p> 109 * 110 * <p> 111 * A provider exists until it is explicitly terminated via the {@link 112 * #terminate() terminate()} method or it is implicitly terminated after a 113 * period of time in which no server interactions are initiated. It is always 114 * best to explicitly terminate a provider when it is no longer needed. This 115 * will free up resources on the server for others to use. 116 * </p> 117 */ 118 public interface StpProvider extends javax.wvcm.Provider 119 { 120 /** 121 * The name of a wvcm.javax.Provider implementation class to be used by 122 * clients that wish to interact with both ClearCase and ClearQuest in a 123 * single provider. The returned object supports only the StpProvider 124 * interface and therefore does not provide direct access to any 125 * domain-specific capabilities. Once this generic provider has been 126 * instantiated, the client can obtain a domain-specific provider extension 127 * using either the {@link #cqProvider()} method or the 128 * {@link #ccProvider()} method. 129 * <p> 130 * A client could create this provider to discover which team services are 131 * installed. The domain-specific provider access methods of this instance 132 * will return <b>null</b> if the domain-specific provider is not 133 * installed. 134 * 135 * @see com.ibm.rational.wvcm.stp.cq.CqProvider#CQ_ONLY_PROVIDER_CLASS 136 * @see com.ibm.rational.wvcm.stp.cc.CcProvider#CC_ONLY_PROVIDER_CLASS 137 */ 138 String PROVIDER_CLASS = 139 "com.ibm.rational.stp.client.internal.core.StpProviderImpl"; 140 141 /** 142 * @return The Provider extension associated with this StpProvider that 143 * implements the CcProvider interface; <b>null</b> if that Provider 144 * extension is not instantiated with this provider. 145 */ 146 CcProvider ccProvider(); 147 148 /** 149 * @return The Provider extension associated with this provider instance 150 * that implements the CqProvider interface; <b>null</b> if that 151 * Provider extension is not instantiated with this provider. 152 */ 153 CqProvider cqProvider(); 154 155 /** 156 * @return The Provider extension associated with this Provider instance 157 * that implements the StpProvider interface; will never be <b>null</b>. 158 */ 159 StpProvider stpProvider(); 160 161 /** 162 * Version information about the code that implements a portion of this 163 * product. This information is available for this Provider, and each of 164 * it's domain-specific subproviders. Version information for the server 165 * used to access a given repository is available as the PRODUCT_INFO 166 * property of those repositories. 167 * <p> 168 * Any field not applicable to the code for which information is requested 169 * will be an empty String (not <b>null</b>). 170 */ 171 static public interface StpProductInfo 172 { 173 /** 174 * @return The product build number, representing the finest granularity 175 * of the product version specification. 176 */ 177 String getBuildNumber(); 178 179 /** 180 * @return the e-mail address of the company for the current locale. 181 */ 182 String getCompanyEmailAddress(); 183 184 /** 185 * @return the full name of the company in the current locale. 186 */ 187 String getCompanyFullName(); 188 189 /** 190 * @return the name of the company in the current locale. 191 */ 192 String getCompanyName(); 193 194 /** 195 * @return the web address of the company for the current locale. 196 */ 197 String getCompanyWebAddress(); 198 199 /** 200 * @return the full product version identifier string, containing both 201 * the product version and the build number. 202 */ 203 String getFullProductVersion(); 204 205 /** 206 * @return the current fix pack version of the product. 207 */ 208 String getPatchVersion(); 209 210 /** 211 * @return the version identifier for the code, without build number. 212 */ 213 String getProductVersion(); 214 215 /** 216 * @return the ClearCase label used to uniquely identify each build. 217 */ 218 String getStageLabel(); 219 } 220 221 /** 222 * Returns the version information for the code implementing this Provider 223 * or one of its domain-specific subproviders. Each subprovider may make 224 * available additional version information as extensions to the 225 * StpProductInfo interface. 226 * 227 * @param domain The domain for which subprovider information is desired. If 228 * <b>null</b>, the version information for this interface and 229 * the shared components of this provider will be returned. 230 * 231 * @return An StpProductInfo structure (or a domain-specific extension 232 * thereof) containing version information for the code that 233 * implements this Provider (domain == <b>null</b>) or for the code 234 * that implements the subprovider for the domain specified by the 235 * domain argument. Will be <b>null</b> if a subprovider for the 236 * specified domain has not be instantiated. 237 */ 238 StpProductInfo stpProductInfo(Domain domain); 239 240 /** 241 * Constructs an StpRepository proxy for a repository at a specified 242 * location. 243 * 244 * @param location The location the new proxy is to refer to. A repository 245 * need not exist at this location, but the location must be 246 * otherwise valid for a repository. Must not be <b>null</b>. 247 * 248 * @return A new StpRepository proxy for a repository at the specified 249 * location. 250 */ 251 StpRepository stpRepository(StpLocation location); 252 253 /** 254 * Returns the Class object for the value type of a property identified by a 255 * PropertyName. Only properties specified explicitly by this API are 256 * supported. For all other properties, the {@link StpProperty#TYPE TYPE} 257 * meta-property may be useful. 258 * 259 * @param name The PropertyName for the property whose value class is being 260 * requested. 261 * 262 * @return a Class object identifying the value type of the property. 263 * Will be <b>null</b> if the PropertyName or value type is unknown. 264 */ 265 <T> Class<T> getPropertyValueClass(PropertyName<T> name); 266 267 /** 268 * Constructs a new proxy of a given type for a resource at a specified 269 * location, defining its {@link javax.wvcm.Resource#RESOURCE_IDENTIFIER} 270 * property value if known. 271 * 272 * <p> 273 * This method and StpResource.initMetaProperty provide the means for 274 * reconstructing a proxy previously archived to persistent storage by a 275 * client. When the proxy is archived, the client needs to save its 276 * location, its proxyType, the value of its RESOURCE_IDENTIFIER property 277 * (if defined), and the name and value of any other property/meta-property 278 * defined by the proxy that will be of interest to the client when the 279 * proxy is restored. 280 * </p> 281 * 282 * <p> 283 * To restore the proxy, invoke this method with the previously saved 284 * location, proxyType and RESOURCE_IDENTIFIER value to get an appropriate 285 * proxy object. Then use StpResource.initMetaProperty to move all of the 286 * remaining saved properties into the proxy. 287 * </p> 288 * 289 * @param location The resource location to which the new proxy is to refer. 290 * Must not be <b>null</b>. A resource need not exist at the 291 * specified location, but the location must otherwise be valid. 292 * @param proxyType A String specifying the type of proxy required. Must not 293 * be <b>null</b>. This value may be obtained either from a 294 * previous proxy for the resource using its {#link 295 * StpResource#proxyType()} method or from the Class object for 296 * the public interface that the new proxy should support using 297 * the {@link #proxyType(Class)} method. 298 * @param resourceIdentifier The value of the RESOURCE_IDENTIFIER property 299 * to be defined by the new proxy. This value would have to come 300 * from the RESOURCE_IDENTIFIER value of a pre-existing proxy. If 301 * <b>null</b>, the RESOURCE_IDENTIFIER property of the new 302 * proxy will not be defined. This property cannot be set after 303 * the proxy is constructed. 304 * 305 * @return A new proxy implementing the interfaces implied by the given 306 * proxyType parameter. Will not be <b>null</b>. 307 * 308 * @throws WvcmException Thrown if an StpLocation object cannot be obtained 309 * from this provider for the given location or if this provider 310 * cannot construct a proxy that implements the interface 311 * implied by the proxyType argument. 312 * 313 * @see StpResource#initMetaProperty(javax.wvcm.PropertyNameList.PropertyName, 314 * com.ibm.rational.wvcm.stp.StpProperty.MetaPropertyName, Object) 315 */ 316 StpResource buildProxy(StpLocation location, 317 String proxyType, 318 String resourceIdentifier) throws WvcmException; 319 320 321 /** 322 * Constructs a proxy implementing a given Resource interface class, using a 323 * String representation of the location. 324 * 325 * @param <T> The Resource interface type that the returned proxy is to 326 * implement. This is inferred from the type argument. 327 * @param type The Class object for the interface class that the returned 328 * proxy is to implement. 329 * @param str A String containing a specification for the location of the 330 * resource to be addressed by the returned proxy. The domain and 331 * namespace do not need to be specified in this location since 332 * they can be inferred from the desired proxy class. The 333 * repository field may also be elided if a default repository 334 * has been established for this provider. 335 * @return A proxy object that implements interface T. 336 * @throws WvcmException Thrown if an StpLocation object cannot be obtained 337 * from this provider for the given location or if this provider 338 * cannot construct a proxy that implements interface T. 339 * 340 * 341 * @see #setDefaultRepository(com.ibm.rational.wvcm.stp.StpProvider.Domain, StpRepository) 342 * @see javax.wvcm.Provider#buildProxy(Class, javax.wvcm.Location) 343 */ 344 <T extends Resource> T buildProxy(Class<T> type, 345 String str) throws WvcmException; 346 347 /** 348 * Computes the proxy type string required by 349 * {@link #buildProxy(StpLocation, String, String)} given the Class object 350 * for a proxy interface that the new proxy should implement. 351 * 352 * <p> 353 * Note that 354 * 355 * <pre> 356 * provider.buildProxy(location, 357 * provider.proxyType(Xyz.class), 358 * null) 359 * </pre> 360 * 361 * is equivalent to 362 * 363 * <pre> 364 * provider.xyz(location) 365 * </pre> 366 * 367 * where <code>provider.xyz()</code> is the proxy factory method that 368 * returns an implementation of the interface Xyz. This facilitates the 369 * building of proxies driven by compile-time data structures by eliminating 370 * the need for the client to develop program logic to switch on such data 371 * down to an appropriate proxy factory method call. 372 * </p> 373 * 374 * @param interfaceClass A public proxy class (i.e. any Class object for 375 * which 376 * javax.wvcm.Resource.class.isAssignableFrom(interfaceClass) is 377 * <b>true</b>). 378 * 379 * @return A String suitable for use as the proxyType argument to 380 * {@link #buildProxy(StpLocation, String, String)}. 381 * 382 * @throws WvcmException If the given Class is not an interface implemented 383 * by a proxy available from this provider. 384 * 385 * @see #buildProxy(Class, String) 386 * @see #buildProxy(StpLocation, String, String) 387 */ 388 String proxyType(Class<? extends Resource> interfaceClass) 389 throws WvcmException; 390 391 /** 392 * The domain to use if the domain field is omitted from location 393 * specifications. 394 * 395 * @return The StpProvider.Domain enumerator representing the domain that 396 * will be used if none is specified in a location specification. 397 */ 398 StpProvider.Domain getDefaultDomain(); 399 400 /** 401 * Establishes the default StpProvider.Domain for this provider. The default 402 * domain is applied when a location missing a domain is used to construct a 403 * proxy. 404 * 405 * @param domain The default StpProvider.Domain. Use <b>null</b> to disable 406 * the automatic filling-in of missing domain fields. 407 * 408 * @throws WvcmException if this provider does not support the given domain. 409 */ 410 void setDefaultDomain(Domain domain) throws WvcmException; 411 412 /** 413 * Returns the default repository associated with this provider. 414 * 415 * @return A proxy for the default repository established for this provider. 416 * Will be <b>null</b> if no default has been established. 417 */ 418 StpRepository getDefaultRepository(); 419 420 /** 421 * Establishes the default repository to be associated with this provider. 422 * The default repository is applied when a location missing a repository 423 * field is used to construct a proxy. 424 * 425 * @param repo The new default repository. May be <b>null</b> to indicate 426 * that there is no default repository associated with this 427 * provider. 428 * 429 * @throws WvcmException if this provider does not support the repository 430 * type of the given repository. 431 */ 432 void setDefaultRepository(StpRepository repo) throws WvcmException; 433 434 /** 435 * Returns the default repository of a specified domain associated with this 436 * provider. 437 * 438 * @param domain The StpProvider.Domain for which a default repository is 439 * being requested. 440 * 441 * @return A proxy for the default repository established for this provider. 442 * Will be <b>null</b> if no default has been established. 443 */ 444 StpRepository getDefaultRepository(StpProvider.Domain domain); 445 446 /** 447 * Establishes the default repository of a specified type to be associated 448 * with this provider. 449 * 450 * @param domain The StpProvider.Domain for which the given repository is to 451 * be the default. 452 * @param repo The new default repository. May be <b>null</b> to 453 * indicate that there is no default repository associated with 454 * this provider. 455 * 456 * @throws WvcmException if this provider does not support the given 457 * domain. 458 */ 459 void setDefaultRepository(StpProvider.Domain domain, 460 StpRepository repo) throws WvcmException; 461 462 /** 463 * The key for the initial argument map entry that contains the lowercase 464 * two-letter ISO-639 code for the language of the client locale for this 465 * provider. 466 * 467 * @see #setUserLocale(String) 468 * @see java.util.Locale 469 */ 470 String USER_LANGUAGE_KEY = "user-language"; 471 472 /** 473 * The key for the initial argument map entry that contains the uppercase 474 * two-letter ISO-3166 code for the country of the client locale for this 475 * provider. 476 * 477 * @see #setUserLocale(String) 478 * @see java.util.Locale 479 */ 480 String USER_COUNTRY_KEY = "user-country"; 481 482 /** 483 * The key for the initial argument map entry that contains the variant 484 * vendor and browser specific code for the client locale of this provider. 485 * 486 * @see #setUserLocale(String) 487 * @see java.util.Locale 488 */ 489 String USER_VARIANT_KEY = "user-variant"; 490 491 /** 492 * The key for the initial argument map entry that contains the server URL 493 * for this provider. 494 * 495 * @see #setServerUrl(String) 496 */ 497 String SERVER_URL_KEY = "server-url"; 498 499 /** 500 * The key for the initial argument map entry that indicates whether or not 501 * the provider is to operate disconnected from a server. 502 */ 503 String IS_DISCONNECTED_KEY = "is-disconnected"; 504 505 /** 506 * The value for the initial argument map entry that indicates 507 * the provider is not allowed to connected to a server. 508 */ 509 String IS_DISCONNECTED_VALUE = "true"; 510 511 /** 512 * The value for the initial argument map entry that indicates 513 * the provider is allowed to connect to a server. 514 */ 515 String NOT_DISCONNECTED_VALUE = "false"; 516 517 /** 518 * Establishes the default server URL for this provider, if one has not 519 * already been established. Within the lifetime of a given instance of an 520 * StpProvider, the server URL may be set only once. This method will throw 521 * an exception if the provider's server URL has already been set when 522 * applied. 523 * <p> 524 * The provider's server URL may also be applied as an initialization 525 * argument using the key {@link #SERVER_URL_KEY}. 526 * <p> 527 * The specified URL is used for ClearCase operations only. ClearQuest 528 * operations do not contact a server, but require an installation of 529 * ClearQuest on the client machine. 530 * 531 * @param url The URL used to contact the CM Server via this provider. Must 532 * not be <b>null</b>. This URL is not validated until the next 533 * "do" method that requires a URL is invoked. 534 * 535 * @throws WvcmException if a server URL has already been established for 536 * this provider. 537 */ 538 void setServerUrl(String url) throws WvcmException; 539 540 /** 541 * Returns the server URL for this provider, as set by an initialization 542 * argument or a previous call to setServerUrl(). If no default server URL 543 * has been established, returns <b>null</b>. 544 * 545 * @return the default server URL for this provider; may be <b>null</b>. 546 * 547 * @see #setServerUrl(String) 548 */ 549 String getServerUrl(); 550 551 /** 552 * Returns the Locale that is being used by this provider and is being 553 * passed to the server to identify the locale to use when performing 554 * locale-dependent operations for this provider. If not explicitly set by 555 * the client, the value returned by java.util.Locale#getDefault() is 556 * returned. 557 * 558 * @return A Locale object representing the locale to be used when 559 * performing locale-dependent operations for this provider. Will 560 * not be <b>null</b>. 561 */ 562 Locale getUserLocale(); 563 564 /** 565 * Defines the Locale that is to be used by this provider and passed to the 566 * server to identify the locale to use when performing locale-dependent 567 * operations for this provider. Does <i>not</i> set the default Locale of 568 * the JVM. 569 * 570 * @param locale A Locale object representing the locale to be used when 571 * performing locale-dependent operations for this provider. Must 572 * not be <b>null</b>; use java.util.Locale#getDefault() to use 573 * the native Locale of the client. 574 */ 575 void setUserLocale(Locale locale); 576 577 /** 578 * Returns the TimeZone that is being used by this provider and is being 579 * passed to the server to identify the time zone of the user. If not 580 * explicitly set by the client, java.util.TimeZone#getDefault() is 581 * returned. 582 * 583 * @return A TimeZone object representing the time zone to be used when 584 * performing date translations for this provider. Will not be 585 * <b>null</b>. 586 */ 587 TimeZone getUserTimeZone(); 588 589 /** 590 * Defines the time zone that is to be used by this provider and passed to 591 * the server for this provider. Does NOT set the default TimeZone of the 592 * JVM. 593 * 594 * @param timeZone A TimeZone object representing the time zone to be used 595 * when performing date translation for this provider. Must not 596 * be <b>null</b>; use java.util.TimeZone#getDefault() to use 597 * the native time zone of the client. 598 */ 599 void setUserTimeZone(TimeZone timeZone); 600 601 /** 602 * The type of a subprovider. 603 */ 604 static public enum Domain implements StpExEnumeration 605 { 606 /** An unspecified domain */ 607 @RpcEnum(id=3, simpleName="") 608 NONE(""), 609 610 /** An invalid domain */ 611 @RpcEnum(id=2, simpleName="<invalid>") 612 INVALID("<invalid>"), 613 614 /** The ClearCase domain. */ 615 @RpcEnum(id=0, simpleName="cc") 616 CLEAR_CASE("cc"), 617 618 /** The ClearQuest domain */ 619 @RpcEnum(id=1, simpleName="cq") 620 CLEAR_QUEST("cq"); 621 622 /** 623 * Returns the Domain object that matches a given domain-field symbol 624 * 625 * @param symbol A String containing the domain-field symbol to be 626 * converted to a Domain object. 627 * 628 * @return A Domain object that matches the given symbol. Will be <b> 629 * INVALID</b> if no Domain object matches the given symbol. 630 */ 631 public static final Domain fromSymbol(String symbol) 632 { 633 if (symbol != null) { 634 for (Domain d : values()) 635 if (symbol.compareToIgnoreCase(d.toSymbol()) == 0) 636 return d; 637 } 638 639 return INVALID; 640 } 641 642 /** 643 * @return Returns the word token to use in the domain field of a 644 * location specification for this Domain. 645 */ 646 public String toSymbol() 647 { 648 return m_symbol; 649 } 650 651 /** 652 * Creates a new Domain object. 653 * 654 * @param symbol The symbol used for this StpProvider.Domain when 655 * forming a location specification. 656 */ 657 private Domain(String symbol) 658 { 659 m_symbol = symbol; 660 } 661 662 /* The domain-field symbol that corresponds to the Domain enumerator */ 663 private String m_symbol; 664 } 665 666 /** 667 * Returns an indication of whether or not this provider is permitted to 668 * communicate with a server. 669 * 670 * @return <b>true</b> if this provider is permitted to connect to a 671 * server to perform operations; <b>false</b> otherwise. 672 */ 673 boolean getIsDisconnected(); 674 675 /** 676 * Grants or denies this provider the ability to connect to a server while 677 * performing tasks for the client. 678 * <p> 679 * Note: Setting this attribute does <i>not</i> cause an interaction with 680 * the server to initialize or terminate the session. Use the 681 * {@link #setAuthentication(com.ibm.rational.wvcm.stp.StpProvider.Domain, String, javax.wvcm.ProviderFactory.Callback.Authentication, boolean) setAuthentication} 682 * method to control session lifetimes. 683 * 684 * @param isDisconnected <b>true</b> if this provider is not to connect to 685 * server; <b>false</b> if this provider may connect to a 686 * server. 687 */ 688 void setIsDisconnected(boolean isDisconnected); 689 690 /** 691 * Returns the callback object passed to the ProviderFactory during the 692 * instantiation or initialization of this provider. 693 * 694 * <p> 695 * The provider maintains a mapping between authentication realms and user 696 * credentials and this callback object is used to populate that map. When 697 * the library generates a request targeting a specific Location, it will 698 * attempt to deduce the realm id from the Location (through its 699 * subprovider). 700 * </p> 701 * 702 * <ol> 703 * <li>If a realm id can be deduced, the provider will consult the 704 * realm-credential map to obtain the credentials for that realm id. 705 * <ul> 706 * <li>If no credentials are found for the realm, this authentication 707 * callback will be called passing the realm id to the client. The returned 708 * credentials will then be entered into the realm-credential map and the 709 * request will proceed with those credentials.</li> 710 * <li>If credentials are found for the realm, the request proceeds with 711 * those credentials.</li> 712 * </ul> 713 * </li> 714 * <li>If the realm id cannot be deduced from the Location, the value of 715 * the AUTHENTICATION_REALM property will be examined. 716 * <ul> 717 * <li>If the AUTHENTICATION_REALM property is defined, the request will be 718 * submitted using its value as the realm id as outlined in bullet 1.</li> 719 * <li>If the AUTHENTICATION_REALM property is not defined, the library 720 * issues the request without credentials. 721 * 722 * <ul> 723 * <li>If the request succeeds, the credentials used are mapped to the 724 * value returned in the AUTHENTICATION_REALM property (if the response 725 * contains this property).</li> 726 * <li>If the request fails, the request will be resubmitted using the 727 * realm id provided in the error response as outlined in bullet 1.</li> 728 * </ul> 729 * </li> 730 * </ul> 731 * </li> 732 * <li>If a request fails authentication when using credentials from the 733 * realm-credential map, this authentication callback is called again for a 734 * new set of credentials for the realm. 735 * <ul> 736 * <li>If a new set of credentials is not returned, the request will fail 737 * with an authentication exception.</li> 738 * <li>If new credentials are returned, the realm-credential map is updated 739 * with the new credentials and the request is retried as outlined in bullet 740 * 1.</li> 741 * </ul> 742 * </li> 743 * </ol> 744 * 745 * <p> 746 * Rather than embedding the policy for establishing the default credentials 747 * in the library, the library always uses the authentication callback (with 748 * a <b>null</b> realm) to obtain from the client the <i>default credentials</i> 749 * to use. The client can then implement the strategy it wishes to use to 750 * come up with the default credentials. 751 * </p> 752 * 753 * @return The call-back object used to initiate the provider. 754 */ 755 javax.wvcm.ProviderFactory.Callback callback(); 756 757 /** 758 * Returns information about the failures, if any, to instantiate providers 759 * for specific product domains. If the map returned contains no information 760 * (i.e. <b>null</b>) for a given StpProvider.Domain, it is safe to use the 761 * type-specific interfaces for that domain. 762 * <p> 763 * Some domains may be served by more than one type of provider--ClearQuest 764 * repositories, for example, can be accessed via the network using one 765 * provider or accessed via an installed ClearQuest application using 766 * another. The StpProvider.Domain entry in the returned error map will be 767 * <b>null</b> if at least one subprovider for the type could be 768 * instantiated. It will be non-<b>null</b> only if <i>all</i> 769 * subproviders for that domain failed to instantiate. 770 * <p> 771 * For more thorough diagnosis of instantiation problems, an entry will be 772 * found in the map associated with the toSymbol() String value of a 773 * StpProvider.Domain if <i>any</i> provider for that type failed to 774 * instantiate. 775 * 776 * @return A mapping from StpProvider.Domain objects and String objects to 777 * an StpException object containing pertinent information about the 778 * failed attempt to instantiate the provider for the given type of 779 * repository. Will never be <b>null</b>, but may be empty or 780 * sparse. 781 */ 782 Map<Object, StpException> getInstantiationErrors(); 783 784 /** 785 * Terminates this provider's association with the servers that it is 786 * actively tracking, releasing any resources it has accumulated as a result 787 * of that tracking. 788 * 789 * <p> 790 * Calling this method marks all of the provider's proxy and location 791 * objects as invalid, and so all client-side references should be 792 * abandoned; any subsequent method calls on the Provider object yields an 793 * UnsupportedOperationException exception. Thus you should typically call 794 * this method immediately prior to the exit of the owning thread or 795 * process. 796 * </p> 797 * 798 * @throws WvcmException if the accumulated resources cannot be disposed of. 799 */ 800 void terminate() throws WvcmException; 801 802 /** 803 * Updates the realm-authentication map maintained by this Provider by 804 * adding or deleting associations between realm strings and Authentication 805 * objects from which user credentials for that realm can be obtained when 806 * they are needed by an operation. 807 * <p> 808 * If a Callback object has been assigned to the Provider, the credential 809 * processing proceeds as follows: 810 * <p> 811 * When credentials are needed to perform an operation in a specific realm, 812 * the Provider first consults the realm-authentication map for an 813 * Authentication object associated with the realm. If there is no 814 * Authentication object registered in the map, the Provider calls the 815 * {@link javax.wvcm.ProviderFactory.Callback#getAuthentication(String, int) Callback.getAuthentication()} 816 * method with a retryCount of 0. If there is an Authentication object in 817 * the map for the realm and the credentials it provides are rejected by the 818 * server, the Authentication object is removed from the map and the 819 * Provider calls Callback.getAuthentication() (with a retryCount > 1) to 820 * obtain a new Authentication object to associate with the realm. 821 * <p> 822 * If no Callback object has been assigned to the Provider, the credential 823 * processing proceeds as follows: 824 * <p> 825 * When credentials are needed to perform an operation in a specific realm, 826 * the Provider consults the realm-authentication map for an Authentication 827 * object associated with the realm. If there is no Authentication object 828 * registered in the map no credentials will be passed to the server. If the 829 * chosen Authentication object is rejected by the server, the Provider 830 * throws an exception to terminate the operation. 831 * <p> 832 * The Provider adds an entry to the realm-authentication map only after it 833 * has determined that a given Authentication object actually provides valid 834 * credentials in the realm. It will remove an entry from the map when it 835 * determines that the Authentication object in the map cannot provide valid 836 * credentials (and there is a Callback object from which to get a 837 * replacement). 838 * <p> 839 * The client may make entries in the realm-authentication map with or 840 * without validating those entries. Validation implies a round-trip to the 841 * server for the realm(s) specified. If the realm-authentication map 842 * contains an entry for an affected realm, the corresponding server is 843 * notified to log the user out of that realm. If the Authentication object 844 * is not <b>null</b>, the server is notified to log the user into the 845 * specified realm with the new set of credentials. 846 * 847 * In this release, the realm string for a ClearQuest database is just the 848 * database set name. It is assumed that all user databases defined in that 849 * database set use the same credentials as stored in the database set. (In 850 * fact, there are times in the history of a given user database when the 851 * credentials it accepts for a user differ from those stored in its 852 * database set. This corner case is not supported in this release.) 853 * 854 * A full user database name may be passed to this method, but the 855 * authentication map remembers only the Db-Set portion of it. The user 856 * database portion of the name, if present, is used only when doValidation 857 * is true. In that case, if the realm parameter includes a user database 858 * name, then the user is logged into or out of that user database (not the 859 * database set). 860 * 861 * @param domain The Domain for which authentication is being provided. Must 862 * not be <b>null</b> unless the authentication parameter is 863 * also <b>null</b>. In that case, the Authentication object is 864 * removed for the given realm in all domains. 865 * @param Realm A String identifying the realm for which authentication is 866 * being provided. (This is the string passed as the realm 867 * parameter to Callback.getAuthentiation()) Must not be <b>null</b> 868 * unless the authentication parameter is also <b>null</b>, in 869 * which case the authentications for all realms (in the 870 * specified domains) will be removed from the map. 871 * @param authentication A ProviderFactory.Authentication instance that can 872 * provide any credentials needed for the user in the specified 873 * realm of the specified domain(s). If <b>null</b>, any 874 * existing authentication associated with the specified realm(s) 875 * will be removed from the map. 876 * @param doValidation If <b>false</b>, only the Provider map will be 877 * updated; if <b>true</b>, each impacted domain server will be 878 * contacted immediately to inform it of the change in 879 * credentials. The user will be logged off the realm(s) already 880 * in the map and, if the Authentication object is not <b>null</b> 881 * a new logon will be attempted using the given credentials. 882 * @throws WvcmException 883 * <ul> 884 * <li>if doValidation is <b>true</b>, the provided 885 * Authentication object is not <b>null</b>, and the 886 * credentials it provides are rejected by a server, or 887 * <li> if doValidation is <b>true</b>, the provided 888 * Authentication object is <b>null</b>, and a server cannot 889 * terminate the provider of (i.e. logoff) a once-active user. 890 * </ul> 891 */ 892 void setAuthentication(Domain domain, 893 String Realm, 894 Authentication authentication, 895 boolean doValidation) throws WvcmException; 896 897 /** 898 * Returns the Authentication object currently associated with a given realm 899 * string in a given Domain. 900 * 901 * @param domain The Domain for which authentication is being requested; 902 * Must not be <b>null</b>; 903 * @param realm The realm for which authentication is being requested; Must 904 * not be <b>null</b>. 905 * @return The Authentication object currently associated with the given 906 * Domain and realm; <b>null</b> if no such association currently 907 * exists. 908 */ 909 Authentication getAuthentication(Domain domain, 910 String realm); 911 912 /** 913 * An extended version of javax.wvcm.ProviderFactory.Callback whose 914 * getAuthentication method provides additional information to the client 915 * when being asked for credentials. If the Callback object passed to this 916 * Provider implements this interface, its getAuthenticationEx will be 917 * called rather than Callback.getAuthentication each time an Authentication 918 * object is required. 919 */ 920 public interface StpCallback extends Callback 921 { 922 /** 923 * An extended version of Callback.getAuthentication that provides 924 * additional information to the client when being asked for 925 * credentials. If the Callback object passed to this Provider 926 * implements this interface, the getAuthenticationEx will be called 927 * rather than getAuthentication each time an Authentication object is 928 * required. 929 * 930 * @param domain The Domain that is requesting credentials. 931 * @param realm an identifier for the authentication realm that is 932 * requesting credentials. A single provider instance can 933 * access resources in different authentication realms, so 934 * the user must be provided with the name of the 935 * authentication realm in order to determine what 936 * credentials to provide. 937 * @param retryCount the number of times the provider has unsuccessfully 938 * attempted to get authentication for this operation. This 939 * parameter helps the client decide when to provide a more 940 * detailed authentication dialog, or potentially abort the 941 * operation rather than making additional attempts to get 942 * credentials from the user. 943 * @param provider The StpProvider instance that is requesting 944 * authentication. 945 * @param failure The WvcmException generated by the attempt to log onto 946 * the realm using the Authentication object last provided by 947 * this Callback. This will be <b>null</b> when retryCount 948 * is zero. 949 * @return user and password authentication interface. Must not be 950 * <b>null</b> 951 * @throws WvcmException if the user or client wish to abort the 952 * authentication request. Note: <i>this method throwing an 953 * exception is the only way the authentication retry 954 * process can be terminated.</i> The provider has no 955 * preset retry limits or conditions and will repeatedly 956 * call this Callback object until a valid set of 957 * credentials is returned or this method throws an 958 * exception. 959 */ 960 public Authentication getAuthenticationEx(Domain domain, 961 String realm, 962 int retryCount, 963 StpProvider provider, 964 WvcmException failure) 965 throws WvcmException; 966 } 967 968 /** 969 * If the Callback object provided to an StpProvider implements this 970 * interface, the callback will be notified when an Authentication object 971 * returned by the Callback's getAuthentication() method is successfully 972 * verified to be valid. 973 */ 974 public interface NotifyAuthenticatedOption 975 { 976 /** 977 * Notifies the Callback object that an authentication object that it 978 * previously returned has been found to be valid for the specified 979 * domain, realm, and provider. If the provided credentials were not 980 * valid, the Callback's getAuthentication method will be called another 981 * time for a new set of credentials. 982 * 983 * @param domain The Domain that had requested credentials. 984 * @param realm an identifier for the authentication realm that had 985 * requested credentials. 986 * @param provider The StpProvider instance that had requested 987 * authentication. 988 * @param authentication The credentials that were returned by the 989 * Callback and were accepted by the provider for the given 990 * domain and realm. 991 */ 992 void notifyAuthenticated(Domain domain, 993 String realm, 994 StpProvider provider, 995 Authentication authentication); 996 } 997 998 /** 999 * If the Callback object provided to an StpProvider implements this 1000 * interface, the callback will be notified when the server reports that 1001 * it is too busy to respond to a request. 1002 */ 1003 public interface NotifyBusyOption 1004 { 1005 /** 1006 * A non-<b>null</b> busyFailure argument indicates the server has 1007 * reported that it is too busy to process a request. This method 1008 * returns if and when that request is to be attempted again. It throws 1009 * an exception to cancel the request. 1010 * <p> 1011 * A <b>null</b> busyFailure argument indicates that a request that was 1012 * re-attempted has now been processed by the server. In this case, this 1013 * method must return and should not throw an exception if it wants the 1014 * operation to continue. This call with a <b>null</b> busyFailure 1015 * argument is intended to give the callback an opportunity to take down 1016 * any user presentation put up to indicate the operation was waiting 1017 * for the server to respond. 1018 * <p> 1019 * This method is <i>not</i> called for every server request, even with 1020 * a <b>null</b> busyFailure argument. It is invoked only when the 1021 * server reports that it is too busy to process a request. 1022 * <p> 1023 * The method returns no value. If the client wants to retry the request 1024 * a little later, the callback should put the current thread to sleep 1025 * for a while to give the server time to catch up. Whenever this method 1026 * returns, the request will be retried immediately. 1027 * <p> 1028 * If the client does not want to retry the request, it must throw an 1029 * exception, such as the busyFailure exception passed into the method. 1030 * 1031 * @param domain 1032 * The Domain in which the request was being executed. 1033 * @param realm 1034 * The authentication realm in which the request was being 1035 * executed. 1036 * @param provider 1037 * The provider that is attempting to perform the request on 1038 * the server. 1039 * @param opStartTime 1040 * A Date object representing the time at which the request 1041 * was first initiated. This object is unique to the request 1042 * being executed and the same object is passed to every 1043 * invocation of this method resulting from any attempt to 1044 * re-exeucte the request. Thus, it could be used by the 1045 * callback as the key to a map containing progress history 1046 * for this operation. It could also be compared to the 1047 * current time to limit the time the client waits for the 1048 * server. 1049 * @param busyFailure 1050 * The exception returned by the server to report that it was 1051 * too busy to process the request. If this method returns 1052 * normally and on the subsequent re-try the server processes 1053 * the request this method is called with <b>null</b> for 1054 * this argument. If the server still reports that it is busy 1055 * this method will be called again with a non-null argument. 1056 * <p> 1057 * A <b>null</b> value for this argument <i>does not</i> 1058 * necessarily mean that the operation was successful. It 1059 * just means that the server was finally able to process the 1060 * request. For example, after the server looks at the 1061 * request, it may determine that authentication is required 1062 * before proceeding or it may find something else wrong with 1063 * it. This callback will be invoked to indicate that the 1064 * busy state has been removed <i>before</i> processing the 1065 * server response, whether it be positive or negative. 1066 * <p> 1067 * If completion of the operation requires multiple 1068 * interactions with the server (as when authentication is 1069 * needed), any of those interactions could find the server 1070 * busy again. Hence, a <b>null</b> busyFailure argument 1071 * <i>does not</i> indicate that this method will not be 1072 * called another time for the same request (opStartTime). 1073 * @throws WvcmException to abort the request. 1074 */ 1075 void notifyBusy(Domain domain, 1076 String realm, 1077 StpProvider provider, 1078 Date opStartTime, 1079 WvcmException busyFailure) throws WvcmException; 1080 } 1081 1082 /** 1083 * Set the HTTP proxy host and port for all future calls from this 1084 * client. 1085 * @param host Name of proxy host. 1086 * @param port Port number of proxy on that host. 1087 */ 1088 void setHttpProxy(String host, 1089 String port); 1090 1091 /** 1092 * @return A String containing the name of the HTTP proxy host used by this 1093 * provider, <b>null</b> if not previously set. 1094 */ 1095 String getHttpProxyHost(); 1096 1097 /** 1098 * @return A String containing the port number on the HTTP proxy host used 1099 * by this provider, <b>null</b> if not previously set. 1100 */ 1101 String getHttpProxyPort(); 1102 1103 /** 1104 * Determines whether a given domain is supported by this provider. It is 1105 * safe to use the type-specific interfaces for a supported domain. 1106 * 1107 * @param domain - the domain in question 1108 * 1109 * @return <b>true</b> if the domain is supported; <b>false</b> otherwise. 1110 * 1111 * @see #getInstantiationErrors() 1112 * @see #ccProvider() 1113 * @see #cqProvider() 1114 */ 1115 boolean isSupported(StpProvider.Domain domain); 1116 1117 /** 1118 * Constructs an StpLocation from its string representation 1119 * 1120 * @param location A string satisfying the syntax for a CM API location 1121 * specification. 1122 * 1123 * @return An StpLocation object capturing the fields specified in the given 1124 * location specification string. 1125 * 1126 * @throws WvcmException If the string is <b>null</b> or empty. 1127 */ 1128 StpLocation stpLocation(String location) throws WvcmException; 1129 1130 /** 1131 * Constructs an StpLocation from the individual fields of a location 1132 * specification that follows the user-friendly object selector scheme 1133 * 1134 * @param domain the Domain. Must not be INVALID 1135 * @param namespace the Namespace for the location. Must not be INVALID, 1136 * REPO, or FAST 1137 * @param name the segmented object name field. Each segment of the name 1138 * must be encoded as required by the namespace. May be <b>null</b> 1139 * or empty to form the root of the namespace in a repository 1140 * resource. 1141 * @param repo the repository name. Each segment of the name must be encoded 1142 * as required by the namespace. 1143 * 1144 * @return An StpLocation object with the specified fields. 1145 * 1146 * @throws WvcmException Thrown if the location String composed from the 1147 * given fields is not in the correct form. StpReasonCode = 1148 * {@link StpException.StpReasonCode#INVALID_OBJECT_SELECTOR} 1149 */ 1150 StpLocation userFriendlySelector(StpProvider.Domain domain, 1151 StpLocation.Namespace namespace, 1152 String name, 1153 String repo) throws WvcmException; 1154 1155 /** 1156 * Constructs an StpLocation from a string representation assuming the 1157 * Location is to be used exclusively in a specified domain. In particular, 1158 * if there is no scheme prefix or the given scheme prefix would not be 1159 * recognized in the given domain, the input is forced to be a pname (in the 1160 * PNAME_IMPLIED namespace). 1161 * 1162 * @param domain The domain in which the location is to be used. Must not be 1163 * <b>null</b>, NONE, or INVALID. 1164 * @param pname The string representation for a location to be used in the 1165 * given domain. Must not be <b>null</b> or empty. 1166 * @return An StpLocation appropriate for the given domain. 1167 * @throws WvcmException if the input is <b>null</b> or empty or an otherwise 1168 * acceptable input specifies a domain different from that 1169 * requested. 1170 * 1171 */ 1172 StpLocation stpLocation(Domain domain, 1173 String pname) throws WvcmException; 1174 1175 /** 1176 * Constructs an StpLocation from the individual fields of a location 1177 * specification that follows the stable selector scheme. 1178 * 1179 * @param domain The domain of the resource. 1180 * @param rType The resource type segment of the name. 1181 * @param objectId The object id of the resource. 1182 * @param repoId The repository id of the resource. 1183 * 1184 * @return A stable-selector scheme StpLocation object with the specified 1185 * fields 1186 * 1187 * @throws WvcmException If the location is not well-formed. 1188 */ 1189 StpLocation stableSelector(StpProvider.Domain domain, 1190 String rType, 1191 String objectId, 1192 String repoId) throws WvcmException; 1193 1194 /** 1195 * Constructs a path-scheme location for a specified scheme and 1196 * domain. 1197 * @param domain The domain type of the repository 1198 * @param namespace the particular path-scheme for the location 1199 * @param path The pathname of the resource. Each type of scheme has its 1200 * own encoding requirements. 1201 * 1202 * @return An StpLocation object for the specified repository 1203 * 1204 * @throws WvcmException If the selector is ill-formed 1205 */ 1206 StpLocation pathLocation(StpProvider.Domain domain, 1207 StpLocation.Namespace namespace, 1208 String path) throws WvcmException; 1209 1210 /** 1211 * Constructs a PNAME StpLocation for a pathname to a file system 1212 * object. 1213 * 1214 * <p> 1215 * Shorthand for 1216 * </p> 1217 * 1218 * <pre> 1219 * stpLocation(null, Namespace.PNAME, encodeFile(file.getPath()), null). 1220 * </pre> 1221 * 1222 * @param file Abstract pathname. The file system object need not exist. 1223 * 1224 * @return An StpLocation object with the specified fields 1225 * 1226 * @throws WvcmException Thrown if an error occurs. 1227 */ 1228 StpLocation filePathLocation(File file) throws WvcmException; 1229 1230 /** 1231 * Constructs a PNAME Location for a pathname to a file system 1232 * object of a specific domain. 1233 * 1234 * <p> 1235 * Shorthand for 1236 * </p> 1237 * 1238 * <pre> 1239 * stpLocation(domain, Namespace.PNAME, encodeFile(file.getPath()), null). 1240 * </pre> 1241 * 1242 * @param domain The StpProvider.Domain of the resource referenced by the 1243 * given file object. 1244 * @param file Abstract pathname. The file system object need not exist. 1245 * 1246 * @return An StpLocation object with the specified fields 1247 * 1248 * @throws WvcmException Thrown if an error occurs. 1249 */ 1250 StpLocation filePathLocation(StpProvider.Domain domain, 1251 File file) throws WvcmException; 1252 1253 /** 1254 * Encodes a plain text string to be a single segment of the object name 1255 * field of a selector by escaping the segment delimiters, repository field 1256 * separator, and the escape character within the string. 1257 * 1258 * <p> 1259 * Note 1: This method is provided as a convenience to clients. It is not 1260 * used by the implementation of the StpLocation class, which does not 1261 * change the encoding of segments unless explicitly stated in method 1262 * documentation. 1263 * 1264 * @param str The String containing the plain text of the segment to be 1265 * encoded. 1266 * 1267 * @return The encoded form of the input String that is suitable for use as 1268 * a segment of the name field within an object selector. 1269 */ 1270 String encodeSegment(String str); 1271 1272 /** 1273 * Undoes the character encoding performed by the {@link #encodeSegment 1274 * encodeSegment} method. This decoding does not need to be performed 1275 * segment by segment as it is only replacing the escape character from each 1276 * escaped character digraph. 1277 * 1278 * @param str The segment of the selector to be decoded. 1279 * 1280 * @return The decoded (plain text) segment. 1281 */ 1282 String decodeSegment(String str); 1283 1284 /** 1285 * Construct an StpAccessControlEntry value 1286 * 1287 * @param principal The group, user, or role to which access is to be 1288 * granted. 1289 * @param accessRights The access rights to be granted; must not be <b>null</b> 1290 * or empty. 1291 * @return an instance of StpAccessControlEntry 1292 */ 1293 StpAccessControlEntry buildAccessControlEntry(StpPrincipal principal, 1294 AccessRight... accessRights); 1295 1296 /** 1297 * Constructs, logs, and throws an StpException. 1298 * 1299 * @param reasonCode The StpException.StpReasonCode to be associated with 1300 * the exception. Must not be <b>null</b>. 1301 * @param messageData A structured message object or the data needed to 1302 * construct one. The message data is passed as an Object[]{ 1303 * message-key, {arg1,...,argN}} if the message format is 1304 * parameterized or as a String containing the message key if it 1305 * is not. If the message-key is not found in the resource bundle 1306 * it is treated as the format string. Must not be <b>null</b>. 1307 * @param resource The Resource argument to WvcmException 1308 * @param nestedExceptions The Throwable[] argument to WvcmException 1309 */ 1310 void raise(StpReasonCode reasonCode, 1311 Object messageData, 1312 Resource resource, 1313 Throwable... nestedExceptions) throws WvcmException; 1314 1315 /** 1316 * Constructs, logs, and throws an StpPropertyException. 1317 * 1318 * @param stpReasonCode The StpReasoCode that defines this exception. 1319 * @param messageData A structured message object or the data needed to 1320 * construct one. The message data is passed as an Object[]{ 1321 * message-key, {arg1,...,argN}} if the message format is 1322 * parameterized or as a String containing the message key if it 1323 * is not. If the message-key is not found in the resource bundle 1324 * it is treated as the format string. Must not be <b>null</b>. 1325 * @param resource The resource causing this exception. 1326 * @param nestedExceptions Subordinate Exceptions that lead to the throwing 1327 * of this StpException. 1328 * @param propertyName The name of the property with which this exception is 1329 * associated. 1330 */ 1331 public void raise(StpReasonCode stpReasonCode, 1332 Object messageData, 1333 Resource resource, 1334 PropertyName propertyName, 1335 Throwable... nestedExceptions) throws WvcmException; 1336 1337 /** 1338 * Constructs, logs, and throws an StpPartialResultsException. 1339 * 1340 * <p> 1341 * The reason code is always StpReasonCode.PARTIAL_RESULTS. 1342 * 1343 * @param messageData A structured message object or the data needed to 1344 * construct one. The message data is passed as an Object[]{ 1345 * message-key, {arg1,...,argN}} if the message format is 1346 * parameterized or as a String containing the message key if it 1347 * is not. If the message-key is not found in the resource bundle 1348 * it is treated as the format string. Must not be <b>null</b>. 1349 * @param resource The resource that caused the exception. 1350 * @param okList A list of resources that were successfully retrieved 1351 * and processed. Can be <b>null</b> or empty. 1352 * @param enumerationError <b>true</b> if accessing some of the resources 1353 * named as targets was not attempted. 1354 * @param name The PropertyName of the property with which this exception is 1355 * associated. May be <b>null</b> if the exception is not associated 1356 * with a property. 1357 * @param nestedExceptions A list of exceptions each of which identifies a 1358 * resource that caused an error when accessed. 1359 */ 1360 public void raise(Object messageData, 1361 Resource resource, 1362 ResourceList<? extends Resource> okList, 1363 boolean enumerationError, 1364 PropertyName name, 1365 Throwable... nestedExceptions) throws WvcmException; 1366 }