com.evanmclean.evlib.cache
Class CacheBuilder

java.lang.Object
  com.evanmclean.evlib.cache.CacheBuilder

public class CacheBuilder
extends Object

Builds caches to spec for a cache manager (see CacheManager.builder() ).

Default builder has the following properites:

• Stores values in the cache map with a strong reference.
• ttl of 10 seconds.
• refresh of false indicating expiry times are never refreshed.
• Does not limit the maximum number of entries in a map ( max entries equals 0).
• No cached value disposer.

Refreshing

Caches include a refresh facility, which can effectively keep most used items in the cache while least used ones expire out of the cache. This is different to the default behaviour in which each item in the cache has a set lifetime (time-to-live).

Note that while you can change the expiry time on an existing cache, this only effects new values that are added to the cache. Existing values will always use the time to live value that was in effect when it was initially added to the cache.

Reference Types and Value Disposers

Entries in a cache can be stored with either a strong, soft or weak reference.

A cache can also have a helper value disposer, that is called only any value that is expired by reaching the end of its time to live, or by a call to Map.clear(). This is useful for cleaning up resources when a value goes out of scope. Only caches that keep a strong reference type can have a value disposer.

Author:

Evan M^cLean M^cLean Computer Services (see the overview for copyright and licensing.)

Method Summary

<K,V> ConcurrentHashMapCache<K,V>	build(Class<?> cls) Builds a cache with the current factory settings.
<K,V> ConcurrentHashMapCache<K,V>	build(String name) Builds a cache with the current factory settings.
<K,V> ConcurrentHashMapCache<K,V>	buildOrGet(Class<?> cls) Builds a cache (if it doesn't already exist) with the current factory settings.
<K,V> ConcurrentHashMapCache<K,V>	buildOrGet(String name) Builds a cache (if it doesn't already exist) with the current factory settings.
CacheBuilder	disposer(CacheValueDisposer<?> value_disposer) Object used to clean up cached values that expire or are removed via a call to Map.clear().
CacheReferenceType	getCacheReferenceType() Get the cache reference type that caches with be created with.
int	getMaxEntries() The maximum number of entries caches with contain (0 for unlimited).
long	getTtlMillisec() The time to live for each entry (in milliseconds).
boolean	isRefreshTtl() True if retrieving a value from the cache refreshes its expiry time.
CacheBuilder	max(int max_entries) Set the maximum number of entries caches will be allowed to contain (0 for unlimited).
CacheBuilder	nodisposer() Set caches to have no value disposer.
CacheBuilder	norefresh() Sets the cache to not refresh the expiry time of values when they are retrieved by calls like Map.get(Object).
CacheBuilder	ref(CacheReferenceType cache_reference_type) The reference type that will be used by caches for storing their values.
CacheBuilder	refresh() Sets the cache to refresh the expiry time of values when they are retrieved by calls like Map.get(Object).
CacheBuilder	refresh(boolean refresh_ttl) Sets the cache to refresh the expiry time of values when they are retrieved by calls like Map.get(Object).
CacheBuilder	reset() Resets the builder to default values.
CacheBuilder	soft() Values will be stored in created caches with a soft reference (see CacheReferenceType.SOFT).
CacheBuilder	strong() Values will be stored in created caches with a strong reference (see CacheReferenceType.STRONG).
CacheBuilder	ttl(long ttl, TimeUnit time_unit) Set the time to live for values that will be used in the caches created.
CacheBuilder	weak() Values will be stored in created caches with a weak reference (see CacheReferenceType.WEAK).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

build

public <K,V> ConcurrentHashMapCache<K,V> build(Class<?> cls)
                                  throws CacheExistsException

Builds a cache with the current factory settings. Caches are identified by their name, and an exception is thrown if the cache already exists.

Type Parameters:

K -

V -

Parameters:

cls - The name of the cache will be the name of the class.

Returns:

The cache.

Throws:

CacheExistsException - Thrown if the cache already exists.

build

public <K,V> ConcurrentHashMapCache<K,V> build(String name)
                                  throws CacheExistsException

Builds a cache with the current factory settings. Caches are identified by their name, and an exception is thrown if the cache already exists.

Type Parameters:

K -

V -

Parameters:

name - The name of the cache.

Returns:

The cache.

Throws:

CacheExistsException - Thrown if the cache already exists.

buildOrGet

public <K,V> ConcurrentHashMapCache<K,V> buildOrGet(Class<?> cls)

Builds a cache (if it doesn't already exist) with the current factory settings. Caches are identified by their name, and if a cache already exists, then this method returns the pre-existing cache and the rest of the arguments to the method are ignored.

Type Parameters:

K -

V -

Parameters:

cls - The name of the cache will be the name of the class.

Returns:

The cache.

buildOrGet

public <K,V> ConcurrentHashMapCache<K,V> buildOrGet(String name)

Builds a cache (if it doesn't already exist) with the current factory settings. Caches are identified by their name, and if a cache already exists, then this method returns the pre-existing cache and the rest of the arguments to the method are ignored.

Type Parameters:

K -

V -

Parameters:

name - The name of the cache.

Returns:

The cache.

disposer

public CacheBuilder disposer(CacheValueDisposer<?> value_disposer)

Object used to clean up cached values that expire or are removed via a call to Map.clear().

Parameters:

value_disposer - Method to clean up expired values (may be null).

Returns:

This cache builder.

getCacheReferenceType

public CacheReferenceType getCacheReferenceType()

Get the cache reference type that caches with be created with.

Returns:

The cache reference type that caches with be created with.

getMaxEntries

public int getMaxEntries()

The maximum number of entries caches with contain (0 for unlimited).

Returns:

The maximum number of entries caches with contain (0 for unlimited).

getTtlMillisec

public long getTtlMillisec()

The time to live for each entry (in milliseconds).

Returns:

The time to live for each entry (in milliseconds).

isRefreshTtl

public boolean isRefreshTtl()

True if retrieving a value from the cache refreshes its expiry time.

Returns:

True if retrieving a value from the cache refreshes its expiry time.

max

public CacheBuilder max(int max_entries)

Set the maximum number of entries caches will be allowed to contain (0 for unlimited).

Parameters:

max_entries - The maximum number of entries caches will be allowed to contain (0 for unlimited).

Returns:

This cache builder.

nodisposer

public CacheBuilder nodisposer()

Set caches to have no value disposer.

Returns:

This cache builder.

norefresh

public CacheBuilder norefresh()

Sets the cache to not refresh the expiry time of values when they are retrieved by calls like Map.get(Object).

Returns:

This cache builder.

ref

public CacheBuilder ref(CacheReferenceType cache_reference_type)

The reference type that will be used by caches for storing their values.

Parameters:

cache_reference_type - The reference type that will be used by caches for storing their values.

Returns:

This cache builder.

refresh

public CacheBuilder refresh()

Sets the cache to refresh the expiry time of values when they are retrieved by calls like Map.get(Object).

Returns:

This cache builder.

refresh

public CacheBuilder refresh(boolean refresh_ttl)

Sets the cache to refresh the expiry time of values when they are retrieved by calls like Map.get(Object).

Parameters:

refresh_ttl - True to refresh the expiry time of values when they are retrieved.

Returns:

This cache builder.

reset

public CacheBuilder reset()

Resets the builder to default values.

Returns:

This cache builder.

soft

public CacheBuilder soft()

Values will be stored in created caches with a soft reference (see CacheReferenceType.SOFT).

Returns:

This cache builder.

strong

public CacheBuilder strong()

Values will be stored in created caches with a strong reference (see CacheReferenceType.STRONG).

Returns:

This cache builder.

ttl

public CacheBuilder ttl(long ttl,
                        TimeUnit time_unit)

Set the time to live for values that will be used in the caches created.

Parameters:

ttl - The time to live for values that will be used in the caches created.

time_unit - The time unit for ttl.

Returns:

This cache builder.

weak

public CacheBuilder weak()

Values will be stored in created caches with a weak reference (see CacheReferenceType.WEAK).

Returns:

This cache builder.