Cache (client 2.0.11 API)

java.lang.Object
- com.scaleout.client.caching.Cache<K,V>

Type Parameters:

K - the key type. Must be int, string, byte[], UUID or provide a custom KeyEncoder for the K type.

V - the value type. V must be serializable or a custom CacheSerializer/CacheDeserializer must be provided to the CacheBuilder.

All Implemented Interfaces:

ServiceEventHandler<K,V>
```
public abstract class Cache<K,V>
extends java.lang.Object
implements ServiceEventHandler<K,V>
```
The Cache class is used to make caching requests to a ScaleOut in-memory data grid.

Cache's are instantiated with the CacheBuilder.

Cache's are logically separated based on the String name provided to the CacheBuilder.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`abstract CacheResponse<K,V>`	`add(K key, V value)` Add an object to the ScaleOut cache.
`abstract CacheResponse<K,V>`	`add(K key, V value, CreatePolicy policy)` Add an object to the ScaleOut cache with a parameter `CreatePolicy`.
`abstract CacheResponse<K,V>`	`add(K key, V value, CreatePolicy policy, java.util.List<K> parentKeys)` Add an object to the ScaleOut cache with a parameter `CreatePolicy`.
`abstract CacheResponse<K,V>`	`add(K key, V value, java.util.List<K> parentKeys)` Add an object to the ScaleOut cache.
`abstract CacheResponse<K,V>`	`addAndLock(K key, V value)` Add an object to the ScaleOut cache with an exclusive lock.
`abstract CacheResponse<K,V>`	`addAndLock(K key, V value, CreatePolicy policy)` Add an object to the ScaleOut cache with an exclusive lock and a parameter `CreatePolicy`.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`addAndLockAsync(K key, V value)` Asynchronously add an object to the ScaleOut cache with an exclusive lock.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`addAndLockAsync(K key, V value, CreatePolicy policy)` Asynchronously add an object to the ScaleOut cache with an exclusive lock and a parameter `CreatePolicy`.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`addAsync(K key, V value)` Asynchronously add an object to the ScaleOut cache.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`addAsync(K key, V value, CreatePolicy policy)` Asynchronously add an object to the ScaleOut cache with a parameter `CreatePolicy`.
`abstract CacheResponse<K,V>`	`addOrUpdate(K key, V value)` Add or update an object to/in the ScaleOut cache.
`abstract CacheResponse<K,V>`	`addOrUpdate(K key, V value, CreatePolicy policy)` Add or update an object to/in the ScaleOut cache with a custom `CreatePolicy`.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`addOrUpdateAsync(K key, V value)` Asynchronously add or update an object to or in the ScaleOut cache.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`addOrUpdateAsync(K key, V value, CreatePolicy policy)` Asynchronously add or update an object to/in the ScaleOut cache with a custom `CreatePolicy`.
`abstract CacheDeserializer<V>`	`cacheValueDeserializer()`
`abstract CacheSerializer<V>`	`cacheValueSerializer()`
`abstract CacheResponse<K,V>`	`clear()` Clear all objects from the ScaleOut cache.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`clearAsync()` Asynchronously clear all objects from the ScaleOut cache.
`abstract CreatePolicy`	`createPolicy()` Retrieve the default `CreatePolicy` used by this `Cache`.
`abstract CacheResponse<K,CachedObjectMetadata<K>>`	`getMetadata(K key)` Retrieves `CachedObjectMetadata` for an object stored in the cache.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,CachedObjectMetadata<K>>>`	`getMetadataAsync(K key)` Retrieves `CachedObjectMetadata` for an object stored in the cache.
`abstract InvokeResponse`	`invoke(java.lang.String invokeOperation, byte[] serializedParamObject, java.time.Duration timeout)` Invoke a parallel operation on this cache.
`abstract InvokeResponse`	`invoke(java.lang.String invokeOperation, java.time.Duration timeout)` Invoke a parallel operation on this cache.
`abstract InvokeResponse`	`invoke(java.lang.String invokeOperation, java.lang.String igName, byte[] serializedParamObject, java.time.Duration timeout)` Invoke a parallel operation on this cache.
`abstract InvokeResponse`	`invoke(java.lang.String invokeOperation, java.lang.String igName, java.time.Duration timeout)` Invoke a parallel operation on this cache.
`abstract CacheResponse<K,V>`	`lock(K key)` Lock an object within the ScaleOut cache for exclusive access.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`lockAsync(K key)` Asynchronously lock an object within the ScaleOut cache for exclusive access.
`abstract InvokeResponse`	`postEvent(K key, java.lang.String eventInfo, byte[] payload, java.time.Duration timeout)` Post an event to a key.
`abstract InvokeResponse`	`postEvent(K key, java.lang.String invocationGrid, java.lang.String eventInfo, byte[] payload, java.time.Duration timeout)` Post an event to a key.
`abstract <C extends V> java.lang.Iterable<K>`	`queryKeys(Filter filter, java.lang.Class<C> clazz)` Query the objects in this `Cache` with the parameter filter returning an iterable of `K` keys.
`abstract int`	`queryObjectCount()` Perform a distributed query to retrieve a count of all objects in the cache.
`abstract <C extends V> java.lang.Iterable<V>`	`queryObjects(Filter filter, java.lang.Class<C> clazz)` Query the objects in this `Cache` with the parameter filter.
`abstract CacheResponse<K,V>`	`read(K key)` Read an object from the ScaleOut cache.
`abstract CacheResponse<K,V>`	`read(K key, ReadPolicy policy)` Read a locked object from the ScaleOut cache.
`abstract CacheResponse<K,V>`	`readAndLock(K key)` Read an object from the ScaleOut cache and acquire an exclusive lock for that object.
`abstract CacheResponse<K,V>`	`readAndLock(K key, ReadPolicy policy)` Read an object from the ScaleOut cache and acquire an exclusive lock for that object using a custom read policy.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`readAndLockAsync(K key)` Asynchronously read an object from the ScaleOut cache and acquire an exclusive lock for that object.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`readAndLockAsync(K key, ReadPolicy policy)` Asynchronously read an object from the ScaleOut cache and acquire an exclusive lock for that object using a custom read policy.
`abstract CacheResponse<K,V>`	`readAndLockOrAdd(K key, ValueFactory<K,V> factory, ReadPolicy policy)` Read and lock an object from the ScaleOut cache.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`readAndLockOrAddAsync(K key, ValueFactory<K,V> factory, ReadPolicy policy)` Read an object from the ScaleOut cache.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`readAsync(K key)` Asynchronously read an object from the ScaleOut cache.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`readAsync(K key, ReadPolicy policy)` Asynchronously read a locked object from the ScaleOut cache.
`abstract CacheResponse<K,V>`	`readLocked(K key, LockToken lockToken)` Read a locked object from the ScaleOut cache.
`abstract CacheResponse<K,V>`	`readLocked(K key, LockToken lockToken, ReadPolicy policy)` Read a locked object from the ScaleOut cache with a custom read policy.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`readLockedAsync(K key, LockToken lockToken)` Asynchronously read a locked object from the ScaleOut cache.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`readLockedAsync(K key, LockToken lockToken, ReadPolicy policy)` Asynchronously read a locked object from the ScaleOut cache with a custom read policy.
`abstract CacheResponse<K,V>`	`readOrAdd(K key, ValueFactory<K,V> factory, ReadPolicy policy)` Read an object from the ScaleOut cache.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`readOrAddAsync(K key, ValueFactory<K,V> factory, ReadPolicy policy)` Read an object from the ScaleOut cache.
`abstract CacheResponse<K,V>`	`refreshLock(K key, LockToken lockToken)` Refresh a lock on an object within the ScaleOut cache.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`refreshLockAsync(K key, LockToken lockToken)` Asynchronously refresh a lock on an object within the ScaleOut cache.
`abstract CacheResponse<K,V>`	`remove(K key)` Remove an object from the ScaleOut cache.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`removeAsync(K key)` Asynchronously remove an object from the ScaleOut cache.
`abstract CacheResponse<K,V>`	`removeLocked(K key, LockToken lockToken)` Remove a locked object from the ScaleOut cache.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`removeLockedAsync(K key, LockToken lockToken)` Asynchronously remove a locked object from the ScaleOut cache.
`abstract CacheResponse<K,V>`	`removeOptimistic(K key, VersionToken versionToken)` Remove an optimistically locked object from the ScaleOut cache.
`abstract java.lang.Iterable<K>`	`retrieveAllKeys()` Retrieve all of the keys in the Cache.
`abstract InvokeResponse`	`singleInvoke(K key, java.lang.String invokeOperation, byte[] serializedParamObject, java.time.Duration timeout)` Invoke a method on a single object in this cache.
`abstract InvokeResponse`	`singleInvoke(K key, java.lang.String invokeOperation, java.time.Duration timeout)` Invoke a method on a single object in this cache.
`abstract InvokeResponse`	`singleInvoke(K key, java.lang.String invokeOperation, java.lang.String igName, byte[] serializedParamObject, java.time.Duration timeout)` Invoke a method on a single object in this cache.
`abstract InvokeResponse`	`singleInvoke(K key, java.lang.String invokeOperation, java.lang.String igName, java.time.Duration timeout)` Invoke a method on a single object in this cache.
`abstract CacheResponse<K,V>`	`unlock(K key, LockToken lockToken)` Unlock a locked object within the ScaleOut cache.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`unlockAsync(K key, LockToken lockToken)` Asynchronously unlock a locked object within the ScaleOut cache.
`abstract CacheResponse<K,V>`	`update(K key, V value)` Update an object in the ScaleOut cache.
`abstract CacheResponse<K,V>`	`update(K key, V value, CreatePolicy policy)` Update an object in the ScaleOut cache.
`abstract CacheResponse<K,V>`	`updateAndRetainLock(K key, V value, LockToken lockToken)` Update a locked object in the ScaleOut cache and retain exclusive access to the object through a lock.
`abstract CacheResponse<K,V>`	`updateAndRetainLock(K key, V value, LockToken lockToken, CreatePolicy policy)` Update a locked object in the ScaleOut cache and retain exclusive access to the object through a lock.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`updateAndRetainLockAsync(K key, V value, LockToken lockToken)` Asynchronously update a locked object in the ScaleOut cache and retain exclusive access to the object through a lock.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`updateAndRetainLockAsync(K key, V value, LockToken lockToken, CreatePolicy policy)` Asynchronously update a locked object in the ScaleOut cache and retain exclusive access to the object through a lock.
`abstract CacheResponse<K,V>`	`updateAndUnlock(K key, V value, LockToken lockToken)` Update a locked object in the ScaleOut cache and unlock the object.
`abstract CacheResponse<K,V>`	`updateAndUnlock(K key, V value, LockToken lockToken, CreatePolicy policy)` Update a locked object in the ScaleOut cache and unlock the object.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`updateAndUnlockAsync(K key, V value, LockToken lockToken)` Asynchronously update a locked object in the ScaleOut cache and unlock the object.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`updateAndUnlockAsync(K key, V value, LockToken lockToken, CreatePolicy policy)` Asynchronously update a locked object in the ScaleOut cache and release exclusive access to the object.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`updateAsync(K key, V value)` Asynchronously update an object in the ScaleOut cache.
`abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>>`	`updateAsync(K key, V value, CreatePolicy policy)` Asynchronously update an object in the ScaleOut cache.
`abstract CacheResponse<K,V>`	`updateOptimistic(K key, V value, VersionToken token)` Update an object in the ScaleOut cache.
`abstract CacheResponse<K,V>`	`updateOptimistic(K key, V value, VersionToken token, CreatePolicy policy)` Update an object in the ScaleOut cache.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.scaleout.client.caching.ServiceEventHandler
enableAsyncReadThrough, enableAsyncWriteThrough, enableReadThrough, getAppId, getGridConnection, getKeyEncoder

- Method Detail
  - add
```
public abstract CacheResponse<K,V> add(K key,
                                       V value)
                                throws CacheException
```
    Add an object to the ScaleOut cache.
    
    The object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAdded.
    
    The object must not exist when calling add. If the object may already exists and the client should update the object, use addOrUpdate(Object, Object).
    
    If the object already exists, or is added by another client (or thread), the CacheResponse.getStatus() will return RequestStatus.ObjectExists.
    
    The CreatePolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key or value are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to add to the ScaleOut cache.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - add
```
public abstract CacheResponse<K,V> add(K key,
                                       V value,
                                       java.util.List<K> parentKeys)
                                throws CacheException
```
    Add an object to the ScaleOut cache.
    
    The object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAdded.
    
    The object must not exist when calling add. If the object may already exists and the client should update the object, use addOrUpdate(Object, Object).
    
    If the object already exists, or is added by another client (or thread), the CacheResponse.getStatus() will return RequestStatus.ObjectExists.
    
    The CreatePolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key or value are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to add to the ScaleOut cache.
    
    parentKeys - the parent keys of which this object should be a child.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - addAndLock
```
public abstract CacheResponse<K,V> addAndLock(K key,
                                              V value)
                                       throws CacheException
```
    Add an object to the ScaleOut cache with an exclusive lock.
    
    The object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAddedAndLocked and the CacheResponse.getLockToken() will have a value.
    
    The object must not exist when calling addExclusive.
    
    If the object already exists, or is added by another client (or thread), the CacheResponse.getStatus() will return RequestStatus.ObjectExists.
    
    The CreatePolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key or value are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to add to the ScaleOut cache.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - addOrUpdate
```
public abstract CacheResponse<K,V> addOrUpdate(K key,
                                               V value)
                                        throws CacheException
```
    Add or update an object to/in the ScaleOut cache.
    
    The object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAdded and the object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdated.
    
    The CreatePolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key or value are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to add to the ScaleOut cache.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - update
```
public abstract CacheResponse<K,V> update(K key,
                                          V value)
                                   throws CacheException
```
    Update an object in the ScaleOut cache.
    
    The object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdated.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    Supplying a null value will remove the object from the ScaleOut cache.
    
    The CreatePolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to update in the ScaleOut cache. Provide null if the object should be removed.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - updateAndRetainLock
```
public abstract CacheResponse<K,V> updateAndRetainLock(K key,
                                                       V value,
                                                       LockToken lockToken)
                                                throws CacheException
```
    Update a locked object in the ScaleOut cache and retain exclusive access to the object through a lock.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    The object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdatedAndLockRetained.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    Supplying a null value will remove the object from the ScaleOut cache. Note, the remove attempt will not bypass the lock. This means the lock token must be the appropriate lock in order to successfully remove the object.
    
    The CreatePolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, or the lock token has no value.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to update in the ScaleOut cache. Provide null if the object should be removed.
    
    lockToken - the LockToken to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - updateAndUnlock
```
public abstract CacheResponse<K,V> updateAndUnlock(K key,
                                                   V value,
                                                   LockToken lockToken)
                                            throws CacheException
```
    Update a locked object in the ScaleOut cache and unlock the object.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    The object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdatedAndUnlocked.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    Supplying a null value will remove the object from the ScaleOut cache. Note, the remove attempt will not bypass the lock. This means the lock token must be the appropriate lock in order to successfully remove the object.
    
    The CreatePolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, or the lock token has no value.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to update in the ScaleOut cache. Provide null if the object should be removed.
    
    lockToken - the LockToken to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - add
```
public abstract CacheResponse<K,V> add(K key,
                                       V value,
                                       CreatePolicy policy)
                                throws CacheException
```
    Add an object to the ScaleOut cache with a parameter CreatePolicy.
    
    Specify a custom CreatePolicy to adjust object metadata such as TimeoutType, GeoServerReadMode, and other properties.
    
    The object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAdded.
    
    The object must not exist when calling add. If the object may already exists and the client should update the object, use addOrUpdate(Object, Object).
    
    If the object already exists, or is added by another client (or thread), the CacheResponse.getStatus() will return RequestStatus.ObjectExists.
    
    IllegalArgumentException is thrown if the key or value are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to add to the ScaleOut cache.
    
    policy - the policy to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - add
```
public abstract CacheResponse<K,V> add(K key,
                                       V value,
                                       CreatePolicy policy,
                                       java.util.List<K> parentKeys)
                                throws CacheException
```
    Add an object to the ScaleOut cache with a parameter CreatePolicy.
    
    Specify a custom CreatePolicy to adjust object metadata such as TimeoutType, GeoServerReadMode, and other properties.
    
    The object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAdded.
    
    The object must not exist when calling add. If the object may already exists and the client should update the object, use addOrUpdate(Object, Object).
    
    If the object already exists, or is added by another client (or thread), the CacheResponse.getStatus() will return RequestStatus.ObjectExists.
    
    IllegalArgumentException is thrown if the key or value are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to add to the ScaleOut cache.
    
    policy - the policy to use.
    
    parentKeys - the parent keys to which this object should be a dependant.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - addAndLock
```
public abstract CacheResponse<K,V> addAndLock(K key,
                                              V value,
                                              CreatePolicy policy)
                                       throws CacheException
```
    Add an object to the ScaleOut cache with an exclusive lock and a parameter CreatePolicy.
    
    Specify a custom CreatePolicy to adjust object metadata such as TimeoutType, GeoServerReadMode, and other properties.
    
    The object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAddedAndLocked and the CacheResponse.getLockToken() will have a value.
    
    The object must not exist when calling addExclusive.
    
    If the object already exists, or is added by another client (or thread), the CacheResponse.getStatus() will return RequestStatus.ObjectExists.
    
    IllegalArgumentException is thrown if the key, value, or create policy are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to add to the ScaleOut cache.
    
    policy - the policy to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - addOrUpdate
```
public abstract CacheResponse<K,V> addOrUpdate(K key,
                                               V value,
                                               CreatePolicy policy)
                                        throws CacheException
```
    Add or update an object to/in the ScaleOut cache with a custom CreatePolicy.
    
    Specify a custom CreatePolicy to adjust object metadata such as TimeoutType, GeoServerReadMode, and other properties.
    
    The object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAdded and the object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdated.
    
    IllegalArgumentException is thrown if the key or value are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to add to the ScaleOut cache.
    
    policy - the policy to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - update
```
public abstract CacheResponse<K,V> update(K key,
                                          V value,
                                          CreatePolicy policy)
                                   throws CacheException
```
    Update an object in the ScaleOut cache.
    
    Specify a custom CreatePolicy to adjust object metadata such as TimeoutType, GeoServerReadMode, and other properties.
    
    The object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdated.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    Supplying a null value will remove the object from the ScaleOut cache.
    
    IllegalArgumentException is thrown if the key or create policy are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to update in the ScaleOut cache. Provide null if the object should be removed.
    
    policy - the policy to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - updateOptimistic
```
public abstract CacheResponse<K,V> updateOptimistic(K key,
                                                    V value,
                                                    VersionToken token)
                                             throws CacheException
```
    Update an object in the ScaleOut cache.
    
    If the version token supplied matches the version of the object stored in the cache then the object will be updated. Otherwise the operation will return RequestStatus.ObjectVersionMismatch.
    
    The object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdated.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to update in the ScaleOut cache. Provide null if the object should be removed.
    
    token - the VersionToken to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - updateOptimistic
```
public abstract CacheResponse<K,V> updateOptimistic(K key,
                                                    V value,
                                                    VersionToken token,
                                                    CreatePolicy policy)
                                             throws CacheException
```
    Update an object in the ScaleOut cache.
    
    If the version token supplied matches the version of the object stored in the cache then the object will be updated. Otherwise the operation will return RequestStatus.ObjectVersionMismatch.
    
    Specify a custom CreatePolicy to adjust object metadata such as TimeoutType, GeoServerReadMode, and other properties.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to update in the ScaleOut cache. Provide null if the object should be removed.
    
    token - the VersionToken to use.
    
    policy - the policy to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - postEvent
```
public abstract InvokeResponse postEvent(K key,
                                         java.lang.String eventInfo,
                                         byte[] payload,
                                         java.time.Duration timeout)
                                  throws CacheException
```
    Post an event to a key. The object may not exist.
    
    The event will be handled through a PostedEventHandler registered through ServiceEvents.setPostedEventHandler(Cache, PostedEventHandler).
    
    The event info can be used to specify the type of event.
    
    The byte[] payload can be used to pass any binary information to the event handler.
    
    The timeout dictates the maximum duration of the request before the operation will timeout.
    
    Parameters:
    
    key - the key to post the event to.
    
    eventInfo - the event info.
    
    payload - the binary payload.
    
    timeout - maximum allowed time for the operation to complete before RequestStatus.Timeout
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - postEvent
```
public abstract InvokeResponse postEvent(K key,
                                         java.lang.String invocationGrid,
                                         java.lang.String eventInfo,
                                         byte[] payload,
                                         java.time.Duration timeout)
                                  throws CacheException
```
    Post an event to a key. The object may not exist.
    
    The event will be handled through a PostedEventHandler registered through ServiceEvents.setPostedEventHandler(Cache, PostedEventHandler).
    
    The event info can be used to specify the type of event.
    
    The byte[] payload can be used to pass any binary information to the event handler.
    
    The timeout dictates the maximum duration of the request before the operation will timeout.
    
    Parameters:
    
    key - the key to post the event to.
    
    invocationGrid - the invocation grid to post the event to.
    
    eventInfo - the event info.
    
    payload - the binary payload.
    
    timeout - maximum allowed time for the operation to complete before RequestStatus.Timeout
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - updateAndRetainLock
```
public abstract CacheResponse<K,V> updateAndRetainLock(K key,
                                                       V value,
                                                       LockToken lockToken,
                                                       CreatePolicy policy)
                                                throws CacheException
```
    Update a locked object in the ScaleOut cache and retain exclusive access to the object through a lock.
    
    Specify a custom CreatePolicy to adjust object metadata such as TimeoutType, GeoServerReadMode, and other properties.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    The object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdatedAndLockRetained.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    Supplying a null value will remove the object from the ScaleOut cache. Note, the remove attempt will not bypass the lock. This means the lock token must be the appropriate lock in order to successfully remove the object.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, the lock token has no value, or the create policy is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to update in the ScaleOut cache. Provide null if the object should be removed.
    
    lockToken - the LockToken to use.
    
    policy - the policy to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - updateAndUnlock
```
public abstract CacheResponse<K,V> updateAndUnlock(K key,
                                                   V value,
                                                   LockToken lockToken,
                                                   CreatePolicy policy)
                                            throws CacheException
```
    Update a locked object in the ScaleOut cache and unlock the object.
    
    Specify a custom CreatePolicy to adjust object metadata such as TimeoutType, GeoServerReadMode, and other properties.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    The object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdatedAndUnlocked.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    Supplying a null value will remove the object from the ScaleOut cache. Note, the remove attempt will not bypass the lock. This means the lock token must be the appropriate lock in order to successfully remove the object.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, the lock token has no value, or the create policy is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to update in the ScaleOut cache. Null if the object should be removed.
    
    lockToken - the LockToken to use.
    
    policy - the policy to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - read
```
public abstract CacheResponse<K,V> read(K key)
                                 throws CacheException
```
    Read an object from the ScaleOut cache.
    
    The object is successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrieved.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    The ReadPolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - readAndLock
```
public abstract CacheResponse<K,V> readAndLock(K key)
                                        throws CacheException
```
    Read an object from the ScaleOut cache and acquire an exclusive lock for that object.
    
    The object is successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrievedAndLocked.
    
    The LockToken is retrieved from the CacheResponse.getLockToken()
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    The object was locked by another client/thread in the ScaleOut cache if CacheResponse.getStatus() returns RequestStatus.ObjectAlreadyLocked.
    
    The ReadPolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - readLocked
```
public abstract CacheResponse<K,V> readLocked(K key,
                                              LockToken lockToken)
                                       throws CacheException
```
    Read a locked object from the ScaleOut cache.
    
    The object is successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrievedAndLocked.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    The refreshed LockToken is retrieved from the CacheResponse.getLockToken()
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    The object was locked by another client/thread in the ScaleOut cache if CacheResponse.getStatus() returns RequestStatus.LockLostError.
    
    The ReadPolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, or the lock token has no value.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    lockToken - the LockToken to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - read
```
public abstract CacheResponse<K,V> read(K key,
                                        ReadPolicy policy)
                                 throws CacheException
```
    Read a locked object from the ScaleOut cache.
    
    Specify a custom ReadPolicy to adjust read properties.
    
    The object is successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrievedAndLocked.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    IllegalArgumentException is thrown if the key is null or ReadPolicy is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    policy - the ReadPolicy to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - readAndLock
```
public abstract CacheResponse<K,V> readAndLock(K key,
                                               ReadPolicy policy)
                                        throws CacheException
```
    Read an object from the ScaleOut cache and acquire an exclusive lock for that object using a custom read policy.
    
    Specify a custom ReadPolicy to adjust read properties.
    
    The object is successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrievedAndLocked.
    
    The LockToken is retrieved from the CacheResponse.getLockToken()
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    The object was locked by another client/thread in the ScaleOut cache if CacheResponse.getStatus() returns RequestStatus.ObjectAlreadyLocked.
    
    IllegalArgumentException is thrown if the key is null or ReadPolicy is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    policy - the ReadPolicy to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - readOrAdd
```
public abstract CacheResponse<K,V> readOrAdd(K key,
                                             ValueFactory<K,V> factory,
                                             ReadPolicy policy)
                                      throws CacheException
```
    Read an object from the ScaleOut cache. If the object is not present, the parameter ValueFactory will be called and the value will be added. Once the value has been added, the newly added value will be returned.
    
    Specify a custom ReadPolicy to adjust read properties.
    
    The object is successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrieved and the object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAdded, or the object was not found by the ValueFactory when CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    IllegalArgumentException is thrown if the key, value factory, or read policy, are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    factory - the ValueFactory to use.
    
    policy - the ReadPolicy to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - readAndLockOrAdd
```
public abstract CacheResponse<K,V> readAndLockOrAdd(K key,
                                                    ValueFactory<K,V> factory,
                                                    ReadPolicy policy)
                                             throws CacheException
```
    Read and lock an object from the ScaleOut cache. If the object is not present, the parameter ValueFactory will be called and the value will be added. Once the value has been added, the newly added value will be returned.
    
    Specify a custom ReadPolicy to adjust read properties.
    
    The object was successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrievedAndLocked, the object was successfully added when CacheResponse.getStatus() return RequestStatus.ObjectAdded, the object was not found by the ValueFactory when CacheResponse.getStatus() returns RequestStatus.ObjectNotFound, or the object is already locked by another caller and CacheResponse.getStatus() returns RequestStatus.ObjectAlreadyLocked.
    
    IllegalArgumentException is thrown if the key, value factory, or read policy, are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    factory - the ValueFactory to use.
    
    policy - the ReadPolicy to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - readLocked
```
public abstract CacheResponse<K,V> readLocked(K key,
                                              LockToken lockToken,
                                              ReadPolicy policy)
                                       throws CacheException
```
    Read a locked object from the ScaleOut cache with a custom read policy.
    
    Specify a custom ReadPolicy to adjust read properties.
    
    The object is successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrievedAndLocked.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    s
    The refreshed LockToken is retrieved from the CacheResponse.getLockToken()
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    The object was locked by another client/thread in the ScaleOut cache if CacheResponse.getStatus() returns RequestStatus.LockLostError.
    IllegalArgumentException is thrown if the key is null, the lock token is null, the lock token has no value, or the ReadPolicy is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    lockToken - the LockToken to use.
    
    policy - the ReadPolicy to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - remove
```
public abstract CacheResponse<K,V> remove(K key)
                                   throws CacheException
```
    Remove an object from the ScaleOut cache.
    
    The object is successfully removed when CacheResponse.getStatus() returns RequestStatus.ObjectRemoved.
    
    IllegalArgumentException is thrown if the key is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - removeLocked
```
public abstract CacheResponse<K,V> removeLocked(K key,
                                                LockToken lockToken)
                                         throws CacheException
```
    Remove a locked object from the ScaleOut cache.
    
    The object is successfully removed when CacheResponse.getStatus() returns RequestStatus.ObjectRemoved.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    The object was locked by another client/thread in the ScaleOut cache if CacheResponse.getStatus() returns RequestStatus.ObjectLocked.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, or the lock token has no value.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    lockToken - the LockToken to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - removeOptimistic
```
public abstract CacheResponse<K,V> removeOptimistic(K key,
                                                    VersionToken versionToken)
                                             throws CacheException
```
    Remove an optimistically locked object from the ScaleOut cache.
    
    The object is successfully removed when CacheResponse.getStatus() returns RequestStatus.ObjectRemoved.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    versionToken - the VersionToken to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - lock
```
public abstract CacheResponse<K,V> lock(K key)
                                 throws CacheException
```
    Lock an object within the ScaleOut cache for exclusive access.
    
    The LockToken is retrieved from the CacheResponse.getLockToken()
    
    The object is successfully locked when CacheResponse.getStatus() returns RequestStatus.ObjectLocked.
    
    IllegalArgumentException is thrown if the key is null
    
    Parameters:
    
    key - the unique identifier for this object.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - refreshLock
```
public abstract CacheResponse<K,V> refreshLock(K key,
                                               LockToken lockToken)
                                        throws CacheException
```
    Refresh a lock on an object within the ScaleOut cache.
    
    The LockToken is retrieved from the CacheResponse.getLockToken()
    
    The lock is successfully refreshed when CacheResponse.getStatus() returns RequestStatus.ObjectLocked.
    
    The LockTimeout has expired when CacheResponse.getStatus() returns RequestStatus.LockLostError.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, or the lock token has no value.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    lockToken - the LockToken to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - unlock
```
public abstract CacheResponse<K,V> unlock(K key,
                                          LockToken lockToken)
                                   throws CacheException
```
    Unlock a locked object within the ScaleOut cache.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    The object is successfully unlocked when CacheResponse.getStatus() returns RequestStatus.ObjectUnlocked.
    
    The LockTimeout has expired when CacheResponse.getStatus() returns RequestStatus.LockLostError.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, or the lock token has no value.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    lockToken - the LockToken to use.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - clear
```
public abstract CacheResponse<K,V> clear()
                                  throws CacheException
```
    Clear all objects from the ScaleOut cache.
    
    The cache is successfully cleared when CacheResponse.getStatus() returns RequestStatus.CacheCleared.
    
    Returns:
    
    a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - queryObjects
```
public abstract <C extends V> java.lang.Iterable<V> queryObjects(Filter filter,
                                                                 java.lang.Class<C> clazz)
                                                          throws CacheException
```
    Query the objects in this Cache with the parameter filter.
    
    Filters are constructed using the FilterFactory
    
    Type Parameters:
    
    C - the value type.
    
    Parameters:
    
    filter - the filter.
    
    clazz - the class type.
    
    Returns:
    
    an iterable of 0 to many objects of type V.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - queryKeys
```
public abstract <C extends V> java.lang.Iterable<K> queryKeys(Filter filter,
                                                              java.lang.Class<C> clazz)
                                                       throws CacheException
```
    Query the objects in this Cache with the parameter filter returning an iterable of K keys.
    
    Filters are constructed using the FilterFactory
    
    Type Parameters:
    
    C - the value type.
    
    Parameters:
    
    filter - the filter.
    
    clazz - the class type.
    
    Returns:
    
    an iterable of 0 to many keys of type K.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - retrieveAllKeys
```
public abstract java.lang.Iterable<K> retrieveAllKeys()
                                               throws CacheException
```
    Retrieve all of the keys in the Cache.
    
    Returns:
    
    an iterable of 0 to many keys of type K.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - singleInvoke
```
public abstract InvokeResponse singleInvoke(K key,
                                            java.lang.String invokeOperation,
                                            java.time.Duration timeout)
                                     throws CacheException
```
    Invoke a method on a single object in this cache.
    
    Register for CacheEntryMethodInvocationHandler using ServiceEvents.setCacheEntryMethodInvocationHandler(Cache, String, CacheEntryMethodInvocationHandler), or ServiceEvents.setCacheEntryMethodInvocationHandler(Cache, String, CacheEntryMethodInvocationHandler, ParamHolder)
    
    The InvokeResponse is used to evaluate the result of the invoke operation.
    
    Exceptions can be handled for logging and tracking purposes during invoke runtime by enabling a ServiceEvents.setEventDeliveryExceptionHandler(Cache, EventDeliveryExceptionHandler).
    
    Parameters:
    
    key - the key to perform the invoke on.
    
    invokeOperation - the invoke operation.
    
    timeout - the invoke timeout.
    
    Returns:
    
    a InvokeResponse detailing the status of the operation.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - singleInvoke
```
public abstract InvokeResponse singleInvoke(K key,
                                            java.lang.String invokeOperation,
                                            java.lang.String igName,
                                            java.time.Duration timeout)
                                     throws CacheException
```
    Invoke a method on a single object in this cache.
    
    Register for CacheEntryMethodInvocationHandler using ServiceEvents.setCacheEntryMethodInvocationHandler(Cache, String, CacheEntryMethodInvocationHandler), or ServiceEvents.setCacheEntryMethodInvocationHandler(Cache, String, CacheEntryMethodInvocationHandler, ParamHolder)
    
    The InvokeResponse is used to evaluate the result of the invoke operation.
    
    Exceptions can be handled for logging and tracking purposes during invoke runtime by enabling a ServiceEvents.setEventDeliveryExceptionHandler(Cache, EventDeliveryExceptionHandler).
    
    Parameters:
    
    key - the key to perform the invoke on.
    
    invokeOperation - the invoke operation.
    
    igName - the invocation grid to perform this invoke.
    
    timeout - the invoke timeout.
    
    Returns:
    
    a InvokeResponse detailing the status of the operation.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - singleInvoke
```
public abstract InvokeResponse singleInvoke(K key,
                                            java.lang.String invokeOperation,
                                            byte[] serializedParamObject,
                                            java.time.Duration timeout)
                                     throws CacheException
```
    Invoke a method on a single object in this cache.
    
    Register for CacheEntryMethodInvocationHandler using ServiceEvents.setCacheEntryMethodInvocationHandler(Cache, String, CacheEntryMethodInvocationHandler), or ServiceEvents.setCacheEntryMethodInvocationHandler(Cache, String, CacheEntryMethodInvocationHandler, ParamHolder)
    
    The InvokeResponse is used to evaluate the result of the invoke operation.
    
    Exceptions can be handled for logging and tracking purposes during invoke runtime by enabling a ServiceEvents.setEventDeliveryExceptionHandler(Cache, EventDeliveryExceptionHandler).
    
    Parameters:
    
    key - the key to perform the invoke on.
    
    invokeOperation - the invoke operation.
    
    serializedParamObject - the serialized parameter object.
    
    timeout - the invoke timeout.
    
    Returns:
    
    a InvokeResponse detailing the status of the operation.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - singleInvoke
```
public abstract InvokeResponse singleInvoke(K key,
                                            java.lang.String invokeOperation,
                                            java.lang.String igName,
                                            byte[] serializedParamObject,
                                            java.time.Duration timeout)
                                     throws CacheException
```
    Invoke a method on a single object in this cache.
    
    Register for CacheEntryMethodInvocationHandler using ServiceEvents.setCacheEntryMethodInvocationHandler(Cache, String, CacheEntryMethodInvocationHandler), or ServiceEvents.setCacheEntryMethodInvocationHandler(Cache, String, CacheEntryMethodInvocationHandler, ParamHolder)
    
    The InvokeResponse is used to evaluate the result of the invoke operation.
    
    Exceptions can be handled for logging and tracking purposes during invoke runtime by enabling a ServiceEvents.setEventDeliveryExceptionHandler(Cache, EventDeliveryExceptionHandler).
    
    Parameters:
    
    key - the key to perform the invoke on.
    
    invokeOperation - the invoke operation.
    
    igName - the name of the invocation grid to perform this invoke.
    
    serializedParamObject - the serialized parameter object.
    
    timeout - the invoke timeout.
    
    Returns:
    
    a InvokeResponse detailing the status of the operation.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - queryObjectCount
```
public abstract int queryObjectCount()
                              throws CacheException
```
    Perform a distributed query to retrieve a count of all objects in the cache.
    
    Note that this call is not locking therefore the value is subject to change based on other accesses.
    
    Returns:
    
    the number of objects in the cache.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - getMetadata
```
public abstract CacheResponse<K,CachedObjectMetadata<K>> getMetadata(K key)
                                                              throws CacheException
```
    Retrieves CachedObjectMetadata for an object stored in the cache.
    
    Returns RequestStatus.ObjectRetrieved if the object exists.
    
    Returns RequestStatus.ObjectNotFound if the object does not exist.
    
    Parameters:
    
    key - the key to get metadata for.
    
    Returns:
    
    the metadata for the cache object.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - invoke
```
public abstract InvokeResponse invoke(java.lang.String invokeOperation,
                                      java.time.Duration timeout)
                               throws CacheException
```
    Invoke a parallel operation on this cache.
    
    Register for invoke events with ServiceEvents.setForEachEventHandler(Cache, String, CacheEntryForEachHandler), ServiceEvents.setForEachEventHandler(Cache, String, CacheEntryForEachHandler, ParamHolder), ServiceEvents.setReduceEventHandler(Cache, String, CacheEntryReduceHandler), and ServiceEvents.setReduceEventHandler(Cache, String, CacheEntryReduceHandler, ParamHolder).
    
    The InvokeResponse is used to evaluate the result of the invoke operation.
    
    Exceptions can be handled for logging and tracking purposes during invoke runtime by enabling a ServiceEvents.setEventDeliveryExceptionHandler(Cache, EventDeliveryExceptionHandler).
    
    Parameters:
    
    invokeOperation - the invoke operation.
    
    timeout - the invoke timeout.
    
    Returns:
    
    a InvokeResponse detailing the status of the operation.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - invoke
```
public abstract InvokeResponse invoke(java.lang.String invokeOperation,
                                      java.lang.String igName,
                                      java.time.Duration timeout)
                               throws CacheException
```
    Invoke a parallel operation on this cache.
    
    Register for invoke events with ServiceEvents.setForEachEventHandler(Cache, String, CacheEntryForEachHandler), ServiceEvents.setForEachEventHandler(Cache, String, CacheEntryForEachHandler, ParamHolder), ServiceEvents.setReduceEventHandler(Cache, String, CacheEntryReduceHandler), and ServiceEvents.setReduceEventHandler(Cache, String, CacheEntryReduceHandler, ParamHolder).
    
    The InvokeResponse is used to evaluate the result of the invoke operation.
    
    Exceptions can be handled for logging and tracking purposes during invoke runtime by enabling a ServiceEvents.setEventDeliveryExceptionHandler(Cache, EventDeliveryExceptionHandler).
    
    Parameters:
    
    invokeOperation - the invoke operation.
    
    igName - the invocation grid to perform this invoke.
    
    timeout - the invoke timeout.
    
    Returns:
    
    a InvokeResponse detailing the status of the operation.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - invoke
```
public abstract InvokeResponse invoke(java.lang.String invokeOperation,
                                      byte[] serializedParamObject,
                                      java.time.Duration timeout)
                               throws CacheException
```
    Invoke a parallel operation on this cache.
    
    Register for invoke events with ServiceEvents.setForEachEventHandler(Cache, String, CacheEntryForEachHandler), ServiceEvents.setForEachEventHandler(Cache, String, CacheEntryForEachHandler, ParamHolder), ServiceEvents.setReduceEventHandler(Cache, String, CacheEntryReduceHandler), and ServiceEvents.setReduceEventHandler(Cache, String, CacheEntryReduceHandler, ParamHolder).
    
    The InvokeResponse is used to evaluate the result of the invoke operation.
    
    Exceptions can be handled for logging and tracking purposes during invoke runtime by enabling a ServiceEvents.setEventDeliveryExceptionHandler(Cache, EventDeliveryExceptionHandler).
    
    Parameters:
    
    invokeOperation - the invoke operation.
    
    serializedParamObject - the serialized parameter object.
    
    timeout - the invoke timeout.
    
    Returns:
    
    a InvokeResponse detailing the status of the operation.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - invoke
```
public abstract InvokeResponse invoke(java.lang.String invokeOperation,
                                      java.lang.String igName,
                                      byte[] serializedParamObject,
                                      java.time.Duration timeout)
                               throws CacheException
```
    Invoke a parallel operation on this cache.
    
    Register for invoke events with ServiceEvents.setForEachEventHandler(Cache, String, CacheEntryForEachHandler), ServiceEvents.setForEachEventHandler(Cache, String, CacheEntryForEachHandler, ParamHolder), ServiceEvents.setReduceEventHandler(Cache, String, CacheEntryReduceHandler), and ServiceEvents.setReduceEventHandler(Cache, String, CacheEntryReduceHandler, ParamHolder).
    
    The InvokeResponse is used to evaluate the result of the invoke operation.
    
    Exceptions can be handled for logging and tracking purposes during invoke runtime by enabling a ServiceEvents.setEventDeliveryExceptionHandler(Cache, EventDeliveryExceptionHandler).
    
    Parameters:
    
    invokeOperation - the invoke operation.
    
    igName - the name of the invocation grid to perform this invoke.
    
    serializedParamObject - the serialized parameter object.
    
    timeout - the invoke timeout.
    
    Returns:
    
    a InvokeResponse detailing the status of the operation.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - addAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> addAsync(K key,
                                                                                    V value)
                                                                             throws CacheException
```
    Asynchronously add an object to the ScaleOut cache.
    
    The object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAdded.
    
    The object must not exist when calling add. If the object may already exists and the client should update the object, use addOrUpdate(Object, Object).
    
    If the object already exists, or is added by another client (or thread), the CacheResponse.getStatus() will return RequestStatus.ObjectExists.
    
    The CreatePolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key or value are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to add to the ScaleOut cache.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - addAndLockAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> addAndLockAsync(K key,
                                                                                           V value)
                                                                                    throws CacheException
```
    Asynchronously add an object to the ScaleOut cache with an exclusive lock.
    
    The object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAddedAndLocked and the CacheResponse.getLockToken() will have a value.
    
    The object must not exist when calling addExclusive.
    
    If the object already exists, or is added by another client (or thread), the CacheResponse.getStatus() will return RequestStatus.ObjectExists.
    
    The CreatePolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key or value are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to add to the ScaleOut cache.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - addOrUpdateAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> addOrUpdateAsync(K key,
                                                                                            V value)
                                                                                     throws CacheException
```
    Asynchronously add or update an object to or in the ScaleOut cache.
    
    The object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAdded and the object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdated.
    
    The CreatePolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key or value are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to add to the ScaleOut cache.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - updateAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> updateAsync(K key,
                                                                                       V value)
                                                                                throws CacheException
```
    Asynchronously update an object in the ScaleOut cache.
    
    The object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdated.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    Supplying a null value will remove the object from the ScaleOut cache.
    
    The CreatePolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to update in the ScaleOut cache. Provide null if the object should be removed.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - updateAndRetainLockAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> updateAndRetainLockAsync(K key,
                                                                                                    V value,
                                                                                                    LockToken lockToken)
                                                                                             throws CacheException
```
    Asynchronously update a locked object in the ScaleOut cache and retain exclusive access to the object through a lock.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    The object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdatedAndLockRetained.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    Supplying a null value will remove the object from the ScaleOut cache. Note, the remove attempt will not bypass the lock. This means the lock token must be the appropriate lock in order to successfully remove the object.
    
    The CreatePolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, or the lock token has no value.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to update in the ScaleOut cache. Provide null if the object should be removed.
    
    lockToken - the LockToken to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - updateAndUnlockAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> updateAndUnlockAsync(K key,
                                                                                                V value,
                                                                                                LockToken lockToken)
                                                                                         throws CacheException
```
    Asynchronously update a locked object in the ScaleOut cache and unlock the object.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    The object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdatedAndUnlocked.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    Supplying a null value will remove the object from the ScaleOut cache. Note, the remove attempt will not bypass the lock. This means the lock token must be the appropriate lock in order to successfully remove the object.
    
    The CreatePolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, or the lock token has no value.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to update in the ScaleOut cache. Provide null if the object should be removed.
    
    lockToken - the LockToken to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - addAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> addAsync(K key,
                                                                                    V value,
                                                                                    CreatePolicy policy)
                                                                             throws CacheException
```
    Asynchronously add an object to the ScaleOut cache with a parameter CreatePolicy.
    
    Specify a custom CreatePolicy to adjust object metadata such as TimeoutType, GeoServerReadMode, and other properties.
    
    The object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAdded.
    
    The object must not exist when calling add. If the object may already exists and the client should update the object, use addOrUpdate(Object, Object).
    
    If the object already exists, or is added by another client (or thread), the CacheResponse.getStatus() will return RequestStatus.ObjectExists.
    
    IllegalArgumentException is thrown if the key or value are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to add to the ScaleOut cache.
    
    policy - the policy to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - addAndLockAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> addAndLockAsync(K key,
                                                                                           V value,
                                                                                           CreatePolicy policy)
                                                                                    throws CacheException
```
    Asynchronously add an object to the ScaleOut cache with an exclusive lock and a parameter CreatePolicy.
    
    Specify a custom CreatePolicy to adjust object metadata such as TimeoutType, GeoServerReadMode, and other properties.
    
    The object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAddedAndLocked and the CacheResponse.getLockToken() will have a value.
    
    The object must not exist when calling addExclusive.
    
    If the object already exists, or is added by another client (or thread), the CacheResponse.getStatus() will return RequestStatus.ObjectExists.
    
    IllegalArgumentException is thrown if the key, value, or create policy are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to add to the ScaleOut cache.
    
    policy - the policy to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - addOrUpdateAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> addOrUpdateAsync(K key,
                                                                                            V value,
                                                                                            CreatePolicy policy)
                                                                                     throws CacheException
```
    Asynchronously add or update an object to/in the ScaleOut cache with a custom CreatePolicy.
    
    Specify a custom CreatePolicy to adjust object metadata such as TimeoutType, GeoServerReadMode, and other properties.
    
    The object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAdded and the object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdated.
    
    IllegalArgumentException is thrown if the key or value are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to add to the ScaleOut cache.
    
    policy - the policy to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - updateAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> updateAsync(K key,
                                                                                       V value,
                                                                                       CreatePolicy policy)
                                                                                throws CacheException
```
    Asynchronously update an object in the ScaleOut cache.
    
    Specify a custom CreatePolicy to adjust object metadata such as TimeoutType, GeoServerReadMode, and other properties.
    
    The object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdated.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    Supplying a null value will remove the object from the ScaleOut cache.
    
    IllegalArgumentException is thrown if the key or create policy are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to update in the ScaleOut cache. Provide null if the object should be removed.
    
    policy - the policy to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - updateAndRetainLockAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> updateAndRetainLockAsync(K key,
                                                                                                    V value,
                                                                                                    LockToken lockToken,
                                                                                                    CreatePolicy policy)
                                                                                             throws CacheException
```
    Asynchronously update a locked object in the ScaleOut cache and retain exclusive access to the object through a lock.
    
    Specify a custom CreatePolicy to adjust object metadata such as TimeoutType, GeoServerReadMode, and other properties.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    The object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdatedAndLockRetained.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    Supplying a null value will remove the object from the ScaleOut cache. Note, the remove attempt will not bypass the lock. This means the lock token must be the appropriate lock in order to successfully remove the object.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, the lock token has no value, or the create policy is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to update in the ScaleOut cache. Provide null if the object should be removed.
    
    lockToken - the LockToken to use.
    
    policy - the policy to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - updateAndUnlockAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> updateAndUnlockAsync(K key,
                                                                                                V value,
                                                                                                LockToken lockToken,
                                                                                                CreatePolicy policy)
                                                                                         throws CacheException
```
    Asynchronously update a locked object in the ScaleOut cache and release exclusive access to the object.
    
    Specify a custom CreatePolicy to adjust object metadata such as TimeoutType, GeoServerReadMode, and other properties.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    The object is successfully updated when CacheResponse.getStatus() returns RequestStatus.ObjectUpdatedAndUnlocked.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    Supplying a null value will remove the object from the ScaleOut cache. Note, the remove attempt will not bypass the lock. This means the lock token must be the appropriate lock in order to successfully remove the object.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, the lock token has no value, or the create policy is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    value - the object to update in the ScaleOut cache. Null if the object should be removed.
    
    lockToken - the LockToken to use.
    
    policy - the policy to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - readAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> readAsync(K key)
                                                                              throws CacheException
```
    Asynchronously read an object from the ScaleOut cache.
    
    The object is successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrieved.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    The ReadPolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - readAndLockAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> readAndLockAsync(K key)
                                                                                     throws CacheException
```
    Asynchronously read an object from the ScaleOut cache and acquire an exclusive lock for that object.
    
    The object is successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrievedAndLocked.
    
    The LockToken is retrieved from the CacheResponse.getLockToken()
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    The object was locked by another client/thread in the ScaleOut cache if CacheResponse.getStatus() returns RequestStatus.ObjectAlreadyLocked.
    
    The ReadPolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - readLockedAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> readLockedAsync(K key,
                                                                                           LockToken lockToken)
                                                                                    throws CacheException
```
    Asynchronously read a locked object from the ScaleOut cache.
    
    The object is successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrievedAndLocked.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    The refreshed LockToken is retrieved from the CacheResponse.getLockToken()
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    The object was locked by another client/thread in the ScaleOut cache if CacheResponse.getStatus() returns RequestStatus.LockLostError.
    
    The ReadPolicy as defined by the CacheBuilder will be used.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, or the lock token has no value.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    lockToken - the LockToken to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - readAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> readAsync(K key,
                                                                                     ReadPolicy policy)
                                                                              throws CacheException
```
    Asynchronously read a locked object from the ScaleOut cache.
    
    Specify a custom ReadPolicy to adjust read properties.
    
    The object is successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrievedAndLocked.
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    IllegalArgumentException is thrown if the key is null or ReadPolicy is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    policy - the ReadPolicy to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - readAndLockAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> readAndLockAsync(K key,
                                                                                            ReadPolicy policy)
                                                                                     throws CacheException
```
    Asynchronously read an object from the ScaleOut cache and acquire an exclusive lock for that object using a custom read policy.
    
    Specify a custom ReadPolicy to adjust read properties.
    
    The object is successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrievedAndLocked.
    
    The LockToken is retrieved from the CacheResponse.getLockToken()
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    The object was locked by another client/thread in the ScaleOut cache if CacheResponse.getStatus() returns RequestStatus.ObjectAlreadyLocked.
    
    IllegalArgumentException is thrown if the key is null or ReadPolicy is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    policy - the ReadPolicy to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - readOrAddAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> readOrAddAsync(K key,
                                                                                          ValueFactory<K,V> factory,
                                                                                          ReadPolicy policy)
                                                                                   throws CacheException
```
    Read an object from the ScaleOut cache. If the object is not present, the parameter ValueFactory will be called and the value will be added. Once the value has been added, the newly added value will be returned.
    
    Specify a custom ReadPolicy to adjust read properties.
    
    The object is successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrieved and the object is successfully added when CacheResponse.getStatus() returns RequestStatus.ObjectAdded, or the object was not found by the ValueFactory when CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    IllegalArgumentException is thrown if the key, value factory, or read policy, are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    factory - the ValueFactory to use.
    
    policy - the ReadPolicy to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - readAndLockOrAddAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> readAndLockOrAddAsync(K key,
                                                                                                 ValueFactory<K,V> factory,
                                                                                                 ReadPolicy policy)
                                                                                          throws CacheException
```
    Read an object from the ScaleOut cache. If the object is not present, the parameter ValueFactory will be called and the value will be added. Once the value has been added, the newly added value will be returned.
    
    Specify a custom ReadPolicy to adjust read properties.
    
    The object was successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrievedAndLocked, the object was successfully added when CacheResponse.getStatus() return RequestStatus.ObjectAdded, the object was not found by the ValueFactory when CacheResponse.getStatus() returns RequestStatus.ObjectNotFound, or the object is already locked by another caller and CacheResponse.getStatus() returns RequestStatus.ObjectAlreadyLocked.
    
    IllegalArgumentException is thrown if the key, value factory, or read policy, are null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    factory - the ValueFactory to use.
    
    policy - the ReadPolicy to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - readLockedAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> readLockedAsync(K key,
                                                                                           LockToken lockToken,
                                                                                           ReadPolicy policy)
                                                                                    throws CacheException
```
    Asynchronously read a locked object from the ScaleOut cache with a custom read policy.
    
    Specify a custom ReadPolicy to adjust read properties.
    
    The object is successfully retrieved when CacheResponse.getStatus() returns RequestStatus.ObjectRetrievedAndLocked.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    The refreshed LockToken is retrieved from the CacheResponse.getLockToken()
    
    The object must exist in the ScaleOut cache. If the object does not exist, CacheResponse.getStatus() returns RequestStatus.ObjectNotFound.
    
    The object was locked by another client/thread in the ScaleOut cache if CacheResponse.getStatus() returns RequestStatus.LockLostError.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, the lock token has no value, or the ReadPolicy is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    lockToken - the LockToken to use.
    
    policy - the ReadPolicy to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - removeAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> removeAsync(K key)
                                                                                throws CacheException
```
    Asynchronously remove an object from the ScaleOut cache.
    
    The object is successfully removed when CacheResponse.getStatus() returns RequestStatus.ObjectRemoved.
    
    IllegalArgumentException is thrown if the key is null.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - removeLockedAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> removeLockedAsync(K key,
                                                                                             LockToken lockToken)
                                                                                      throws CacheException
```
    Asynchronously remove a locked object from the ScaleOut cache.
    
    The object is successfully removed when CacheResponse.getStatus() returns RequestStatus.ObjectRemoved.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    The object was locked by another client/thread in the ScaleOut cache if CacheResponse.getStatus() returns RequestStatus.ObjectLocked.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, or the lock token has no value.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    lockToken - the LockToken to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - lockAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> lockAsync(K key)
                                                                              throws CacheException
```
    Asynchronously lock an object within the ScaleOut cache for exclusive access.
    
    The LockToken is retrieved from the CacheResponse.getLockToken()
    
    The object is successfully locked when CacheResponse.getStatus() returns RequestStatus.ObjectLocked.
    
    IllegalArgumentException is thrown if the key is null
    
    Parameters:
    
    key - the unique identifier for this object.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - refreshLockAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> refreshLockAsync(K key,
                                                                                            LockToken lockToken)
                                                                                     throws CacheException
```
    Asynchronously refresh a lock on an object within the ScaleOut cache.
    
    The LockToken is retrieved from the CacheResponse.getLockToken()
    
    The lock is successfully refreshed when CacheResponse.getStatus() returns RequestStatus.ObjectLocked.
    
    The LockTimeout has expired when CacheResponse.getStatus() returns RequestStatus.LockLostError.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, or the lock token has no value.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    lockToken - the LockToken to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - unlockAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> unlockAsync(K key,
                                                                                       LockToken lockToken)
                                                                                throws CacheException
```
    Asynchronously unlock a locked object within the ScaleOut cache.
    
    A lock on an object is acquired through addExclusive, lock, or readAndLock.
    
    The object is successfully unlocked when CacheResponse.getStatus() returns RequestStatus.ObjectUnlocked.
    
    The LockTimeout has expired when CacheResponse.getStatus() returns RequestStatus.LockLostError.
    
    IllegalArgumentException is thrown if the key is null, the lock token is null, or the lock token has no value.
    
    Parameters:
    
    key - the unique identifier for this object.
    
    lockToken - the LockToken to use.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - clearAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,V>> clearAsync()
                                                                               throws CacheException
```
    Asynchronously clear all objects from the ScaleOut cache.
    
    The cache is successfully cleared when CacheResponse.getStatus() returns RequestStatus.CacheCleared.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - getMetadataAsync
```
public abstract java.util.concurrent.CompletableFuture<CacheResponse<K,CachedObjectMetadata<K>>> getMetadataAsync(K key)
                                                                                                           throws CacheException
```
    Retrieves CachedObjectMetadata for an object stored in the cache.
    
    Returns RequestStatus.ObjectRetrieved if the object exists.
    
    Returns RequestStatus.ObjectNotFound if the object does not exist.
    
    Parameters:
    
    key - the key to get metadata for.
    
    Returns:
    
    a CompletableFuture that returns a CacheResponse.
    
    Throws:
    
    CacheException - The cache will automatically retry the request if no ScaleOut gateways are available. If all retries are exhausted, a CacheException will be thrown.
  - createPolicy
```
public abstract CreatePolicy createPolicy()
```
    Retrieve the default CreatePolicy used by this Cache.
    
    Returns:
    
    the CreatePolicy used by this Cache.
  - cacheValueDeserializer
```
public abstract CacheDeserializer<V> cacheValueDeserializer()
```
  - cacheValueSerializer
```
public abstract CacheSerializer<V> cacheValueSerializer()
```

Class Cache<K,V>

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface com.scaleout.client.caching.ServiceEventHandler

Method Detail

add

add

addAndLock

addOrUpdate

update

updateAndRetainLock

updateAndUnlock

add

add

addAndLock

addOrUpdate

update

updateOptimistic

updateOptimistic

postEvent

postEvent

updateAndRetainLock

updateAndUnlock

read

readAndLock

readLocked

read

readAndLock

readOrAdd

readAndLockOrAdd

readLocked

remove

removeLocked

removeOptimistic

lock

refreshLock

unlock

clear

queryObjects

queryKeys

retrieveAllKeys

singleInvoke

singleInvoke

singleInvoke

singleInvoke

queryObjectCount

getMetadata

invoke

invoke

invoke

invoke

addAsync

addAndLockAsync

addOrUpdateAsync

updateAsync

updateAndRetainLockAsync

updateAndUnlockAsync

addAsync

addAndLockAsync

addOrUpdateAsync

updateAsync

updateAndRetainLockAsync

updateAndUnlockAsync

readAsync

readAndLockAsync

readLockedAsync

readAsync

readAndLockAsync

readOrAddAsync

readAndLockOrAddAsync

readLockedAsync

removeAsync

removeLockedAsync

lockAsync

refreshLockAsync

unlockAsync

clearAsync

getMetadataAsync

createPolicy

cacheValueDeserializer