Interface Cache
-
- All Implemented Interfaces:
public interface Cache<K, V>
In general, a cache is a key/value store that has a maximum storage capacity and exposes methods to support CRUD operations to provide temporary storage which maintains a single copy of items that are expensive to create or load, for example via remote network calls.
Because the cache has limited storage capacity, any new item added to a full cache requires an item be removed first. The Cache Replacement Policy of the cache implementation specifies which item to remove.
Each entry in the cache contains a key and its associated value using generics. In addition, a cost value may be specified. Cost is an arbitrary value (can be the size factor of the value, for example). How the cost is handled is implementation dependent.
The
Cache
interface declares the basic CRUD operations an implementation must support. A typicalCache implementation
usually follows similar usage patterns/stages:- Creation-- provides constructor(s) to create an instance of the cache.
- Configuration-- configures features/options and enables the CRUD operations.
- CRUD operations:
The
Creation
andConfiguration
methods are implementation dependent, the CRUD operations are common but may have additional implementation specific semantics.
-
-
Method Summary
Modifier and Type Method Description abstract V
put(@NonNull() K key, @NonNull() V value, double cost)
Adds the value and the associated cost to the cache for the key. abstract V
put(@NonNull() K key, @NonNull() V value)
Adds or updates a value associated with a key. abstract V
get(@NonNull() K key)
Returns the value associated with a key. abstract CacheEntry
getEntry(@NonNull() K key)
Retrieves the value associated with a key, then returns a CacheEntry
object that embeds the key and value.abstract double
getCostOfEntries()
Returns the aggregated value of the cost of the entries in the cache. abstract int
getEntryCount()
Returns the number of entries (key-value pairs) in the cache. abstract List<K>
keys()
Returns a list of keys of all entries in the cache or a non- null
empty list.abstract void
remove(@NonNull() K key)
Removes a cache entry. abstract void
removeAll()
Removes all entries from the cache. -
-
Method Detail
-
put
@Nullable() abstract V put(@NonNull() K key, @NonNull() V value, double cost)
Adds the value and the associated cost to the cache for the key. The behavior when the aggregate of costs exceeds the maximum cost during the execution of this method is implementation dependent.
- Parameters:
key
- anon-null
key of a cache entryvalue
- anon-null
value to addcost
- the cost associated with this entry.- Returns:
The previous value associated with the existed
key
,null
if the entry did exist.
-
put
@Nullable() abstract V put(@NonNull() K key, @NonNull() V value)
Adds or updates a value associated with a key.
- Parameters:
key
- anon-null
key of a cache entryvalue
- anon-null
value to add- Returns:
The original value of an existing cache entry, or
null
if this is a new entry.
-
get
@Nullable() abstract V get(@NonNull() K key)
Returns the value associated with a key.
- Parameters:
key
- anon-null
key of a cache entry- Returns:
The value associated with a key or
null
if the key is not found.
-
getEntry
@Nullable() abstract CacheEntry getEntry(@NonNull() K key)
Retrieves the value associated with a key, then returns a
CacheEntry
object that embeds the key and value.- Parameters:
key
- anon-null
key of a cache entry- Returns:
A CacheEntry or
null
if the key is not found.
-
getCostOfEntries
abstract double getCostOfEntries()
Returns the aggregated value of the cost of the entries in the cache. The concrete behavior is implementation dependent.
- Returns:
The aggregated value of the cost of the entries in the cache.
-
getEntryCount
abstract int getEntryCount()
Returns the number of entries (key-value pairs) in the cache.
- Returns:
The number of entries.
-
keys
@NonNull() abstract List<K> keys()
Returns a list of keys of all entries in the cache or a non-
null
empty list. The order of the entries in the list is implementation dependent.- Returns:
A list of keys of all entries in the cache or a non-
null
empty list (use isEmpty to check).
-
remove
abstract void remove(@NonNull() K key)
Removes a cache entry.
- Parameters:
key
- anon-null
key of the entry to remove
-
removeAll
abstract void removeAll()
Removes all entries from the cache.
-
-
-
-