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