Project: stp

com.ibm.rational.wvcm.stp
Interface StpProvider

All Superinterfaces:
Provider
All Known Subinterfaces:
CcProvider, CqProvider

public interface StpProvider
extends Provider

StpProvider is an extension to the WVCM Provider interface. It defines additional features supported by providers of this API that are common to both the ClearCase and ClearQuest domains. The StpProvider implementation classes that are available for instantiation are named by the String fields of this interface and its extensions and must be instantiated using the WVCM ProviderFactory class.

For more flexible deployment of the API implementation, this library is partitioned into two domain-specific subcomponents or subproviders. There is at least one subprovider for each StpProvider.Domain. If access to a given domain is available along multiple paths--e.g., locally or via WAN--there will likely be one subprovider for each different access method. The services of a single subprovider interface will be available only if its subprovider class can be instantiated and such a subprovider can be instantiated only if the Rational product underlying the subprovider's domain has been properly installed and licensed. Each subprovider is autonomous, however, and this provider can be instantiated as long as at least one of its subproviders can be instantiated. If a client needs to know which domains are supported by an instance of this provider, it may use the isSupported method to discover this and use getInstantiationErrors() for more information why a subprovider failed to instantiated.

ProviderFactory.createProvider may be invoked with a non-null Callback object from which an Authentication object can be obtained for each authentication realm visited by the provider. The realmId provided to the getAuthentication method tells the user what credentials to provide. For ClearQuest, the realm identifier is the database set name (also known as the schema repository, master database, profile, or connection name); for ClearCase, the realm identifier is the URL for the server.

This interface defines StpProvider.StpCallback, which extends ProviderFactory.Callback to allow the library to provide more information to the client's callback object when it is asked for credentials.

If no Callback instance is made available to the provider, operations that require an authenticated identity will fail unless the client has already provided an Authentication object to the provider via the setAuthentication method

Some subproviders require the client to tell them the URL for their associated server. That is accomplished using the setServerUrl method following Provider construction. Setting a server URL does not result in any validation that the server is accessible. A client must perform some operation (e.g., Resource.doReadProperties(javax.wvcm.Feedback)) to attempt to use, and hence check, a server URL. An attempt to create a Location associated with such a subprovider will fail if the server URL has not yet been specified. The server URL associated with a subprovider cannot be changed once it has been set via setServerUrl(java.lang.String). A new StpProvider instance must be created to reference a different server.

When a Provider is instantiated via the ProviderFactory, a new, independent sequence of server interactions is started for a single user. The user of the provider is identified by the Callback instance passed through the ProviderFactory to the Provider instance.

A provider exists until it is explicitly terminated via the terminate() method or it is implicitly terminated after a period of time in which no server interactions are initiated. It is always best to explicitly terminate a provider when it is no longer needed. This will free up resources on the server for others to use.


Nested Class Summary
static class StpProvider.Domain
          The type of a subprovider.
static interface StpProvider.NotifyAuthenticatedOption
          If the Callback object provided to an StpProvider implements this interface, the callback will be notified when an Authentication object returned by the Callback's getAuthentication() method is successfully verified to be valid.
static interface StpProvider.NotifyBusyOption
          If the Callback object provided to an StpProvider implements this interface, the callback will be notified when the server reports that it is too busy to respond to a request.
static interface StpProvider.StpCallback
          An extended version of javax.wvcm.ProviderFactory.Callback whose getAuthentication method provides additional information to the client when being asked for credentials.
static interface StpProvider.StpProductInfo
          Version information about the code that implements a portion of this product.
 
Field Summary
static String IS_DISCONNECTED_KEY
          The key for the initial argument map entry that indicates whether or not the provider is to operate disconnected from a server.
static String IS_DISCONNECTED_VALUE
          The value for the initial argument map entry that indicates the provider is not allowed to connected to a server.
static String NOT_DISCONNECTED_VALUE
          The value for the initial argument map entry that indicates the provider is allowed to connect to a server.
static String PROVIDER_CLASS
          The name of a wvcm.javax.Provider implementation class to be used by clients that wish to interact with both ClearCase and ClearQuest in a single provider.
static String SERVER_URL_KEY
          The key for the initial argument map entry that contains the server URL for this provider.
static String USER_COUNTRY_KEY
          The key for the initial argument map entry that contains the uppercase two-letter ISO-3166 code for the country of the client locale for this provider.
static String USER_LANGUAGE_KEY
          The key for the initial argument map entry that contains the lowercase two-letter ISO-639 code for the language of the client locale for this provider.
static String USER_VARIANT_KEY
          The key for the initial argument map entry that contains the variant vendor and browser specific code for the client locale of this provider.
 
Method Summary
 StpAccessControlEntry buildAccessControlEntry(StpPrincipal principal, StpAccessControlEntry.AccessRight... accessRights)
          Construct an StpAccessControlEntry value
<T extends Resource>
T
buildProxy(Class<T> type, String str)
          Constructs a proxy implementing a given Resource interface class, using a String representation of the location.
 StpResource buildProxy(StpLocation location, String proxyType, String resourceIdentifier)
          Constructs a new proxy of a given type for a resource at a specified location, defining its Resource.RESOURCE_IDENTIFIER property value if known.
 ProviderFactory.Callback callback()
          Returns the callback object passed to the ProviderFactory during the instantiation or initialization of this provider.
 CcProvider ccProvider()
           
 CqProvider cqProvider()
           
 String decodeSegment(String str)
          Undoes the character encoding performed by the encodeSegment method.
 String encodeSegment(String str)
          Encodes a plain text string to be a single segment of the object name field of a selector by escaping the segment delimiters, repository field separator, and the escape character within the string.
 StpLocation filePathLocation(File file)
          Constructs a PNAME StpLocation for a pathname to a file system object.
 StpLocation filePathLocation(StpProvider.Domain domain, File file)
          Constructs a PNAME Location for a pathname to a file system object of a specific domain.
 ProviderFactory.Callback.Authentication getAuthentication(StpProvider.Domain domain, String realm)
          Returns the Authentication object currently associated with a given realm string in a given Domain.
 StpProvider.Domain getDefaultDomain()
          The domain to use if the domain field is omitted from location specifications.
 StpRepository getDefaultRepository()
          Returns the default repository associated with this provider.
 StpRepository getDefaultRepository(StpProvider.Domain domain)
          Returns the default repository of a specified domain associated with this provider.
 String getHttpProxyHost()
           
 String getHttpProxyPort()
           
 Map<Object,StpException> getInstantiationErrors()
          Returns information about the failures, if any, to instantiate providers for specific product domains.
 boolean getIsDisconnected()
          Returns an indication of whether or not this provider is permitted to communicate with a server.
<T> Class<T>
getPropertyValueClass(PropertyNameList.PropertyName<T> name)
          Returns the Class object for the value type of a property identified by a PropertyName.
 String getServerUrl()
          Returns the server URL for this provider, as set by an initialization argument or a previous call to setServerUrl().
 Locale getUserLocale()
          Returns the Locale that is being used by this provider and is being passed to the server to identify the locale to use when performing locale-dependent operations for this provider.
 TimeZone getUserTimeZone()
          Returns the TimeZone that is being used by this provider and is being passed to the server to identify the time zone of the user.
 boolean isSupported(StpProvider.Domain domain)
          Determines whether a given domain is supported by this provider.
 StpLocation pathLocation(StpProvider.Domain domain, StpLocation.Namespace namespace, String path)
          Constructs a path-scheme location for a specified scheme and domain.
 String proxyType(Class<? extends Resource> interfaceClass)
          Computes the proxy type string required by buildProxy(StpLocation, String, String) given the Class object for a proxy interface that the new proxy should implement.
 void raise(Object messageData, Resource resource, ResourceList<? extends Resource> okList, boolean enumerationError, PropertyNameList.PropertyName name, Throwable... nestedExceptions)
          Constructs, logs, and throws an StpPartialResultsException.
 void raise(StpException.StpReasonCode stpReasonCode, Object messageData, Resource resource, PropertyNameList.PropertyName propertyName, Throwable... nestedExceptions)
          Constructs, logs, and throws an StpPropertyException.
 void raise(StpException.StpReasonCode reasonCode, Object messageData, Resource resource, Throwable... nestedExceptions)
          Constructs, logs, and throws an StpException.
 void setAuthentication(StpProvider.Domain domain, String Realm, ProviderFactory.Callback.Authentication authentication, boolean doValidation)
          Updates the realm-authentication map maintained by this Provider by adding or deleting associations between realm strings and Authentication objects from which user credentials for that realm can be obtained when they are needed by an operation.
 void setDefaultDomain(StpProvider.Domain domain)
          Establishes the default StpProvider.Domain for this provider.
 void setDefaultRepository(StpProvider.Domain domain, StpRepository repo)
          Establishes the default repository of a specified type to be associated with this provider.
 void setDefaultRepository(StpRepository repo)
          Establishes the default repository to be associated with this provider.
 void setHttpProxy(String host, String port)
          Set the HTTP proxy host and port for all future calls from this client.
 void setIsDisconnected(boolean isDisconnected)
          Grants or denies this provider the ability to connect to a server while performing tasks for the client.
 void setServerUrl(String url)
          Establishes the default server URL for this provider, if one has not already been established.
 void setUserLocale(Locale locale)
          Defines the Locale that is to be used by this provider and passed to the server to identify the locale to use when performing locale-dependent operations for this provider.
 void setUserTimeZone(TimeZone timeZone)
          Defines the time zone that is to be used by this provider and passed to the server for this provider.
 StpLocation stableSelector(StpProvider.Domain domain, String rType, String objectId, String repoId)
          Constructs an StpLocation from the individual fields of a location specification that follows the stable selector scheme.
 StpLocation stpLocation(StpProvider.Domain domain, String pname)
          Constructs an StpLocation from a string representation assuming the Location is to be used exclusively in a specified domain.
 StpLocation stpLocation(String location)
          Constructs an StpLocation from its string representation
 StpProvider.StpProductInfo stpProductInfo(StpProvider.Domain domain)
          Returns the version information for the code implementing this Provider or one of its domain-specific subproviders.
 StpProvider stpProvider()
           
 StpRepository stpRepository(StpLocation location)
          Constructs an StpRepository proxy for a repository at a specified location.
 void terminate()
          Terminates this provider's association with the servers that it is actively tracking, releasing any resources it has accumulated as a result of that tracking.
 StpLocation userFriendlySelector(StpProvider.Domain domain, StpLocation.Namespace namespace, String name, String repo)
          Constructs an StpLocation from the individual fields of a location specification that follows the user-friendly object selector scheme
 
Methods inherited from interface javax.wvcm.Provider
buildProxy, folder, initArgs, initialize, location, relativeRootLocation, resource, resourceList, rootLocation
 

Field Detail

IS_DISCONNECTED_KEY

static final String IS_DISCONNECTED_KEY
The key for the initial argument map entry that indicates whether or not the provider is to operate disconnected from a server.

See Also:
Constant Field Values

IS_DISCONNECTED_VALUE

static final String IS_DISCONNECTED_VALUE
The value for the initial argument map entry that indicates the provider is not allowed to connected to a server.

See Also:
Constant Field Values

NOT_DISCONNECTED_VALUE

static final String NOT_DISCONNECTED_VALUE
The value for the initial argument map entry that indicates the provider is allowed to connect to a server.

See Also:
Constant Field Values

PROVIDER_CLASS

static final String PROVIDER_CLASS
The name of a wvcm.javax.Provider implementation class to be used by clients that wish to interact with both ClearCase and ClearQuest in a single provider. The returned object supports only the StpProvider interface and therefore does not provide direct access to any domain-specific capabilities. Once this generic provider has been instantiated, the client can obtain a domain-specific provider extension using either the cqProvider() method or the ccProvider() method.

A client could create this provider to discover which team services are installed. The domain-specific provider access methods of this instance will return null if the domain-specific provider is not installed.

See Also:
CqProvider.CQ_ONLY_PROVIDER_CLASS, CcProvider.CC_ONLY_PROVIDER_CLASS, Constant Field Values

SERVER_URL_KEY

static final String SERVER_URL_KEY
The key for the initial argument map entry that contains the server URL for this provider.

See Also:
setServerUrl(String), Constant Field Values

USER_COUNTRY_KEY

static final String USER_COUNTRY_KEY
The key for the initial argument map entry that contains the uppercase two-letter ISO-3166 code for the country of the client locale for this provider.

See Also:
#setUserLocale(String), Locale, Constant Field Values

USER_LANGUAGE_KEY

static final String USER_LANGUAGE_KEY
The key for the initial argument map entry that contains the lowercase two-letter ISO-639 code for the language of the client locale for this provider.

See Also:
#setUserLocale(String), Locale, Constant Field Values

USER_VARIANT_KEY

static final String USER_VARIANT_KEY
The key for the initial argument map entry that contains the variant vendor and browser specific code for the client locale of this provider.

See Also:
#setUserLocale(String), Locale, Constant Field Values
Method Detail

buildAccessControlEntry

StpAccessControlEntry buildAccessControlEntry(StpPrincipal principal,
                                              StpAccessControlEntry.AccessRight... accessRights)
Construct an StpAccessControlEntry value

Parameters:
principal - The group, user, or role to which access is to be granted.
accessRights - The access rights to be granted; must not be null or empty.
Returns:
an instance of StpAccessControlEntry

buildProxy

<T extends Resource> T buildProxy(Class<T> type,
                                  String str)
                              throws WvcmException
Constructs a proxy implementing a given Resource interface class, using a String representation of the location.

Type Parameters:
T - The Resource interface type that the returned proxy is to implement. This is inferred from the type argument.
Parameters:
type - The Class object for the interface class that the returned proxy is to implement.
str - A String containing a specification for the location of the resource to be addressed by the returned proxy. The domain and namespace do not need to be specified in this location since they can be inferred from the desired proxy class. The repository field may also be elided if a default repository has been established for this provider.
Returns:
A proxy object that implements interface T.
Throws:
WvcmException - Thrown if an StpLocation object cannot be obtained from this provider for the given location or if this provider cannot construct a proxy that implements interface T.
See Also:
setDefaultRepository(com.ibm.rational.wvcm.stp.StpProvider.Domain, StpRepository), Provider.buildProxy(Class, javax.wvcm.Location)

buildProxy

StpResource buildProxy(StpLocation location,
                       String proxyType,
                       String resourceIdentifier)
                       throws WvcmException
Constructs a new proxy of a given type for a resource at a specified location, defining its Resource.RESOURCE_IDENTIFIER property value if known.

This method and StpResource.initMetaProperty provide the means for reconstructing a proxy previously archived to persistent storage by a client. When the proxy is archived, the client needs to save its location, its proxyType, the value of its RESOURCE_IDENTIFIER property (if defined), and the name and value of any other property/meta-property defined by the proxy that will be of interest to the client when the proxy is restored.

To restore the proxy, invoke this method with the previously saved location, proxyType and RESOURCE_IDENTIFIER value to get an appropriate proxy object. Then use StpResource.initMetaProperty to move all of the remaining saved properties into the proxy.

Parameters:
location - The resource location to which the new proxy is to refer. Must not be null. A resource need not exist at the specified location, but the location must otherwise be valid.
proxyType - A String specifying the type of proxy required. Must not be null. This value may be obtained either from a previous proxy for the resource using its {#link StpResource#proxyType()} method or from the Class object for the public interface that the new proxy should support using the proxyType(Class) method.
resourceIdentifier - The value of the RESOURCE_IDENTIFIER property to be defined by the new proxy. This value would have to come from the RESOURCE_IDENTIFIER value of a pre-existing proxy. If null, the RESOURCE_IDENTIFIER property of the new proxy will not be defined. This property cannot be set after the proxy is constructed.
Returns:
A new proxy implementing the interfaces implied by the given proxyType parameter. Will not be null.
Throws:
WvcmException - Thrown if an StpLocation object cannot be obtained from this provider for the given location or if this provider cannot construct a proxy that implements the interface implied by the proxyType argument.
See Also:
StpResource.initMetaProperty(javax.wvcm.PropertyNameList.PropertyName, com.ibm.rational.wvcm.stp.StpProperty.MetaPropertyName, Object)

callback

ProviderFactory.Callback callback()
Returns the callback object passed to the ProviderFactory during the instantiation or initialization of this provider.

The provider maintains a mapping between authentication realms and user credentials and this callback object is used to populate that map. When the library generates a request targeting a specific Location, it will attempt to deduce the realm id from the Location (through its subprovider).

  1. If a realm id can be deduced, the provider will consult the realm-credential map to obtain the credentials for that realm id.
    • If no credentials are found for the realm, this authentication callback will be called passing the realm id to the client. The returned credentials will then be entered into the realm-credential map and the request will proceed with those credentials.
    • If credentials are found for the realm, the request proceeds with those credentials.
  2. If the realm id cannot be deduced from the Location, the value of the AUTHENTICATION_REALM property will be examined.
    • If the AUTHENTICATION_REALM property is defined, the request will be submitted using its value as the realm id as outlined in bullet 1.
    • If the AUTHENTICATION_REALM property is not defined, the library issues the request without credentials.
      • If the request succeeds, the credentials used are mapped to the value returned in the AUTHENTICATION_REALM property (if the response contains this property).
      • If the request fails, the request will be resubmitted using the realm id provided in the error response as outlined in bullet 1.
  3. If a request fails authentication when using credentials from the realm-credential map, this authentication callback is called again for a new set of credentials for the realm.
    • If a new set of credentials is not returned, the request will fail with an authentication exception.
    • If new credentials are returned, the realm-credential map is updated with the new credentials and the request is retried as outlined in bullet 1.

Rather than embedding the policy for establishing the default credentials in the library, the library always uses the authentication callback (with a null realm) to obtain from the client the default credentials to use. The client can then implement the strategy it wishes to use to come up with the default credentials.

Specified by:
callback in interface Provider
Returns:
The call-back object used to initiate the provider.

ccProvider

CcProvider ccProvider()
Returns:
The Provider extension associated with this StpProvider that implements the CcProvider interface; null if that Provider extension is not instantiated with this provider.

cqProvider

CqProvider cqProvider()
Returns:
The Provider extension associated with this provider instance that implements the CqProvider interface; null if that Provider extension is not instantiated with this provider.

decodeSegment

String decodeSegment(String str)
Undoes the character encoding performed by the encodeSegment method. This decoding does not need to be performed segment by segment as it is only replacing the escape character from each escaped character digraph.

Parameters:
str - The segment of the selector to be decoded.
Returns:
The decoded (plain text) segment.

encodeSegment

String encodeSegment(String str)
Encodes a plain text string to be a single segment of the object name field of a selector by escaping the segment delimiters, repository field separator, and the escape character within the string.

Note 1: This method is provided as a convenience to clients. It is not used by the implementation of the StpLocation class, which does not change the encoding of segments unless explicitly stated in method documentation.

Parameters:
str - The String containing the plain text of the segment to be encoded.
Returns:
The encoded form of the input String that is suitable for use as a segment of the name field within an object selector.

filePathLocation

StpLocation filePathLocation(File file)
                             throws WvcmException
Constructs a PNAME StpLocation for a pathname to a file system object.

Shorthand for

 stpLocation(null, Namespace.PNAME, encodeFile(file.getPath()), null).
 

Parameters:
file - Abstract pathname. The file system object need not exist.
Returns:
An StpLocation object with the specified fields
Throws:
WvcmException - Thrown if an error occurs.

filePathLocation

StpLocation filePathLocation(StpProvider.Domain domain,
                             File file)
                             throws WvcmException
Constructs a PNAME Location for a pathname to a file system object of a specific domain.

Shorthand for

 stpLocation(domain, Namespace.PNAME, encodeFile(file.getPath()), null).
 

Parameters:
domain - The StpProvider.Domain of the resource referenced by the given file object.
file - Abstract pathname. The file system object need not exist.
Returns:
An StpLocation object with the specified fields
Throws:
WvcmException - Thrown if an error occurs.

getAuthentication

ProviderFactory.Callback.Authentication getAuthentication(StpProvider.Domain domain,
                                                          String realm)
Returns the Authentication object currently associated with a given realm string in a given Domain.

Parameters:
domain - The Domain for which authentication is being requested; Must not be null;
realm - The realm for which authentication is being requested; Must not be null.
Returns:
The Authentication object currently associated with the given Domain and realm; null if no such association currently exists.

getDefaultDomain

StpProvider.Domain getDefaultDomain()
The domain to use if the domain field is omitted from location specifications.

Returns:
The StpProvider.Domain enumerator representing the domain that will be used if none is specified in a location specification.

getDefaultRepository

StpRepository getDefaultRepository()
Returns the default repository associated with this provider.

Returns:
A proxy for the default repository established for this provider. Will be null if no default has been established.

getDefaultRepository

StpRepository getDefaultRepository(StpProvider.Domain domain)
Returns the default repository of a specified domain associated with this provider.

Parameters:
domain - The StpProvider.Domain for which a default repository is being requested.
Returns:
A proxy for the default repository established for this provider. Will be null if no default has been established.

getHttpProxyHost

String getHttpProxyHost()
Returns:
A String containing the name of the HTTP proxy host used by this provider, null if not previously set.

getHttpProxyPort

String getHttpProxyPort()
Returns:
A String containing the port number on the HTTP proxy host used by this provider, null if not previously set.

getInstantiationErrors

Map<Object,StpException> getInstantiationErrors()
Returns information about the failures, if any, to instantiate providers for specific product domains. If the map returned contains no information (i.e. null) for a given StpProvider.Domain, it is safe to use the type-specific interfaces for that domain.

Some domains may be served by more than one type of provider--ClearQuest repositories, for example, can be accessed via the network using one provider or accessed via an installed ClearQuest application using another. The StpProvider.Domain entry in the returned error map will be null if at least one subprovider for the type could be instantiated. It will be non-null only if all subproviders for that domain failed to instantiate.

For more thorough diagnosis of instantiation problems, an entry will be found in the map associated with the toSymbol() String value of a StpProvider.Domain if any provider for that type failed to instantiate.

Returns:
A mapping from StpProvider.Domain objects and String objects to an StpException object containing pertinent information about the failed attempt to instantiate the provider for the given type of repository. Will never be null, but may be empty or sparse.

getIsDisconnected

boolean getIsDisconnected()
Returns an indication of whether or not this provider is permitted to communicate with a server.

Returns:
true if this provider is permitted to connect to a server to perform operations; false otherwise.

getPropertyValueClass

<T> Class<T> getPropertyValueClass(PropertyNameList.PropertyName<T> name)
Returns the Class object for the value type of a property identified by a PropertyName. Only properties specified explicitly by this API are supported. For all other properties, the TYPE meta-property may be useful.

Parameters:
name - The PropertyName for the property whose value class is being requested.
Returns:
a Class object identifying the value type of the property. Will be null if the PropertyName or value type is unknown.

getServerUrl

String getServerUrl()
Returns the server URL for this provider, as set by an initialization argument or a previous call to setServerUrl(). If no default server URL has been established, returns null.

Returns:
the default server URL for this provider; may be null.
See Also:
setServerUrl(String)

getUserLocale

Locale getUserLocale()
Returns the Locale that is being used by this provider and is being passed to the server to identify the locale to use when performing locale-dependent operations for this provider. If not explicitly set by the client, the value returned by java.util.Locale#getDefault() is returned.

Returns:
A Locale object representing the locale to be used when performing locale-dependent operations for this provider. Will not be null.

getUserTimeZone

TimeZone getUserTimeZone()
Returns the TimeZone that is being used by this provider and is being passed to the server to identify the time zone of the user. If not explicitly set by the client, java.util.TimeZone#getDefault() is returned.

Returns:
A TimeZone object representing the time zone to be used when performing date translations for this provider. Will not be null.

isSupported

boolean isSupported(StpProvider.Domain domain)
Determines whether a given domain is supported by this provider. It is safe to use the type-specific interfaces for a supported domain.

Parameters:
domain - - the domain in question
Returns:
true if the domain is supported; false otherwise.
See Also:
getInstantiationErrors(), ccProvider(), cqProvider()

pathLocation

StpLocation pathLocation(StpProvider.Domain domain,
                         StpLocation.Namespace namespace,
                         String path)
                         throws WvcmException
Constructs a path-scheme location for a specified scheme and domain.

Parameters:
domain - The domain type of the repository
namespace - the particular path-scheme for the location
path - The pathname of the resource. Each type of scheme has its own encoding requirements.
Returns:
An StpLocation object for the specified repository
Throws:
WvcmException - If the selector is ill-formed

proxyType

String proxyType(Class<? extends Resource> interfaceClass)
                 throws WvcmException
Computes the proxy type string required by buildProxy(StpLocation, String, String) given the Class object for a proxy interface that the new proxy should implement.

Note that

 provider.buildProxy(location,
                     provider.proxyType(Xyz.class),
                     null)
 
is equivalent to
 provider.xyz(location)
 
where provider.xyz() is the proxy factory method that returns an implementation of the interface Xyz. This facilitates the building of proxies driven by compile-time data structures by eliminating the need for the client to develop program logic to switch on such data down to an appropriate proxy factory method call.

Parameters:
interfaceClass - A public proxy class (i.e. any Class object for which javax.wvcm.Resource.class.isAssignableFrom(interfaceClass) is true).
Returns:
A String suitable for use as the proxyType argument to buildProxy(StpLocation, String, String).
Throws:
WvcmException - If the given Class is not an interface implemented by a proxy available from this provider.
See Also:
buildProxy(Class, String), buildProxy(StpLocation, String, String)

raise

void raise(Object messageData,
           Resource resource,
           ResourceList<? extends Resource> okList,
           boolean enumerationError,
           PropertyNameList.PropertyName name,
           Throwable... nestedExceptions)
           throws WvcmException
Constructs, logs, and throws an StpPartialResultsException.

The reason code is always StpReasonCode.PARTIAL_RESULTS.

Parameters:
messageData - A structured message object or the data needed to construct one. The message data is passed as an Object[]{ message-key, {arg1,...,argN}} if the message format is parameterized or as a String containing the message key if it is not. If the message-key is not found in the resource bundle it is treated as the format string. Must not be null.
resource - The resource that caused the exception.
okList - A list of resources that were successfully retrieved and processed. Can be null or empty.
enumerationError - true if accessing some of the resources named as targets was not attempted.
name - The PropertyName of the property with which this exception is associated. May be null if the exception is not associated with a property.
nestedExceptions - A list of exceptions each of which identifies a resource that caused an error when accessed.
Throws:
WvcmException

raise

void raise(StpException.StpReasonCode stpReasonCode,
           Object messageData,
           Resource resource,
           PropertyNameList.PropertyName propertyName,
           Throwable... nestedExceptions)
           throws WvcmException
Constructs, logs, and throws an StpPropertyException.

Parameters:
stpReasonCode - The StpReasoCode that defines this exception.
messageData - A structured message object or the data needed to construct one. The message data is passed as an Object[]{ message-key, {arg1,...,argN}} if the message format is parameterized or as a String containing the message key if it is not. If the message-key is not found in the resource bundle it is treated as the format string. Must not be null.
resource - The resource causing this exception.
nestedExceptions - Subordinate Exceptions that lead to the throwing of this StpException.
propertyName - The name of the property with which this exception is associated.
Throws:
WvcmException

raise

void raise(StpException.StpReasonCode reasonCode,
           Object messageData,
           Resource resource,
           Throwable... nestedExceptions)
           throws WvcmException
Constructs, logs, and throws an StpException.

Parameters:
reasonCode - The StpException.StpReasonCode to be associated with the exception. Must not be null.
messageData - A structured message object or the data needed to construct one. The message data is passed as an Object[]{ message-key, {arg1,...,argN}} if the message format is parameterized or as a String containing the message key if it is not. If the message-key is not found in the resource bundle it is treated as the format string. Must not be null.
resource - The Resource argument to WvcmException
nestedExceptions - The Throwable[] argument to WvcmException
Throws:
WvcmException

setAuthentication

void setAuthentication(StpProvider.Domain domain,
                       String Realm,
                       ProviderFactory.Callback.Authentication authentication,
                       boolean doValidation)
                       throws WvcmException
Updates the realm-authentication map maintained by this Provider by adding or deleting associations between realm strings and Authentication objects from which user credentials for that realm can be obtained when they are needed by an operation.

If a Callback object has been assigned to the Provider, the credential processing proceeds as follows:

When credentials are needed to perform an operation in a specific realm, the Provider first consults the realm-authentication map for an Authentication object associated with the realm. If there is no Authentication object registered in the map, the Provider calls the Callback.getAuthentication() method with a retryCount of 0. If there is an Authentication object in the map for the realm and the credentials it provides are rejected by the server, the Authentication object is removed from the map and the Provider calls Callback.getAuthentication() (with a retryCount > 1) to obtain a new Authentication object to associate with the realm.

If no Callback object has been assigned to the Provider, the credential processing proceeds as follows:

When credentials are needed to perform an operation in a specific realm, the Provider consults the realm-authentication map for an Authentication object associated with the realm. If there is no Authentication object registered in the map no credentials will be passed to the server. If the chosen Authentication object is rejected by the server, the Provider throws an exception to terminate the operation.

The Provider adds an entry to the realm-authentication map only after it has determined that a given Authentication object actually provides valid credentials in the realm. It will remove an entry from the map when it determines that the Authentication object in the map cannot provide valid credentials (and there is a Callback object from which to get a replacement).

The client may make entries in the realm-authentication map with or without validating those entries. Validation implies a round-trip to the server for the realm(s) specified. If the realm-authentication map contains an entry for an affected realm, the corresponding server is notified to log the user out of that realm. If the Authentication object is not null, the server is notified to log the user into the specified realm with the new set of credentials. In this release, the realm string for a ClearQuest database is just the database set name. It is assumed that all user databases defined in that database set use the same credentials as stored in the database set. (In fact, there are times in the history of a given user database when the credentials it accepts for a user differ from those stored in its database set. This corner case is not supported in this release.) A full user database name may be passed to this method, but the authentication map remembers only the Db-Set portion of it. The user database portion of the name, if present, is used only when doValidation is true. In that case, if the realm parameter includes a user database name, then the user is logged into or out of that user database (not the database set).

Parameters:
domain - The Domain for which authentication is being provided. Must not be null unless the authentication parameter is also null. In that case, the Authentication object is removed for the given realm in all domains.
Realm - A String identifying the realm for which authentication is being provided. (This is the string passed as the realm parameter to Callback.getAuthentiation()) Must not be null unless the authentication parameter is also null, in which case the authentications for all realms (in the specified domains) will be removed from the map.
authentication - A ProviderFactory.Authentication instance that can provide any credentials needed for the user in the specified realm of the specified domain(s). If null, any existing authentication associated with the specified realm(s) will be removed from the map.
doValidation - If false, only the Provider map will be updated; if true, each impacted domain server will be contacted immediately to inform it of the change in credentials. The user will be logged off the realm(s) already in the map and, if the Authentication object is not null a new logon will be attempted using the given credentials.
Throws:
WvcmException -
  • if doValidation is true, the provided Authentication object is not null, and the credentials it provides are rejected by a server, or
  • if doValidation is true, the provided Authentication object is null, and a server cannot terminate the provider of (i.e. logoff) a once-active user.

setDefaultDomain

void setDefaultDomain(StpProvider.Domain domain)
                      throws WvcmException
Establishes the default StpProvider.Domain for this provider. The default domain is applied when a location missing a domain is used to construct a proxy.

Parameters:
domain - The default StpProvider.Domain. Use null to disable the automatic filling-in of missing domain fields.
Throws:
WvcmException - if this provider does not support the given domain.

setDefaultRepository

void setDefaultRepository(StpProvider.Domain domain,
                          StpRepository repo)
                          throws WvcmException
Establishes the default repository of a specified type to be associated with this provider.

Parameters:
domain - The StpProvider.Domain for which the given repository is to be the default.
repo - The new default repository. May be null to indicate that there is no default repository associated with this provider.
Throws:
WvcmException - if this provider does not support the given domain.

setDefaultRepository

void setDefaultRepository(StpRepository repo)
                          throws WvcmException
Establishes the default repository to be associated with this provider. The default repository is applied when a location missing a repository field is used to construct a proxy.

Parameters:
repo - The new default repository. May be null to indicate that there is no default repository associated with this provider.
Throws:
WvcmException - if this provider does not support the repository type of the given repository.

setHttpProxy

void setHttpProxy(String host,
                  String port)
Set the HTTP proxy host and port for all future calls from this client.

Parameters:
host - Name of proxy host.
port - Port number of proxy on that host.

setIsDisconnected

void setIsDisconnected(boolean isDisconnected)
Grants or denies this provider the ability to connect to a server while performing tasks for the client.

Note: Setting this attribute does not cause an interaction with the server to initialize or terminate the session. Use the setAuthentication method to control session lifetimes.

Parameters:
isDisconnected - true if this provider is not to connect to server; false if this provider may connect to a server.

setServerUrl

void setServerUrl(String url)
                  throws WvcmException
Establishes the default server URL for this provider, if one has not already been established. Within the lifetime of a given instance of an StpProvider, the server URL may be set only once. This method will throw an exception if the provider's server URL has already been set when applied.

The provider's server URL may also be applied as an initialization argument using the key SERVER_URL_KEY.

The specified URL is used for ClearCase operations only. ClearQuest operations do not contact a server, but require an installation of ClearQuest on the client machine.

Parameters:
url - The URL used to contact the CM Server via this provider. Must not be null. This URL is not validated until the next "do" method that requires a URL is invoked.
Throws:
WvcmException - if a server URL has already been established for this provider.

setUserLocale

void setUserLocale(Locale locale)
Defines the Locale that is to be used by this provider and passed to the server to identify the locale to use when performing locale-dependent operations for this provider. Does not set the default Locale of the JVM.

Parameters:
locale - A Locale object representing the locale to be used when performing locale-dependent operations for this provider. Must not be null; use java.util.Locale#getDefault() to use the native Locale of the client.

setUserTimeZone

void setUserTimeZone(TimeZone timeZone)
Defines the time zone that is to be used by this provider and passed to the server for this provider. Does NOT set the default TimeZone of the JVM.

Parameters:
timeZone - A TimeZone object representing the time zone to be used when performing date translation for this provider. Must not be null; use java.util.TimeZone#getDefault() to use the native time zone of the client.

stableSelector

StpLocation stableSelector(StpProvider.Domain domain,
                           String rType,
                           String objectId,
                           String repoId)
                           throws WvcmException
Constructs an StpLocation from the individual fields of a location specification that follows the stable selector scheme.

Parameters:
domain - The domain of the resource.
rType - The resource type segment of the name.
objectId - The object id of the resource.
repoId - The repository id of the resource.
Returns:
A stable-selector scheme StpLocation object with the specified fields
Throws:
WvcmException - If the location is not well-formed.

stpLocation

StpLocation stpLocation(StpProvider.Domain domain,
                        String pname)
                        throws WvcmException
Constructs an StpLocation from a string representation assuming the Location is to be used exclusively in a specified domain. In particular, if there is no scheme prefix or the given scheme prefix would not be recognized in the given domain, the input is forced to be a pname (in the PNAME_IMPLIED namespace).

Parameters:
domain - The domain in which the location is to be used. Must not be null, NONE, or INVALID.
pname - The string representation for a location to be used in the given domain. Must not be null or empty.
Returns:
An StpLocation appropriate for the given domain.
Throws:
WvcmException - if the input is null or empty or an otherwise acceptable input specifies a domain different from that requested.

stpLocation

StpLocation stpLocation(String location)
                        throws WvcmException
Constructs an StpLocation from its string representation

Parameters:
location - A string satisfying the syntax for a CM API location specification.
Returns:
An StpLocation object capturing the fields specified in the given location specification string.
Throws:
WvcmException - If the string is null or empty.

stpProductInfo

StpProvider.StpProductInfo stpProductInfo(StpProvider.Domain domain)
Returns the version information for the code implementing this Provider or one of its domain-specific subproviders. Each subprovider may make available additional version information as extensions to the StpProductInfo interface.

Parameters:
domain - The domain for which subprovider information is desired. If null, the version information for this interface and the shared components of this provider will be returned.
Returns:
An StpProductInfo structure (or a domain-specific extension thereof) containing version information for the code that implements this Provider (domain == null) or for the code that implements the subprovider for the domain specified by the domain argument. Will be null if a subprovider for the specified domain has not be instantiated.

stpProvider

StpProvider stpProvider()
Returns:
The Provider extension associated with this Provider instance that implements the StpProvider interface; will never be null.

stpRepository

StpRepository stpRepository(StpLocation location)
Constructs an StpRepository proxy for a repository at a specified location.

Parameters:
location - The location the new proxy is to refer to. A repository need not exist at this location, but the location must be otherwise valid for a repository. Must not be null.
Returns:
A new StpRepository proxy for a repository at the specified location.

terminate

void terminate()
               throws WvcmException
Terminates this provider's association with the servers that it is actively tracking, releasing any resources it has accumulated as a result of that tracking.

Calling this method marks all of the provider's proxy and location objects as invalid, and so all client-side references should be abandoned; any subsequent method calls on the Provider object yields an UnsupportedOperationException exception. Thus you should typically call this method immediately prior to the exit of the owning thread or process.

Throws:
WvcmException - if the accumulated resources cannot be disposed of.

userFriendlySelector

StpLocation userFriendlySelector(StpProvider.Domain domain,
                                 StpLocation.Namespace namespace,
                                 String name,
                                 String repo)
                                 throws WvcmException
Constructs an StpLocation from the individual fields of a location specification that follows the user-friendly object selector scheme

Parameters:
domain - the Domain. Must not be INVALID
namespace - the Namespace for the location. Must not be INVALID, REPO, or FAST
name - the segmented object name field. Each segment of the name must be encoded as required by the namespace. May be null or empty to form the root of the namespace in a repository resource.
repo - the repository name. Each segment of the name must be encoded as required by the namespace.
Returns:
An StpLocation object with the specified fields.
Throws:
WvcmException - Thrown if the location String composed from the given fields is not in the correct form. StpReasonCode = StpException.StpReasonCode.INVALID_OBJECT_SELECTOR

Generated Wed 20-Apr-2011 11:26 AM

Copyright © IBM 2011. All rights reserved.