local-scheme

local-scheme

Used in: caching-schemes, distributed-scheme, replicated-scheme, optimistic-scheme, near-scheme, versioned-near-scheme, overflow-scheme, read-write-backing-map-scheme, versioned-backing-map-scheme

Description

Local cache schemes define in-memory "local" caches. Local caches are generally nested within other cache schemes, for instance as the front-tier of a near-scheme.

Implementation

Local caches are implemented by the com.tangosol.net.cache.LocalCache class.

Cache of an External Store

A local cache may be backed by an external cache store, cache misses will read-through to the backend store to retrieve the data. If a writable store is provided, cache writes will propogate to the cache store as well. For optimizing read/write access against a cache store see the read-write-backing-map-scheme.

Size Limited Cache

The cache may be configured as size-limited, which means that once it reaches its maximum allowable size it prunes itself back to a specified smaller size, choosing which entries to evict according to its eviction-policy. The entries and size limitiations are measured in terms of units as calculated by the scheme's unit-calculator.

Entry Expiration

The local cache supports automatic expiration of entries based on the age of the value, as configured by the expiry-delay.

Elements

The following table describes the elements you can define within the local-scheme element.

Element Required/Optional Description
<scheme-name> Optional Specifies the scheme's name. The name must be unique within a configuration file.
<scheme-ref> Optional Specifies the name of another scheme to inherit from.
<service-name> Optional Specifies the name of the service which will manage caches created from this scheme.

services are configured from within the operational descriptor.
<class-name> Optional Specifies a custom implementation of the local cache.

Any custom implementation must extend the com.tangosol.net.cache.LocalCache class and declare the exact same set of public constructors.
<init-params> Optional Specifies initialization parameters, for use in custom local cache implementations which implement the com.tangosol.run.xml.XmlConfigurable interface.
<listener> Optional Specifies an implementation of a com.tangosol.util.MapListener which will be notified of events occuring on the cache.
<cachestore-scheme> Optional Specifies the store which is being cached. If unspecified the cached data will only reside in memory, and only reflect operations performed on the cache itself.
<eviction-policy> Optional Specifies the type of eviction policy to use.

Legal values are:

  • LRU - Least Recently Used eviction policy chooses which entries to evict based on how recently they were last accessed, evicting those that were not accessed the for the longest period first.
  • LFU - Least Frequently Used eviction policy chooses which entries to evict based on how often they are being accessed, evicting those that are accessed least frequently first.
  • HYBRID - Hybrid eviction policy chooses which entries to evict based the combination (weighted score) of how often and recently they were accessed, evicting those that are accessed least frequently and were not accessed for the longest period first.
  • <class-scheme> - A custom eviction policy, specified as a class-scheme. The class specified within this scheme must implement the com.tangosol.net.cache.LocalCache.EvictionPolicy interface.

Default value is HYBRID.

<high-units> Optional Used to limit the size of the cache. Contains the maximum number of units that can be placed in the cache before pruning occurs. An entry is the unit of measurement, unless it is overridden by an alternate unit-calculator. Once this limit is exceeded, the cache will begin the pruning process, evicting entries according to the eviction policy until the low-units size is reached.

Legal values are positive integers or zero. Zero implies no limit.

Default value is 1000.
<low-units> Optional Contains the number of units that the cache will be pruned down to when pruning takes place. An entry is the unit of measurement, unless it is overridden by an alternate unit-calculator. When pruning occurs entries will continue to be evicted according to the eviction policy until this size.

Legal values are positive integers or zero. Zero implies no limit.

Default value is 75% of the high-units setting (i.e. for a high-units setting of 1000 the default low-units will be 750).
<unit-calculator> Optional Specifies the type of unit calculator to use.

A unit calculator is used to determine the cost (in "units") of a given object.

Legal values are:

Default value is FIXED.

<expiry-delay> Optional Specifies the amount of time from last update that entries will be kept by the cache before being marked as expired. Any attempt to read an expired entry will result in a reloading of the entry from the configured cache store. Expired values are periodically discarded from the cache based on the flush-delay.

The value of this element must be in the following format:
[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

  • MS or ms (milliseconds)
  • S or s (seconds)
  • M or m (minutes)
  • H or h (hours)
  • D or d (days)

If the value does not contain a unit, a unit of seconds is assumed.

A value of zero implies no expiry.

Default value is zero.

<flush-delay> Optional Specifies the time interval between periodic cache flushes, which will discard expired entries from the cache, thus freeing resources.

The value of this element must be in the following format:
[\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

where the first non-digits (from left to right) indicate the unit of time duration:

  • MS or ms (milliseconds)
  • S or s (seconds)
  • M or m (minutes)
  • H or h (hours)
  • D or d (days)

If the value does not contain a unit, a unit of seconds is assumed.

If expiry is enabled, the default flush-delay is 1m, otherwise automatic flushes are disabled by default.