A Map that is size-limited using an LRU algorithm
/**
* $Revision: 1456 $
* $Date: 2005-06-01 22:04:54 -0700 (Wed, 01 Jun 2005) $
*
* Copyright 2003-2005 Jive Software.
*
* All rights reserved. Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import java.util.AbstractCollection;
import java.util.AbstractSet;
import java.util.Collection;
import java.util.Collections;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;
import java.util.Set;
/**
* A specialized Map that is size-limited (using an LRU algorithm) and
* has an optional expiration time for cache items. The Map is thread-safe.<p>
*
* The algorithm for cache is as follows: a HashMap is maintained for fast
* object lookup. Two linked lists are maintained: one keeps objects in the
* order they are accessed from cache, the other keeps objects in the order
* they were originally added to cache. When objects are added to cache, they
* are first wrapped by a CacheObject which maintains the following pieces
* of information:<ul>
* <li> A pointer to the node in the linked list that maintains accessed
* order for the object. Keeping a reference to the node lets us avoid
* linear scans of the linked list.
* <li> A pointer to the node in the linked list that maintains the age
* of the object in cache. Keeping a reference to the node lets us avoid
* linear scans of the linked list.</ul>
* <p/>
* To get an object from cache, a hash lookup is performed to get a reference
* to the CacheObject that wraps the real object we are looking for.
* The object is subsequently moved to the front of the accessed linked list
* and any necessary cache cleanups are performed. Cache deletion and expiration
* is performed as needed.
*
* @author Matt Tucker
*/
public class Cache<K, V> implements Map<K, V> {
/**
* The map the keys and values are stored in.
*/
protected Map<K, CacheObject<V>> map;
/**
* Linked list to maintain order that cache objects are accessed
* in, most used to least used.
*/
protected LinkedList lastAccessedList;
/**
* Linked list to maintain time that cache objects were initially added
* to the cache, most recently added to oldest added.
*/
protected LinkedList ageList;
/**
* Maximum number of items the cache will hold.
*/
protected int maxCacheSize;
/**
* Maximum length of time objects can exist in cache before expiring.
*/
protected long maxLifetime;
/**
* Maintain the number of cache hits and misses. A cache hit occurs every
* time the get method is called and the cache contains the requested
* object. A cache miss represents the opposite occurence.<p>
*
* Keeping track of cache hits and misses lets one measure how efficient
* the cache is; the higher the percentage of hits, the more efficient.
*/
protected long cacheHits, cacheMisses = 0L;
/**
* Create a new cache and specify the maximum size of for the cache in
* bytes, and the maximum lifetime of objects.
*
* @param maxSize the maximum number of objects the cache will hold. -1
* means the cache has no max size.
* @param maxLifetime the maximum amount of time (in ms) objects can exist in
* cache before being deleted. -1 means objects never expire.
*/
public Cache(int maxSize, long maxLifetime) {
if (maxSize == 0) {
throw new IllegalArgumentException("Max cache size cannot be 0.");
}
this.maxCacheSize = maxSize;
this.maxLifetime = maxLifetime;
// Our primary data structure is a hash map. The default capacity of 11
// is too small in almost all cases, so we set it bigger.
map = new HashMap<K, CacheObject<V>>(103);
lastAccessedList = new LinkedList();
ageList = new LinkedList();
}
public synchronized V put(K key, V value) {
V oldValue = null;
// Delete an old entry if it exists.
if (map.containsKey(key)) {
oldValue = remove(key, true);
}
CacheObject<V> cacheObject = new CacheObject<V>(value);
map.put(key, cacheObject);
// Make an entry into the cache order list.
// Store the cache order list entry so that we can get back to it
// during later lookups.
cacheObject.lastAccessedListNode = lastAccessedList.addFirst(key);
// Add the object to the age list
LinkedListNode ageNode = ageList.addFirst(key);
ageNode.timestamp = System.currentTimeMillis();
cacheObject.ageListNode = ageNode;
// If cache is too full, remove least used cache entries until it is not too full.
cullCache();
return oldValue;
}
public synchronized V get(Object key) {
// First, clear all entries that have been in cache longer than the
// maximum defined age.
deleteExpiredEntries();
CacheObject<V> cacheObject = map.get(key);
if (cacheObject == null) {
// The object didn't exist in cache, so increment cache misses.
cacheMisses++;
return null;
}
// Remove the object from it's current place in the cache order list,
// and re-insert it at the front of the list.
cacheObject.lastAccessedListNode.remove();
lastAccessedList.addFirst(cacheObject.lastAccessedListNode);
// The object exists in cache, so increment cache hits. Also, increment
// the object's read count.
cacheHits++;
cacheObject.readCount++;
return cacheObject.object;
}
public synchronized V remove(Object key) {
return remove(key, false);
}
/*
* Remove operation with a flag so we can tell coherence if the remove was
* caused by cache internal processing such as eviction or loading
*/
public synchronized V remove(Object key, boolean internal) {
//noinspection SuspiciousMethodCalls
CacheObject<V> cacheObject = map.remove(key);
// If the object is not in cache, stop trying to remove it.
if (cacheObject == null) {
return null;
}
// Remove from the cache order list
cacheObject.lastAccessedListNode.remove();
cacheObject.ageListNode.remove();
// Remove references to linked list nodes
cacheObject.ageListNode = null;
cacheObject.lastAccessedListNode = null;
return cacheObject.object;
}
public synchronized void clear() {
Object[] keys = map.keySet().toArray();
for (Object key : keys) {
remove(key);
}
// Now, reset all containers.
map.clear();
lastAccessedList.clear();
ageList.clear();
cacheHits = 0;
cacheMisses = 0;
}
public synchronized int size() {
// First, clear all entries that have been in cache longer than the
// maximum defined age.
deleteExpiredEntries();
return map.size();
}
public synchronized boolean isEmpty() {
// First, clear all entries that have been in cache longer than the
// maximum defined age.
deleteExpiredEntries();
return map.isEmpty();
}
public synchronized Collection<V> values() {
// First, clear all entries that have been in cache longer than the
// maximum defined age.
deleteExpiredEntries();
return Collections.unmodifiableCollection(new AbstractCollection<V>() {
Collection<CacheObject<V>> values = map.values();
public Iterator<V> iterator() {
return new Iterator<V>() {
Iterator<CacheObject<V>> it = values.iterator();
public boolean hasNext() {
return it.hasNext();
}
public V next() {
return it.next().object;
}
public void remove() {
it.remove();
}
};
}
public int size() {
return values.size();
}
});
}
public synchronized boolean containsKey(Object key) {
// First, clear all entries that have been in cache longer than the
// maximum defined age.
deleteExpiredEntries();
return map.containsKey(key);
}
public void putAll(Map<? extends K, ? extends V> map) {
for (Entry<? extends K, ? extends V> entry : map.entrySet()) {
V value = entry.getValue();
// If the map is another DefaultCache instance than the
// entry values will be CacheObject instances that need
// to be converted to the normal object form.
if (value instanceof CacheObject) {
//noinspection unchecked
value = ((CacheObject<V>) value).object;
}
put(entry.getKey(), value);
}
}
public synchronized boolean containsValue(Object value) {
// First, clear all entries that have been in cache longer than the
// maximum defined age.
deleteExpiredEntries();
//noinspection unchecked
CacheObject<V> cacheObject = new CacheObject<V>((V) value);
return map.containsValue(cacheObject);
}
public synchronized Set<Map.Entry<K, V>> entrySet() {
// Warning -- this method returns CacheObject instances and not Objects
// in the same form they were put into cache.
// First, clear all entries that have been in cache longer than the
// maximum defined age.
deleteExpiredEntries();
return new AbstractSet<Map.Entry<K, V>>() {
private final Set<Map.Entry<K, CacheObject<V>>> set = map.entrySet();
public Iterator<Entry<K, V>> iterator() {
return new Iterator<Entry<K, V>>() {
private final Iterator<Entry<K, CacheObject<V>>> it = set.iterator();
public boolean hasNext() {
return it.hasNext();
}
public Entry<K, V> next() {
Map.Entry<K, CacheObject<V>> entry = it.next();
return new AbstractMapEntry<K, V>(entry.getKey(), entry.getValue().object) {
@Override
public V setValue(V value) {
throw new UnsupportedOperationException("Cannot set");
}
};
}
public void remove() {
it.remove();
}
};
}
public int size() {
return set.size();
}
};
}
public synchronized Set<K> keySet() {
// First, clear all entries that have been in cache longer than the
// maximum defined age.
deleteExpiredEntries();
return Collections.unmodifiableSet(map.keySet());
}
public long getCacheHits() {
return cacheHits;
}
public long getCacheMisses() {
return cacheMisses;
}
public int getMaxCacheSize() {
return maxCacheSize;
}
public synchronized void setMaxCacheSize(int maxCacheSize) {
this.maxCacheSize = maxCacheSize;
// It's possible that the new max size is smaller than our current cache
// size. If so, we need to delete infrequently used items.
cullCache();
}
public long getMaxLifetime() {
return maxLifetime;
}
public void setMaxLifetime(long maxLifetime) {
this.maxLifetime = maxLifetime;
}
/**
* Clears all entries out of cache where the entries are older than the
* maximum defined age.
*/
protected synchronized void deleteExpiredEntries() {
// Check if expiration is turned on.
if (maxLifetime <= 0) {
return;
}
// Remove all old entries. To do this, we remove objects from the end
// of the linked list until they are no longer too old. We get to avoid
// any hash lookups or looking at any more objects than is strictly
// neccessary.
LinkedListNode node = ageList.getLast();
// If there are no entries in the age list, return.
if (node == null) {
return;
}
// Determine the expireTime, which is the moment in time that elements
// should expire from cache. Then, we can do an easy check to see
// if the expire time is greater than the expire time.
long expireTime = System.currentTimeMillis() - maxLifetime;
while (expireTime > node.timestamp) {
if (remove(node.object, true) == null) {
System.err.println("Error attempting to remove(" + node.object.toString() +
") - cacheObject not found in cache!");
// remove from the ageList
node.remove();
}
// Get the next node.
node = ageList.getLast();
// If there are no more entries in the age list, return.
if (node == null) {
return;
}
}
}
/**
* Removes the least recently used elements if the cache size is greater than
* or equal to the maximum allowed size until the cache is at least 10% empty.
*/
protected synchronized void cullCache() {
// Check if a max cache size is defined.
if (maxCacheSize < 0) {
return;
}
// See if the cache is too big. If so, clean out cache until it's 10% free.
if (map.size() > maxCacheSize) {
// First, delete any old entries to see how much memory that frees.
deleteExpiredEntries();
// Next, delete the least recently used elements until 10% of the cache
// has been freed.
int desiredSize = (int) (maxCacheSize * .90);
for (int i=map.size(); i>desiredSize; i--) {
// Get the key and invoke the remove method on it.
if (remove(lastAccessedList.getLast().object, true) == null) {
System.err.println("Error attempting to cullCache with remove(" +
lastAccessedList.getLast().object.toString() + ") - " +
"cacheObject not found in cache!");
lastAccessedList.getLast().remove();
}
}
}
}
/**
* Wrapper for all objects put into cache. It's primary purpose is to maintain
* references to the linked lists that maintain the creation time of the object
* and the ordering of the most used objects.
*
* This class is optimized for speed rather than strictly correct encapsulation.
*/
private static class CacheObject<V> {
/**
* Underlying object wrapped by the CacheObject.
*/
public V object;
/**
* A reference to the node in the cache order list. We keep the reference
* here to avoid linear scans of the list. Every time the object is
* accessed, the node is removed from its current spot in the list and
* moved to the front.
*/
public LinkedListNode lastAccessedListNode;
/**
* A reference to the node in the age order list. We keep the reference
* here to avoid linear scans of the list. The reference is used if the
* object has to be deleted from the list.
*/
public LinkedListNode ageListNode;
/**
* A count of the number of times the object has been read from cache.
*/
public int readCount = 0;
/**
* Creates a new cache object wrapper.
*
* @param object the underlying Object to wrap.
*/
public CacheObject(V object) {
this.object = object;
}
public boolean equals(Object o) {
if (this == o) {
return true;
}
if (!(o instanceof CacheObject)) {
return false;
}
final CacheObject cacheObject = (CacheObject) o;
return object.equals(cacheObject.object);
}
public int hashCode() {
return object.hashCode();
}
}
/**
* Simple LinkedList implementation. The main feature is that list nodes
* are public, which allows very fast delete operations when one has a
* reference to the node that is to be deleted.<p>
*/
private static class LinkedList {
/**
* The root of the list keeps a reference to both the first and last
* elements of the list.
*/
private LinkedListNode head = new LinkedListNode("head", null, null);
/**
* Creates a new linked list.
*/
public LinkedList() {
head.next = head.previous = head;
}
/**
* Returns the first linked list node in the list.
*
* @return the first element of the list.
*/
public LinkedListNode getFirst() {
LinkedListNode node = head.next;
if (node == head) {
return null;
}
return node;
}
/**
* Returns the last linked list node in the list.
*
* @return the last element of the list.
*/
public LinkedListNode getLast() {
LinkedListNode node = head.previous;
if (node == head) {
return null;
}
return node;
}
/**
* Adds a node to the beginning of the list.
*
* @param node the node to add to the beginning of the list.
* @return the node
*/
public LinkedListNode addFirst(LinkedListNode node) {
node.next = head.next;
node.previous = head;
node.previous.next = node;
node.next.previous = node;
return node;
}
/**
* Adds an object to the beginning of the list by automatically creating a
* a new node and adding it to the beginning of the list.
*
* @param object the object to add to the beginning of the list.
* @return the node created to wrap the object.
*/
public LinkedListNode addFirst(Object object) {
LinkedListNode node = new LinkedListNode(object, head.next, head);
node.previous.next = node;
node.next.previous = node;
return node;
}
/**
* Adds an object to the end of the list by automatically creating a
* a new node and adding it to the end of the list.
*
* @param object the object to add to the end of the list.
* @return the node created to wrap the object.
*/
public LinkedListNode addLast(Object object) {
LinkedListNode node = new LinkedListNode(object, head, head.previous);
node.previous.next = node;
node.next.previous = node;
return node;
}
/**
* Erases all elements in the list and re-initializes it.
*/
public void clear() {
//Remove all references in the list.
LinkedListNode node = getLast();
while (node != null) {
node.remove();
node = getLast();
}
//Re-initialize.
head.next = head.previous = head;
}
/**
* Returns a String representation of the linked list with a comma
* delimited list of all the elements in the list.
*
* @return a String representation of the LinkedList.
*/
public String toString() {
LinkedListNode node = head.next;
StringBuilder buf = new StringBuilder();
while (node != head) {
buf.append(node.toString()).append(", ");
node = node.next;
}
return buf.toString();
}
}
/**
* Doubly linked node in a LinkedList. Most LinkedList implementations keep the
* equivalent of this class private. We make it public so that references
* to each node in the list can be maintained externally.
*
* Exposing this class lets us make remove operations very fast. Remove is
* built into this class and only requires two reference reassignments. If
* remove existed in the main LinkedList class, a linear scan would have to
* be performed to find the correct node to delete.
*
* The linked list implementation was specifically written for the Jive
* cache system. While it can be used as a general purpose linked list, for
* most applications, it is more suitable to use the linked list that is part
* of the Java Collections package.
*/
private static class LinkedListNode {
public LinkedListNode previous;
public LinkedListNode next;
public Object object;
/**
* This class is further customized for the Jive cache system. It
* maintains a timestamp of when a Cacheable object was first added to
* cache. Timestamps are stored as long values and represent the number
* of milliseconds passed since January 1, 1970 00:00:00.000 GMT.<p>
*
* The creation timestamp is used in the case that the cache has a
* maximum lifetime set. In that case, when
* [current time] - [creation time] > [max lifetime], the object will be
* deleted from cache.
*/
public long timestamp;
/**
* Constructs a new linked list node.
*
* @param object the Object that the node represents.
* @param next a reference to the next LinkedListNode in the list.
* @param previous a reference to the previous LinkedListNode in the list.
*/
public LinkedListNode(Object object, LinkedListNode next,
LinkedListNode previous)
{
this.object = object;
this.next = next;
this.previous = previous;
}
/**
* Removes this node from the linked list that it is a part of.
*/
public void remove() {
previous.next = next;
next.previous = previous;
}
/**
* Returns a String representation of the linked list node by calling the
* toString method of the node's object.
*
* @return a String representation of the LinkedListNode.
*/
public String toString() {
return object.toString();
}
}
}
//GenericsNote: Converted.
/*
* Copyright 2003-2004 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* Abstract Pair class to assist with creating correct Map Entry implementations.
*
* @author James Strachan
* @author Michael A. Smith
* @author Neil O'Toole
* @author Matt Hall, John Watkinson, Stephen Colebourne
* @version $Revision: 1.1 $ $Date: 2005/10/11 17:05:32 $
* @since Commons Collections 3.0
*/
abstract class AbstractMapEntry <K,V> extends AbstractKeyValue<K, V> implements Map.Entry<K, V> {
/**
* Constructs a new entry with the given key and given value.
*
* @param key the key for the entry, may be null
* @param value the value for the entry, may be null
*/
protected AbstractMapEntry(K key, V value) {
super(key, value);
}
// Map.Entry interface
//-------------------------------------------------------------------------
/**
* Sets the value stored in this Map Entry.
* <p/>
* This Map Entry is not connected to a Map, so only the local data is changed.
*
* @param value the new value
* @return the previous value
*/
public V setValue(V value) {
V answer = this.value;
this.value = value;
return answer;
}
/**
* Compares this Map Entry with another Map Entry.
* <p/>
* Implemented per API documentation of {@link java.util.Map.Entry#equals(Object)}
*
* @param obj the object to compare to
* @return true if equal key and value
*/
public boolean equals(Object obj) {
if (obj == this) {
return true;
}
if (obj instanceof Map.Entry == false) {
return false;
}
Map.Entry other = (Map.Entry) obj;
return (getKey() == null ? other.getKey() == null : getKey().equals(other.getKey())) && (getValue() == null ? other.getValue() == null : getValue().equals(other.getValue()));
}
/**
* Gets a hashCode compatible with the equals method.
* <p/>
* Implemented per API documentation of {@link java.util.Map.Entry#hashCode()}
*
* @return a suitable hash code
*/
public int hashCode() {
return (getKey() == null ? 0 : getKey().hashCode()) ^ (getValue() == null ? 0 : getValue().hashCode());
}
}
//GenericsNote: Converted.
/*
* Copyright 2003-2004 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* Abstract pair class to assist with creating KeyValue and MapEntry implementations.
*
* @author James Strachan
* @author Michael A. Smith
* @author Neil O'Toole
* @author Matt Hall, John Watkinson, Stephen Colebourne
* @version $Revision: 1.1 $ $Date: 2005/10/11 17:05:32 $
* @since Commons Collections 3.0
*/
abstract class AbstractKeyValue <K,V> implements KeyValue<K, V> {
/**
* The key
*/
protected K key;
/**
* The value
*/
protected V value;
/**
* Constructs a new pair with the specified key and given value.
*
* @param key the key for the entry, may be null
* @param value the value for the entry, may be null
*/
protected AbstractKeyValue(K key, V value) {
super();
this.key = key;
this.value = value;
}
/**
* Gets the key from the pair.
*
* @return the key
*/
public K getKey() {
return key;
}
/**
* Gets the value from the pair.
*
* @return the value
*/
public V getValue() {
return value;
}
/**
* Gets a debugging String view of the pair.
*
* @return a String view of the entry
*/
public String toString() {
return new StringBuilder().append(getKey()).append('=').append(getValue()).toString();
}
}
//GenericsNote: Converted.
/*
* Copyright 2003-2004 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* Defines a simple key value pair.
* <p/>
* A Map Entry has considerable additional semantics over and above a simple
* key-value pair. This interface defines the minimum key value, with just the
* two get methods.
*
* @author Matt Hall, John Watkinson, Stephen Colebourne
* @version $Revision: 1.1 $ $Date: 2005/10/11 17:05:19 $
* @since Commons Collections 3.0
*/
interface KeyValue <K,V> {
/**
* Gets the key from the pair.
*
* @return the key
*/
K getKey();
/**
* Gets the value from the pair.
*
* @return the value
*/
V getValue();
}
Related examples in the same category