public class

VersionRegistry

extends Object
java.lang.Object
   ↳ com.google.gdata.util.VersionRegistry

Class Overview

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.

Summary

Fields
private List<Version> defaultVersions Maintains the global defaults.
private ThreadLocal<List<Version>> threadVersions Maintains the per-thread version information.
private static VersionRegistry versionRegistry Singleton registry instance.
Public Constructors
VersionRegistry()
Public Methods
void addDefaultVersion(Version newDefault, boolean includeImplied)
Adds a default version to the version registry.
synchronized static VersionRegistry ensureRegistry()
Returns the current VersionRegistry, creating it if necessary.
final static VersionRegistry get()
Returns the version registry being used to manage version information.
List<Version> getDefaultVersions()
Returns the list of default versions for the registry.
List<Version> getThreadVersions()
Returns the list of versions associated with the current thread or null if there are currently no thread versions.
Version getVersion(Class<? extends Service> serviceClass)
Returns the version of a service.
static Version getVersionFromProperty(Class<? extends Service> serviceClass)
Constructs a new Version instance based upon the value of a Java system property associated with a Service class.
synchronized void reset(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.
[Expand]
Inherited Methods
From class java.lang.Object

Fields

private List<Version> defaultVersions

Maintains the global defaults.

private ThreadLocal<List<Version>> threadVersions

Maintains the per-thread version information. The field may be null if thread tracking is not enabled and the thread local value may be null if no versions have been set for the current thread.

private static VersionRegistry versionRegistry

Singleton registry instance. The singleton is lazily initialized when the ensureRegistry() method is called. The reason for this design is to support the detect of version-conditional code running in unit tests. Such tests need to be run in a version-aware test environment (that will validate the behavior against all valid versions), so having a model so that they will fail by default is helpful to guarantee this.

Public Constructors

public VersionRegistry ()

Public Methods

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.

public static synchronized 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.

public static final VersionRegistry get ()

Returns the version registry being used to manage version information.

Returns
  • the active version registry instance.
Throws
IllegalStateException if the registry has not been initialized.

public 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.

public 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

public Version getVersion (Class<? extends Service> serviceClass)

Returns the version of a service.

Parameters
serviceClass Of the service to return.
Returns
  • version of the service.
Throws
IllegalStateException if no version information could be found for the requested service.

public static Version getVersionFromProperty (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
IllegalStateException if the property value does not contain valid revision information.

public synchronized void reset (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.

public void resetThreadVersion ()

Resets the version information for the current thread back to the default state.

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.