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