paged-external-scheme

`paged-external-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

As with external-schemes, paged-external-schemes define caches which are not JVM heap based, allowing for greater storage capacity. The paged-external-scheme optimizes LRU eviction by using a paging approach. See the Serialization Paged Cache overview for a detailed description of the paged cache functionality.

Implementation

This scheme is implemented by the com.tangosol.net.cache.SerializationPagedCache class.

Paging

Cache entries are maintained over a series of pages, where each page is a separate com.tangosol.io.BinaryStore, obtained from the configured storage manager. When a page is created it is considered to be the "current" page, and all write operations are performed against this page. On a configurable interval the current page is closed and a new current page is created. Read operations for a given key are performed against the last page in which the key was stored. When the number of pages exceeds a configured maximum, the oldest page is destroyed and those items which were not updated since the page was closed are be evicted. For example configuring a cache with a duration of ten minutes per page, and a maximum of six pages, will result in entries being cached for at most an hour.

Paging improves performance by avoiding individual delete operations against the storage manager as cache entries are removed or evicted. Instead the cache simply releases its references to those entries, and relies on the eventual destruction of an entire page to free the associated storage of all page entries in a single stroke.

Pluggable Storage Manager

External schemes use a pluggable store manager to create and destroy pages, as well as to access entries within those pages. Supported store-managers include:

async-store-manager - a wrapper providing asynchronous write capabilities for of other store-manager implementations
custom-store-manager - allows definition of custom implementations of store-managers
bdb-store-manager - uses Berkeley Database JE to implement an on-disk cache
lh-file-manager - uses a Tangosol LH on-disk database cache
nio-file-manager - uses NIO to implement memory-mapped file based cache
nio-memory-manager - uses NIO to implement an off JVM heap, in-memory cache

Persistence (long-term storage)

Paged external caches are used for temporary storage of large data sets, for example as the back-tier of an overflow-scheme. These caches are not usable as for long-term storage (persistence), and will not survive beyond the life of the JVM. Clustered persistence should be configured via a read-write-backing-map-scheme on a distributed-scheme. If a non-clustered persistent cache is what is needed, refer to the external-scheme.

Elements

The following table describes the elements you can define within the paged-external-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 external paged cache. Any custom implementation must extend the `com.tangosol.net.cache.SerializationPagedCache` class and declare the exact same set of public constructors.
`<init-params>`	Optional	Specifies initialization parameters, for use in custom external paged 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 occurring on the cache.
`<page-limit>`	Required	Specifies the maximum number of active pages for the paged cache. Legal values are positive integers between `2` and `3600`.
`<page-duration>`	Optional	Specifies the length of time, in seconds, that a page in the paged cache is current. 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. Legal values are between `5` and `604800` seconds (one week) and `zero` (no expiry). Default value is `zero`
`<async-store-manager>`	Optional	Configures the paged external cache to use an asynchronous storage manager wrapper for any other storage manager.
`<custom-store-manager>`	Optional	Configures the paged external cache to use a custom storage manager implementation.
`<bdb-store-manager>`	Optional	Configures the paged external cache to use Berkeley Database JE on-disk databases for cache storage.
`<lh-file-manager>`	Optional	Configures the paged external cache to use a Tangosol LH on-disk database for cache storage.
`<nio-file-manager>`	Optional	Configures the paged external cache to use a memory-mapped file for cache storage.
`<nio-memory-manager>`	Optional	Configures the paged external cache to use an off JVM heap, memory region for cache storage.