org.nerd4j.utils.cache

Interface CacheProvider<V>

Type Parameters:

V - type of the objects stored in the cache.

All Known Implementing Classes:

AbstractCacheProvider, EmptyCacheProvider, HeapCacheProvider

public interface CacheProvider<V>

Represents a provider of a caching system.

Usually a caching system returns the value related to a given key if it is present and still valid and null if it is not present or expired. The implementations of this interface need to return null if the given key is not present and an object of type CacheEntry otherwise. The CacheEntry need to be returned even if CacheEntry.isExpired() is true.

The concept behind this choice is to perform the following behavior:

1. if the key is not present (i.e. is never been cached) the related value will be retrieved and inserted.
2. if the key is present and still valid, the related value will be returned.
3. if the key is present but expired the expiration time will be updated (calling touch(CacheKey,long)) then the value will be updated. The best practice to perform this point is to set the expected expiration time in the CacheEntry while the actual cache will expire later.

If more threads are requesting the same key and the key is expired, only the first thread invoking touch(CacheKey,long) will succeed, for the other threads the invocation will fail. This way the first thread will update the value related to the key while the other threads will consider the cached value as still valid.

If touch(CacheKey,long) is called for a key not present in the cache a CacheProviderException will be thrown.

Since:

2.0.0

Author:

Massimo Coluzzi

Method Summary

Modifier and Type	Method and Description
void	clear() Removes all elements from the cache.
CacheEntry<V>	get(CacheKey key) Returns the cache entry related to the given key.
void	put(CacheKey key, V value, long duration) Inserts the given key and the related value into the cache.
void	remove(CacheKey key) Removes the given key from the cache.
boolean	touch(CacheKey key, long duration) Defers the expiration time of the entry related to the given key.

Method Detail

get

CacheEntry<V> get(CacheKey key)

Returns the cache entry related to the given key.

If the given key is never been cached null will be returned, otherwise an object of type CacheEntry will be returned containing the related value and expiration time. The value in the CacheEntry can be null.

Parameters:

key - the key to search for.

Returns:

the related entry if present, null otherwise.

Throws:

CacheProviderException - if an error occurs during the operation.

put

void put(CacheKey key,
         V value,
         long duration)

Inserts the given key and the related value into the cache.

If the given key is already present, the related CacheEntry will be replaced.

The duration is expressed in milliseconds. If the duration is 0 or less nothing will be done.

Parameters:

key - key to be cached.

value - value to be cached.

duration - the amount of time the value will last in cache.

Throws:

CacheProviderException - if an error occurs during the operation.

touch

boolean touch(CacheKey key,
              long duration)

Defers the expiration time of the entry related to the given key.

If the key is not present a CacheProviderException will be thrown.

The duration is expressed in milliseconds. If the duration is 0 or less nothing will be done.

Parameters:

key - the key to search for.

duration - number of milliseconds until expiration.

Returns:

true if the operation was successful, @code false} otherwise.

Throws:

CacheProviderException - if an error occurs during the operation.

remove

void remove(CacheKey key)

Removes the given key from the cache.

If the key is not present nothing will be done.

Parameters:

key - the key to be removed.

Throws:

CacheProviderException - if an error occurs during the operation.

clear

void clear()

Removes all elements from the cache.

This method will clear the underlying cache.

Throws:

CacheProviderException - if an error occurs during the operation.