Used in: caching-schemes, distributed-scheme, replicated-scheme, optimistic-scheme.
The versioned-backing-map-scheme is an extension of a read-write-backing-map-scheme, defining a size limited cache of a persistent store. It utilizes object versioning to determine what updates need to be written to the persistent store.
The versioned-backing-map-scheme scheme is implemented by the com.tangosol.net.cache.VersionedBackingMap class.
As with the read-write-backing-map-scheme, a versioned 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. Cache stores may also support updates to the backend data store.
As with the read-write-backing-map-scheme both the refresh-ahead and write-behind caching optimizations are supported. See Read-Through, Write-Through, Refresh-Ahead and Write-Behind Caching for more details.
For entries whose values implement the com.tangosol.util.Versionable interface, the versioned backing map will utilize the version identifier to determine if an update needs to be written to the persistent store. The primary benefit of this feature is that in the event of cluster node failover, the backup node can determine if the most recent version of an entry has already been written to the persistent store, and if so it can avoid an extraneous write.
The following table describes the elements you can define within the versioned-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 versioned backing map.
Any custom implementation must extend the com.tangosol.net.cache.VersionedBackingMap class and declare the exact same set of public constructors. |
| <init-params> | Optional | Specifies initialization parameters, for use in custom versioned backing map 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 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: [\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:
If the value does not contain a unit, a unit of seconds is assumed.
|
| <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). 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. For example, if the value is zero, only "ripe" entries from the write-behind queue will be batched. On the other hand, if the value is 1.0, all currently queued entries will be batched and the value of the write-delay element will be effectively ignored. 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. |
| <version-persistent-scheme> | Optional | Specifies a cache-scheme for tracking the version identifier for entries in the persistent cachestore. |
| <version-transient-scheme> | Optional | Specifies a cache-scheme for tracking the version identifier for entries in the transient internal cache. |
| <manage-transient> | Optional | Specifies if the backing map is responsible for keeping the transient version cache up to date.
If disabled the backing map manages the transient version cache only for operations for which no other party is aware (such as entry expiry). This is used when there is already a transient version cache of the same name being maintained at a higher level, for instance within a versioned-near-scheme. Legal values are true or false. Default value is false. |