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
014package com.ibm.rational.wvcm.stp;
015
016import java.io.File;
017import java.util.Date;
018import java.util.Locale;
019import java.util.Map;
020import java.util.TimeZone;
021
022import javax.wvcm.PropertyNameList.PropertyName;
023import javax.wvcm.ProviderFactory.Callback;
024import javax.wvcm.ProviderFactory.Callback.Authentication;
025import javax.wvcm.Resource;
026import javax.wvcm.ResourceList;
027import javax.wvcm.WvcmException;
028
029import com.ibm.rational.wvcm.stp.StpAccessControlEntry.AccessRight;
030import com.ibm.rational.wvcm.stp.StpException.StpReasonCode;
031import com.ibm.rational.wvcm.stp.cc.CcProvider;
032import com.ibm.rational.wvcm.stp.cq.CqProvider;
033import com.ibm.rational.wvcm.stpex.StpExEnumeration;
034import 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 */
118public 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    
1368}