Package org.opensaml.core.xml.util

Class 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 Detail

      • log

        private final org.slf4j.Logger log
        Class logger.

      • 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

      • 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