gov.nasa.worldwind.cache

Class BasicMemoryCache

java.lang.Object

gov.nasa.worldwind.cache.BasicMemoryCache

All Implemented Interfaces:

MemoryCache

Direct Known Subclasses:

BasicRasterServerCache

public class BasicMemoryCache
extends java.lang.Object
implements MemoryCache

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	BasicMemoryCache.CacheEntry

Nested classes/interfaces inherited from interface gov.nasa.worldwind.cache.MemoryCache

MemoryCache.CacheListener

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.concurrent.atomic.AtomicLong	capacity
protected java.util.concurrent.atomic.AtomicLong	currentUsedCapacity
protected java.util.concurrent.ConcurrentHashMap<java.lang.Object,BasicMemoryCache.CacheEntry>	entries
protected java.util.concurrent.CopyOnWriteArrayList<MemoryCache.CacheListener>	listeners
protected java.lang.Object	lock
protected java.lang.Long	lowWater
protected java.lang.String	name

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
boolean	add(java.lang.Object key, Cacheable clientObject) Attempts to add the Cacheable object referenced by the key.
boolean	add(java.lang.Object key, java.lang.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(java.lang.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.
long	getFreeCapacity() Retrieves the available space for storing new items.
long	getLowWater() Returns the low water level in cache units.
java.lang.String	getName()
int	getNumObjects() Retrieve the number of items stored in the MemoryCache.
java.lang.Object	getObject(java.lang.Object key) Obtain the object referenced by key without removing it.
long	getUsedCapacity() Retrieves the amount of used MemoryCache space.
void	remove(java.lang.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.
protected void	removeEntry(BasicMemoryCache.CacheEntry entry) Removes entry from the cache.
void	setCapacity(long newCapacity) Sets the new capacity for the cache.
void	setLowWater(long loWater) Sets the new low water level in cache units, which controls how aggresively the cache discards items.
void	setName(java.lang.String name)
java.lang.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

Field Detail

capacity

protected java.util.concurrent.atomic.AtomicLong capacity

currentUsedCapacity

protected java.util.concurrent.atomic.AtomicLong currentUsedCapacity

entries

protected java.util.concurrent.ConcurrentHashMap<java.lang.Object,BasicMemoryCache.CacheEntry> entries

listeners

protected java.util.concurrent.CopyOnWriteArrayList<MemoryCache.CacheListener> listeners

lock

protected final java.lang.Object lock

lowWater

protected java.lang.Long lowWater

name

protected java.lang.String name

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(java.lang.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

Parameters:

key - an object used to reference the cached item.

clientObject - the item to be cached.

Returns:

true if object was added, false otherwise.

See Also:

Cacheable

add

public boolean add(java.lang.Object key,
                   java.lang.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 cache units.

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:

java.lang.IllegalArgumentException - is listener is null.

clear

public void clear()

Empties the cache.

Specified by:

clear in interface MemoryCache

contains

public boolean contains(java.lang.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:

java.lang.IllegalArgumentException - if key is null.

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

getCapacity

public long getCapacity()

Description copied from interface: MemoryCache

Retrieves the maximum size of the cache.

Specified by:

getCapacity in interface MemoryCache

Returns:

the capacity of the cache.

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 cache units).

getLowWater

public long getLowWater()

Returns the low water level in cache units. 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.

getName

public java.lang.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 java.lang.Object getObject(java.lang.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:

java.lang.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 cache units.

Specified by:

getUsedCapacity in interface MemoryCache

Returns:

the number of cache units that the cache currently holds.

remove

public void remove(java.lang.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:

java.lang.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:

java.lang.IllegalArgumentException - if listener is null.

removeEntry

protected void removeEntry(BasicMemoryCache.CacheEntry entry)

Removes entry from the cache. To remove an entry using its key, use remove().

Parameters:

entry - The entry (as opposed to key) of the item to be removed.

setCapacity

public void setCapacity(long newCapacity)

Sets the new capacity 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 cache units, 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.

setName

public void setName(java.lang.String name)

Specified by:

setName in interface MemoryCache

toString

public java.lang.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 java.lang.Object

Returns:

a String representation of this object.