Class AbstractResourceCache<I,R>
- java.lang.Object
-
- resources.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 bycreateCacheMetrics(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)
Returnstrue
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.
-
-
-
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 isnull
, 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 isnull
-
-
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 callingloadResource(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 isnull
-
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 isnull
-
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 callestimateResourceMemoryUse(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-null
identifier to convert to canonical form- Returns:
- the canonical form of the identifier
-
allowCaching
protected boolean allowCaching(I canonicalIdentifier, R loadedResource)
Returnstrue
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 objectloadedResource
- the resource object, as returned fromloadResource(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
- iffalse
, 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 classjava.lang.Object
- Returns:
- a description of the cache
-
-