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.Calendar; 018 import java.util.Date; 019 import java.util.Locale; 020 import java.util.Map; 021 import java.util.TimeZone; 022 023 import javax.wvcm.Resource; 024 import javax.wvcm.ResourceList; 025 import javax.wvcm.WvcmException; 026 import javax.wvcm.PropertyNameList.PropertyName; 027 import javax.wvcm.ProviderFactory.Callback; 028 import javax.wvcm.ProviderFactory.Callback.Authentication; 029 030 import com.ibm.rational.wvcm.stp.StpAccessControlEntry.AccessRight; 031 import com.ibm.rational.wvcm.stp.StpException.StpReasonCode; 032 import com.ibm.rational.wvcm.stp.cc.CcProvider; 033 import com.ibm.rational.wvcm.stp.cq.CqProvider; 034 import com.ibm.rational.wvcm.stpex.StpExEnumeration; 035 import com.ibm.rational.wvcm.stpex.StpExEnumerationBase; 036 037 038 /** 039 * StpProvider is an extension to the WVCM {@link javax.wvcm.Provider Provider} 040 * interface. It defines additional features supported by providers of this API 041 * that are common to both the ClearCase and ClearQuest domains. The StpProvider 042 * implementation <i>classes</i> that are available for instantiation are named 043 * by the String fields of this interface and its extensions and must be 044 * instantiated using the WVCM 045 * {@link javax.wvcm.ProviderFactory ProviderFactory} class. 046 * 047 * <p> 048 * For more flexible deployment of the API implementation, this library is 049 * partitioned into two domain-specific subcomponents or <i>subproviders</i>. 050 * There is at least one subprovider for each {@link StpProvider.Domain}. If 051 * access to a given domain is available along multiple paths--e.g., locally or 052 * via WAN--there will likely be one subprovider for each different access 053 * method. The services of a single subprovider interface will be available only 054 * if its subprovider class can be instantiated and such a subprovider can be 055 * instantiated only if the Rational product underlying the subprovider's domain 056 * has been properly installed and licensed. Each subprovider is autonomous, 057 * however, and this provider can be instantiated as long as at least one of its 058 * subproviders can be instantiated. If a client needs to know which domains are 059 * supported by an instance of this provider, it may use the 060 * {@link #isSupported(com.ibm.rational.wvcm.stp.StpProvider.Domain) isSupported} 061 * method to discover this and use {@link #getInstantiationErrors()} for more 062 * information why a subprovider failed to instantiated. 063 * </p> 064 * 065 * <p> 066 * {@link javax.wvcm.ProviderFactory#createProvider(String, 067 * javax.wvcm.ProviderFactory.Callback) ProviderFactory.createProvider} may be 068 * invoked with a non-<b>null</b> Callback object from which an {@link 069 * javax.wvcm.ProviderFactory.Callback.Authentication Authentication} object can 070 * be obtained for each authentication realm visited by the provider. The 071 * <b>realmId</b> provided to the 072 * {@link javax.wvcm.ProviderFactory.Callback#getAuthentication getAuthentication} 073 * method tells the user what credentials to provide. For ClearQuest, the realm 074 * identifier is the database set name (also known as the schema repository, 075 * master database, profile, or connection name); for ClearCase, the realm 076 * identifier is the URL for the server. 077 * </p> 078 * <p> 079 * This interface defines {@link StpCallback}, which extends 080 * {@link javax.wvcm.ProviderFactory.Callback} to allow the library to provide 081 * more information to the client's callback object when it is asked for 082 * credentials. 083 * </p> 084 * If no Callback instance is made available to the provider, operations that 085 * require an authenticated identity will fail unless the client has already 086 * provided an Authentication object to the provider via the 087 * {@link #setAuthentication(com.ibm.rational.wvcm.stp.StpProvider.Domain, String, javax.wvcm.ProviderFactory.Callback.Authentication, boolean) setAuthentication} 088 * method 089 * <p> 090 * Some subproviders require the client to tell them the URL for their 091 * associated server. That is accomplished using the 092 * {@link #setServerUrl(String) setServerUrl} method following Provider 093 * construction. Setting a server URL does not result in any validation that the 094 * server is accessible. A client must perform some operation (e.g., 095 * {@link javax.wvcm.Resource#doReadProperties(javax.wvcm.Feedback)}) to 096 * attempt to use, and hence check, a server URL. An attempt to create a 097 * Location associated with such a subprovider will fail if the server URL has 098 * not yet been specified. The server URL associated with a subprovider cannot 099 * be changed once it has been set via {@link #setServerUrl}. A new StpProvider 100 * instance must be created to reference a different server. 101 * </p> 102 * 103 * <p> 104 * When a Provider is instantiated via the ProviderFactory, a new, independent 105 * sequence of server interactions is started for a single user. The user of the 106 * provider is identified by the {@link javax.wvcm.ProviderFactory.Callback 107 * Callback} instance passed through the ProviderFactory to the Provider 108 * instance. 109 * </p> 110 * 111 * <p> 112 * A provider exists until it is explicitly terminated via the {@link 113 * #terminate() terminate()} method or it is implicitly terminated after a 114 * period of time in which no server interactions are initiated. It is always 115 * best to explicitly terminate a provider when it is no longer needed. This 116 * will free up resources on the server for others to use. 117 * </p> 118 */ 119 public interface StpProvider extends javax.wvcm.Provider 120 { 121 /** 122 * The name of a wvcm.javax.Provider implementation class to be used by 123 * clients that wish to interact with both ClearCase and ClearQuest in a 124 * single provider. The returned object supports only the StpProvider 125 * interface and therefore does not provide direct access to any 126 * domain-specific capabilities. Once this generic provider has been 127 * instantiated, the client can obtain a domain-specific provider extension 128 * using either the {@link #cqProvider()} method or the 129 * {@link #ccProvider()} method. 130 * <p> 131 * A client could create this provider to discover which team services are 132 * installed. The domain-specific provider access methods of this instance 133 * will return <b>null</b> if the domain-specific provider is not 134 * installed. 135 * 136 * @see com.ibm.rational.wvcm.stp.cq.CqProvider#CQ_ONLY_PROVIDER_CLASS 137 * @see com.ibm.rational.wvcm.stp.cc.CcProvider#CC_ONLY_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(String) 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(String) 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(String) 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 * <p> 528 * The specified URL is used for ClearCase operations only. ClearQuest 529 * operations do not contact a server, but require an installation of 530 * ClearQuest on the client machine. 531 * 532 * @param url The URL used to contact the CM Server via this provider. Must 533 * not be <b>null</b>. This URL is not validated until the next 534 * "do" method that requires a URL is invoked. 535 * 536 * @throws WvcmException if a server URL has already been established for 537 * this provider. 538 */ 539 void setServerUrl(String url) throws WvcmException; 540 541 /** 542 * Returns the server URL for this provider, as set by an initialization 543 * argument or a previous call to setServerUrl(). If no default server URL 544 * has been established, returns <b>null</b>. 545 * 546 * @return the default server URL for this provider; may be <b>null</b>. 547 * 548 * @see #setServerUrl(String) 549 */ 550 String getServerUrl(); 551 552 /** 553 * Returns the Locale that is being used by this provider and is being 554 * passed to the server to identify the locale to use when performing 555 * locale-dependent operations for this provider. If not explicitly set by 556 * the client, the value returned by java.util.Locale#getDefault() is 557 * returned. 558 * 559 * @return A Locale object representing the locale to be used when 560 * performing locale-dependent operations for this provider. Will 561 * not be <b>null</b>. 562 */ 563 Locale getUserLocale(); 564 565 /** 566 * Defines the Locale that is to be used by this provider and passed to the 567 * server to identify the locale to use when performing locale-dependent 568 * operations for this provider. Does <i>not</i> set the default Locale of 569 * the JVM. 570 * 571 * @param locale A Locale object representing the locale to be used when 572 * performing locale-dependent operations for this provider. Must 573 * not be <b>null</b>; use java.util.Locale#getDefault() to use 574 * the native Locale of the client. 575 */ 576 void setUserLocale(Locale locale); 577 578 /** 579 * Returns the TimeZone that is being used by this provider and is being 580 * passed to the server to identify the time zone of the user. If not 581 * explicitly set by the client, java.util.TimeZone#getDefault() is 582 * returned. 583 * 584 * @return A TimeZone object representing the time zone to be used when 585 * performing date translations for this provider. Will not be 586 * <b>null</b>. 587 */ 588 TimeZone getUserTimeZone(); 589 590 /** 591 * Defines the time zone that is to be used by this provider and passed to 592 * the server for this provider. Does NOT set the default TimeZone of the 593 * JVM. 594 * 595 * @param timeZone A TimeZone object representing the time zone to be used 596 * when performing date translation for this provider. Must not 597 * be <b>null</b>; use java.util.TimeZone#getDefault() to use 598 * the native time zone of the client. 599 */ 600 void setUserTimeZone(TimeZone timeZone); 601 602 /** 603 * The type of a subprovider. 604 */ 605 static public enum Domain implements StpExEnumeration 606 { 607 /** An unspecified domain */ 608 NONE(""), 609 610 /** An invalid domain */ 611 INVALID("<invalid>"), 612 613 /** The ClearCase domain. */ 614 CLEAR_CASE("cc"), 615 616 /** The ClearQuest domain */ 617 CLEAR_QUEST("cq"); 618 619 /** 620 * Returns the Domain object that matches a given domain-field symbol 621 * 622 * @param symbol A String containing the domain-field symbol to be 623 * converted to a Domain object. 624 * 625 * @return A Domain object that matches the given symbol. Will be <b> 626 * INVALID</b> if no Domain object matches the given symbol. 627 */ 628 public static final Domain fromSymbol(String symbol) 629 { 630 if (symbol != null) { 631 for (Domain d : values()) 632 if (symbol.compareToIgnoreCase(d.toSymbol()) == 0) 633 return d; 634 } 635 636 return INVALID; 637 } 638 639 /** 640 * @return Returns the word token to use in the domain field of a 641 * location specification for this Domain. 642 */ 643 public String toSymbol() 644 { 645 return m_symbol; 646 } 647 648 /** 649 * Creates a new Domain object. 650 * 651 * @param symbol The symbol used for this StpProvider.Domain when 652 * forming a location specification. 653 */ 654 private Domain(String symbol) 655 { 656 m_symbol = symbol; 657 } 658 659 /* The domain-field symbol that corresponds to the Domain enumerator */ 660 private String m_symbol; 661 } 662 663 /** 664 * Returns an indication of whether or not this provider is permitted to 665 * communicate with a server. 666 * 667 * @return <b>true</b> if this provider is permitted to connect to a 668 * server to perform operations; <b>false</b> otherwise. 669 */ 670 boolean getIsDisconnected(); 671 672 /** 673 * Grants or denies this provider the ability to connect to a server while 674 * performing tasks for the client. 675 * <p> 676 * Note: Setting this attribute does <i>not</i> cause an interaction with 677 * the server to initialize or terminate the session. Use the 678 * {@link #setAuthentication(com.ibm.rational.wvcm.stp.StpProvider.Domain, String, javax.wvcm.ProviderFactory.Callback.Authentication, boolean) setAuthentication} 679 * method to control session lifetimes. 680 * 681 * @param isDisconnected <b>true</b> if this provider is not to connect to 682 * server; <b>false</b> if this provider may connect to a 683 * server. 684 */ 685 void setIsDisconnected(boolean isDisconnected); 686 687 /** 688 * Returns the callback object passed to the ProviderFactory during the 689 * instantiation or initialization of this provider. 690 * 691 * <p> 692 * The provider maintains a mapping between authentication realms and user 693 * credentials and this callback object is used to populate that map. When 694 * the library generates a request targeting a specific Location, it will 695 * attempt to deduce the realm id from the Location (through its 696 * subprovider). 697 * </p> 698 * 699 * <ol> 700 * <li>If a realm id can be deduced, the provider will consult the 701 * realm-credential map to obtain the credentials for that realm id. 702 * <ul> 703 * <li>If no credentials are found for the realm, this authentication 704 * callback will be called passing the realm id to the client. The returned 705 * credentials will then be entered into the realm-credential map and the 706 * request will proceed with those credentials.</li> 707 * <li>If credentials are found for the realm, the request proceeds with 708 * those credentials.</li> 709 * </ul> 710 * </li> 711 * <li>If the realm id cannot be deduced from the Location, the value of 712 * the AUTHENTICATION_REALM property will be examined. 713 * <ul> 714 * <li>If the AUTHENTICATION_REALM property is defined, the request will be 715 * submitted using its value as the realm id as outlined in bullet 1.</li> 716 * <li>If the AUTHENTICATION_REALM property is not defined, the library 717 * issues the request without credentials. 718 * 719 * <ul> 720 * <li>If the request succeeds, the credentials used are mapped to the 721 * value returned in the AUTHENTICATION_REALM property (if the response 722 * contains this property).</li> 723 * <li>If the request fails, the request will be resubmitted using the 724 * realm id provided in the error response as outlined in bullet 1.</li> 725 * </ul> 726 * </li> 727 * </ul> 728 * </li> 729 * <li>If a request fails authentication when using credentials from the 730 * realm-credential map, this authentication callback is called again for a 731 * new set of credentials for the realm. 732 * <ul> 733 * <li>If a new set of credentials is not returned, the request will fail 734 * with an authentication exception.</li> 735 * <li>If new credentials are returned, the realm-credential map is updated 736 * with the new credentials and the request is retried as outlined in bullet 737 * 1.</li> 738 * </ul> 739 * </li> 740 * </ol> 741 * 742 * <p> 743 * Rather than embedding the policy for establishing the default credentials 744 * in the library, the library always uses the authentication callback (with 745 * a <b>null</b> realm) to obtain from the client the <i>default credentials</i> 746 * to use. The client can then implement the strategy it wishes to use to 747 * come up with the default credentials. 748 * </p> 749 * 750 * @return The call-back object used to initiate the provider. 751 */ 752 javax.wvcm.ProviderFactory.Callback callback(); 753 754 /** 755 * Returns information about the failures, if any, to instantiate providers 756 * for specific product domains. If the map returned contains no information 757 * (i.e. <b>null</b>) for a given StpProvider.Domain, it is safe to use the 758 * type-specific interfaces for that domain. 759 * <p> 760 * Some domains may be served by more than one type of provider--ClearQuest 761 * repositories, for example, can be accessed via the network using one 762 * provider or accessed via an installed ClearQuest application using 763 * another. The StpProvider.Domain entry in the returned error map will be 764 * <b>null</b> if at least one subprovider for the type could be 765 * instantiated. It will be non-<b>null</b> only if <i>all</i> 766 * subproviders for that domain failed to instantiate. 767 * <p> 768 * For more thorough diagnosis of instantiation problems, an entry will be 769 * found in the map associated with the toSymbol() String value of a 770 * StpProvider.Domain if <i>any</i> provider for that type failed to 771 * instantiate. 772 * 773 * @return A mapping from StpProvider.Domain objects and String objects to 774 * an StpException object containing pertinent information about the 775 * failed attempt to instantiate the provider for the given type of 776 * repository. Will never be <b>null</b>, but may be empty or 777 * sparse. 778 */ 779 Map<Object, StpException> getInstantiationErrors(); 780 781 /** 782 * Terminates this provider's association with the servers that it is 783 * actively tracking, releasing any resources it has accumulated as a result 784 * of that tracking. 785 * 786 * <p> 787 * Calling this method marks all of the provider's proxy and location 788 * objects as invalid, and so all client-side references should be 789 * abandoned; any subsequent method calls on the Provider object yields an 790 * UnsupportedOperationException exception. Thus you should typically call 791 * this method immediately prior to the exit of the owning thread or 792 * process. 793 * </p> 794 * 795 * @throws WvcmException if the accumulated resources cannot be disposed of. 796 */ 797 void terminate() throws WvcmException; 798 799 /** 800 * Updates the realm-authentication map maintained by this Provider by 801 * adding or deleting associations between realm strings and Authentication 802 * objects from which user credentials for that realm can be obtained when 803 * they are needed by an operation. 804 * <p> 805 * If a Callback object has been assigned to the Provider, the credential 806 * processing proceeds as follows: 807 * <p> 808 * When credentials are needed to perform an operation in a specific realm, 809 * the Provider first consults the realm-authentication map for an 810 * Authentication object associated with the realm. If there is no 811 * Authentication object registered in the map, the Provider calls the 812 * {@link javax.wvcm.ProviderFactory.Callback#getAuthentication(String, int) Callback.getAuthentication()} 813 * method with a retryCount of 0. If there is an Authentication object in 814 * the map for the realm and the credentials it provides are rejected by the 815 * server, the Authentication object is removed from the map and the 816 * Provider calls Callback.getAuthentication() (with a retryCount > 1) to 817 * obtain a new Authentication object to associate with the realm. 818 * <p> 819 * If no Callback object has been assigned to the Provider, the credential 820 * processing proceeds as follows: 821 * <p> 822 * When credentials are needed to perform an operation in a specific realm, 823 * the Provider consults the realm-authentication map for an Authentication 824 * object associated with the realm. If there is no Authentication object 825 * registered in the map no credentials will be passed to the server. If the 826 * chosen Authentication object is rejected by the server, the Provider 827 * throws an exception to terminate the operation. 828 * <p> 829 * The Provider adds an entry to the realm-authentication map only after it 830 * has determined that a given Authentication object actually provides valid 831 * credentials in the realm. It will remove an entry from the map when it 832 * determines that the Authentication object in the map cannot provide valid 833 * credentials (and there is a Callback object from which to get a 834 * replacement). 835 * <p> 836 * The client may make entries in the realm-authentication map with or 837 * without validating those entries. Validation implies a round-trip to the 838 * server for the realm(s) specified. If the realm-authentication map 839 * contains an entry for an affected realm, the corresponding server is 840 * notified to log the user out of that realm. If the Authentication object 841 * is not <b>null</b>, the server is notified to log the user into the 842 * specified realm with the new set of credentials. 843 * 844 * In this release, the realm string for a ClearQuest database is just the 845 * database set name. It is assumed that all user databases defined in that 846 * database set use the same credentials as stored in the database set. (In 847 * fact, there are times in the history of a given user database when the 848 * credentials it accepts for a user differ from those stored in its 849 * database set. This corner case is not supported in this release.) 850 * 851 * A full user database name may be passed to this method, but the 852 * authentication map remembers only the Db-Set portion of it. The user 853 * database portion of the name, if present, is used only when doValidation 854 * is true. In that case, if the realm parameter includes a user database 855 * name, then the user is logged into or out of that user database (not the 856 * database set). 857 * 858 * @param domain The Domain for which authentication is being provided. Must 859 * not be <b>null</b> unless the authentication parameter is 860 * also <b>null</b>. In that case, the Authentication object is 861 * removed for the given realm in all domains. 862 * @param Realm A String identifying the realm for which authentication is 863 * being provided. (This is the string passed as the realm 864 * parameter to Callback.getAuthentiation()) Must not be <b>null</b> 865 * unless the authentication parameter is also <b>null</b>, in 866 * which case the authentications for all realms (in the 867 * specified domains) will be removed from the map. 868 * @param authentication A ProviderFactory.Authentication instance that can 869 * provide any credentials needed for the user in the specified 870 * realm of the specified domain(s). If <b>null</b>, any 871 * existing authentication associated with the specified realm(s) 872 * will be removed from the map. 873 * @param doValidation If <b>false</b>, only the Provider map will be 874 * updated; if <b>true</b>, each impacted domain server will be 875 * contacted immediately to inform it of the change in 876 * credentials. The user will be logged off the realm(s) already 877 * in the map and, if the Authentication object is not <b>null</b> 878 * a new logon will be attempted using the given credentials. 879 * @throws WvcmException 880 * <ul> 881 * <li>if doValidation is <b>true</b>, the provided 882 * Authentication object is not <b>null</b>, and the 883 * credentials it provides are rejected by a server, or 884 * <li> if doValidation is <b>true</b>, the provided 885 * Authentication object is <b>null</b>, and a server cannot 886 * terminate the provider of (i.e. logoff) a once-active user. 887 * </ul> 888 */ 889 void setAuthentication(Domain domain, 890 String Realm, 891 Authentication authentication, 892 boolean doValidation) throws WvcmException; 893 894 /** 895 * Returns the Authentication object currently associated with a given realm 896 * string in a given Domain. 897 * 898 * @param domain The Domain for which authentication is being requested; 899 * Must not be <b>null</b>; 900 * @param realm The realm for which authentication is being requested; Must 901 * not be <b>null</b>. 902 * @return The Authentication object currently associated with the given 903 * Domain and realm; <b>null</b> if no such association currently 904 * exists. 905 */ 906 Authentication getAuthentication(Domain domain, 907 String realm); 908 909 /** 910 * An extended version of javax.wvcm.ProviderFactory.Callback whose 911 * getAuthentication method provides additional information to the client 912 * when being asked for credentials. If the Callback object passed to this 913 * Provider implements this interface, its getAuthenticationEx will be 914 * called rather than Callback.getAuthentication each time an Authentication 915 * object is required. 916 */ 917 public interface StpCallback extends Callback 918 { 919 /** 920 * An extended version of Callback.getAuthentication that provides 921 * additional information to the client when being asked for 922 * credentials. If the Callback object passed to this Provider 923 * implements this interface, the getAuthenticationEx will be called 924 * rather than getAuthentication each time an Authentication object is 925 * required. 926 * 927 * @param domain The Domain that is requesting credentials. 928 * @param realm an identifier for the authentication realm that is 929 * requesting credentials. A single provider instance can 930 * access resources in different authentication realms, so 931 * the user must be provided with the name of the 932 * authentication realm in order to determine what 933 * credentials to provide. 934 * @param retryCount the number of times the provider has unsuccessfully 935 * attempted to get authentication for this operation. This 936 * parameter helps the client decide when to provide a more 937 * detailed authentication dialog, or potentially abort the 938 * operation rather than making additional attempts to get 939 * credentials from the user. 940 * @param provider The StpProvider instance that is requesting 941 * authentication. 942 * @param failure The WvcmException generated by the attempt to log onto 943 * the realm using the Authentication object last provided by 944 * this Callback. This will be <b>null</b> when retryCount 945 * is zero. 946 * @return user and password authentication interface. Must not be 947 * <b>null</b> 948 * @throws WvcmException if the user or client wish to abort the 949 * authentication request. Note: <i>this method throwing an 950 * exception is the only way the authentication retry 951 * process can be terminated.</i> The provider has no 952 * preset retry limits or conditions and will repeatedly 953 * call this Callback object until a valid set of 954 * credentials is returned or this method throws an 955 * exception. 956 */ 957 public Authentication getAuthenticationEx(Domain domain, 958 String realm, 959 int retryCount, 960 StpProvider provider, 961 WvcmException failure) 962 throws WvcmException; 963 } 964 965 /** 966 * If the Callback object provided to an StpProvider implements this 967 * interface, the callback will be notified when an Authentication object 968 * returned by the Callback's getAuthentication() method is successfully 969 * verified to be valid. 970 */ 971 public interface NotifyAuthenticatedOption 972 { 973 /** 974 * Notifies the Callback object that an authentication object that it 975 * previously returned has been found to be valid for the specified 976 * domain, realm, and provider. If the provided credentials were not 977 * valid, the Callback's getAuthentication method will be called another 978 * time for a new set of credentials. 979 * 980 * @param domain The Domain that had requested credentials. 981 * @param realm an identifier for the authentication realm that had 982 * requested credentials. 983 * @param provider The StpProvider instance that had requested 984 * authentication. 985 * @param authentication The credentials that were returned by the 986 * Callback and were accepted by the provider for the given 987 * domain and realm. 988 */ 989 void notifyAuthenticated(Domain domain, 990 String realm, 991 StpProvider provider, 992 Authentication authentication); 993 } 994 995 /** 996 * If the Callback object provided to an StpProvider implements this 997 * interface, the callback will be notified when the server reports that 998 * it is too busy to respond to a request. 999 */ 1000 public interface NotifyBusyOption 1001 { 1002 /** 1003 * A non-<b>null</b> busyFailure argument indicates the server has 1004 * reported that it is too busy to process a request. This method 1005 * returns if and when that request is to be attempted again. It throws 1006 * an exception to cancel the request. 1007 * <p> 1008 * A <b>null</b> busyFailure argument indicates that a request that was 1009 * re-attempted has now been processed by the server. In this case, this 1010 * method must return and should not throw an exception if it wants the 1011 * operation to continue. This call with a <b>null</b> busyFailure 1012 * argument is intended to give the callback an opportunity to take down 1013 * any user presentation put up to indicate the operation was waiting 1014 * for the server to respond. 1015 * <p> 1016 * This method is <i>not</i> called for every server request, even with 1017 * a <b>null</b> busyFailure argument. It is invoked only when the 1018 * server reports that it is too busy to process a request. 1019 * <p> 1020 * The method returns no value. If the client wants to retry the request 1021 * a little later, the callback should put the current thread to sleep 1022 * for a while to give the server time to catch up. Whenever this method 1023 * returns, the request will be retried immediately. 1024 * <p> 1025 * If the client does not want to retry the request, it must throw an 1026 * exception, such as the busyFailure exception passed into the method. 1027 * 1028 * @param domain 1029 * The Domain in which the request was being executed. 1030 * @param realm 1031 * The authentication realm in which the request was being 1032 * executed. 1033 * @param provider 1034 * The provider that is attempting to perform the request on 1035 * the server. 1036 * @param opStartTime 1037 * A Date object representing the time at which the request 1038 * was first initiated. This object is unique to the request 1039 * being executed and the same object is passed to every 1040 * invocation of this method resulting from any attempt to 1041 * re-exeucte the request. Thus, it could be used by the 1042 * callback as the key to a map containing progress history 1043 * for this operation. It could also be compared to the 1044 * current time to limit the time the client waits for the 1045 * server. 1046 * @param busyFailure 1047 * The exception returned by the server to report that it was 1048 * too busy to process the request. If this method returns 1049 * normally and on the subsequent re-try the server processes 1050 * the request this method is called with <b>null</b> for 1051 * this argument. If the server still reports that it is busy 1052 * this method will be called again with a non-null argument. 1053 * <p> 1054 * A <b>null</b> value for this argument <i>does not</i> 1055 * necessarily mean that the operation was successful. It 1056 * just means that the server was finally able to process the 1057 * request. For example, after the server looks at the 1058 * request, it may determine that authentication is required 1059 * before proceeding or it may find something else wrong with 1060 * it. This callback will be invoked to indicate that the 1061 * busy state has been removed <i>before</i> processing the 1062 * server response, whether it be positive or negative. 1063 * <p> 1064 * If completion of the operation requires multiple 1065 * interactions with the server (as when authentication is 1066 * needed), any of those interactions could find the server 1067 * busy again. Hence, a <b>null</b> busyFailure argument 1068 * <i>does not</i> indicate that this method will not be 1069 * called another time for the same request (opStartTime). 1070 * @throws WvcmException to abort the request. 1071 */ 1072 void notifyBusy(Domain domain, 1073 String realm, 1074 StpProvider provider, 1075 Date opStartTime, 1076 WvcmException busyFailure) throws WvcmException; 1077 } 1078 1079 /** 1080 * Set the HTTP proxy host and port for all future calls from this 1081 * client. 1082 * @param host Name of proxy host. 1083 * @param port Port number of proxy on that host. 1084 */ 1085 void setHttpProxy(String host, 1086 String port); 1087 1088 /** 1089 * @return A String containing the name of the HTTP proxy host used by this 1090 * provider, <b>null</b> if not previously set. 1091 */ 1092 String getHttpProxyHost(); 1093 1094 /** 1095 * @return A String containing the port number on the HTTP proxy host used 1096 * by this provider, <b>null</b> if not previously set. 1097 */ 1098 String getHttpProxyPort(); 1099 1100 /** 1101 * Determines whether a given domain is supported by this provider. It is 1102 * safe to use the type-specific interfaces for a supported domain. 1103 * 1104 * @param domain - the domain in question 1105 * 1106 * @return <b>true</b> if the domain is supported; <b>false</b> otherwise. 1107 * 1108 * @see #getInstantiationErrors() 1109 * @see #ccProvider() 1110 * @see #cqProvider() 1111 */ 1112 boolean isSupported(StpProvider.Domain domain); 1113 1114 /** 1115 * Constructs an StpLocation from its string representation 1116 * 1117 * @param location A string satisfying the syntax for a CM API location 1118 * specification. 1119 * 1120 * @return An StpLocation object capturing the fields specified in the given 1121 * location specification string. 1122 * 1123 * @throws WvcmException If the string is <b>null</b> or empty. 1124 */ 1125 StpLocation stpLocation(String location) throws WvcmException; 1126 1127 /** 1128 * Constructs an StpLocation from the individual fields of a location 1129 * specification that follows the user-friendly object selector scheme 1130 * 1131 * @param domain the Domain. Must not be INVALID 1132 * @param namespace the Namespace for the location. Must not be INVALID, 1133 * REPO, or FAST 1134 * @param name the segmented object name field. Each segment of the name 1135 * must be encoded as required by the namespace. May be <b>null</b> 1136 * or empty to form the root of the namespace in a repository 1137 * resource. 1138 * @param repo the repository name. Each segment of the name must be encoded 1139 * as required by the namespace. 1140 * 1141 * @return An StpLocation object with the specified fields. 1142 * 1143 * @throws WvcmException Thrown if the location String composed from the 1144 * given fields is not in the correct form. StpReasonCode = 1145 * {@link StpException.StpReasonCode#INVALID_OBJECT_SELECTOR} 1146 */ 1147 StpLocation userFriendlySelector(StpProvider.Domain domain, 1148 StpLocation.Namespace namespace, 1149 String name, 1150 String repo) throws WvcmException; 1151 1152 /** 1153 * Constructs an StpLocation from a string representation assuming the 1154 * Location is to be used exclusively in a specified domain. In particular, 1155 * if there is no scheme prefix or the given scheme prefix would not be 1156 * recognized in the given domain, the input is forced to be a pname (in the 1157 * PNAME_IMPLIED namespace). 1158 * 1159 * @param domain The domain in which the location is to be used. Must not be 1160 * <b>null</b>, NONE, or INVALID. 1161 * @param pname The string representation for a location to be used in the 1162 * given domain. Must not be <b>null</b> or empty. 1163 * @return An StpLocation appropriate for the given domain. 1164 * @throws WvcmException if the input is <b>null</b> or empty or an otherwise 1165 * acceptable input specifies a domain different from that 1166 * requested. 1167 * 1168 */ 1169 StpLocation stpLocation(Domain domain, 1170 String pname) throws WvcmException; 1171 1172 /** 1173 * Constructs an StpLocation from the individual fields of a location 1174 * specification that follows the stable selector scheme. 1175 * 1176 * @param domain The domain of the resource. 1177 * @param rType The resource type segment of the name. 1178 * @param objectId The object id of the resource. 1179 * @param repoId The repository id of the resource. 1180 * 1181 * @return A stable-selector scheme StpLocation object with the specified 1182 * fields 1183 * 1184 * @throws WvcmException If the location is not well-formed. 1185 */ 1186 StpLocation stableSelector(StpProvider.Domain domain, 1187 String rType, 1188 String objectId, 1189 String repoId) throws WvcmException; 1190 1191 /** 1192 * Constructs a path-scheme location for a specified scheme and 1193 * domain. 1194 * @param domain The domain type of the repository 1195 * @param namespace the particular path-scheme for the location 1196 * @param path The pathname of the resource. Each type of scheme has its 1197 * own encoding requirements. 1198 * 1199 * @return An StpLocation object for the specified repository 1200 * 1201 * @throws WvcmException If the selector is ill-formed 1202 */ 1203 StpLocation pathLocation(StpProvider.Domain domain, 1204 StpLocation.Namespace namespace, 1205 String path) throws WvcmException; 1206 1207 /** 1208 * Constructs a PNAME StpLocation for a pathname to a file system 1209 * object. 1210 * 1211 * <p> 1212 * Shorthand for 1213 * </p> 1214 * 1215 * <pre> 1216 * stpLocation(null, Namespace.PNAME, encodeFile(file.getPath()), null). 1217 * </pre> 1218 * 1219 * @param file Abstract pathname. The file system object need not exist. 1220 * 1221 * @return An StpLocation object with the specified fields 1222 * 1223 * @throws WvcmException Thrown if an error occurs. 1224 */ 1225 StpLocation filePathLocation(File file) throws WvcmException; 1226 1227 /** 1228 * Constructs a PNAME Location for a pathname to a file system 1229 * object of a specific domain. 1230 * 1231 * <p> 1232 * Shorthand for 1233 * </p> 1234 * 1235 * <pre> 1236 * stpLocation(domain, Namespace.PNAME, encodeFile(file.getPath()), null). 1237 * </pre> 1238 * 1239 * @param domain The StpProvider.Domain of the resource referenced by the 1240 * given file object. 1241 * @param file Abstract pathname. The file system object need not exist. 1242 * 1243 * @return An StpLocation object with the specified fields 1244 * 1245 * @throws WvcmException Thrown if an error occurs. 1246 */ 1247 StpLocation filePathLocation(StpProvider.Domain domain, 1248 File file) throws WvcmException; 1249 1250 /** 1251 * Encodes a plain text string to be a single segment of the object name 1252 * field of a selector by escaping the segment delimiters, repository field 1253 * separator, and the escape character within the string. 1254 * 1255 * <p> 1256 * Note 1: This method is provided as a convenience to clients. It is not 1257 * used by the implementation of the StpLocation class, which does not 1258 * change the encoding of segments unless explicitly stated in method 1259 * documentation. 1260 * 1261 * @param str The String containing the plain text of the segment to be 1262 * encoded. 1263 * 1264 * @return The encoded form of the input String that is suitable for use as 1265 * a segment of the name field within an object selector. 1266 */ 1267 String encodeSegment(String str); 1268 1269 /** 1270 * Undoes the character encoding performed by the {@link #encodeSegment 1271 * encodeSegment} method. This decoding does not need to be performed 1272 * segment by segment as it is only replacing the escape character from each 1273 * escaped character digraph. 1274 * 1275 * @param str The segment of the selector to be decoded. 1276 * 1277 * @return The decoded (plain text) segment. 1278 */ 1279 String decodeSegment(String str); 1280 1281 /** 1282 * Construct an StpAccessControlEntry value 1283 * 1284 * @param principal The group, user, or role to which access is to be 1285 * granted. 1286 * @param accessRights The access rights to be granted; must not be <b>null</b> 1287 * or empty. 1288 * @return an instance of StpAccessControlEntry 1289 */ 1290 StpAccessControlEntry buildAccessControlEntry(StpPrincipal principal, 1291 AccessRight... accessRights); 1292 1293 /** 1294 * Constructs, logs, and throws an StpException. 1295 * 1296 * @param reasonCode The StpException.StpReasonCode to be associated with 1297 * the exception. Must not be <b>null</b>. 1298 * @param messageData A structured message object or the data needed to 1299 * construct one. The message data is passed as an Object[]{ 1300 * message-key, {arg1,...,argN}} if the message format is 1301 * parameterized or as a String containing the message key if it 1302 * is not. If the message-key is not found in the resource bundle 1303 * it is treated as the format string. Must not be <b>null</b>. 1304 * @param resource The Resource argument to WvcmException 1305 * @param nestedExceptions The Throwable[] argument to WvcmException 1306 */ 1307 void raise(StpReasonCode reasonCode, 1308 Object messageData, 1309 Resource resource, 1310 Throwable... nestedExceptions) throws WvcmException; 1311 1312 /** 1313 * Constructs, logs, and throws an StpPropertyException. 1314 * 1315 * @param stpReasonCode The StpReasoCode that defines this exception. 1316 * @param messageData A structured message object or the data needed to 1317 * construct one. The message data is passed as an Object[]{ 1318 * message-key, {arg1,...,argN}} if the message format is 1319 * parameterized or as a String containing the message key if it 1320 * is not. If the message-key is not found in the resource bundle 1321 * it is treated as the format string. Must not be <b>null</b>. 1322 * @param resource The resource causing this exception. 1323 * @param nestedExceptions Subordinate Exceptions that lead to the throwing 1324 * of this StpException. 1325 * @param propertyName The name of the property with which this exception is 1326 * associated. 1327 */ 1328 public void raise(StpReasonCode stpReasonCode, 1329 Object messageData, 1330 Resource resource, 1331 PropertyName propertyName, 1332 Throwable... nestedExceptions) throws WvcmException; 1333 1334 /** 1335 * Constructs, logs, and throws an StpPartialResultsException. 1336 * 1337 * <p> 1338 * The reason code is always StpReasonCode.PARTIAL_RESULTS. 1339 * 1340 * @param messageData A structured message object or the data needed to 1341 * construct one. The message data is passed as an Object[]{ 1342 * message-key, {arg1,...,argN}} if the message format is 1343 * parameterized or as a String containing the message key if it 1344 * is not. If the message-key is not found in the resource bundle 1345 * it is treated as the format string. Must not be <b>null</b>. 1346 * @param resource The resource that caused the exception. 1347 * @param okList A list of resources that were successfully retrieved 1348 * and processed. Can be <b>null</b> or empty. 1349 * @param enumerationError <b>true</b> if accessing some of the resources 1350 * named as targets was not attempted. 1351 * @param name The PropertyName of the property with which this exception is 1352 * associated. May be <b>null</b> if the exception is not associated 1353 * with a property. 1354 * @param nestedExceptions A list of exceptions each of which identifies a 1355 * resource that caused an error when accessed. 1356 */ 1357 public void raise(Object messageData, 1358 Resource resource, 1359 ResourceList<? extends Resource> okList, 1360 boolean enumerationError, 1361 PropertyName name, 1362 Throwable... nestedExceptions) throws WvcmException; 1363 }