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