src.gov.nasa.worldwind.cache.MemoryCache Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of worldwindx Show documentation
Show all versions of worldwindx Show documentation
World Wind is a collection of components that interactively display 3D geographic information within Java applications or applets.
/*
* Copyright (C) 2012 United States Government as represented by the Administrator of the
* National Aeronautics and Space Administration.
* All Rights Reserved.
*/
package gov.nasa.worldwind.cache;
/**
* @author Eric Dalgliesh
* @version $Id: MemoryCache.java 1171 2013-02-11 21:45:02Z dcollins $
*/
public interface MemoryCache
{
void setName(String name);
String getName();
/**
* Provides the interface for cache clients to be notified of key events. Currently the only key event is the
* removal of an entry from the cache. A client may need to know a removal instigated by the cache occurred in order
* to adjust its own state or to free resources associated with the removed entry.
*/
public interface CacheListener
{
/**
* Called just after an entry has been removed from the cache. Listeners should deallocate any resources that
* won't be deallocated by normal garbage collection.
*
* @param key the entry's cache key.
* @param clientObject the cached object.
*/
public void entryRemoved(Object key, Object clientObject);
/**
* Called when an exception occurs within the {@link #entryRemoved(Object, Object)} call.
*
* @param exception the exception that occurred.
* @param key the entry's cache key.
* @param clientObject the cached object.
*/
public void removalException(Throwable exception, Object key, Object clientObject);
}
/**
* Adds a new cacheListener, which will be sent notification whenever an entry is removed from the
* cache.
*
* @param listener the new MemoryCache.CacheListener
*/
void addCacheListener(CacheListener listener);
/**
* Removes a CacheListener, notifications of events will no longer be sent to this listener.
*
* @param listener the cache listener to remove.
*/
void removeCacheListener(CacheListener listener);
/**
* Discovers whether or not this cache contains the object referenced by key. Currently no interface exists
* to discover if an object resides in the cache by referencing itself.
*
* @param key the key which the object is referenced by.
*
* @return true if the key is found in the cache, false otherwise.
*/
boolean contains(Object key);
/**
* Attempts to add the object clientObject, with size objectSize and referred to by
* key to the cache. objectSize is the size in cache units, but is not checked for
* accuracy. Returns whether or not the add was successful.
*
* Note that the size passed in may be used, rather than the real size of the object. In some implementations, the
* accuracy of the space used calls will depend on the collection of these sizes, rather than actual size.
*
* This method should be declared synchronized when it is implemented.
*
* @param key an object used to reference the cached item.
* @param clientObject the item to be cached.
* @param objectSize the size of the item in cache units.
*
* @return true if object was added, false otherwise.
*/
boolean add(Object key, Object clientObject, long objectSize);
/**
* 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.
*
* @param key an object used to reference the cached item.
* @param clientObject the item to be cached.
*
* @return true if object was added, false otherwise.
*
* @see Cacheable
*/
boolean add(Object key, Cacheable clientObject);
/**
* Remove an object from the MemoryCache referenced by key. If the object is already absent, this
* method simply returns without indicating the absence.
*
* @param key an Object used to represent the item to remove.
*/
void remove(Object key);
/**
* Retrieves the requested item from the cache. If key is null or the item is not found, this method
* returns null.
*
* @param key an Object used to represent the item to retrieve.
*
* @return the requested Object if found, null otherwise.
*/
Object getObject(Object key);
/**
* Empties the cache. After calling clear() on a MemoryCache, calls relating to used
* capacity and number of items should return zero and the free capacity should be the maximum capacity.
*
* This method should be declared synchronized when it is implemented and should notify all
* CacheListeners of entries removed.
*/
void clear();
/* *************************************************************************/
// capacity related accessors
/**
* Retrieve the number of items stored in the MemoryCache.
*
* @return the number of items in the cache.
*/
int getNumObjects();
/**
* Retrieves the maximum size of the cache.
*
* @return the maximum size of the MemoryCache.
*/
long getCapacity();
/**
* Retrieves the amount of used MemoryCache space. The value returned is in cache units.
*
* @return the long value of the number of cache units used by cached items.
*/
long getUsedCapacity();
/**
* Retrieves the available space for storing new items.
*
* @return the long value of the remaining space for storing cached items.
*/
long getFreeCapacity();
/**
* Retrieves the low water value of the MemoryCache. When a MemoryCache runs out of free
* space, it must remove some items if it wishes to add any more. It continues removing items until the low water
* level is reached. Not every MemoryCache necessarily uses the low water system, so this may not
* return a useful value.
*
* @return the low water value of the MemoryCache.
*/
long getLowWater();
/* *******************************************************************************/
//capacity related mutators
/**
* Sets the new low water capacity value for this MemoryCache. When a MemoryCache runs out
* of free space, it must remove some items if it wishes to add any more. It continues removing items until the low
* water level is reached. Not every MemoryCache necessarily uses the low water system, so this method
* may not have any actual effect in some implementations.
*
* @param loWater the new low water value.
*/
void setLowWater(long loWater);
/**
* Sets the maximum capacity for this cache. This capacity has no impact on the number of items stored
* in the MemoryCache, except that every item must have a positive size. Generally the used capacity is
* the total of the sizes of all stored items.
*
* @param capacity the new capacity.
*/
void setCapacity(long capacity);
}