Module net.shibboleth.utilities.java.support
Package net.shibboleth.utilities.java.support.collection

Class IndexingObjectStore<T>

  • Type Parameters:
    T - type of object being stored
    @ThreadSafe
public class IndexingObjectStore<T>
extends Object

    This class is used to store instances of objects that may be created independently but are, in fact, the same object. For example, KeyInfo XML structures contain keys, certs, and CRLs. Multiple unique instances of a KeyInfo may contain, and separately construct, the exact same cert. KeyInfo could, therefore, create a class-level instance of this object store and put certs within it. In this manner the cert is only sitting in memory once and each KeyInfo simply stores a reference (index) to stored object.

    This store uses basic reference counting to keep track of how many of the respective objects are pointing to an entry. Adding an object that already exists, as determined by the object's equals() method, simply increments the reference counter. Removing an object decrements the counter. Only when the counter reaches zero is the object actually freed for garbage collection.

    Note: the instance of an object returned by get(String) need not be the same object as stored via put(Object). However, the instances will be equal according to their equals(). The indexing and storage is based on use of Map, so the normal caveats related to use of hash-based collection types apply: if the stored object's hashCode() and equals() methods are implemented based on mutable properties of the object, then those object instance's properties should not be mutated while the object is stored, otherwise unpredictable behavior will result.

    • Field Detail

      • rwLock

        private ReadWriteLock rwLock
        Read/Write lock used to control synchronization over the backing data store.

      • indexStore

        private Map<T,​Integer> indexStore
        Map of object instances to the index value used to reference them externally.

      • lastIndex

        private int lastIndex
        The last index sequence used.

    • Constructor Detail

      • IndexingObjectStore

        public IndexingObjectStore()
        Constructor.

    • Method Detail

      • clear

        public void clear()
        Clears the object store.

      • containsIndex

        public boolean containsIndex​(String index)
        Checks whether the store contains an object registered under the given index.
        Parameters:
        index - the index to check
        Returns:
        true if an object is associated with the given index, false if not

      • containsInstance

        public boolean containsInstance​(T instance)
        Checks whether the store contains an object instance equal to the specified one.
        Parameters:
        instance - the object instance to check
        Returns:
        true if an object instance equal to the specified one is stored, false if not

      • isEmpty

        public boolean isEmpty()
        Checks if the store is empty.
        Returns:
        true if the store is empty, false if not

      • put

        public String put​(T object)
        Adds the given object to the store. Technically this method only adds the object if it does not already exist in the store. If it does this method simply increments the reference count of the object.
        Parameters:
        object - the object to add to the store, may be null
        Returns:
        the index that may be used to later retrieve the object or null if the object was null

      • get

        public T get​(String index)
        Gets a registered object by its index.
        Parameters:
        index - the index of an object previously registered, may be null
        Returns:
        the registered object or null if no object is registered for that index

      • remove

        public void remove​(String index)
        Removes the object associated with the given index. Technically this method decrements the reference counter to the object. If, after the decrement, the reference counter is zero then, and only then, is the object actually freed for garbage collection.
        Parameters:
        index - the index of the object, may be null

      • size

        public int size()
        Gets the total number of unique items in the store. This number is unaffected by the reference count of the individual stored objects.
        Returns:
        number of items in the store

      • getIndex

        protected String getIndex​(T object)
        Get the index for the specified object.
        Parameters:
        object - the target object
        Returns:
        the object index value

      • removeIndex

        protected void removeIndex​(T object)
        Remove the index for the specified object.
        Parameters:
        object - the target index