Evaluating Software Design Patterns
— the "Gang of Four" patterns implemented in Java 6

dk.rode.thesis.singleton
Class StatefullSingletonRegistry<T>

java.lang.Object
  extended by dk.rode.thesis.singleton.StatefullSingletonRegistry<T>
Type Parameters:
T - The super type of all singleton types handled by this registry. Use Object if any type of singleton type can be handled.
All Implemented Interfaces:
SingletonRegistry<T>, Iterable<T>
Direct Known Subclasses:
LoadableSingletonRegistry

public class StatefullSingletonRegistry<T>
extends Object
implements SingletonRegistry<T>, Iterable<T>

A statefull singleton registry stores a reference to each acquired singleton instance using a live daemon thread: as long as the registry is not garbage collected, the singleton instances acquired through it will not be garbage collected either.

By using composition, this registry defers acquisition of the singleton types to another registry. The registry to use is specified at construction time.

References to created singletons can also be discarded explicitly.

Implementation notes:
This registry do not utilise an internal cache to store the acquired singletons because that would require synchronisation. Furthermore, we do not know how the actual singleton classes are implemented, i.e. static initialisation, lazily initialised, synchronised, or not synchronised!? Hence, each time the getInstance(Class) method is invoked the call is forwarded to the registry actually used to acquire the singleton types.

By deferring the responsibility to another registry, the other registry may also be able to acquire broader singleton types, i.e. any singleton type <? super T>. It also ensures that the internal state kept by this registry has nothing to do with the actual creation of singleton types, only with references to the unique instances of the singleton types once created.

The anonymous java.lang.Runnable target object used by the live daemon thread is an application of the Adapter pattern.

Author:
Gunni Rode / rode.dk

Field Summary
private  SingletonRegistry<? super T> registry
          The actual registry used to acquire the singleton types supplied at construction time.
private  Set<T> singletons
          References to all acquired singleton types based on their identity so they will not be garbage collected.
private  Thread thread
          Live daemon thread to ensure that the references to acquired singleton instances never goes out of scope.
 
Constructor Summary
StatefullSingletonRegistry()
          Constructor.
StatefullSingletonRegistry(SingletonRegistry<? super T> registry)
          Constructor.
 
Method Summary
<S extends T>
boolean
discard(Class<S> type)
          Discards the reference to the singleton instance of the type supplied as type, if such a reference is kept by this registry.
<S extends T>
S
getInstance(Class<S> type)
          Returns the singleton instance of the type supplied as type.
 boolean isSingleton(Class<?> type)
          Returns true of the type supplied as type is a singleton type handled by this registry, false if not.
 Iterator<T> iterator()
          Returns an iterator to iterate over all singleton instances referenced by this registry.
 String toString()
          Returns the string representation of this registry.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

registry

private final SingletonRegistry<? super T> registry
The actual registry used to acquire the singleton types supplied at construction time.

Never null.


singletons

private final Set<T> singletons
References to all acquired singleton types based on their identity so they will not be garbage collected.

Never null, but can be empty.


thread

private final Thread thread
Live daemon thread to ensure that the references to acquired singleton instances never goes out of scope.

Never null.

Constructor Detail

StatefullSingletonRegistry

public StatefullSingletonRegistry()
Constructor.

An instance of the StatelessSingletonRegistry type will be used to acquire the singleton instances.


StatefullSingletonRegistry

public StatefullSingletonRegistry(SingletonRegistry<? super T> registry)
Constructor.

Parameters:
registry - The registry that will be used to acquire the singleton instances; cannot be null.
Throws:
NullPointerException - If registry is null.
Method Detail

discard

public <S extends T> boolean discard(Class<S> type)
Discards the reference to the singleton instance of the type supplied as type, if such a reference is kept by this registry.

If this registry has no such reference, false is returned.

Type Parameters:
S - The actual singleton type.
Parameters:
type - The class token identifying the type; cannot be null.
Returns:
True if type represents a singleton type this registry had a reference to, false if not.
Throws:
NullPointerException - If type is null.
See Also:
isSingleton(Class)

getInstance

public <S extends T> S getInstance(Class<S> type)
Description copied from interface: SingletonRegistry
Returns the singleton instance of the type supplied as type.

Whether or not type is a singleton type handled by this registry can be determined by the SingletonRegistry.isSingleton(Class) method.

Specified by:
getInstance in interface SingletonRegistry<T>
Type Parameters:
S - The actual singleton type.
Parameters:
type - The class token identifying the singleton type; cannot be null.
Returns:
The singleton instance of the type supplied as type; never null.
Throws:
NullPointerException - If type is null.
SingletonException - If type is not a singleton type handled by this registry, or if the type cannot be created when first requested.

isSingleton

public boolean isSingleton(Class<?> type)
Description copied from interface: SingletonRegistry
Returns true of the type supplied as type is a singleton type handled by this registry, false if not.

Even if this method returns true, the actual singleton instance may not be created before it is requested. The creation of the singleton instance can therefore still fail!

Specified by:
isSingleton in interface SingletonRegistry<T>
Parameters:
type - The class token identifying the type; cannot be null.
Returns:
True if type represents a singleton type handled by this registry.
Throws:
NullPointerException - If type is null.
See Also:
discard(Class)

iterator

public Iterator<T> iterator()
Returns an iterator to iterate over all singleton instances referenced by this registry.

Modifying the returned iterator will not affect this registry.

Specified by:
iterator in interface Iterable<T>
Returns:
An iterator; never null, but can be empty.

toString

public String toString()
Returns the string representation of this registry.

Overrides:
toString in class Object
Returns:
The string representation; never null.

Gunni Rode / rode.dk

Feel free to use and/or modify the Java 6 source code developed for this thesis AT YOUR OWN RISK, but note that the source code comes WITHOUT ANY — and I do mean WITHOUT ANY — form of warranty WHAT SO EVER!

The original thesis and source code are available at rode.dk/thesis.