org.terracotta.cache
Class MutableConfig

java.lang.Object
  org.terracotta.cache.MutableConfig

All Implemented Interfaces:

CacheConfig

public class MutableConfig
extends Object
implements CacheConfig

Initialized with default configuration values. The default values are:

• maxTTISeconds = 0 (off)
• maxTTLSeconds = 0 (off)
• orphanEvictionEnabled = true
• orphanEvictionPeriod = 4
• loggingEnabled = false
• targetMaxInMemoryCount = 0
• targetMaxTotalCount = 0

Field Summary

static String	CAPACITY_EVICTION_POLICY_DATA_FACTORY
static String	LOCAL_CACHE_ENABLED
static String	LOGGING_ENABLED
static String	MAX_TTI_SECONDS
static String	MAX_TTL_SECONDS
static String	NAME
static String	ORPHAN_EVICTION_ENABLED
static String	ORPHAN_EVICTION_PERIOD
static String	TARGET_MAX_ENTRIES_LOCAL_HEAP
static String	TARGET_MAX_TOTAL_COUNT

Constructor Summary

MutableConfig()
Constructs a mutable cache configuration with all default values.

MutableConfig(String name, boolean loggingEnabled, int maxTTISeconds, int maxTTLSeconds, boolean orphanEvictionEnabled, int orphanEvictionPeriod, int targetMaxInMemoryCount, int targetMaxTotalCount, CapacityEvictionPolicyData.Factory capacityEvictionPolicyDataFactory)
Constructs a mutable cache configuration with the given initial values.

Method Summary

void	addConfigChangeListener(ConfigChangeListener ccl) Register the supplied listener to receive notifications when this configuration changes.
boolean	equals(Object o)
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.
int	hashCode()
void	initializeOnLoad()
boolean	isLocalCacheEnabled()
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 new cache instance based on the configuration changes specified in this instance of the builder so far.
boolean	refresh() Take a new snapshot of the current state of the config.
void	removeConfigChangeListener(ConfigChangeListener ccl) Remove the supplied listener from this configurations list of listeners.
CacheConfig	setCapacityEvictionPolicyDataFactory(CapacityEvictionPolicyData.Factory factory) Set the CapacityEvictionPolicyData.Factory to use for creating CapacityEvictionPolicyData
CacheConfig	setLocalCacheEnabled(boolean localCacheEnabled)
MutableConfig	setLoggingEnabled(boolean loggingEnabled) Set distributed cache logging on or off.
MutableConfig	setMaxTTISeconds(int maxTTISeconds) Set max "time to idle" in seconds.
MutableConfig	setMaxTTLSeconds(int maxTTLSeconds) Set max "time to live" in seconds.
MutableConfig	setName(String name) Set distributed cache name, used solely for logging and thread naming purposes.
MutableConfig	setOrphanEvictionEnabled(boolean orphanEvictionEnabled) Turn orphan eviction on or off.
MutableConfig	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
MutableConfig	setTargetMaxInMemoryCount(int targetMaxInMemoryCount) Set the current target for maximum in-memory number of entries.
MutableConfig	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.

Methods inherited from class java.lang.Object

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

Field Detail

LOCAL_CACHE_ENABLED

public static final String LOCAL_CACHE_ENABLED

See Also:

Constant Field Values

CAPACITY_EVICTION_POLICY_DATA_FACTORY

public static final String CAPACITY_EVICTION_POLICY_DATA_FACTORY

See Also:

Constant Field Values

TARGET_MAX_TOTAL_COUNT

public static final String TARGET_MAX_TOTAL_COUNT

See Also:

Constant Field Values

TARGET_MAX_ENTRIES_LOCAL_HEAP

public static final String TARGET_MAX_ENTRIES_LOCAL_HEAP

See Also:

Constant Field Values

ORPHAN_EVICTION_PERIOD

public static final String ORPHAN_EVICTION_PERIOD

See Also:

Constant Field Values

ORPHAN_EVICTION_ENABLED

public static final String ORPHAN_EVICTION_ENABLED

See Also:

Constant Field Values

MAX_TTL_SECONDS

public static final String MAX_TTL_SECONDS

See Also:

Constant Field Values

MAX_TTI_SECONDS

public static final String MAX_TTI_SECONDS

See Also:

Constant Field Values

LOGGING_ENABLED

public static final String LOGGING_ENABLED

See Also:

Constant Field Values

NAME

public static final String NAME

See Also:

Constant Field Values

Constructor Detail

MutableConfig

public MutableConfig()

Constructs a mutable cache configuration with all default values.

MutableConfig

public MutableConfig(String name,
                     boolean loggingEnabled,
                     int maxTTISeconds,
                     int maxTTLSeconds,
                     boolean orphanEvictionEnabled,
                     int orphanEvictionPeriod,
                     int targetMaxInMemoryCount,
                     int targetMaxTotalCount,
                     CapacityEvictionPolicyData.Factory capacityEvictionPolicyDataFactory)

Constructs a mutable cache configuration with the given initial values.

Parameters:

name - the cache name

loggingEnabled - true if logging should be enabled

maxTTISeconds - maximum time-to-live in seconds

maxTTLSeconds - maximum time-to-idle in seconds

orphanEvictionEnabled - true if orphan eviction should be enabled

orphanEvictionPeriod - number of local eviction cycles between orphan evictions

targetMaxInMemoryCount - maximum number of local in-heap elements

targetMaxBytesLocalHeap - maximum bytes in local heap

targetMaxTotalCount - maximum number of elements

capacityEvictionPolicyDataFactory - factory for capacity eviction data types

Method Detail

initializeOnLoad

public void initializeOnLoad()

getName

public String getName()

Description copied from interface: CacheConfig

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

Specified by:

getName in interface CacheConfig

Returns:

Distributed cache instance name

getMaxTTISeconds

public int getMaxTTISeconds()

Description copied from interface: CacheConfig

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.

Specified by:

getMaxTTISeconds in interface CacheConfig

Returns:

Max TTI in seconds, must be >= 0

getMaxTTLSeconds

public int getMaxTTLSeconds()

Description copied from interface: CacheConfig

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.

Specified by:

getMaxTTLSeconds in interface CacheConfig

Returns:

Max TTL in seconds, must be >= 0

isOrphanEvictionEnabled

public boolean isOrphanEvictionEnabled()

Description copied from interface: CacheConfig

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.

Specified by:

isOrphanEvictionEnabled in interface CacheConfig

Returns:

True if orphan eviction is enabled

getOrphanEvictionPeriod

public int getOrphanEvictionPeriod()

Description copied from interface: CacheConfig

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.

Specified by:

getOrphanEvictionPeriod in interface CacheConfig

Returns:

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

isLoggingEnabled

public boolean isLoggingEnabled()

Description copied from interface: CacheConfig

Return true if distributed cache logging is enabled

Specified by:

isLoggingEnabled in interface CacheConfig

Returns:

True for distributed cache logging

getTargetMaxInMemoryCount

public int getTargetMaxInMemoryCount()

Description copied from interface: CacheConfig

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.

Specified by:

getTargetMaxInMemoryCount in interface CacheConfig

Returns:

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

getTargetMaxTotalCount

public int getTargetMaxTotalCount()

Description copied from interface: CacheConfig

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.

Specified by:

getTargetMaxTotalCount in interface CacheConfig

Returns:

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

getCapacityEvictionPolicyDataFactory

public CapacityEvictionPolicyData.Factory getCapacityEvictionPolicyDataFactory()

Description copied from interface: CacheConfig

Get the CapacityEvictionPolicyData.Factory to use for creating CapacityEvictionPolicyData

Specified by:

getCapacityEvictionPolicyDataFactory in interface CacheConfig

isServerMap

public boolean isServerMap()

Description copied from interface: CacheConfig

Returns true if Cache should have a server map backend

Specified by:

isServerMap in interface CacheConfig

Returns:

boolean

isLocalCacheEnabled

public boolean isLocalCacheEnabled()

setServerMap

public CacheConfig setServerMap(boolean serverMap)

Description copied from interface: CacheConfig

Sets whether to use server map or not for the backend

Specified by:

setServerMap in interface CacheConfig

Returns:

boolean

setMaxTTISeconds

public MutableConfig setMaxTTISeconds(int maxTTISeconds)

Description copied from interface: CacheConfig

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.

Specified by:

setMaxTTISeconds in interface CacheConfig

Parameters:

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

Returns:

Current config instance for method chaining

setMaxTTLSeconds

public MutableConfig setMaxTTLSeconds(int maxTTLSeconds)

Description copied from interface: CacheConfig

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.

Specified by:

setMaxTTLSeconds in interface CacheConfig

Parameters:

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

Returns:

Current config instance for method chaining

setOrphanEvictionEnabled

public MutableConfig setOrphanEvictionEnabled(boolean orphanEvictionEnabled)

Description copied from interface: CacheConfig

Turn orphan eviction on or off.

Specified by:

setOrphanEvictionEnabled in interface CacheConfig

Returns:

Current config instance for method chaining

See Also:

CacheConfig.isOrphanEvictionEnabled()

setOrphanEvictionPeriod

public MutableConfig setOrphanEvictionPeriod(int orphanEvictionPeriod)

Description copied from interface: CacheConfig

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.

Specified by:

setOrphanEvictionPeriod in interface CacheConfig

Returns:

Current config instance for method chaining

setLoggingEnabled

public MutableConfig setLoggingEnabled(boolean loggingEnabled)

Description copied from interface: CacheConfig

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

Specified by:

setLoggingEnabled in interface CacheConfig

Parameters:

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

Returns:

Current config instance for method chaining

setTargetMaxInMemoryCount

public MutableConfig setTargetMaxInMemoryCount(int targetMaxInMemoryCount)

Description copied from interface: CacheConfig

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.

Specified by:

setTargetMaxInMemoryCount in interface CacheConfig

Parameters:

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

Returns:

Current config instance for method chaining

setTargetMaxTotalCount

public MutableConfig setTargetMaxTotalCount(int targetMaxTotalCount)

Description copied from interface: CacheConfig

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.

Specified by:

setTargetMaxTotalCount in interface CacheConfig

Parameters:

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

Returns:

Current config instance for method chaining

setName

public MutableConfig setName(String name)

Description copied from interface: CacheConfig

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

Specified by:

setName in interface CacheConfig

Parameters:

name - Distributed cache instance name

Returns:

Current config instance for method chaining

setCapacityEvictionPolicyDataFactory

public CacheConfig setCapacityEvictionPolicyDataFactory(CapacityEvictionPolicyData.Factory factory)

Description copied from interface: CacheConfig

Set the CapacityEvictionPolicyData.Factory to use for creating CapacityEvictionPolicyData

Specified by:

setCapacityEvictionPolicyDataFactory in interface CacheConfig

setLocalCacheEnabled

public CacheConfig setLocalCacheEnabled(boolean localCacheEnabled)

waitForChange

public 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

Specified by:

waitForChange in interface CacheConfig

Parameters:

maxWait - maximum time to wait (in milliseconds)

refresh

public boolean refresh()

Description copied from interface: CacheConfig

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.

Specified by:

refresh in interface CacheConfig

Returns:

true if the config has changed due to the refresh

newCache

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

Construct a new cache instance based on the configuration changes specified in this instance of the builder so far. If Terracotta is not being used, a non-clustered implementation will be returned instead.

Specified by:

newCache in interface CacheConfig

Type Parameters:

K - Key type

V - Value type

Returns:

Map constructed by this method based on previous parameters and defaults

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

addConfigChangeListener

public void addConfigChangeListener(ConfigChangeListener ccl)

Register the supplied listener to receive notifications when this configuration changes.

removeConfigChangeListener

public void removeConfigChangeListener(ConfigChangeListener ccl)

Remove the supplied listener from this configurations list of listeners.