org.gridgain.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 GridGain 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

Methods

Modifier and Type	Method and Description
<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.