h2.{{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]}}
h3.Description
External schemes define caches which are not JVM heap based, allowing for greater storage capacity. See the [local cache samples|Sample Cache Configurations#Local caches] for examples of various external cache configurations.
h4.Implementation
This scheme is implemented by:
* {javadoc:com.tangosol.net.cache.SerializationMap} - for unlimited size caches
* {javadoc:com.tangosol.net.cache.SerializationCache} - for size limited caches
The implementation type is chosen based on the following rule:
* if the {{[#high-units]}} element is specified and not zero then {{SerializationCache}} is used;
* otherwise {{SerializationMap}} is used.
h4.Pluggable Storage Manager {anchor:Pluggable Storage Manager}
External schemes use a pluggable store manager to store and retrieve binary key value pairs. 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 Coherence 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
h4.Size Limited Cache
The cache may be configured as size-limited, which means that once it reaches its maximum [allowable size|#high-units] it prunes itself.
{note}Eviction against disk based caches can be expensive, consider using a {{[paged-external-scheme]}} for such cases.{note}
h4. Entry Expiration
External schemes support automatic expiration of entries based on the age of the value, as configured by the {{[#expiry-delay]}}.
h4.Persistence (long-term storage) {anchor:Persistence}
External caches are generally used for temporary storage of large data sets, for example as the back-tier of an {{[overflow-scheme]}}. Certain implementations do however support persistence for non-clustered caches, see the {{[bdb-store-manager|bdb-store-manager#store-name]}} and {{[lh-file-manager|lh-file-manager#file-name]}} for details. Clustered persistence should be configured via a {{[read-write-backing-map-scheme]}} on a {{[distributed-scheme]}}.
h3.Elements
The following table describes the elements you can define within the {{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|caching-schemes#Scheme Inheritance] from.|
|{{<class-name>}}|Optional|{anchor:class-name}Specifies a custom implementation of the external cache.
\\ \\
Any custom implementation must extend one of the following classes:\\
\\
{panel}
* {javadoc:com.tangosol.net.cache.SerializationCache} - for size limited caches
* {javadoc:com.tangosol.net.cache.SerializationMap} - for unlimited size caches
* {javadoc:com.tangosol.net.cache.SimpleSerializationMap} - for unlimited size caches
{panel}
and declare the exact same set of public constructors as the superclass.|
|{{<init-params>}}|Optional|Specifies initialization parameters, for use in custom external cache implementations which implement the {javadoc:com.tangosol.run.xml.XmlConfigurable} (or {doxygen:coherence::run::xml::XmlConfigurable} for C+\+) interface.|
|{{<[listener]>}}|Optional|Specifies an implementation of a {javadoc:com.tangosol.util.MapListener} (or {doxygen:coherence::util::MapListener} for C+\+) which will be notified of events occurring on the cache.|
|{{<high-units>}}|Optional|{anchor:high-units}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. Once this limit is exceeded, the cache will begin the pruning process, evicting the least recently used entries until the number of units is brought below this limit. The scheme's {{[#class-name]}} element may be used to provide custom extensions to {{SerializationCache}}, which implement alternative eviction policies.
\\ \\
Legal values are positive integers or {{zero}}. Zero implies no limit.
\\ \\
Default value is {{zero}}.|
| {{<unit-calculator>}} | Optional | {anchor:unit-calculator}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: \\
\\
...