/* Copyright (C) 2001, 2006 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 2471 2007-07-31 21:50:57Z tgaskins $ */ public interface MemoryCache /*extends gov.nasa.worldwind.MemoryCache*/ { /** * retrieve an unordered <code>Set</code> of the keys of the objects in this <code>MemoryCache</code>. * * @return a <code>Set</code> containing all the keys in the cache. */ java.util.Set<Object> getKeySet(); 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 { public void entryRemoved(Object key, Object clientObject); } /** * Adds a new <code>cacheListener</code>, which will be sent notification whenever an entry is removed from the * cache. * * @param listener the new <code>MemoryCache.CacheListener</code> */ void addCacheListener(CacheListener listener); /** * Removes a <code>CacheListener</code>, notifications of events will no longer be sent to this listener. * * @param listener */ void removeCacheListener(CacheListener listener); /** * Discovers whether or not this cache contains the object referenced by <code> 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 <code>clientObject</code>, with size <code>objectSize</code> and referred to by * <code>key</code> to the cache. <code>objectSize</code> is the size in bytes, but is not checked for accuracy. * Returns whether or not the add was successful. * <p/> * 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. * <p/> * This method should be declared <code>synchronized</code> 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 bytes. * @return true if object was added, false otherwise */ boolean add(Object key, Object clientObject, long objectSize); /** * Attempts to add the <code>Cacheable</code> object referenced by the key. No explicit size value is required as * this method queries the Cacheable to discover the size. * <p/> * This method should be declared <code>synchronized</code> when it is implemented. * * @param key * @param clientObject * @return true if object was added, false otherwise * @see Cacheable */ boolean add(Object key, Cacheable clientObject); /** * Remove an object from the MemoryCache referenced by <code>key</code>. If the object is already absent, this * method simply returns without indicating the absence. * * @param key an <code>Object</code> used to represent the item to remove. */ void remove(Object key); /** * Retrieves the requested item from the cache. If <code>key</code> is null or the item is not found, this method * returns null. * * @param key an <code>Object</code> used to represent the item to retrieve * @return the requested <code>Object</code> if found, null otherwise */ Object getObject(Object key); /** * Empties the cache. After calling <code>clear()</code> on a <code>MemoryCache</code>, calls relating to used * capacity and number of items should return zero and the free capacity should be the maximum capacity. * <p/> * This method should be declared <code>synchronized</code> when it is implemented and should notify all * <code>CacheListener</code>s of entries removed. */ void clear(); /* *************************************************************************/ // capacity related accessors /** * Retrieve the number of items stored in the <code>MemoryCache</code>. * * @return the number of items in the cache */ int getNumObjects(); /** * Retrieves the maximum size of the cache in bytes. * * @return the maximum size of the <code>MemoryCache</code> in bytes. */ long getCapacity(); /** * Retrieves the amount of used <code>MemoryCache</code> space. The value returned is in bytes. * * @return the long value of the number of bytes 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 <code>MemoryCache</code>. When a <code>MemoryCache</code> 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 <code>MemoryCache</code> necessarily uses the low water system, so this may not * return a useful value. * * @return the low water value of the <code>MemoryCache</code>. */ long getLowWater(); /* *******************************************************************************/ //capacity related mutators /** * Sets the new low water capacity value for this <code>MemoryCache</code>. When a <code>MemoryCache</code> 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 <code>MemoryCache</code> 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 in bytes */ void setLowWater(long loWater); /** * Sets the maximum capacity for this <code>cache</code> in bytes. This capacity has no impact on the number of * items stored in the <code>MemoryCache</code>, 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 in bytes */ void setCapacity(long capacity); }