Package org.opensaml.core.xml.util

Class AbstractWrappedSingletonFactory<Input,Output>

java.lang.Object
org.opensaml.core.xml.util.AbstractSingletonFactory<Input,Output>
org.opensaml.core.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

    Fields
    Modifier and Type
    Field
    Description
    private boolean
    explicitRelease
    Flag indicating whether explicit release of the output instances is required.
    private final org.slf4j.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

    Constructors
    Constructor
    Description
    AbstractWrappedSingletonFactory()
    Constructor.
    AbstractWrappedSingletonFactory(boolean requireExplicitRelease)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    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.core.xml.util.AbstractSingletonFactory

    createNewInstance

    Methods inherited from class java.lang.Object

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

  • Field Details

    • log

      private final org.slf4j.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 Details

    • 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 Details

    • 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