gov.nasa.worldwind.cache.MemoryCache Maven / Gradle / Ivy
The newest version!
/*
* 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);
}
© 2015 - 2024 Weber Informatics LLC | Privacy Policy