Package resources

Class AbstractResourceCache<I,​R>

  • public abstract class AbstractResourceCache<I,​R>
extends java.lang.Object
    An abstract base class for creating memory-sensitive caches of objects that can be loaded (or created) on demand from an identifier. The cache operates like a map: objects are requested by their identifier (such as a file or URL). If the object matching the identifier is not already in the cache, it will be loaded from the identifier, stored in the cache, and returned. The next time the object is requested using its identifier, it will be returned immediately (without loading) if it is still in the cache. However, if the object has no references to it outside of the cache, then it may be cleared from the cache at any time in order to make more memory available. If it is requested again in the future after being cleared, it will be reloaded.

    It is guaranteed that every cached object that has no other references to it will be cleared before an OutOfMemory error is thrown. The cache can also be cleared on demand, and individual objects removed.

    Caches based on this class also support the cache metrics registry provided by the ResourceKit. To use this feature, simply register a metrics instance returned by createCacheMetrics(boolean). Then your cache will be listed with others in, for example, the developer tools plug-in.

    Since:
    3.0
    Author:
    Chris Jennings

    • Constructor Summary

      Constructors 
      Constructor Description
      AbstractResourceCache​(java.lang.Class<? extends R> contentType, java.lang.String name)
      Creates a new resource cache with the given name.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected boolean allowCaching​(I canonicalIdentifier, R loadedResource)
      Returns true if this resource should be cached.
      protected I canonicalizeIdentifier​(I identifier)
      Normalizes an identifier before attempting to find the cached resource or load the resource from a source.
      void clear()
      Clears all cached resources.
      CacheMetrics createCacheMetrics​(boolean allowClearing)
      Creates a new cache metrics instance for this cache.
      long estimateMemoryUse()
      Returns an estimate of the amount of memory currently consumed by cached objects, or -1 if an estimate is not available.
      protected long estimateResourceMemoryUse​(R resource)
      Returns an estimate of how much memory the cached resource is consuming, or -1 if the size is unknown.
      R get​(I identifier)
      Returns the resource associated with the specified identifier.
      protected abstract R loadResource​(I canonicalIdentifier)
      Loads the identified resource.
      void remove​(I identifier)
      Removes the identified object from the cache, if it is present.
      int size()
      Returns the number of resources that are currently cached.
      java.lang.String toString()
      Returns a string description of the cache useful for debugging purposes.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • AbstractResourceCache

        public AbstractResourceCache​(java.lang.Class<? extends R> contentType,
                             java.lang.String name)
        Creates a new resource cache with the given name. If the given name is null, a default name will be generated using the name of the concrete class.
        Parameters:
        name - a descriptive name for the resource cache
        Throws:
        java.lang.NullPointerException - if the content type is null

    • Method Detail

      • get

        public final R get​(I identifier)
        Returns the resource associated with the specified identifier. The resource may be returned from the cache, or if it is unavailable in the cache it will be created by calling loadResource(I).

        If the requested resource does not exist, the result depends on the subclass implementation. Some subclasses may return a default resource to stand in for the requested resource. Others may return null or throw an exception.

        Parameters:
        identifier - the identifier of the resource to obtain
        Returns:
        the requested resource
        Throws:
        java.lang.NullPointerException - if the identifier is null

      • remove

        public final void remove​(I identifier)
        Removes the identified object from the cache, if it is present. The object will be reloaded the next time it is requested.
        Parameters:
        identifier - the identifier of the resource to remove from the cache
        Throws:
        java.lang.NullPointerException - if the identifier is null

      • clear

        public final void clear()
        Clears all cached resources.

      • size

        public final int size()
        Returns the number of resources that are currently cached.
        Returns:
        the number of cached objects

      • estimateMemoryUse

        public final long estimateMemoryUse()
        Returns an estimate of the amount of memory currently consumed by cached objects, or -1 if an estimate is not available. This method will call estimateResourceMemoryUse(R) for each cached resource. If any resource returns -1, this method will return -1. Otherwise, it returns the sum of all of the size estimates of the individual resources.
        Returns:
        current estimated memory consumption, in bytes, or -1

      • canonicalizeIdentifier

        protected I canonicalizeIdentifier​(I identifier)
        Normalizes an identifier before attempting to find the cached resource or load the resource from a source. If the same resource can be located using any of several identifiers, this method should convert these equivalent forms into a canonical form in order to prevent the same resource from being loaded and cached under multiple aliases.

        The base class will return the original identifier without changes.

        Parameters:
        identifier - the non-nullidentifier to convert to canonical form
        Returns:
        the canonical form of the identifier

      • allowCaching

        protected boolean allowCaching​(I canonicalIdentifier,
                               R loadedResource)
        Returns true if this resource should be cached.

        The base class returns true. Subclasses can override this if they wish to decide whether individual objects should be cached. For example, a subclass might only allow caching of objects if the identifier refers to a read-only storage facility.

        Parameters:
        canonicalIdentifier - the identifier of the resource object
        loadedResource - the resource object, as returned from loadResource(I)
        Returns:
        true if the object should be cached

      • loadResource

        protected abstract R loadResource​(I canonicalIdentifier)
        Loads the identified resource. This method is called when the requested resource is not available in the cache.
        Parameters:
        canonicalIdentifier - the canonicalized identifier for the resource
        Returns:
        the object to associate with the identifier in the cache

      • estimateResourceMemoryUse

        protected long estimateResourceMemoryUse​(R resource)
        Returns an estimate of how much memory the cached resource is consuming, or -1 if the size is unknown.

        The base class returns -1. Subclasses should override this if they can provide a reasonable estimate.

        Parameters:
        resource - the resource to estimate the size of
        Returns:
        an estimate of the memory used by the resource, or -1 if unknown

      • createCacheMetrics

        public CacheMetrics createCacheMetrics​(boolean allowClearing)
        Creates a new cache metrics instance for this cache. Typically, only one instance is created and it is then registered so it can be looked up by support tools.
        Parameters:
        allowClearing - if false, then the returned metrics instance cannot be used to clear the cache
        Returns:
        a new cache metrics instance that reflects the state of this cache
        See Also:
        ResourceKit.registerCacheMetrics(resources.CacheMetrics)

      • toString

        public java.lang.String toString()
        Returns a string description of the cache useful for debugging purposes.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a description of the cache