memorycache.java

来自「world wind java sdk 源码」· Java 代码 · 共 179 行

/*
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);
}