org.apache.ignite.internal.client

## Interface GridClientCompute

    public interface GridClientCompute

A compute projection of grid client. Contains various methods for task execution, full and partial (per node) topology refresh, and log viewing. An initial instance of compute projection over the whole remote grid is provided via `GridClient.compute()` method. Further sub-projections may be created via any of the `projection(...)` methods on this API.

You can create custom client projections based on any user-defined filtering. For example you can create a projection over a certain group of nodes, or over all nodes that have a certain attribute. Once projection is created, only nodes that belong to this projection will be contacted on remote grid for any operation. This essentially allows users to create virtual subgrids for remote task execution.

Use any of the `execute(...)` methods to execute tasks on remote grid. Note that tasks need to be deployed to remote grid first prior to execution. You can also use any of the `affinityExecute(...)` methods to execute tasks on node that have affinity with some data key. This way you can collocate your computation with the data cached on remote nodes.

You can also use any of the `refreshNode(...)` or `refreshTopology(...)` methods to eagerly refresh metrics or attributes on remote nodes (note that attributes are static, so it is sufficient to fetch and cache them only once). Metrics and attributes will be cached in `GridClientNode` instances automatically if `GridClientConfiguration.isEnableMetricsCache()` or `GridClientConfiguration.isEnableAttributesCache()` property is set to `true`.

Compute client also allows fetching contents of remote log files (including backwards mode) via any of the provided `log(...)` methods.

# 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. Use `affinityExecute(String, String, Object, Object)` and `affinityExecuteAsync(String, String, Object, Object)` to synchronously or asynchronously execute remote tasks on affinity nodes based on provided affinity keys.

### Method Summary

Methods
`<R> R` `affinityExecute(String taskName, String cacheName, Object affKey, Object taskArg)` Executes task using cache affinity key for routing.
`<R> GridClientFuture<R>` `affinityExecuteAsync(String taskName, String cacheName, Object affKey, Object taskArg)` Asynchronously executes task using cache affinity key for routing.
`GridClientLoadBalancer` `balancer()` Gets load balancer used by this projection.
`Collection<GridClientNode>` `daemonNodes()` Gets most recently refreshed set of daemon nodes.
`<R> R` `execute(String taskName, Object taskArg)` Executes task on remote grid.
`<R> GridClientFuture<R>` `executeAsync(String taskName, Object taskArg)` Asynchronously executes task on remote grid.
`GridClientNode` `node(UUID id)` Gets cached node with given id from most recently refreshed topology.
`Collection<GridClientNode>` `nodes()` Gets most recently refreshed topology (only non-daemon nodes included).
`Collection<GridClientNode>` `nodes(Collection<UUID> ids)` Gets cached nodes for the given IDs based on most recently refreshed topology.
`Collection<GridClientNode>` `nodes(GridClientPredicate<GridClientNode> filter)` Gets all cached nodes that pass the filter.
`GridClientCompute` `projection(Collection<GridClientNode> nodes)` Creates a projection that will communicate only with specified remote nodes.
`GridClientCompute` `projection(Collection<GridClientNode> nodes, GridClientLoadBalancer balancer)` Creates a projection that will communicate only with specified remote nodes.
`GridClientCompute` `projection(GridClientNode node)` Creates a projection that will communicate only with specified remote node.
`GridClientCompute` `projection(GridClientPredicate<? super GridClientNode> filter)` Creates a projection that will communicate only with nodes that are accepted by the passed filter.
`GridClientCompute` `projection(GridClientPredicate<? super GridClientNode> filter, GridClientLoadBalancer balancer)` Creates a projection that will communicate only with nodes that are accepted by the passed filter.
`GridClientNode` `refreshNode(String ip, boolean includeAttrs, boolean includeMetrics)` Refreshes and returns node by its IP address from remote grid.
`GridClientNode` `refreshNode(UUID id, boolean includeAttrs, boolean includeMetrics)` Refreshes and returns node by its ID from remote grid.
`GridClientFuture<GridClientNode>` `refreshNodeAsync(String ip, boolean includeAttrs, boolean includeMetrics)` Asynchronously refreshes and returns node by its IP address from remote grid.
`GridClientFuture<GridClientNode>` `refreshNodeAsync(UUID id, boolean includeAttrs, boolean includeMetrics)` Asynchronously refreshes and returns node by its ID from remote grid.
`List<GridClientNode>` `refreshTopology(boolean includeAttrs, boolean includeMetrics)` Refreshes and returns all nodes within topology.
`GridClientFuture<List<GridClientNode>>` `refreshTopologyAsync(boolean includeAttrs, boolean includeMetrics)` Asynchronously refreshes and returns all nodes within topology.
`GridClientCompute` `withKeepBinaries()` Sets keep binary flag for the next task execution in the current thread.

### Method Detail

#### projection

    GridClientCompute projection(GridClientNode node)
                                 throws GridClientException

Creates a projection that will communicate only with specified remote node.

If current projection is dynamic projection, then this method will check is passed node is in topology. If any filters were specified in current topology, this method will check if passed node is accepted by the filter. If current projection was restricted to any subset of nodes, this method will check if passed node is in that subset. If any of the checks fails an exception will be thrown.

Parameters:
  `node` - Single node to which this projection will be restricted.
Returns:
  Resulting static projection that is bound to a given node.
Throws:
  `GridClientException` - If resulting projection is empty.

#### projection

    GridClientCompute projection(GridClientPredicate<? super GridClientNode> filter)
                                 throws GridClientException

Creates a projection that will communicate only with nodes that are accepted by the passed filter.

If current projection is dynamic projection, then filter will be applied to the most relevant topology snapshot every time a node to communicate is selected. If current projection is a static projection, then resulting projection will only be restricted to nodes that were in parent projection and were accepted by the passed filter. If any of the checks fails an exception will be thrown.

Parameters:
  `filter` - Filter that will select nodes for projection. If `null`, then no filter would be applied to nodes in projection.
Returns:
  Resulting projection (static or dynamic, depending in parent projection type).
Throws:
  `GridClientException` - If resulting projection is empty.

#### projection

    GridClientCompute projection(Collection<GridClientNode> nodes)
                                 throws GridClientException

Creates a projection that will communicate only with specified remote nodes. For any particular call a node to communicate will be selected with balancer of this projection.

If current projection is dynamic projection, then this method will check is passed nodes are in topology. If any filters were specified in current topology, this method will check if passed nodes are accepted by the filter. If current projection was restricted to any subset of nodes, this method will check if passed nodes are in that subset (i.e. calculate the intersection of two collections). If any of the checks fails an exception will be thrown.

Parameters:
  `nodes` - Collection of nodes to which this projection will be restricted. If `null`, created projection is dynamic and will take nodes from topology.
Returns:
  Resulting static projection that is bound to a given nodes.
Throws:
  `GridClientException` - If resulting projection is empty.

#### projection

    GridClientCompute projection(GridClientPredicate<? super GridClientNode> filter,
                               GridClientLoadBalancer balancer)
                                 throws GridClientException

Creates a projection that will communicate only with nodes that are accepted by the passed filter. The balancer passed will override default balancer specified in configuration.

If current projection is dynamic projection, then filter will be applied to the most relevant topology snapshot every time a node to communicate is selected. If current projection is a static projection, then resulting projection will only be restricted to nodes that were in parent projection and were accepted by the passed filter. If any of the checks fails an exception will be thrown.

Parameters:
  `filter` - Filter that will select nodes for projection. If `null`, then no filter would be applied to nodes in projection.
  `balancer` - Balancer that will select balanced node in resulting projection. If `null`, then balancer which was specified while projection construction will be used.
Returns:
  Resulting projection (static or dynamic, depending in parent projection type).
Throws:
  `GridClientException` - If resulting projection is empty.

#### projection

    GridClientCompute projection(Collection<GridClientNode> nodes,
                               GridClientLoadBalancer balancer)
                                 throws GridClientException

Creates a projection that will communicate only with specified remote nodes. For any particular call a node to communicate will be selected with passed balancer..

If current projection is dynamic projection, then this method will check is passed nodes are in topology. If any filters were specified in current topology, this method will check if passed nodes are accepted by the filter. If current projection was restricted to any subset of nodes, this method will check if passed nodes are in that subset (i.e. calculate the intersection of two collections). If any of the checks fails an exception will be thrown.

Parameters:
  `nodes` - Collection of nodes to which this projection will be restricted. If `null`, then no filter would be applied to nodes in projection.
  `balancer` - Balancer that will select nodes in resulting projection. If `null`, then balancer which was specified while projection construction will be used.
Returns:
  Resulting static projection that is bound to a given nodes.
Throws:
  `GridClientException` - If resulting projection is empty.

#### balancer

    GridClientLoadBalancer balancer()

Gets load balancer used by this projection. By default, the balancer specified in `GridClientConfiguration.getBalancer()` property is used. User can provide custom balancers for different projections via `projection(GridClientPredicate, GridClientLoadBalancer)` method.

Returns:
  Instance of `GridClientLoadBalancer` used by this projection.

#### execute

    <R> R execute(String taskName,
                Object taskArg)
              throws GridClientException

Executes task on remote grid. Only nodes included into this projection will be contacted. Note that task must be deployed on remote grid prior to the execution.

Parameters:
  `taskName` - Task name or task class name.
  `taskArg` - Optional task argument.
Returns:
  Task execution result.
Throws:
  `GridClientException` - In case of error.
  `GridServerUnreachableException` - If none of the servers can be reached.
  `GridClientClosedException` - If client was closed manually.

#### executeAsync

    <R> GridClientFuture<R> executeAsync(String taskName,
                                       Object taskArg)

Asynchronously executes task on remote grid. Only nodes included into this projection will be contacted. Note that task must be deployed on remote grid prior to the execution.

Parameters:
  `taskName` - Task name or task class name.
  `taskArg` - Optional task argument.
Returns:
  Future for remote execution.

#### affinityExecute

    <R> R affinityExecute(String taskName,
                        String cacheName,
                        Object affKey,
                        Object taskArg)
                      throws GridClientException

Executes task using cache affinity key for routing. This way the task will start executing exactly on the node where this affinity key is cached hence allowing for collocation of computations and data.

Parameters:
  `taskName` - Task name or task class name.
  `cacheName` - Name of the cache on which affinity should be calculated. If `null`, then default cache will be used.
  `affKey` - Affinity key.
  `taskArg` - Optional task argument.
Returns:
  Task execution result.
Throws:
  `GridClientException` - In case of error.
  `GridServerUnreachableException` - If none of the servers can be reached.
  `GridClientClosedException` - If client was closed manually.

#### affinityExecuteAsync

    <R> GridClientFuture<R> affinityExecuteAsync(String taskName,
                                               String cacheName,
                                               Object affKey,
                                               Object taskArg)

Asynchronously executes task using cache affinity key for routing. This way the task will start executing exactly on the node where this affinity key is cached hence allowing for collocation of computations and data.

Parameters:
  `taskName` - Task name or task class name.
  `cacheName` - Name of the cache on which affinity should be calculated. If `null`, then balancer which was specified while projection construction will be used.
  `affKey` - Affinity key.
  `taskArg` - Optional task argument.
Returns:
  Future for the remote execution.

#### nodes

    Collection<GridClientNode> nodes()
                                     throws GridClientException

Gets most recently refreshed topology (only non-daemon nodes included). If this compute instance is a projection, then only nodes that satisfy projection criteria will be returned.

Returns:
  Most recently refreshed topology.
Throws:
  `GridClientException` - If client doesn't have an actual topology version.

#### node

    GridClientNode node(UUID id)
                        throws GridClientException

Gets cached node with given id from most recently refreshed topology.

Parameters:
  `id` - Node ID.
Returns:
  Node for given ID or `null` if node with given id was not found.
Throws:
  `GridClientException` - If client doesn't have an actual topology version.

#### nodes

    Collection<GridClientNode> nodes(Collection<UUID> ids)
                                     throws GridClientException

Gets cached nodes for the given IDs based on most recently refreshed topology. If this compute instance is a projection, then only nodes that passes projection criteria will be returned.

Parameters:
  `ids` - Node IDs.
Returns:
  Collection of nodes for provided IDs.
Throws:
  `GridClientException` - If client doesn't have an actual topology version.

#### nodes

    Collection<GridClientNode> nodes(GridClientPredicate<GridClientNode> filter)
                                     throws GridClientException

Gets all cached nodes that pass the filter. If this compute instance is a projection, then only nodes that passes projection criteria will be passed to the filter.

Parameters:
  `filter` - Node filter.
Returns:
  Collection of nodes that satisfy provided filter.
Throws:
  `GridClientException` - If client doesn't have an actual topology version.

#### daemonNodes

    Collection<GridClientNode> daemonNodes()
                                           throws GridClientException

Gets most recently refreshed set of daemon nodes. If this compute instance is a projection, then only nodes that satisfy projection criteria will be returned.

Returns:
  Daemon nodes in most recently refreshed topology.
Throws:
  `GridClientException` - If client doesn't have an actual topology version.

#### refreshNode

    GridClientNode refreshNode(UUID id,
                             boolean includeAttrs,
                             boolean includeMetrics)
                               throws GridClientException

Refreshes and returns node by its ID from remote grid. Use `includeAttrs` and `includeMetrics` parameters to automatically fetch remote node attributes and metrics.

Note that fetched attributes and metrics may or may note be cached in `GridClientNode` based on `GridClientConfiguration.isEnableMetricsCache()` and `GridClientConfiguration.isEnableAttributesCache()` parameters. Even though topology is refreshed automatically every `GridClientConfiguration.getTopologyRefreshFrequency()` interval, node metrics and attributes will be fetched in background only if `GridClientConfiguration.isAutoFetchMetrics()` or `GridClientConfiguration.isAutoFetchAttributes()` set to true.

Also note that node attributes are static and, if cached, there is no need to refresh them again.

Parameters:
  `id` - Node ID.
  `includeAttrs` - Whether to include node attributes.
  `includeMetrics` - Whether to include node metrics.
Returns:
  Node descriptor or `null` if node doesn't exist.
Throws:
  `GridClientException` - In case request failed.
  `GridServerUnreachableException` - If none of the servers can be reached.
  `GridClientClosedException` - If client was closed manually.

#### refreshNodeAsync

    GridClientFuture<GridClientNode> refreshNodeAsync(UUID id,
                                                    boolean includeAttrs,
                                                    boolean includeMetrics)

Asynchronously refreshes and returns node by its ID from remote grid. Use `includeAttrs` and `includeMetrics` parameters to automatically fetch remote node attributes and metrics.

Note that fetched attributes and metrics may or may note be cached in `GridClientNode` based on `GridClientConfiguration.isEnableMetricsCache()` and `GridClientConfiguration.isEnableAttributesCache()` parameters. Even though topology is refreshed automatically every `GridClientConfiguration.getTopologyRefreshFrequency()` interval, node metrics and attributes will be fetched in background only if `GridClientConfiguration.isAutoFetchMetrics()` or `GridClientConfiguration.isAutoFetchAttributes()` set to true.

Also note that node attributes are static and, if cached, there is no need to refresh them again.

Parameters:
  `id` - Node ID.
  `includeAttrs` - Whether to include node attributes.
  `includeMetrics` - Whether to include node metrics.
Returns:
  Future for the refresh

#### refreshNode

    @Nullable
    GridClientNode refreshNode(String ip,
                                      boolean includeAttrs,
                                      boolean includeMetrics)
                               throws GridClientException

Refreshes and returns node by its IP address from remote grid. All possible IP addresses of a node will be checked. If there is more than one node for given IP address, then first found node will be refreshed. Use `includeAttrs` and `includeMetrics` parameters to automatically fetch remote node attributes and metrics.

Note that fetched attributes and metrics may or may note be cached in `GridClientNode` based on `GridClientConfiguration.isEnableMetricsCache()` and `GridClientConfiguration.isEnableAttributesCache()` parameters. Even though topology is refreshed automatically every `GridClientConfiguration.getTopologyRefreshFrequency()` interval, node metrics and attributes will be fetched in background only if `GridClientConfiguration.isAutoFetchMetrics()` or `GridClientConfiguration.isAutoFetchAttributes()` set to true.

Also note that node attributes are static and, if cached, there is no need to refresh them again.

Parameters:
  `ip` - IP address.
  `includeAttrs` - Whether to include node attributes.
  `includeMetrics` - Whether to include node metrics.
Returns:
  Node descriptor or `null` if node doesn't exist.
Throws:
  `GridClientException` - In case of error.
  `GridServerUnreachableException` - If none of the servers can be reached.
  `GridClientClosedException` - If client was closed manually.

#### refreshNodeAsync

    GridClientFuture<GridClientNode> refreshNodeAsync(String ip,
                                                    boolean includeAttrs,
                                                    boolean includeMetrics)

Asynchronously refreshes and returns node by its IP address from remote grid. All possible IP addresses of a node will be checked. If there is more than one node for given IP address, then first found node will be refreshed. Use `includeAttrs` and `includeMetrics` parameters to automatically fetch remote node attributes and metrics.

Note that fetched attributes and metrics may or may note be cached in `GridClientNode` based on `GridClientConfiguration.isEnableMetricsCache()` and `GridClientConfiguration.isEnableAttributesCache()` parameters. Even though topology is refreshed automatically every `GridClientConfiguration.getTopologyRefreshFrequency()` interval, node metrics and attributes will be fetched in background only if `GridClientConfiguration.isAutoFetchMetrics()` or `GridClientConfiguration.isAutoFetchAttributes()` set to true.

Also note that node attributes are static and, if cached, there is no need to refresh them again.

Parameters:
  `ip` - IP address.
  `includeAttrs` - Whether to include node attributes.
  `includeMetrics` - Whether to include node metrics.
Returns:
  Future for the refresh operation.

#### refreshTopology

    List<GridClientNode> refreshTopology(boolean includeAttrs,
                                       boolean includeMetrics)
                                         throws GridClientException

Refreshes and returns all nodes within topology. Use `includeAttrs` and `includeMetrics` parameters to automatically fetch remote node attributes and metrics.

Note that fetched attributes and metrics may or may note be cached in `GridClientNode` based on `GridClientConfiguration.isEnableMetricsCache()` and `GridClientConfiguration.isEnableAttributesCache()` parameters. Even though topology is refreshed automatically every `GridClientConfiguration.getTopologyRefreshFrequency()` interval, node metrics and attributes will be fetched in background only if `GridClientConfiguration.isAutoFetchMetrics()` or `GridClientConfiguration.isAutoFetchAttributes()` set to `true`.

Also note that node attributes are static and, if cached, there is no need to refresh them again.

Parameters:
  `includeAttrs` - Whether to include node attributes.
  `includeMetrics` - Whether to include node metrics.
Returns:
  Node descriptors.
Throws:
  `GridClientException` - In case of error.
  `GridServerUnreachableException` - If none of the servers can be reached.
  `GridClientClosedException` - If client was closed manually.

#### refreshTopologyAsync

    GridClientFuture<List<GridClientNode>> refreshTopologyAsync(boolean includeAttrs,
                                                              boolean includeMetrics)

Asynchronously refreshes and returns all nodes within topology. Use `includeAttrs` and `includeMetrics` parameters to automatically fetch remote node attributes and metrics.

Note that fetched attributes and metrics may or may note be cached in `GridClientNode` based on `GridClientConfiguration.isEnableMetricsCache()` and `GridClientConfiguration.isEnableAttributesCache()`parameters. Even though topology is refreshed automatically every `GridClientConfiguration.getTopologyRefreshFrequency()` interval, node metrics and attributes will be fetched in background only if `GridClientConfiguration.isAutoFetchMetrics()` or `GridClientConfiguration.isAutoFetchAttributes()` set to `true`.

Also note that node attributes are static and, if cached, there is no need to refresh them again.

Parameters:
  `includeAttrs` - Whether to include node attributes.
  `includeMetrics` - Whether to include node metrics.
Returns:
  Future.

#### withKeepBinaries

    GridClientCompute withKeepBinaries()

Sets keep binary flag for the next task execution in the current thread.

2015 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 1.6.0
Release Date | : May 18 2016