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 }