amy/venice-main-classic
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

did javadocs for the new CacheMap classes

Browse Source
This commit is contained in:
Eric J. Bowersox 2001-11-14 08:56:52 +00:00
parent 7e0f7b441f
commit e290ce2a8c
3 changed files with 309 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

189
src/com/silverwrist/util/cache/CacheMap.java vendored
View File

@ -20,6 +20,17 @@ package com.silverwrist.util.cache;
import java.lang.ref.*;
import java.util.*;
/**
* A special kind of <CODE>Map</CODE> that acts as a cache of data items. The <CODE>CacheMap</CODE>
* uses <CODE>SoftReferences</CODE>, so its data values will be shed if the virtual machine needs
* more memory; also, if too many entries are added to the map, certain entries will be removed in
* accordance with the supplied or default <CODE>CacheMapStrategy</CODE> object.
*
* @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
* @version X
* @see CacheMapStrategy
* @see java.util.Map
*/
public class CacheMap implements Map
{
/*--------------------------------------------------------------------------------
@ -27,7 +38,7 @@ public class CacheMap implements Map
*--------------------------------------------------------------------------------
*/
static class CacheOrdering implements Comparator
static final class CacheOrdering implements Comparator
{
private CacheMapStrategy strategy; // CacheMap's strategy object
private long tick; // when the sort operation started
@ -60,7 +71,7 @@ public class CacheMap implements Map
*--------------------------------------------------------------------------------
*/
static class DefaultStrategy implements CacheMapStrategy
static final class DefaultStrategy implements CacheMapStrategy
{
private static final long SCALING_FACTOR = 5000;
@ -100,6 +111,17 @@ public class CacheMap implements Map
*--------------------------------------------------------------------------------
*/
/**
* Constructs a new <CODE>CacheMap</CODE>.
*
* @param capacity The maximum number of entries this map can contain.
* @param shrink_percentage The percentage of entries which will be removed from the cache
* whenever it needs to shrink itself.
* @param strategy The strategy object which is used to determine which elements to remove.
* @exception java.lang.IllegalArgumentException If the specified capacity is negative or zero, or
* the shrink percentage is not in the range [1..100].
* @exception java.lang.NullPointerException If the strategy object reference is <CODE>null</CODE>.
*/
public CacheMap(int capacity, int shrink_percentage, CacheMapStrategy strategy)
{
if (capacity<=0)
@ -118,12 +140,27 @@ public class CacheMap implements Map
} // end constructor
/**
* Constructs a new <CODE>CacheMap</CODE> with a default strategy.
*
* @param capacity The maximum number of entries this map can contain.
* @param shrink_percentage The percentage of entries which will be removed from the cache
* whenever it needs to shrink itself.
* @exception java.lang.IllegalArgumentException If the specified capacity is negative or zero, or
* the shrink percentage is not in the range [1..100].
*/
public CacheMap(int capacity, int shrink_percentage)
{
this(capacity,shrink_percentage,default_strategy_singleton);
} // end constructor
/**
* Constructs a new <CODE>CacheMap</CODE> with a default strategy and shrink percentage.
*
* @param capacity The maximum number of entries this map can contain.
* @exception java.lang.IllegalArgumentException If the specified capacity is negative or zero.
*/
public CacheMap(int capacity)
{
this(capacity,10,default_strategy_singleton);
@ -137,9 +174,9 @@ public class CacheMap implements Map
private void doSweep()
{
Reference r = rq.poll();
ArrayList ditch = new ArrayList();
Iterator it;
Reference r = rq.poll(); // the reference that's been cleared
ArrayList ditch = new ArrayList(); // a list of entries to ditch
Iterator it; // current iterator
while (r!=null)
{ // look for the dead reference in the element list
@ -195,6 +232,12 @@ public class CacheMap implements Map
*--------------------------------------------------------------------------------
*/
/**
* Returns the number of key-value mappings in this map. If the map contains more than
* <CODE>Integer.MAX_VALUE</CODE> elements, returns <CODE>Integer.MAX_VALUE</CODE>.
*
* @return The number of key-value mappings in this map.
*/
public int size()
{
doSweep();
@ -202,6 +245,11 @@ public class CacheMap implements Map
} // end size
/**
* Returns <CODE>true</CODE> if this map contains no key-value mappings.
*
* @return <CODE>true</CODE> if this map contains no key-value mappings.
*/
public boolean isEmpty()
{
doSweep();
@ -209,6 +257,14 @@ public class CacheMap implements Map
} // end isEmpty
/**
* Returns <CODE>true</CODE> if this map contains a mapping for the specified key.
*
* @param key Key whose presence in this map is to be tested.
* @return <CODE>true</CODE> if this map contains a mapping for the specified key.
* @exception java.lang.ClassCastException If the key is of an inappropriate type for this map.
* @exception java.lang.NullPointerException If the key is <CODE>null</CODE>.
*/
public boolean containsKey(Object key)
{
doSweep();
@ -216,6 +272,12 @@ public class CacheMap implements Map
} // end containsKey
/**
* Returns <CODE>true</CODE> if this map maps one or more keys to the specified value.
*
* @param value Value whose presence in this map is to be tested.
* @return <CODE>true</CODE> if this map maps one or more keys to the specified value.
*/
public boolean containsValue(Object value)
{
doSweep();
@ -243,6 +305,17 @@ public class CacheMap implements Map
} // end containsValue
/**
* Returns the value to which this map maps the specified key. Returns <CODE>null</CODE> if the map
* contains no mapping for this key.
*
* @param key Key whose associated value is to be returned.
* @return The value to which this map maps the specified key, or <CODE>null</CODE> if the map contains
* no mapping for this key.
* @exception java.lang.ClassCastException If the key is of an inappropriate type for this map.
* @exception java.lang.NullPointerException If the key is <CODE>null</CODE>.
* @see #containsKey(java.lang.Object)
*/
public Object get(Object key)
{
doSweep();
@ -254,6 +327,20 @@ public class CacheMap implements Map
} // end get
/**
* Associates the specified value with the specified key in this map. If the map previously contained
* a mapping for this key, the old value is replaced.
*
* @param key Key with which the specified value is to be associated.
* @param value Value to be associated with the specified key.
* @return The previous value associated with the specified key, or <CODE>null</CODE> if there was no
* mapping for the key.
* @exception java.lang.ClassCastException If the class of the specified key or value prevents it from
* being stored in this map.
* @exception java.lang.IllegalArgumentException If some aspect of this key or value prevents it from
* being stored in this map.
* @exception java.lang.NullPointerException If the specified key or value is <CODE>null</CODE>.
*/
public Object put(Object key, Object value)
{
doSweep();
@ -284,6 +371,13 @@ public class CacheMap implements Map
} // end put
/**
* Removes the mapping for this key from this map if present.
*
* @param key Key whose mapping is to be removed from the map.
* @return The previous value associated with the specified key, or <CODE>null</CODE> if there was no
* mapping for the key.
*/
public Object remove(Object key)
{
doSweep();
@ -308,6 +402,17 @@ public class CacheMap implements Map
} // end remove
/**
* Copies all of the mappings from the specified map to this map. These mappings will replace any mappings
* that this map had for any of the keys currently in the specified map.
*
* @param map Mappings to be stored in this map.
* @exception java.lang.ClassCastException If the class of a key or value in the specified map prevents
* it from being stored in this map.
* @exception java.lang.IllegalArgumentException If some aspect of a key or value in the specified map
* prevents it from being stored in this map.
* @exception java.lang.NullPointerException If the specified key or value is <CODE>null</CODE>.
*/
public void putAll(Map map)
{
doSweep();
@ -329,6 +434,9 @@ public class CacheMap implements Map
} // end putAll
/**
* Removes all mappings from this map.
*/
public synchronized void clear()
{
base_map.clear();
@ -344,24 +452,48 @@ public class CacheMap implements Map
} // end clear
/**
* Returns a set view of the keys contained in this map.
*
* @return A set view of the keys contained in this map.
*/
public Set keySet()
{
return base_map.keySet();
} // end keySet
/**
* Returns a collection view of the values contained in this map.
*
* @return A collection view of the values contained in this map.
* @exception java.lang.UnsupportedOperationException This map does not support this operation.
*/
public Collection values()
{
throw new UnsupportedOperationException("CacheMap.values() is not implemented");
} // end values
/**
* Returns a set view of the mappings contained in this map.
*
* @return A set view of the mappings contained in this map.
* @exception java.lang.UnsupportedOperationException This map does not support this operation.
*/
public Set entrySet()
{
throw new UnsupportedOperationException("CacheMap.entrySet() is not implemented");
} // end entrySet
/**
* Compares the specified object with this map for equality. Returns <CODE>true</CODE> if the given object
* is also a map and the two Maps represent the same mappings.
*
* @param o Object to be compared for equality with this map.
* @return <CODE>true</CODE> if the specified object is equal to this map.
*/
public boolean equals(Object o)
{
if ((o==null) || !(o instanceof Map))
@ -395,6 +527,14 @@ public class CacheMap implements Map
} // end equals
/**
* Returns the hash code value for this map. The hash code of a map is defined to be the sum of the
* hash codes of each entry in the map's entrySet view.
*
* @return The hash code value for this map.
* @see #equals(java.lang.Object)
* @see CacheMapEntry#hashCode()
*/
public int hashCode()
{
doSweep();
@ -416,12 +556,23 @@ public class CacheMap implements Map
*--------------------------------------------------------------------------------
*/
/**
* Returns the capacity of this cache map.
*
* @return The capacity of this cache map.
*/
public int getCapacity()
{
return capacity;
} // end getCapacity
/**
* Sets the capacity of this cache map.
*
* @param c The new capacity for this cache map.
* @exception java.lang.IllegalArgumentException If the specified capacity is negative or zero.
*/
public void setCapacity(int c)
{
if (c<=0)
@ -430,12 +581,24 @@ public class CacheMap implements Map
} // end setCapacity
/**
* Returns the shrink percentage of this cache map.
*
* @return The shrink percentage of this cache map.
*/
public int getShrinkPercentage()
{
return shrink_percentage;
} // end getShrinkPercentage
/**
* Sets the shrink percentage of this cache map.
*
* @param p The new shrink percentage for this cache map.
* @exception java.lang.IllegalArgumentException If the specified shrink percentage is not in the
* range [1..100].
*/
public void setShrinkPercentage(int p)
{
if ((p<=0) || (p>100))
@ -444,12 +607,23 @@ public class CacheMap implements Map
} // end setShrinkPercentage
/**
* Returns the strategy object associated with the cache map.
*
* @return The strategy object associated with the cache map.
*/
public CacheMapStrategy getStrategy()
{
return strategy;
} // end getStrategy
/**
* Sets the strategy object associated with this cache map.
*
* @param s The new strategy object to be associated with the cache map.
* @exception java.lang.NullPointerException If the strategy object reference is <CODE>null</CODE>.
*/
public void setStrategy(CacheMapStrategy s)
{
if (s==null)
@ -463,6 +637,11 @@ public class CacheMap implements Map
*--------------------------------------------------------------------------------
*/
/**
* Causes the current size of the cache map to shrink by at least the shrink percentage specified
* in the constructor or in <CODE>setShrinkPercentage</CODE>. Cached items already reclaimed by the
* garbage collector are stripped out first.
*/
public synchronized void shrink()
{
// Figure out how many elements to remove.

113
src/com/silverwrist/util/cache/CacheMapEntry.java vendored
View File

@ -20,7 +20,19 @@ package com.silverwrist.util.cache;
import java.lang.ref.*;
import java.util.*;
final class CacheMapEntry implements Map.Entry
/**
* An entry from the <CODE>CacheMap</CODE> class. This object holds the key, a <CODE>SoftReference</CODE>
* to the value, the timestamp of its last access, and the number of times this element has been accessed.
* The latter two values are frequently used by an object implementing the <CODE>CacheMapStrategy</CODE>
* interface to compute a "figure of merit" for the entry that decides whether or not it gets discarded.
*
* @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
* @version X
* @see CacheMap
* @see CacheMapStrategy
* @see java.lang.ref.SoftReference
*/
public final class CacheMapEntry implements Map.Entry
{
/*--------------------------------------------------------------------------------
* Attributes
@ -37,6 +49,12 @@ final class CacheMapEntry implements Map.Entry
*--------------------------------------------------------------------------------
*/
/**
* Creates a new <CODE>CacheMapEntry</CODE>.
*
* @param key The key for this entry.
* @param value The value to be held in this entry.
*/
CacheMapEntry(Object key, Object value)
{
this.key = key;
@ -45,6 +63,13 @@ final class CacheMapEntry implements Map.Entry
} // end constructor
/**
* Creates a new <CODE>CacheMapEntry</CODE>.
*
* @param key The key for this entry.
* @param value The value to be held in this entry.
* @param q The <CODE>ReferenceQueue</CODE> to add the new reference generated by this constructor to.
*/
CacheMapEntry(Object key, Object value, ReferenceQueue q)
{
this.key = key;
@ -58,6 +83,10 @@ final class CacheMapEntry implements Map.Entry
*--------------------------------------------------------------------------------
*/
/**
* Called by the garbage collector on an object when garbage collection determines that there are no
* more references to the object.
*/
protected void finalize()
{
key = null;
@ -71,26 +100,53 @@ final class CacheMapEntry implements Map.Entry
*--------------------------------------------------------------------------------
*/
/**
* Returns the key corresponding to this entry.
*
* @return The key corresponding to this entry.
*/
public final Object getKey()
{
return key;
} // end getKey
/**
* Returns the value corresponding to this entry. If the value has already been reclaimed by the
* garbage collector, the return value is <CODE>null</CODE>.
*
* @return The value corresponding to this entry.
*/
public final Object getValue()
{
return value.get();
} // end getValue
/**
* Replaces the value corresponding to this entry with the specified value.
*
* @param o The new value to be stored in this entry.
* @return The former value stored in this entry. If the value has already been reclaimed by the
* garbage collector, the return value is <CODE>null</CODE>.
*/
public final Object setValue(Object o)
{
Object rc = value.get();
value.clear();
value = new SoftReference(o);
return rc;
} // end setValue
/**
* Compares the specified object with this object for equality. The <CODE>CacheMap</CODE> considers
* two entries to be equivalent if they have the same key. (The value is not considered because it
* might already have been garbage-collected.)
*
* @param o The other object to compare to.
* @return <CODE>true</CODE> if the specified object is equal to this entry.
*/
public final boolean equals(Object o)
{
// make sure the other element is a Map.Entry
@ -106,6 +162,11 @@ final class CacheMapEntry implements Map.Entry
} // end equals
/**
* Returns the hash code value for this map entry, defined to be the hash code value of the key.
*
* @return The hash code value for this map entry.
*/
public final int hashCode()
{
return ((key==null) ? 0 : key.hashCode());
@ -117,6 +178,14 @@ final class CacheMapEntry implements Map.Entry
*--------------------------------------------------------------------------------
*/
/**
* Replaces the value corresponding to this entry with the specified value.
*
* @param o The new value to be stored in this entry.
* @param q The <CODE>ReferenceQueue</CODE> to add the freshly-generated reference to.
* @return The former value stored in this entry. If the value has already been reclaimed by the
* garbage collector, the return value is <CODE>null</CODE>.
*/
final Object setValue(Object o, ReferenceQueue q)
{
Object rc = value.get();
@ -126,12 +195,24 @@ final class CacheMapEntry implements Map.Entry
} // end setValue
final boolean isCleared()
/**
* Returns <CODE>true</CODE> if the value in this map entry has been cleared by the garbage collector.
*
* @return <CODE>true</CODE> if the value has been cleared, <CODE>false</CODE> if not.
*/
public final boolean isCleared()
{
return (value.get()==null);
} // end isCleared
/**
* Returns <CODE> true if the specified reference is the one contained in this map entry.
*
* @param r The reference we're trying to match.
* @return <CODE>true/CODE> if this reference is the same as the one contained in the map entry,
* <CODE>false</CODE> if not.
*/
final boolean matchReference(Reference r)
{
if (r instanceof SoftReference)
@ -141,6 +222,9 @@ final class CacheMapEntry implements Map.Entry
} // end matchReference
/**
* Clears out all references held by this map entry.
*/
final void discard()
{
key = null;
@ -149,24 +233,43 @@ final class CacheMapEntry implements Map.Entry
} // end discard
final int getHits()
/**
* Returns the number of times this map entry has been referenced.
*
* @return The number of times this map entry has been referenced.
*/
public final int getHits()
{
return hits;
} // end getHits
final long getTimestamp()
/**
* Returns the timestamp of the most recent reference to this map entry.
*
* @return The timestamp of the most recent reference to this map entry.
*/
public final long getTimestamp()
{
return timestamp;
} // end getTimestamp
final long getAge(long tick)
/**
* Returns the number of milliseconds since this map entry was last referenced.
*
* @param tick The current time tick of the system in milliseconds.
* @return The number of milliseconds since this map entry was last referenced.
*/
public final long getAge(long tick)
{
return (tick - timestamp);
} // end getAge
/**
* References this entry, which increments its "hit" counter and updates its current time stamp.
*/
final void touch()
{
hits++;

17
src/com/silverwrist/util/cache/CacheMapStrategy.java vendored
View File

@ -17,8 +17,25 @@
*/
package com.silverwrist.util.cache;
/**
* An interface which allows external code to define a "strategy" for use with the <CODE>CacheMap</CODE>
* object, in deciding which entries in the map are to be released.
*
* @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
* @version X
* @see CacheMap
*/
public interface CacheMapStrategy
{
/**
* Computes a "figure of merit" for a given <CODE>CacheMapEntry</CODE>. This value is used by the
* <CODE>CacheMap</CODE> to determine which entries to remove; entries with lower "figure of merit"
* values get removed first.
*
* @param entry The cache map entry to compute a figure of merit for.
* @param tick The current time stamp, which may be used in a call to <CODE>CacheMapEntry.getAge</CODE>.
* @return The "figure of merit" value.
*/
public abstract long getEntryValue(CacheMapEntry entry, long tick);
} // end interface CacheMapStrategy