org.apache.ignite.internal.client

## Interface GridClientData

All Known Implementing Classes:
  GridClientDataImpl

    public interface GridClientData

A data projection of grid client. Contains various methods for cache operations and metrics retrieval. An instance of data projection over some remote cache is provided via `GridClient.data(String)` method.

# Affinity Awareness

One of the unique properties of the Ignite remote clients is that they are affinity aware. In other words, both compute and data APIs will optionally contact exactly the node where the data is cached based on some affinity key. This allows for collocation of computations and data and avoids extra network hops that would be necessary if non-affinity nodes were contacted. By default all operations on `GridClientData` API will be affinity-aware unless such behavior is overridden by pinning one or more remote nodes (see `pinNodes(GridClientNode, GridClientNode...)` for more information).

### Method Summary

All Methods Instance Methods Abstract Methods
`<K> UUID` `affinity(K key)` Gets affinity node ID for provided key.
`<K,V> boolean` `append(K key, V val)` Append requested value to already cached one.
`<K,V> GridClientFuture<Boolean>` `appendAsync(K key, V val)` Append requested value to already cached one.
`GridClientDataMetrics` `cachedMetrics()` Tries to get metrics from local cache.
`String` `cacheName()` Gets name of the remote cache.
`<K,V> boolean` `cas(K key, V val1, V val2)` Sets entry value to `val1` if current value is `val2` with following conditions: If `val1` is `null` and `val2` is equal to current value, entry is removed from cache.
`<K,V> GridClientFuture<Boolean>` `casAsync(K key, V val1, V val2)` Asynchronously sets entry value to `val1` if current value is `val2` with following conditions: If `val1` is `null` and `val2` is equal to current value, entry is removed from cache.
`Set<GridClientCacheFlag>` `flags()` Gets cache flags enabled on this data projection.
`GridClientData` `flagsOff(GridClientCacheFlag... flags)` Creates new client data object with disabled cache flags.
`GridClientData` `flagsOn(GridClientCacheFlag... flags)` Creates new client data object with enabled cache flags.
`<K,V> V` `get(K key)` Gets value from cache on remote node.
`<K,V> Map<K,V>` `getAll(Collection<K> keys)` Gets entries from cache on remote grid.
`<K,V> GridClientFuture<Map<K,V>>` `getAllAsync(Collection<K> keys)` Asynchronously gets entries from cache on remote grid.
`<K,V> GridClientFuture<V>` `getAsync(K key)` Asynchronously gets value from cache on remote grid.
`GridClientDataMetrics` `metrics()` Fetches metrics for cache from remote grid.
`GridClientFuture<GridClientDataMetrics>` `metricsAsync()` Asynchronously fetches metrics for cache from remote grid.
`Collection<GridClientNode>` `pinnedNodes()` Gets pinned node or `null` if no nodes were pinned.
`GridClientData` `pinNodes(GridClientNode node, GridClientNode... nodes)` Gets client data projection which will only contact specified remote grid node.
`<K,V> boolean` `prepend(K key, V val)` Prepend requested value to already cached one.
`<K,V> GridClientFuture<Boolean>` `prependAsync(K key, V val)` Prepend requested value to already cached one.
`<K,V> boolean` `put(K key, V val)` Puts value to cache on remote grid.
`<K,V> void` `putAll(Map<K,V> entries)` Puts entries to cache on remote grid.
`<K,V> GridClientFuture<?>` `putAllAsync(Map<K,V> entries)` Asynchronously puts entries to cache on remote grid.
`<K,V> GridClientFuture<Boolean>` `putAsync(K key, V val)` Asynchronously puts value to cache on remote node.
`<K> boolean` `remove(K key)` Removes value from cache on remote node.
`<K> void` `removeAll(Collection<K> keys)` Removes entries from cache on remote node.
`<K> GridClientFuture<?>` `removeAllAsync(Collection<K> keys)` Asynchronously removes entries from cache on remote grid.
`<K> GridClientFuture<Boolean>` `removeAsync(K key)` Asynchronously removes value from cache on remote grid.
`<K,V> boolean` `replace(K key, V val)` Replaces value in cache on remote grid only if there was a `non-null` value associated with this key.
`<K,V> GridClientFuture<Boolean>` `replaceAsync(K key, V val)` Asynchronously replaces value in cache on remote grid only if there was a `non-null` value associated with this key.

### Method Detail

#### cacheName

    String cacheName()

Gets name of the remote cache. The cache name for this projection was specified via `GridClient.data(String)` method at the time of creation.

Returns:
  Name of the remote cache.

#### pinNodes

    GridClientData pinNodes(GridClientNode node,
                            GridClientNode... nodes)
                     throws GridClientException

Gets client data projection which will only contact specified remote grid node. By default, remote node is determined based on `GridClientDataAffinity` provided - this method allows to override default behavior and use only specified server for all cache operations.

Use this method when there are other than `key-affinity` reasons why a certain node should be contacted.

Parameters:
  `node` - Node to be contacted (optional).
  `nodes` - Additional nodes (optional).
Returns:
  Client data which will only contact server with given node ID.
Throws:
  `GridClientException` - If resulting projection is empty.

#### pinnedNodes

    Collection<GridClientNode> pinnedNodes()

Gets pinned node or `null` if no nodes were pinned.

Returns:
  Pinned node.

#### put

    <K,V> boolean put(K key,
                      V val)
               throws GridClientException

Puts value to cache on remote grid.

Note that this operation is affinity-aware and will immediately contact exactly the remote node on which this key is supposed to be cached (unless some nodes were `pinned`).

Parameters:
  `key` - Key to put in cache.
  `val` - Value to put in cache.
Returns:
  Whether value was actually put to cache.
Throws:
  `GridClientException` - In case of error.
  `GridServerUnreachableException` - If none of the servers can be reached.
  `GridClientClosedException` - If client was closed manually.

#### putAsync

    <K,V> GridClientFuture<Boolean> putAsync(K key,
                                             V val)

Asynchronously puts value to cache on remote node.

Note that this operation is affinity-aware and will immediately contact exactly the remote node on which this key is supposed to be cached (unless some nodes were `pinned`).

Parameters:
  `key` - Key to put in cache.
  `val` - Value to put in cache.
Returns:
  Future whether value was actually put to cache.

#### putAll

    <K,V> void putAll(Map<K,V> entries)
               throws GridClientException

Puts entries to cache on remote grid.

Note that this operation is affinity-aware and will immediately contact exactly the remote nodes on which these keys are supposed to be cached (unless some nodes were `pinned`). If entries do not map to one node, then the node which has most mapped entries will be contacted.

Parameters:
  `entries` - Entries to put in cache.
Throws:
  `GridClientException` - In case of error.
  `GridServerUnreachableException` - If none of the servers can be reached.
  `GridClientClosedException` - If client was closed manually.

#### putAllAsync

    <K,V> GridClientFuture<?> putAllAsync(Map<K,V> entries)

Asynchronously puts entries to cache on remote grid.

Note that this operation is affinity-aware and will immediately contact exactly the remote nodes on which these keys are supposed to be cached (unless some nodes were `pinned`). If entries do not map to one node, then the node which has most mapped entries will be contacted.

Parameters:
  `entries` - Entries to put in cache.
Returns:
  Future whether this operation completes.

#### get

    <K,V> V get(K key)
         throws GridClientException

Gets value from cache on remote node.

Note that this operation is affinity-aware and will immediately contact exactly the remote node on which this key is supposed to be cached (unless some nodes were `pinned`).

Parameters:
  `key` - Key to get from cache.
Returns:
  Value for given key or `null` if no value was cached.
Throws:
  `GridClientException` - In case of error.
  `GridServerUnreachableException` - If none of the servers can be reached.
  `GridClientClosedException` - If client was closed manually.

#### getAsync

    <K,V> GridClientFuture<V> getAsync(K key)

Asynchronously gets value from cache on remote grid.

Note that this operation is affinity-aware and will immediately contact exactly the remote node on which this key is supposed to be cached (unless some nodes were `pinned`).

Parameters:
  `key` - Key to get from cache.
Returns:
  Future with value for given key or with `null` if no value was cached.

#### getAll

    <K,V> Map<K,V> getAll(Collection<K> keys)
                   throws GridClientException

Gets entries from cache on remote grid.

Note that this operation is affinity-aware and will immediately contact exactly the remote nodes on which these keys are supposed to be cached (unless some nodes were `pinned`). If entries do not map to one node, then the node which has most mapped entries will be contacted.

Parameters:
  `keys` - Keys to get.
Returns:
  Entries retrieved from remote cache nodes.
Throws:
  `GridClientException` - In case of error.
  `GridServerUnreachableException` - If none of the servers can be reached.
  `GridClientClosedException` - If client was closed manually.

#### getAllAsync

    <K,V> GridClientFuture<Map<K,V>> getAllAsync(Collection<K> keys)

Asynchronously gets entries from cache on remote grid.

Note that this operation is affinity-aware and will immediately contact exactly the remote nodes on which these keys are supposed to be cached (unless some nodes were `pinned`). If entries do not map to one node, then the node which has most mapped entries will be contacted.

Parameters:
  `keys` - Keys to get.
Returns:
  Future with entries retrieved from remote cache nodes.

#### remove

    <K> boolean remove(K key)
                throws GridClientException

Removes value from cache on remote node.

Note that this operation is affinity-aware and will immediately contact exactly the remote node on which this key is supposed to be cached (unless some nodes were `pinned`).

Parameters:
  `key` - Key to remove.
Returns:
  Whether value was actually removed.
Throws:
  `GridClientException` - In case of error.
  `GridServerUnreachableException` - If none of the servers can be reached.
  `GridClientClosedException` - If client was closed manually.

#### removeAsync

    <K> GridClientFuture<Boolean> removeAsync(K key)

Asynchronously removes value from cache on remote grid.

Note that this operation is affinity-aware and will immediately contact exactly the remote node on which this key is supposed to be cached (unless some nodes were `pinned`).

Parameters:
  `key` - Key to remove.
Returns:
  Future whether value was actually removed.

#### removeAll

    <K> void removeAll(Collection<K> keys)
                throws GridClientException

Removes entries from cache on remote node.

Note that this operation is affinity-aware and will immediately contact exactly the remote nodes on which these keys are supposed to be cached (unless some nodes were `pinned`). If entries do not map to one node, then the node which has most mapped entries will be contacted.

Parameters:
  `keys` - Keys to remove.
Throws:
  `GridClientException` - In case of error.
  `GridServerUnreachableException` - If none of the servers can be reached.
  `GridClientClosedException` - If client was closed manually.

#### removeAllAsync

    <K> GridClientFuture<?> removeAllAsync(Collection<K> keys)

Asynchronously removes entries from cache on remote grid.

Note that this operation is affinity-aware and will immediately contact exactly the remote nodes on which these keys are supposed to be cached (unless some nodes were `pinned`). If entries do not map to one node, then the node which has most mapped entries will be contacted.

Parameters:
  `keys` - Keys to remove.
Returns:
  Future whether operation finishes.

#### replace

    <K,V> boolean replace(K key,
                          V val)
                   throws GridClientException

Replaces value in cache on remote grid only if there was a `non-null` value associated with this key.

Note that this operation is affinity-aware and will immediately contact exactly the remote node on which this key is supposed to be cached (unless some nodes were `pinned`).

Parameters:
  `key` - Key to replace.
  `val` - Value to replace.
Returns:
  Whether value was actually replaced.
Throws:
  `GridClientException` - In case of error.
  `GridServerUnreachableException` - If none of the servers can be reached.
  `GridClientClosedException` - If client was closed manually.

#### replaceAsync

    <K,V> GridClientFuture<Boolean> replaceAsync(K key,
                                                 V val)

Asynchronously replaces value in cache on remote grid only if there was a `non-null` value associated with this key.

Note that this operation is affinity-aware and will immediately contact exactly the remote node on which this key is supposed to be cached (unless some nodes were `pinned`).

Parameters:
  `key` - Key to replace.
  `val` - Value to replace.
Returns:
  Future whether value was actually replaced.

#### cas

    <K,V> boolean cas(K key,
                      V val1,
                      V val2)
               throws GridClientException

Sets entry value to `val1` if current value is `val2` with following conditions:

- If `val1` is `null` and `val2` is equal to current value, entry is removed from cache.
- If `val2` is `null`, entry is created if it doesn't exist.
- If both `val1` and `val2` are `null`, entry is removed.

Note that this operation is affinity-aware and will immediately contact exactly the remote node on which this key is supposed to be cached (unless some nodes were `pinned`).

Parameters:
  `key` - Key to set.
  `val1` - Value to set.
  `val2` - Check value.
Returns:
  Whether value of entry was changed.
Throws:
  `GridClientException` - In case of error.
  `GridServerUnreachableException` - If none of the servers can be reached.
  `GridClientClosedException` - If client was closed manually.

#### casAsync

    <K,V> GridClientFuture<Boolean> casAsync(K key,
                                             V val1,
                                             V val2)

Asynchronously sets entry value to `val1` if current value is `val2` with following conditions:

- If `val1` is `null` and `val2` is equal to current value, entry is removed from cache.
- If `val2` is `null`, entry is created if it doesn't exist.
- If both `val1` and `val2` are `null`, entry is removed.

Note that this operation is affinity-aware and will immediately contact exactly the remote node on which this key is supposed to be cached (unless some nodes were `pinned`).

Parameters:
  `key` - Key to set.
  `val1` - Value to set.
  `val2` - Check value.
Returns:
  Future whether value of entry was changed.

#### affinity

    <K> UUID affinity(K key)
               throws GridClientException

Gets affinity node ID for provided key. This method will return `null` if no affinity was configured for the given cache for this client or there are no nodes in topology with cache enabled.

Parameters:
  `key` - Key.
Returns:
  Node ID.
Throws:
  `GridClientException` - In case of error.

#### metrics

    GridClientDataMetrics metrics()
                           throws GridClientException

Fetches metrics for cache from remote grid.

Returns:
  Cache metrics.
Throws:
  `GridClientException` - In case of error.
  `GridServerUnreachableException` - If none of the servers can be reached.
  `GridClientClosedException` - If client was closed manually.

#### metricsAsync

    GridClientFuture<GridClientDataMetrics> metricsAsync()

Asynchronously fetches metrics for cache from remote grid.

Returns:
  Future with cache metrics.

#### cachedMetrics

    GridClientDataMetrics cachedMetrics()
                                 throws GridClientException

Tries to get metrics from local cache.

Local cache is updated on every `metrics()` or `metricsAsync()` call if `GridClientConfiguration.isEnableMetricsCache()` is enabled. If it is disabled then this method will always return `null`.

Returns:
  Cached metrics or `null` if no cached metrics available.
Throws:
  `GridClientException` - In case of error.
  `GridServerUnreachableException` - If none of the servers can be reached.
  `GridClientClosedException` - If client was closed manually.

#### append

    <K,V> boolean append(K key,
                         V val)
                  throws GridClientException

Append requested value to already cached one. This method supports work with strings, lists and maps.

Note that this operation is affinity-aware and will immediately contact exactly the remote node on which this key is supposed to be cached (unless some nodes were `pinned`).

Parameters:
  `key` - Key to manipulate cache value for.
  `val` - Value to append to the cached one.
Returns:
  Whether value of entry was changed.
Throws:
  `GridClientException` - In case of error.

#### appendAsync

    <K,V> GridClientFuture<Boolean> appendAsync(K key,
                                                V val)
                                         throws GridClientException

Append requested value to already cached one. This method supports work with strings, lists and maps.

Note that this operation is affinity-aware and will immediately contact exactly the remote node on which this key is supposed to be cached (unless some nodes were `pinned`).

Parameters:
  `key` - Key to manipulate cache value for.
  `val` - Value to append to the cached one.
Returns:
  Future whether value of entry was changed.
Throws:
  `GridClientException` - In case of error.

#### prepend

    <K,V> boolean prepend(K key,
                          V val)
                   throws GridClientException

Prepend requested value to already cached one. This method supports work with strings, lists and maps.

Note that this operation is affinity-aware and will immediately contact exactly the remote node on which this key is supposed to be cached (unless some nodes were `pinned`).

Parameters:
  `key` - Key to manipulate cache value for.
  `val` - Value to prepend to the cached one.
Returns:
  Whether value of entry was changed.
Throws:
  `GridClientException` - In case of error.

#### prependAsync

    <K,V> GridClientFuture<Boolean> prependAsync(K key,
                                                 V val)
                                          throws GridClientException

Prepend requested value to already cached one. This method supports work with strings, lists and maps.

Note that this operation is affinity-aware and will immediately contact exactly the remote node on which this key is supposed to be cached (unless some nodes were `pinned`).

Parameters:
  `key` - Key to manipulate cache value for.
  `val` - Value to prepend to the cached one.
Returns:
  Future whether value of entry was changed.
Throws:
  `GridClientException` - In case of error.

#### flags

    Set<GridClientCacheFlag> flags()

Gets cache flags enabled on this data projection.

Returns:
  Flags for this data projection (empty set if no flags have been set).

#### flagsOn

    GridClientData flagsOn(GridClientCacheFlag... flags)
                    throws GridClientException

Creates new client data object with enabled cache flags.

Parameters:
  `flags` - Optional cache flags to be enabled.
Returns:
  New client data object.
Throws:
  `GridClientException` - In case of error.

#### flagsOff

    GridClientData flagsOff(GridClientCacheFlag... flags)
                     throws GridClientException

Creates new client data object with disabled cache flags.

Parameters:
  `flags` - Cache flags to be disabled.
Returns:
  New client data object.
Throws:
  `GridClientException` - In case of error.

${current.year} Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Database and Caching Platform | : ver. 2.7.6
Release Date | : September 11 2019