org.chwf.registry
Class UserRegistry

java.lang.Object
  |
  +--org.chwf.registry.UserRegistry

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

GlobalUserRegistry, ServletData

public class UserRegistry

extends java.lang.Object

implements java.io.Serializable

A class for caching user-specific data. It provides an abstraction layer for components that can run both in single-user applications (such as test applications) and multi-user applications (such as a web application). Single-user application should initialize a global registry by using the GlobalUserRegistry.init() method:

 GlobalUserRegistry.init();

Multi-user applications should cache their registry in the user's session and transfer them to this class at the beginning of each thread of execution using the initLocalRegistry(UserRegistry). This method stores the registry in a ThreadLocal variable, so that it can be retrieved anywhere in the thread of execution. This local registry should be released when the thread of execution is complete using the releaseLocalRegistry() method:

 // A servlet example:
 UserRegistry registry =
   (UserRegistry) session.getAttribute("UserRegistry");
 UserRegistry.initLocalRegistry(registy);
 
 // Do work ...
 
 UserRegistry.releaseLocalRegistry();

Releasing the local registry is important because multi-user applications often use thread-pooling, and failing to release the registry might mean that the ThreadLocal variable could bleed between users. Failure to release local registries could lead to memory leaks and weird errors.

The various initialization methods are protected, so that the user registry can only be initialized by subclasses. For each application, you should create a subclass of the UserRegistry class with the correct initializations for that application. See GlobalUserRegistry and ServletData for examples. The registry may be initialized in one way for production and another for testing.

Whether the application is using global or local registries, data inside the registry is manipulated in the same way:

 UserRegistry.setRegistryEntry("My data", value);
 Object data = UserRegistry.getRegistryEntry("My data");
 UserRegistry.removeRegistryEntry("My data");

Ideally, you should create encapsulating classes that prevent direct access to the user registry. You should use a good naming convention (based on class names) to minimize name collisions for information stored in the registry.

 public class UserLocale {
   private static final String REGISTRY_NAME = UserLocale.class.getName();
 
   public Locale getLocale() {
     return (Locale) UserRegistry.getRegistryEntry(UserLocale.REGISTRY_NAME);
   }

   public void setLocale(Locale locale) {
    UserRegistry.overwriteRegistryEntry(UserLocale.REGISTRY_NAME, locale);
   }
 }

Finally, because the registry is global and global data is bad, you should use it sparingly.

Author:

Paul Strack

See Also:

Serialized Form

Constructor Summary

UserRegistry()

Method Summary

static UserRegistry	getRegistry() Retrieve the registry.
static java.lang.Object	getRegistryEntry(java.lang.String name) Get registry entry value.
static java.lang.Object	getSingleton(java.lang.Class cls) Get class-based, user-specific singleton for the given class, creating a new one if none exists.
static java.lang.Object	getSingleton(java.lang.String cls) Get class-based, user-specific singleton for the given class, creating a new one if none exists.
protected static void	initGlobalRegistry(UserRegistry registry) Initialize a global registry.
protected static void	initLocalRegistry(UserRegistry registry) Initialize a local registry.
static boolean	isInitialized() Returns true if the registry is initialized.
static java.lang.Object	overwriteRegistryEntry(java.lang.String name, java.lang.Object value) Overwrite registry entry.
protected static void	releaseGlobalRegistry() Release the global registry.
protected static void	releaseLocalRegistry() Release the local registry.
static void	releaseSingleton(java.lang.Class cls) Release registry singleton for the given class.
static java.lang.Object	removeRegistryEntry(java.lang.String name) Remove and return registry entry.
static void	setRegistryEntry(java.lang.String name, java.lang.Object value) Set registry entry value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UserRegistry

public UserRegistry()

Method Detail

isInitialized

public static boolean isInitialized()

Returns true if the registry is initialized.

Returns:

true if the registry is initialized.

getRegistry

public static UserRegistry getRegistry()
                                throws RegistryException

Retrieve the registry. This can be used for registry serialization, or to retrieve additional registry data from subclasses:

 CustomRegistry custom = (CustomRegistry) UserRegistry.getRegistry();
 custom.getCustomData();

Returns:

The registry.

Throws:

RegistryException - If the registry is not initialized.

getRegistryEntry

public static java.lang.Object getRegistryEntry(java.lang.String name)
                                         throws RegistryException

Get registry entry value.

Parameters:

name - The registry entry name.

Returns:

The registry entry value.

Throws:

RegistryException - If the registry is not initialized.

setRegistryEntry

public static void setRegistryEntry(java.lang.String name,
                                    java.lang.Object value)
                             throws RegistryException

Set registry entry value. Throws a runtime exception if this overwrites an existing registry entry.

Parameters:

name - The registry entry name.

value - The registry entry value.

Throws:

RegistryException - If the registry is not initialized or an existing value is overwritten.

overwriteRegistryEntry

public static java.lang.Object overwriteRegistryEntry(java.lang.String name,
                                                      java.lang.Object value)
                                               throws RegistryException

Overwrite registry entry.

Parameters:

name - The registry entry name.

value - The registry entry value.

Returns:

The original value.

Throws:

RegistryException - If the registry is not initialized.

removeRegistryEntry

public static java.lang.Object removeRegistryEntry(java.lang.String name)
                                            throws RegistryException

Remove and return registry entry.

Parameters:

name - The registry entry name.

Returns:

The original value.

Throws:

RegistryException - If the registry is not initialized.

getSingleton

public static java.lang.Object getSingleton(java.lang.Class cls)
                                     throws RegistryException

Get class-based, user-specific singleton for the given class, creating a new one if none exists. This method uses the class's no-parameter constructor.

Parameters:

cls - The class for the singleton.

Returns:

The singleton object.

Throws:

RegistryException - If the registry is not initialized or singleton creation fails.

getSingleton

public static java.lang.Object getSingleton(java.lang.String cls)
                                     throws RegistryException

Get class-based, user-specific singleton for the given class, creating a new one if none exists. This method uses the class's no-parameter constructor.

Parameters:

cls - The class for the singleton as a String.

Returns:

The singleton object.

Throws:

RegistryException - If the registry is not initialized or singleton creation fails.

releaseSingleton

public static void releaseSingleton(java.lang.Class cls)
                             throws RegistryException

Release registry singleton for the given class.

Parameters:

cls - The class for the singleton.

Throws:

RegistryException - If the registry is not initialized.

initLocalRegistry

protected static void initLocalRegistry(UserRegistry registry)

Initialize a local registry. Used by subclasses. Re-initializing the registry over-writes existing data.

Parameters:

registry - The registry.

releaseLocalRegistry

protected static void releaseLocalRegistry()

Release the local registry. Used by subclasses.

initGlobalRegistry

protected static void initGlobalRegistry(UserRegistry registry)

Initialize a global registry. Used by subclasses. An application that uses a global registry should not use local registries.

Parameters:

registry - The registry.

releaseGlobalRegistry

protected static void releaseGlobalRegistry()

Release the global registry. Used by subclasses.