org.terracotta.cache
Interface CacheConfig

All Known Implementing Classes:

ImmutableConfig, MutableConfig

public interface CacheConfig

Defines the configuration for a DistributedCache. Most parameters can be changed dynamically after the cache is constructed. Exceptions will be noted in the javadoc for the property.

Config implementations are permitted to return out-of-date results from getters; that is, a change made to a DynamicConfig may not immediately be visible. This permits clustered Configs to be accessed without locking. In order to ensure that values are up to date, the user should periodically call refresh().

Method Summary

CapacityEvictionPolicyData.Factory	getCapacityEvictionPolicyDataFactory() Get the CapacityEvictionPolicyData.Factory to use for creating CapacityEvictionPolicyData
int	getMaxTTISeconds() Max "time to idle" in seconds.
int	getMaxTTLSeconds() Max "time to live" in seconds.
String	getName() Get distributed cache name, used solely for logging, thread naming, and identification purposes.
int	getOrphanEvictionPeriod() Get frequency at which orphan eviction will occur.
int	getTargetMaxInMemoryCount() Get the current target for maximum in-memory number of entries.
int	getTargetMaxTotalCount() Get the current target for maximum total number of entries.
boolean	isLoggingEnabled() Return true if distributed cache logging is enabled
boolean	isOrphanEvictionEnabled() Indicates whether orphan eviction is turned on.
boolean	isServerMap() Returns true if Cache should have a server map backend
<K,V> DistributedCache<K,V>	newCache() Construct a cache instance based on this config's settings.
boolean	refresh() Take a new snapshot of the current state of the config.
CacheConfig	setCapacityEvictionPolicyDataFactory(CapacityEvictionPolicyData.Factory factory) Set the CapacityEvictionPolicyData.Factory to use for creating CapacityEvictionPolicyData
CacheConfig	setLoggingEnabled(boolean loggingEnabled) Set distributed cache logging on or off.
CacheConfig	setMaxTTISeconds(int maxTTISeconds) Set max "time to idle" in seconds.
CacheConfig	setMaxTTLSeconds(int maxTTLSeconds) Set max "time to live" in seconds.
CacheConfig	setName(String name) Set distributed cache name, used solely for logging and thread naming purposes.
CacheConfig	setOrphanEvictionEnabled(boolean orphanEvictionEnabled) Turn orphan eviction on or off.
CacheConfig	setOrphanEvictionPeriod(int orphanEvictionPeriod) Set frequency at which orphan eviction will occur.
CacheConfig	setServerMap(boolean serverMap) Sets whether to use server map or not for the backend
CacheConfig	setTargetMaxInMemoryCount(int targetMaxInMemoryCount) Set the current target for maximum in-memory number of entries.
CacheConfig	setTargetMaxTotalCount(int targetMaxTotalCount) Set the current target for maximum total number of entries.
void	waitForChange(long maxWait) Causes the current thread to wait for this configuration object to change.

Method Detail

getName

String getName()

Get distributed cache name, used solely for logging, thread naming, and identification purposes. If no name is specified, a generic name is used.

Returns:

Distributed cache instance name

setName

CacheConfig setName(String name)

Set distributed cache name, used solely for logging and thread naming purposes. The name of a cache cannot be changed after construction.

Parameters:

name - Distributed cache instance name

Returns:

Current config instance for method chaining

Throws:

IllegalStateException - If called after cache is constructed

getMaxTTISeconds

int getMaxTTISeconds()

Max "time to idle" in seconds. When an element in the DistributedCache has been in the map but not been accessed longer than the MaxTTI, it will expire and can be evicted. Passing 0 for the MaxTTI indicates items do not expire due to lack of use.

Returns:

Max TTI in seconds, must be >= 0

setMaxTTISeconds

CacheConfig setMaxTTISeconds(int maxTTISeconds)

Set max "time to idle" in seconds. If the Max TTI is dynamically changed from UNUSED (0) to some value, items in the cache may expire immediately.

The background eviction thread sleep interval is based on this value and the Max TTL, so a side effect of changing this value is to change the sleep interval of the eviction thread.

Parameters:

maxTTISeconds - Max TTI in seconds, must be >= 0, 0 = no TTI

Returns:

Current config instance for method chaining

getMaxTTLSeconds

int getMaxTTLSeconds()

Max "time to live" in seconds. When an element in the DistributedCache has been in the map longer than the MaxTTL, it will expire and can be evicted. Passing 0 for the MaxTTL indicates items do not expire due to their length of time in map.

Returns:

Max TTL in seconds, must be >= 0

isServerMap

boolean isServerMap()

Returns true if Cache should have a server map backend

Returns:

boolean

setServerMap

CacheConfig setServerMap(boolean serverMap)

Sets whether to use server map or not for the backend

Returns:

boolean

setMaxTTLSeconds

CacheConfig setMaxTTLSeconds(int maxTTLSeconds)

Set max "time to live" in seconds. If the Max TTL is dynamically changed from UNUSED (0) to some value, items in the cache may expire immediately.

The background eviction thread sleep interval is based on this value and the Max TTL, so a side effect of changing this value is to change the sleep interval of the eviction thread.

Parameters:

maxTTLSeconds - Max TTL in seconds, must be >= 0, 0 = no TTL

Returns:

Current config instance for method chaining

isLoggingEnabled

boolean isLoggingEnabled()

Return true if distributed cache logging is enabled

Returns:

True for distributed cache logging

setLoggingEnabled

CacheConfig setLoggingEnabled(boolean loggingEnabled)

Set distributed cache logging on or off. This setting should only be used for development purposes and may have a performance impact.

Parameters:

loggingEnabled - Change logging to on (true) or off (false)

Returns:

Current config instance for method chaining

isOrphanEvictionEnabled

boolean isOrphanEvictionEnabled()

Indicates whether orphan eviction is turned on. Normal local eviction will only detect whether items in the local node have expired and need to be evicted. Orphan eviction is used to detect that items in the map, but not currently local to ANY node, have expired and need to be evicted. This can happen either due to node failures or due to object flushing.

Returns:

True if orphan eviction is enabled

setOrphanEvictionEnabled

CacheConfig setOrphanEvictionEnabled(boolean orphanEvictionEnabled)

Turn orphan eviction on or off.

Returns:

Current config instance for method chaining

See Also:

isOrphanEvictionEnabled()

getOrphanEvictionPeriod

int getOrphanEvictionPeriod()

Get frequency at which orphan eviction will occur. The number indicates the number of local eviction cycles that should occur in between orphan eviction runs. Generally, you will not need to modify this setting.

Returns:

Number of local eviction cycles to wait between orphan eviction. If orphan eviction is enabled, must be > 0.

setOrphanEvictionPeriod

CacheConfig setOrphanEvictionPeriod(int orphanEvictionPeriod)

Set frequency at which orphan eviction will occur. The number indicates the number of local eviction cycles that should occur in between orphan eviction runs. Generally, you will not need to modify this setting.

Returns:

Current config instance for method chaining

getTargetMaxInMemoryCount

int getTargetMaxInMemoryCount()

Get the current target for maximum in-memory number of entries. If the target is crossed, the evictor will start flushing values from the cache back to the Terracotta server array. "Flushing" is a Terracotta concept where an object reference is removed from a JVM but can be reconstituted from the Terracotta server state on demand. Flushed values are NOT evicted from the cache (although they are still eligible to be evicted for other reasons).

A value of 0 indicates that there is no in-memory limit.

Returns:

Target max in-memory count, >= 0, 0 = no max

setTargetMaxInMemoryCount

CacheConfig setTargetMaxInMemoryCount(int targetMaxInMemoryCount)

Set the current target for maximum in-memory number of entries. If the target is crossed, the evictor will start flushing values from the cache back to the Terracotta server array. "Flushing" is a Terracotta concept where an object reference is removed from a JVM but can be reconstituted from the Terracotta server state on demand. Flushed values are NOT evicted from the cache (although they are still eligible to be evicted for other reasons).

A value of 0 indicates that there is no in-memory limit.

Parameters:

targetMaxInMemoryCount - Target max in-memory count, must be >= 0, 0 = no max

Returns:

Current config instance for method chaining

getTargetMaxTotalCount

int getTargetMaxTotalCount()

Get the current target for maximum total number of entries. If the target is crossed, items will be evicted from the cache. For eviction, a preference will be given to items that are not currently in use in any node - these are likely not recently used and also can be removed without causing a Terracotta "fault" into memory.

A value of 0 indicates that there is no limit.

Returns:

Target max total count, >= 0, 0 = no max

setTargetMaxTotalCount

CacheConfig setTargetMaxTotalCount(int targetMaxTotalCount)

Set the current target for maximum total number of entries. If the target is crossed, items will be evicted from the cache. For eviction, a preference will be given to items that are not currently in use in any node - these are likely not recently used and also can be removed without causing a Terracotta "fault" into memory.

A value of 0 indicates that there is no limit.

Parameters:

targetMaxTotalCount - Target max total count, >= 0, 0 = no max

Returns:

Current config instance for method chaining

newCache

<K,V> DistributedCache<K,V> newCache()

Construct a cache instance based on this config's settings. Note that this config instance is NOT connected to the new cache instance - it will have a copy of these settings.

Type Parameters:

K - Key type

V - Value type

Returns:

Map constructed by this method based on previous parameters and defaults

refresh

boolean refresh()

Take a new snapshot of the current state of the config. For immutable configs this will generally be a no-op. For dynamic configs, calling refresh will ensure that values returned by getters reflect the most recent changes.

Returns:

true if the config has changed due to the refresh

waitForChange

void waitForChange(long maxWait)

Causes the current thread to wait for this configuration object to change. If the config has not changed within maxWait milliseconds then the method will return regardless.

This operation can be interrupted using Thread.interrupt(). The interrupt status of the thread will be set on return from this method if interrupted. Interrupting this method will not throw InterruptedException

Parameters:

maxWait - maximum time to wait (in milliseconds)

getCapacityEvictionPolicyDataFactory

CapacityEvictionPolicyData.Factory getCapacityEvictionPolicyDataFactory()

Get the CapacityEvictionPolicyData.Factory to use for creating CapacityEvictionPolicyData

setCapacityEvictionPolicyDataFactory

CacheConfig setCapacityEvictionPolicyDataFactory(CapacityEvictionPolicyData.Factory factory)

Set the CapacityEvictionPolicyData.Factory to use for creating CapacityEvictionPolicyData