Persisting entries to a CacheStore, either when they are evicted as an overflow,
or all the time, to maintain persistent copies that would withstand server failure or restarts.

For convenience, Cache extends ConcurrentMap and implements all methods accordingly, although methods like
Map.keySet(), Map.values() and Map.entrySet() are expensive
(prohibitively so when using a distributed cache) and frequent use of these methods is not recommended.

Other methods such as Map.size() provide an approximation-only, and should not be relied on for an accurate picture
as to the size of the entire, distributed cache. Remote nodes are not queried and in-fly transactions are not
taken into account, even if Map.size() is invoked from within such a transaction.

Also, like many ConcurrentMap implementations, Cache does not support the use of null keys or
values.

Unsupported operations

Asynchronous operations

Cache also supports the use of "async" remote operations. Note that these methods
only really make sense if you are using a clustered cache. I.e., when used in LOCAL mode, these "async" operations
offer no benefit whatsoever. These methods, such as putAsync(Object, Object) offer the best of both worlds
between a fully synchronous and a fully asynchronous cache in that a NotifyingFuture is returned. The
NotifyingFuture can then be ignored or thrown away for typical asynchronous behaviour, or queried for
synchronous behaviour, which would block until any remote calls complete. Note that all remote calls are, as far as
the transport is concerned, synchronous. This allows you the guarantees that remote calls succeed, while not
blocking your application thread unnecessarily. For example, usage such as the following could benefit from the
async operations:

The net result is behavior similar to synchronous RPC calls in that at the end, you have guarantees that all calls
completed successfully, but you have the added benefit that the three calls could happen in parallel. This is
especially advantageous if the cache uses distribution and the three keys map to different cache instances in the
cluster.

Also, the use of async operations when within a transaction return your local value only, as expected. A
NotifyingFuture is still returned though for API consistency.

Constructing a Cache

An instance of the Cache is usually obtained by using a CacheContainer.

0ms lock timeout to prevent any blocking here either. If the lock is not acquired, this method is a
no-op, and swallows the timeout exception.

Ongoing transactions are suspended before this call, so
failures here will not affect any ongoing transactions.

Errors and exceptions are 'silent' - logged at a
much lower level than normal, and this method does not throw exceptions

This method is for caching data
that has an external representation in storage, where, concurrent modification and transactions are not a
consideration, and failure to put the data in the cache should be treated as a 'suboptimal outcome' rather than a
'failing outcome'.

An example of when this method is useful is when data is read from, for example, a legacy datastore, and is cached
before returning the data to the caller. Subsequent calls would prefer to get the data from the cache and if the
data doesn't exist in the cache, fetch again from the legacy datastore.

evict

Evicts an entry from the memory of the cache. Note that the entry is not removed from any configured cache
stores or any other caches in the cluster (if used in a clustered mode). Use Map.remove(Object) to remove an
entry from the entire cache system.

This method is designed to evict an entry from memory to free up memory used by the application. This method uses
a 0 lock acquisition timeout so it does not block in attempting to acquire locks. It behaves as a no-op if the
lock on the entry cannot be acquired immediately.

Important: this method should not be called from within a transaction scope.

getAsync

Asynchronous version of Map.get(Object) that allows user code to
retrieve the value associated with a key at a later stage, hence allowing
multiple parallel get requests to be sent. Normally, when this method
detects that the value is likely to be retrieved from from a remote
entity, it will span a different thread in order to allow the
asynchronous get call to return immediately. If the call will definitely
resolve locally, for example when the cache is configured with LOCAL mode
and no cache loaders are configured, the get asynchronous call will act
sequentially and will have no different to Map.get(Object).

Parameters:

key - key to retrieve

Returns:

a future that can be used to retrieve value associated with the
key when this is available. The actual value returned by the future
follows the same rules as Map.get(Object)

getAdvancedCache

compact

void compact()

Method that releases object references of cached objects held in the cache by serializing them to byte buffers.
Cached objects are lazily de-serialized when accessed again, based on the calling thread's context class loader.

This can be expensive, based on the effort required to serialize cached objects.

getStatus

keySet

Returns a set view of the keys contained in this cache. This set is immutable, so it cannot be modified
and changes to the cache won't be reflected in the set. When this method is called on a cache configured with
distribution mode, the set returned only contains the keys locally available in the cache instance. To avoid
memory issues, there will be not attempt to bring keys from other nodes.

This method should only be used for debugging purposes such as to verify that the cache contains all the keys
entered. Any other use involving execution of this method on a production system is not recommended.

values

Returns a collection view of the values contained in this cache. This collection is immutable, so it cannot be modified
and changes to the cache won't be reflected in the set. When this method is called on a cache configured with
distribution mode, the collection returned only contains the values locally available in the cache instance. To avoid
memory issues, there is not attempt to bring values from other nodes.

This method should only be used for testing or debugging purposes such as to verify that the cache contains all the
values entered. Any other use involving execution of this method on a production system is not recommended.

entrySet

Returns a set view of the mappings contained in this cache. This set is immutable, so it cannot be modified
and changes to the cache won't be reflected in the set. Besides, each element in the returned set is an immutable
Map.Entry. When this method is called on a cache configured with distribution mode, the set returned only
contains the mappings locally available in the cache instance. To avoid memory issues, there will be not attempt
to bring mappings from other nodes.

This method should only be used for debugging purposes such as to verify that the cache contains all the mappings
entered. Any other use involving execution of this method on a production system is not recommended.