NASA World Wind

gov.nasa.worldwind.cache
Class BasicMemoryCache

java.lang.Object
  extended by gov.nasa.worldwind.cache.BasicMemoryCache
All Implemented Interfaces:
MemoryCache

public final class BasicMemoryCache
extends Object
implements MemoryCache


Nested Class Summary
 
Nested classes/interfaces inherited from interface gov.nasa.worldwind.cache.MemoryCache
MemoryCache.CacheListener
 
Constructor Summary
BasicMemoryCache(long loWater, long capacity)
          Constructs a new cache using capacity for maximum size, and loWater for the low water.
 
Method Summary
 boolean add(Object key, Cacheable clientObject)
          Attempts to add the Cacheable object referenced by the key.
 boolean add(Object key, Object clientObject, long clientObjectSize)
          Adds an object to the cache.
 void addCacheListener(MemoryCache.CacheListener listener)
          Adds a cache listener, MemoryCache listeners are used to notify classes when an item is removed from the cache.
 void clear()
          Empties the cache.
 boolean contains(Object key)
          Returns true if the cache contains the item referenced by key.
protected  void finalize()
           
 long getCapacity()
          Retrieves the maximum size of the cache in bytes.
 long getFreeCapacity()
          Retrieves the available space for storing new items.
 Set<Object> getKeySet()
          Obtain a list of all the keys in the cache.
 long getLowWater()
          Returns the low water level in bytes.
 String getName()
           
 int getNumObjects()
          Retrieve the number of items stored in the MemoryCache.
 Object getObject(Object key)
          Obtain the object referenced by key without removing it.
 long getUsedCapacity()
          Retrieves the amount of used MemoryCache space.
 void remove(Object key)
          Remove the object reference by key from the cache.
 void removeCacheListener(MemoryCache.CacheListener listener)
          Removes a cache listener, objects using this listener will no longer receive notification of cache events.
 void setCapacity(long newCapacity)
          Sets the new capacity (in bytes) for the cache.
 void setLowWater(long loWater)
          Sets the new low water level in bytes, which controls how aggresively the cache discards items.
 void setName(String name)
           
 String toString()
          a String representation of this object is returned.  This representation consists of maximum size, current used capacity and number of currently cached items.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

BasicMemoryCache

public BasicMemoryCache(long loWater,
                        long capacity)
Constructs a new cache using capacity for maximum size, and loWater for the low water.

Parameters:
loWater - the low water level
capacity - the maximum capacity
Method Detail

add

public boolean add(Object key,
                   Cacheable clientObject)
Description copied from interface: MemoryCache
Attempts to add the Cacheable object referenced by the key. No explicit size value is required as this method queries the Cacheable to discover the size.

This method should be declared synchronized when it is implemented.

Specified by:
add in interface MemoryCache
Returns:
true if object was added, false otherwise
See Also:
Cacheable

add

public boolean add(Object key,
                   Object clientObject,
                   long clientObjectSize)
Adds an object to the cache. The add fails if the object or key is null, or if the size is zero, negative or greater than the maximmum capacity

Specified by:
add in interface MemoryCache
Parameters:
key - The unique reference key that identifies this object.
clientObject - The actual object to be cached.
clientObjectSize - The size of the object in bytes.
Returns:
returns true if clientObject was added, false otherwise.

addCacheListener

public void addCacheListener(MemoryCache.CacheListener listener)
Adds a cache listener, MemoryCache listeners are used to notify classes when an item is removed from the cache.

Specified by:
addCacheListener in interface MemoryCache
Parameters:
listener - The new CacheListener
Throws:
IllegalArgumentException - is listener is null

clear

public void clear()
Empties the cache.

Specified by:
clear in interface MemoryCache

contains

public boolean contains(Object key)
Returns true if the cache contains the item referenced by key. No guarantee is made as to whether or not the item will remain in the cache for any period of time.

This function does not cause the object referenced by the key to be marked as accessed. getObject() should be used for that purpose

Specified by:
contains in interface MemoryCache
Parameters:
key - The key of a specific object
Returns:
true if the cache holds the item referenced by key
Throws:
IllegalArgumentException - if key is null

finalize

protected void finalize()
                 throws Throwable
Overrides:
finalize in class Object
Throws:
Throwable

getCapacity

public long getCapacity()
Description copied from interface: MemoryCache
Retrieves the maximum size of the cache in bytes.

Specified by:
getCapacity in interface MemoryCache
Returns:
the capacity of the cache in bytes

getFreeCapacity

public long getFreeCapacity()
Description copied from interface: MemoryCache
Retrieves the available space for storing new items.

Specified by:
getFreeCapacity in interface MemoryCache
Returns:
the amount of free space left in the cache (in bytes)

getKeySet

public Set<Object> getKeySet()
Obtain a list of all the keys in the cache.

Specified by:
getKeySet in interface MemoryCache
Returns:
a Set of all keys in the cache.

getLowWater

public long getLowWater()
Returns the low water level in bytes. When the cache fills, it removes items until it reaches the low water level.

Specified by:
getLowWater in interface MemoryCache
Returns:
the low water level in bytes.

getName

public String getName()
Specified by:
getName in interface MemoryCache

getNumObjects

public int getNumObjects()
Description copied from interface: MemoryCache
Retrieve the number of items stored in the MemoryCache.

Specified by:
getNumObjects in interface MemoryCache
Returns:
the number of objects currently stored in this cache

getObject

public Object getObject(Object key)
Obtain the object referenced by key without removing it. Apart from adding an object, this is the only way to mark an object as recently used.

Specified by:
getObject in interface MemoryCache
Parameters:
key - The key for the object to be found.
Returns:
the object referenced by key if it is present, null otherwise.
Throws:
IllegalArgumentException - if key is null

getUsedCapacity

public long getUsedCapacity()
Description copied from interface: MemoryCache
Retrieves the amount of used MemoryCache space. The value returned is in bytes.

Specified by:
getUsedCapacity in interface MemoryCache
Returns:
the number of bytes that the cache currently holds

remove

public void remove(Object key)
Remove the object reference by key from the cache. If no object with the corresponding key is found, this method returns immediately.

Specified by:
remove in interface MemoryCache
Parameters:
key - the key of the object to be removed
Throws:
IllegalArgumentException - if key is null

removeCacheListener

public void removeCacheListener(MemoryCache.CacheListener listener)
Removes a cache listener, objects using this listener will no longer receive notification of cache events.

Specified by:
removeCacheListener in interface MemoryCache
Parameters:
listener - The CacheListener to remove
Throws:
IllegalArgumentException - if listener is null

setCapacity

public void setCapacity(long newCapacity)
Sets the new capacity (in bytes) for the cache. When decreasing cache size, it is recommended to check that the lowWater variable is suitable. If the capacity infringes on items stored in the cache, these items are removed. Setting a new low water is up to the user, that is, it remains unchanged and may be higher than the maximum capacity. When the low water level is higher than or equal to the maximum capacity, it is ignored, which can lead to poor performance when adding entries.

Specified by:
setCapacity in interface MemoryCache
Parameters:
newCapacity - the new capacity of the cache.

setLowWater

public void setLowWater(long loWater)
Sets the new low water level in bytes, which controls how aggresively the cache discards items.

When the cache fills, it removes items until it reaches the low water level.

Setting a high loWater level will increase cache misses, but decrease average add time, but setting a low loWater will do the opposite.

Specified by:
setLowWater in interface MemoryCache
Parameters:
loWater - the new low water level in bytes.

setName

public void setName(String name)
Specified by:
setName in interface MemoryCache

toString

public String toString()
a String representation of this object is returned.  This representation consists of maximum size, current used capacity and number of currently cached items.

Overrides:
toString in class Object
Returns:
a String representation of this object

NASA World Wind