org.opensaml.xml.util
Class AbstractWrappedSingletonFactory<Input,Output>

java.lang.Object
  org.opensaml.xml.util.AbstractSingletonFactory<Input,Output>
      org.opensaml.xml.util.AbstractWrappedSingletonFactory<Input,Output>

Type Parameters:

Input - the factory input class type

Output - the factory output class type

All Implemented Interfaces:

SingletonFactory<Input,Output>

public abstract class AbstractWrappedSingletonFactory<Input,Output>
extends AbstractSingletonFactory<Input,Output>

An implementation of SingletonFactory, which provides some support for handling cases where the output class instance holds a reference to the input class instance.

A WeakHashMap is used as the underlying store. This ensures that if the input class instance become otherwise unused (weakly reachable), the input class instance key used within the factory will not prevent the input class from being garbage-collected, thereby preventing a memory leak.

This class differs from AbstractSimpleSingletonFactory in that output value instances stored and returned by the factory are also wrapped internally in a WeakReference. This class should be used in cases where the output class holds a reference to the input class key, so as not to prevent the described weak reference-based garbage collection of the input class key, and thereby avoiding a memory leak.

Because the output instance is held in a WeakReference, it is subject to aggressive garbage collection if it is otherwise weakly reachable (i.e. no strong or soft references to it are held outside of this factory), ostensibly defeating the purpose of this factory. Therefore if the lifecycle of external strong or soft references to any obtained output instances obtained from the factory is shorter than the desired lifecyle of the output instance (i.e. callers do not hold a strong or soft reference to an output instance for at least as long as to the input instance), then an option requireExplicitRelease is provided that causes the factory to internally maintain a strong reference to each output instance. This inhibits the garbage collection of the output instance. If this option is enabled, then callers must explicity indicate when the output instance may be garbage collected by calling release(Object). Failure to release an output instance when necessary will result in a memory leak of the output instance as well as the input instance (if the output instance holds a strong or soft reference to the input instance).

The default value of requireExplicitRelease is false. This is appropriate for cases where calling code holds long-lived strong or soft references to the output instance, typically as long or longer than references to the corresponding input instance, or where explict release is undesirable or impractical.

Subclasses of this class might also implement automatic release of output instances, instead of or in addition to, the explicit release mechanism supported by this class. This might be based for example on mechanisms such as object aging or a fixed size FIFO queue.

Field Summary

private boolean	explicitRelease Flag indicating whether explicit release of the output instances is required.
private Logger	log Class logger.
private WeakHashMap<Input,WeakReference<Output>>	map Storage for the factory.
private HashSet<Output>	outputSet Set which holds a separate strong reference to output class instances, to inhibit garbage collection of the referent of the WeakReference.

Constructor Summary

AbstractWrappedSingletonFactory()
Constructor.

AbstractWrappedSingletonFactory(boolean requireExplicitRelease)
Constructor.

Method Summary

protected Output	get(Input input) Get the output instance currently associated with the input instance.
Output	getInstance(Input input) Obtain an instance of the output class based on an input class instance.
boolean	isRequireExplicitRelease() Get whether explict release of output instances is required, in order to allow garbage collection and prevent memory leaks.
protected void	put(Input input, Output output) Store the input and output instance association.
protected void	register(Output output) Register the output instance so as to inhibit garbage collection.
void	release(Output output) Release the specified output instance so that, as the referent of a WeakReference, it may be garbage collected when it otherwise becomse weakly reachable.
void	releaseAll() Release all currently held output instances so they may be garbage collected when they become otherwise weakly reachable.

Methods inherited from class org.opensaml.xml.util.AbstractSingletonFactory

createNewInstance

Methods inherited from class java.lang.Object

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

Field Detail

log

private final Logger log

Class logger.

map

private WeakHashMap<Input,WeakReference<Output>> map

Storage for the factory.

outputSet

private HashSet<Output> outputSet

Set which holds a separate strong reference to output class instances, to inhibit garbage collection of the referent of the WeakReference.

explicitRelease

private boolean explicitRelease

Flag indicating whether explicit release of the output instances is required.

Constructor Detail

AbstractWrappedSingletonFactory

public AbstractWrappedSingletonFactory()

Constructor.

AbstractWrappedSingletonFactory

public AbstractWrappedSingletonFactory(boolean requireExplicitRelease)

Constructor.

Parameters:

requireExplicitRelease - if true, callers must explicitly release output instances when garbage collection is desired.

Method Detail

getInstance

public Output getInstance(Input input)

Obtain an instance of the output class based on an input class instance.

Specified by:

getInstance in interface SingletonFactory<Input,Output>

Overrides:

getInstance in class AbstractSingletonFactory<Input,Output>

Parameters:

input - the input class instance

Returns:

an output class instance

isRequireExplicitRelease

public boolean isRequireExplicitRelease()

Get whether explict release of output instances is required, in order to allow garbage collection and prevent memory leaks.

Returns:

true if enabled, false otherwise

release

public void release(Output output)

Release the specified output instance so that, as the referent of a WeakReference, it may be garbage collected when it otherwise becomse weakly reachable.

Parameters:

output - the output instance to release

releaseAll

public void releaseAll()

Release all currently held output instances so they may be garbage collected when they become otherwise weakly reachable.

register

protected void register(Output output)

Register the output instance so as to inhibit garbage collection.

Parameters:

output - the ouput instance to register

get

protected Output get(Input input)

Get the output instance currently associated with the input instance.

The output instance will be automatically unwrapped from within the WeakReference.

Note this will return null if either the input does not currently have an associated output, or if the WeakReference to the output stored had already been clearly in preparation for garbage collection.

Specified by:

get in class AbstractSingletonFactory<Input,Output>

Parameters:

input - the input instance key

Returns:

the output instance which corresponds to the input instance, or null if not present

put

protected void put(Input input,
                   Output output)

Store the input and output instance association.

The output instance will be automatically wrapped in a WeakReference.

Specified by:

put in class AbstractSingletonFactory<Input,Output>

Parameters:

input - the input instance key

output - the output instance value