Java Doc for LRUMap.java in  » Library » Apache-common-Collections » org » apache » commons » collections » map » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The least recently used algorithm works on the get and put operations only. Iteration of any kind, including setting the value by iteration, does not change the order. Queries such as containsKey and containsValue or access via views also do not change the order.

The map implements OrderedMap and entries may be queried using the bidirectional OrderedMapIterator. The order returned is least recently used to most recently used. Iterators from map views can also be cast to OrderedIterator if required.

All the available iterators can be reset back to the start by casting to ResettableIterator and calling reset().

Note that LRUMap is not synchronized and is not thread-safe. If you wish to use this map from multiple threads concurrently, you must use appropriate synchronization. The simplest approach is to wrap this map using java.util.Collections.synchronizedMap(Map) . This class may throw NullPointerException's when accessed by concurrent threads.
since:
   Commons Collections 3.0 (previously in main package v1.0)
version:
   $Revision: 348299 $ $Date: 2005-11-22 23:51:45 +0000 (Tue, 22 Nov 2005) $
author:
   James Strachan
author:
   Morgan Delagrange
author:
   Stephen Colebourne
author:
   Mike Pettypiece
author:
   Mario Ivankovits

This method exists for subclasses to override.

The maximum size is set from the map's size.
Parameters:
  map - the map to copy
throws:
  NullPointerException - if the map is null
throws:
  IllegalArgumentException - if the map is empty

The maximum size is set from the map's size.
Parameters:
  map - the map to copy
Parameters:
  scanUntilRemovable - scan until a removeable entry is found, default false
throws:
  NullPointerException - if the map is null
throws:
  IllegalArgumentException - if the map is empty
since:
   Commons Collections 3.1

This implementation checks the LRU size and determines whether to discard an entry or not using LRUMap.removeLRU(AbstractLinkedMap.LinkEntry) .

From Commons Collections 3.1 this method uses LRUMap.isFull() rather than accessing size and maxSize directly. It also handles the scanUntilRemovable functionality.
Parameters:
  hashIndex - the index into the data array to store at
Parameters:
  hashCode - the hash code of the key to add
Parameters:
  key - the key to add
Parameters:
  value - the value to add

This operation changes the position of the key in the map to the most recently used position (first).
Parameters:
  key - the key the mapped value, null if no match

This implementation moves the updated entry to the end of the list.
Parameters:
  entry - the entry to update

This method exists for subclasses to override. A subclass may wish to provide cleanup of resources when an entry is removed. For example:

 protected boolean removeLRU(LinkEntry entry) {
 releaseResources(entry.getValue());  // release resources held by entry
 return true;  // actually delete entry
 }
 

Alternatively, a subclass may choose to not remove the entry or selectively keep certain LRU entries. For example:

 protected boolean removeLRU(LinkEntry entry) {
 if (entry.getKey().toString().startsWith("System.")) {
 return false;  // entry not removed from LRUMap
 } else {
 return true;  // actually delete entry
 }
 }
 

NOTE: Commons Collections 3.0 passed the wrong entry to this method. This is fixed in version 3.1 onwards.
Parameters:
  entry - the entry to be removed

This method uses LRUMap.removeEntry , LRUMap.reuseEntry and LRUMap.addEntry .
Parameters:
  entry - the entry to reuse
Parameters:
  hashIndex - the index into the data array to store at
Parameters:
  hashCode - the hash code of the key to add
Parameters:
  key - the key to add
Parameters:
  value - the value to add

This implementation moves the updated entry to the top of the list using LRUMap.moveToMRU(AbstractLinkedMap.LinkEntry) .
Parameters:
  entry - the entry to update
Parameters:
  newValue - the new value to store