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 W. Sorst <philip@sorst.net>

### Field Summary

Fields
`static long` `UNLIMITED_IDLE_TIME`

### Method Summary

Methods
`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.