net.dontdrinkandroot.cache

Interface Cache<K,V>

Type Parameters:

K - Type of the key that is used to store and lookup entries. Keys should be kept simple as they might be stored in memory. A Key relies on correct implementations of HashCode and Equals.

V - Type of entries that can be stored and retrieved from the cache.

All Known Subinterfaces:

BufferedRecyclingCache<K,V>, CustomTtlCache<K,V>, RecyclingCache<K,V>

All Known Implementing Classes:

AbstractCache, AbstractIndexedDiskCache, AbstractMapBackedCache, AbstractMapBackedCustomTtlCache, BufferedSerializableIndexedDiskCache, ByteArrayIndexedDiskCache, FileCache, MemoryCache, NoopCache, SerializableIndexedDiskCache

public interface Cache<K,V>

A cache is a component that transparently stores data so that future requests for that data can be served faster. Usually caches are used to "remember" the results of computationally complex operations or to speed up the access to a slow medium. The general approach is to ask the cache if it has the result available, if yes then return the stored result, if not, compute the result and store it in the cache. Caches are usually chosen to have a (much) smaller size than the amount of the overall available data, so strategies come into play how entries are evicted when the cache size becomes to large. Therefore caches are not "reliable" as one might expect from a persistent storage: when an entries is stored in the cache, there is no guarantee that it is still available on the next get. Cache entries can also have a time to live which means that even if the entry is available after its expiration it is discarded in favor of new data.

Author:

Philip Washington Sorst

Field Summary

Fields

Modifier and Type	Field and Description
static long	UNLIMITED_IDLE_TIME

Method Summary

Modifier and Type	Method and Description
void	cleanUp() Removes expired and stale entries.
void	delete(K key) Manually remove an entry from the cache.
void	expunge() Cleanup the cache.
<T extends V> T	get(K key) Retrieve an entry from the cache if it is available.
long	getDefaultMaxIdleTime() Get the default max idle time for cache entries.
long	getDefaultTtl() Retrieve the default time to live for cache entries.
MetaData	getMetaData(K key) Retrieve the MetaData of a cached entry if it is available.
String	getName() Get the name of this cache.
CacheStatistics	getStatistics() Get statistics of the cache like hitrate, or size.
<T extends V> T	getWithErrors(K key) Retrieve an entry from the cache if it is available.
<T extends V> T	put(K key, T data) Store an entry in the cache with the default time to live.
<T extends V> T	putWithErrors(K key, T data) Store an entry in the cache with the default time to live.
void	setDefaultTtl(long defaultTTL) Sets the default time to live for cache entries.

Field Detail

UNLIMITED_IDLE_TIME

static final long UNLIMITED_IDLE_TIME

See Also:

Constant Field Values

Method Detail

put

<T extends V> T put(K key,
                    T data)

Store an entry in the cache with the default time to live. Any errors are swallowed, use putWithErrors(Object, Object) if you want to handle them.

Parameters:

key - A unique identifier.

data - The data to store. Make sure that you don't alter the data after it has been put to cache as (depending on the implementation) this might lead to altering the entry in the cache. Use the returned data instead.

Returns:

The entry that has been stored in the cache. It is save to alter this as implementations as implementations make sure that this is always (at least) a copy.

putWithErrors

<T extends V> T putWithErrors(K key,
                              T data)
                       throws CacheException

Store an entry in the cache with the default time to live.

Parameters:

key - A unique identifier.

data - The data to store. Make sure that you don't alter the data after it has been put to cache as (depending on the implementation) this might lead to altering the entry in the cache. Use the returned data instead.

Returns:

The entry that has been stored in the cache. It is save to alter this as implementations as implementations make sure that this is always (at least) a copy.

Throws:

CacheException - Thrown on any errors encountered, supposed to include the stacktrace (if any).

get

<T extends V> T get(K key)

Retrieve an entry from the cache if it is available. Any errors are swallowed, use getWithErrors(Object) if you want to handle them.

Parameters:

key - The unique key under which the entry was stored.

Returns:

The cache entry if it is valid and not expired, null otherwise.

getWithErrors

<T extends V> T getWithErrors(K key)
                       throws CacheException

Retrieve an entry from the cache if it is available.

Parameters:

key - The unique key under which the entry was stored.

Returns:

The cache entry if it is valid and not expired, null otherwise.

Throws:

CacheException - Thrown on any errors encountered, supposed to include the stacktrace (if any).

getMetaData

MetaData getMetaData(K key)
              throws CacheException

Retrieve the MetaData of a cached entry if it is available.

Parameters:

key - The key under which the entry was stored.

Returns:

The MetaData of the entry if found, null otherwise.

Throws:

CacheException - Thrown on any errors encountered, supposed to include the stacktrace (if any).

getDefaultTtl

long getDefaultTtl()

Retrieve the default time to live for cache entries.

Returns:

The default time to live for a cache entry in milliseconds.

setDefaultTtl

void setDefaultTtl(long defaultTTL)

Sets the default time to live for cache entries.

Parameters:

defaultTTL - The default time to live for a cache entry in milliseconds.

getDefaultMaxIdleTime

long getDefaultMaxIdleTime()

Get the default max idle time for cache entries.

Returns:

The default max idle time for cache entries in milliseconds.

delete

void delete(K key)
     throws CacheException

Manually remove an entry from the cache.

Parameters:

key - The key under which the entry was stored.

Throws:

CacheException - Thrown on any errors encountered, supposed to include the stacktrace (if any).

expunge

void expunge()
      throws CacheException

Cleanup the cache. Usually this means that expired entries are deleted but this can also incorporate optimization functions etc. depending on the implementation.

Throws:

CacheException - Thrown on any errors encountered, supposed to include the stacktrace (if any).

getName

String getName()

Get the name of this cache.

Returns:

The name of this cache.

getStatistics

CacheStatistics getStatistics()

Get statistics of the cache like hitrate, or size.

Returns:

Statistics of the cache.

cleanUp

void cleanUp()
      throws CacheException

Removes expired and stale entries.

Throws:

CacheException - Thrown if the cleanup failed.