Google Data APIs Client Library (1.41.1)



com.google.gdata.util
Class VersionRegistry

java.lang.Object
  extended by com.google.gdata.util.VersionRegistry

public class VersionRegistry
extends java.lang.Object

The VersionRegistry class is used to manage and retrieve version information about executing services. The registry supports the ability to configure versions for a running thread (via the setThreadVersion(Version) method) or global defaults that will apply to all threads (using the addDefaultVersion(Version, boolean) method. Thread defaults will have precedence over global defaults if present for the same service. The class provides a singleton instance that is being used to manage version information. This instance is initialized by the ensureRegistry() method. The active VersionRegistry instance can be retrieved using the get() method. This method will throw an IllegalStateException if the version registry has not been initialized to aid in the detection of when version-conditional code is being executed in an environment where versions have net been configured. The getVersion(Class) method can be used to request the version information for a particular service. A model for writing version conditional code based upon the registry is: Version myServiceVersion = VersionRegistry.get().getVersion(MyService.class); if (myServiceVersion.isCompatible(MyService.VERSIONS.V1) { ... execute V1-specific handling ... } VersionRegistry access is thread-safe.


Constructor Summary
VersionRegistry()
           
 
Method Summary
 void addDefaultVersion(Version newDefault, boolean includeImplied)
          Adds a default version to the version registry.
static VersionRegistry ensureRegistry()
          Returns the current VersionRegistry, creating it if necessary.
static VersionRegistry get()
          Returns the version registry being used to manage version information.
 java.util.List<Version> getDefaultVersions()
          Returns the list of default versions for the registry.
 java.util.List<Version> getThreadVersions()
          Returns the list of versions associated with the current thread or null if there are currently no thread versions.
 Version getVersion(java.lang.Class<? extends Service> serviceClass)
          Returns the version of a service.
static Version getVersionFromProperty(java.lang.Class<? extends Service> serviceClass)
          Constructs a new Version instance based upon the value of a Java system property associated with a Service class.
 void reset(java.util.List<Version> initialDefaults)
          Resets the VersionRegistry to a clean state with no thread local configuration and the specified set of version defaults.
 void resetThreadVersion()
          Resets the version information for the current thread back to the default state.
 void setThreadVersion(Version version)
          Sets the desired version for the current thread to the provided values.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

VersionRegistry

public VersionRegistry()
Method Detail

ensureRegistry

public static VersionRegistry ensureRegistry()
Returns the current VersionRegistry, creating it if necessary. The get() method is preferred for most registry usage, as it enables the discovery of the execution of version-conditional code in an environment (such as unit test cases) where versioning has not been properly configured.


get

public static final VersionRegistry get()
Returns the version registry being used to manage version information.

Returns:
the active version registry instance.
Throws:
java.lang.IllegalStateException - if the registry has not been initialized.

getVersionFromProperty

public static Version getVersionFromProperty(java.lang.Class<? extends Service> serviceClass)
Constructs a new Version instance based upon the value of a Java system property associated with a Service class. The system property name is computed from the service class name with ".version" appended. The syntax of the property value is "[service]<major>[.<minor>]". The default value of the service is assumed to be the initiating or target service and the minor revision will be assumed to be zero if not present. If the associated system property is not set, the method will return null.

Parameters:
serviceClass - service class to use in computing the version property name.
Returns:
the Version computed from the property of null if the property is not set.
Throws:
java.lang.IllegalStateException - if the property value does not contain valid revision information.

getDefaultVersions

public java.util.List<Version> getDefaultVersions()
Returns the list of default versions for the registry. The default version is the version that will be used if no version is explicitly selected.

Returns:
list of default versions.

addDefaultVersion

public void addDefaultVersion(Version newDefault,
                              boolean includeImplied)
Adds a default version to the version registry. This will overwrite any existing default version for the same service.

Parameters:
newDefault - default version to add to the registry (not null)
includeImplied - if true, indicates that all implied versions associated with the new default should be set as defaults too.

setThreadVersion

public void setThreadVersion(Version version)
Sets the desired version for the current thread to the provided values. This method will update any existing request version information set by defaults or a previous call to this method. The specified version (and any related implied versions} will be set for the current thread until the resetThreadVersion() method is called to reset to the version information back to the default state.

Parameters:
version - the new active version for this request.

getThreadVersions

public java.util.List<Version> getThreadVersions()
Returns the list of versions associated with the current thread or null if there are currently no thread versions.

Returns:
thread version list or null

resetThreadVersion

public void resetThreadVersion()
Resets the version information for the current thread back to the default state.


getVersion

public Version getVersion(java.lang.Class<? extends Service> serviceClass)
Returns the version of a service.

Parameters:
serviceClass - of the service to return.
Returns:
version of the service.
Throws:
java.lang.IllegalStateException - if no version information could be found for the requested service.

reset

public void reset(java.util.List<Version> initialDefaults)
Resets the VersionRegistry to a clean state with no thread local configuration and the specified set of version defaults.

Parameters:
initialDefaults - the list of default versions that should be used to initialize the version registry, or null for an empty default list.