Package com.cedarsoftware.util.cache

Class LockingLRUCacheStrategy<K,V>

java.lang.Object
com.cedarsoftware.util.cache.LockingLRUCacheStrategy<K,V>
Type Parameters:
K - the type of keys maintained by this cache
V - the type of mapped values
All Implemented Interfaces:
Map<K,V>
public class LockingLRUCacheStrategy<K,V> extends Object implements Map<K,V>
This class provides a thread-safe Least Recently Used (LRU) cache API that evicts the least recently used items once a threshold is met. It implements the Map interface for convenience.

The Locking strategy allows for O(1) access for get(), put(), and remove(). For put(), remove(), and many other methods, a write-lock is obtained. For get(), it attempts to lock but does not lock unless it can obtain it right away. This 'try-lock' approach ensures that the get() API is never blocking, but it also means that the LRU order is not perfectly maintained under heavy load.

LRUCache supports null for both key and value.

Author:
John DeRegnaucourt ([email protected])
Copyright (c) Cedar Software LLC

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

License

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.

  • Constructor Details

    • LockingLRUCacheStrategy

      public LockingLRUCacheStrategy(int capacity)
      Constructs a new LRU cache with the specified maximum capacity.
      Parameters:
      capacity - the maximum number of entries the cache can hold
      Throws:
      IllegalArgumentException - if capacity is negative

  • Method Details

    • getCapacity

      public int getCapacity()
      Returns:
      the maximum number of entries in the cache.

    • get

      public V get(Object key)
      Returns the value associated with the specified key in this cache. If the key exists, attempts to move it to the front of the LRU list using a non-blocking try-lock approach.
      Specified by:
      get in interface Map<K,V>
      Parameters:
      key - the key whose associated value is to be returned
      Returns:
      the value associated with the specified key, or null if no mapping exists

    • put

      public V put(K key, V value)
      Associates the specified value with the specified key in this cache. If the cache previously contained a mapping for the key, the old value is replaced and moved to the front of the LRU list. If the cache is at capacity, removes the least recently used item before adding the new item.
      Specified by:
      put in interface Map<K,V>
      Parameters:
      key - the key with which the specified value is to be associated
      value - the value to be associated with the specified key
      Returns:
      the previous value associated with key, or null if there was no mapping

    • putAll

      public void putAll(Map<? extends K,? extends V> m)
      Copies all mappings from the specified map to this cache. These operations will be performed atomically under a single lock.
      Specified by:
      putAll in interface Map<K,V>
      Parameters:
      m - mappings to be stored in this cache
      Throws:
      NullPointerException - if the specified map is null

    • remove

      public V remove(Object key)
      Removes the mapping for the specified key from this cache if present.
      Specified by:
      remove in interface Map<K,V>
      Parameters:
      key - key whose mapping is to be removed from the cache
      Returns:
      the previous value associated with key, or null if there was no mapping

    • clear

      public void clear()
      Removes all mappings from this cache. The cache will be empty after this call returns.
      Specified by:
      clear in interface Map<K,V>

    • size

      public int size()
      Returns the number of key-value mappings in this cache.
      Specified by:
      size in interface Map<K,V>
      Returns:
      the number of key-value mappings in this cache

    • isEmpty

      public boolean isEmpty()
      Returns true if this cache contains no key-value mappings.
      Specified by:
      isEmpty in interface Map<K,V>
      Returns:
      true if this cache contains no key-value mappings

    • containsKey

      public boolean containsKey(Object key)
      Returns true if this cache contains a mapping for the specified key.
      Specified by:
      containsKey in interface Map<K,V>
      Parameters:
      key - key whose presence in this cache is to be tested
      Returns:
      true if this cache contains a mapping for the specified key

    • containsValue

      public boolean containsValue(Object value)
      Returns true if this cache maps one or more keys to the specified value. This operation requires a full traversal of the cache under a lock.
      Specified by:
      containsValue in interface Map<K,V>
      Parameters:
      value - value whose presence in this cache is to be tested
      Returns:
      true if this cache maps one or more keys to the specified value

    • entrySet

      public Set<Map.Entry<K,V>> entrySet()
      Returns a Set view of the mappings contained in this cache. The set is backed by a new LinkedHashMap to maintain the LRU order. This operation requires a full traversal under a lock.
      Specified by:
      entrySet in interface Map<K,V>
      Returns:
      a set view of the mappings contained in this cache

    • keySet

      public Set<K> keySet()
      Returns a Set view of the keys contained in this cache. The set maintains the LRU order of the cache. This operation requires a full traversal under a lock.
      Specified by:
      keySet in interface Map<K,V>
      Returns:
      a set view of the keys contained in this cache

    • values

      public Collection<V> values()
      Returns a Collection view of the values contained in this cache. The collection maintains the LRU order of the cache. This operation requires a full traversal under a lock.
      Specified by:
      values in interface Map<K,V>
      Returns:
      a collection view of the values contained in this cache

    • equals

      public boolean equals(Object o)
      Compares the specified object with this cache for equality. Returns true if the given object is also a map and the two maps represent the same mappings.
      Specified by:
      equals in interface Map<K,V>
      Overrides:
      equals in class Object
      Parameters:
      o - object to be compared for equality with this cache
      Returns:
      true if the specified object is equal to this cache

    • toString

      public String toString()
      Returns a string representation of this cache. The string representation consists of a list of key-value mappings in LRU order (most recently used first) enclosed in braces ("{}"). Adjacent mappings are separated by the characters ", ".
      Overrides:
      toString in class Object
      Returns:
      a string representation of this cache

    • hashCode

      public int hashCode()
      Returns the hash code value for this cache. The hash code is computed by iterating over all entries in LRU order and combining their hash codes.
      Specified by:
      hashCode in interface Map<K,V>
      Overrides:
      hashCode in class Object
      Returns:
      the hash code value for this cache