Used in: caching-schemes, distributed-scheme, replicated-scheme, optimistic-scheme.


The read-write-backing-map-scheme defines a backing map which provides a size limited cache of a persistent store. See the Read-Through, Write-Through, Refresh-Ahead and Write-Behind Caching overview for more details.


The read-write-backing-map-scheme is implemented by the class.

Cache of an External Store

A read write backing map maintains a cache backed by an external persistent 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.

Refresh-Ahead Caching

When enabled the cache will watch for recently accessed entries which are about to expire, and asynchronously reload them from the cache store. This insulates the application from potentially slow reads against the cache store, as items periodically expire.

Write-Behind Caching

When enabled the cache will delay writes to the backend cache store. This allows for the writes to be batched into more efficient update blocks, which occur asynchronously from the client thread.


The following table describes the elements you can define within the read-write-backing-map-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.
<class-name> Optional Specifies a custom implementation of the read write backing map.

Any custom implementation must extend the class and declare the exact same set of public constructors.
<init-params> Optional Specifies initialization parameters, for use in custom read write backing map implementations which implement the interface.
<listener> Optional Specifies an implementation of a com.tangosol.util.MapListener which will be notified of events occurring on the cache.
<cachestore-scheme> Optional Specifies the store to cache. If unspecified the cached data will only reside within the internal cache, and only reflect operations performed on the cache itself.
<internal-cache-scheme> Required Specifies a cache-scheme which will be used to cache entries.

Legal values are:

<miss-cache-scheme> Optional Specifies a cache-scheme for maintaining information on cache misses. The miss-cache is used track keys which were not found in the cache store. The knowledge that a key is not in the cache store allows some operations to perform faster, as they can avoid querying the potentially slow cache store. A size-limited scheme may be used to control how many misses are cached. If unspecified no cache-miss data will be maintained.

Legal values are:

<read-only> Optional Specifies if the cache is read only. If true the cache will load data from cachestore for read operations and will not perform any writing to the cachestore when the cache is updated.

Legal values are true or false.

Default value is false.
<write-delay> Optional Specifies the time interval for a write-behind queue to defer asynchronous writes to the cachestore by.

The value of this element must be in the following format:


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 zero, synchronous writes to the cachestore (without queuing) will take place, otherwise the writes will be asynchronous and deferred by the number of seconds after the last update to the value in the cache.

Default is zero.

<write-batch-factor> Optional The write-batch-factor element is used to calculate the "soft-ripe" time for write-behind queue entries.

A queue entry is considered to be "ripe" for a write operation if it has been in the write-behind queue for no less than the write-delay interval. The "soft-ripe" time is the point in time prior to the actual ripe time after which an entry will be included in a batched asynchronous write operation to the CacheStore (along with all other ripe and soft-ripe entries). In other words, a soft-ripe entry is an entry that has been in the write-behind queue for at least the following duration:

D' = (1.0 - F)*D


D = write-delay interval
F = write-batch-factor

Conceptually, the write-behind thread uses the following logic when performing a batched update:

  1. The thread waits for a queued entry to become ripe.
  2. When an entry becomes ripe, the thread dequeues all ripe and soft-ripe entries in the queue.
  3. The thread then writes all ripe and soft-ripe entries either via store() (if there is only the single ripe entry) or storeAll() (if there are multiple ripe/soft-ripe entries).
  4. The thread then repeats (1).

This element is only applicable if asynchronous writes are enabled (i.e. the value of the write-delay element is greater than zero) and the CacheStore implements the storeAll() method.

The value of the element is expressed as a percentage of the write-delay interval.

Legal values are non-negative doubles less than or equal to 1.0.

Default is zero.

<write-requeue-threshold> Optional Specifies the maximum size of the write-behind queue for which failed cachestore write operations are requeued.

The purpose of this setting is to prevent flooding of the write-behind queue with failed cachestore operations. This can happened in situations where a large number of successive write operations fail.

If zero, write-behind requeueing is disabled.

Legal values are positive integers or zero.

Default is zero.
<refresh-ahead-factor> Optional The refresh-ahead-factor element is used to calculate the "soft-expiration" time for cache entries.

Soft-expiration is the point in time prior to the actual expiration after which any access request for an entry will schedule an asynchronous load request for the entry.

This attribute is only applicable if the internal cache is a LocalCache, configured with automatic expiration.

The value is expressed as a percentage of the internal LocalCache expiration interval. If zero, refresh-ahead scheduling will be disabled. If 1.0, then any get operation will immediately trigger an asynchronous reload.

Legal values are non-negative doubles less than or equal to 1.0.

Default value is zero.
<rollback-cachestore-failures> Optional Specifies whether or not exceptions caught during synchronous cachestore operations are rethrown to the calling thread (possibly over the network to a remote member).

If the value of this element is false, an exception caught during a synchronous cachestore operation is logged locally and the internal cache is updated.

If the value is true, the exception is rethrown to the calling thread and the internal cache is not changed. If the operation was called within a transactional context, this would have the effect of rolling back the current transaction.

Legal values are true or false.

Default value is false.