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

Modifier and Type	Method and Description
<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.
List<String>	log(int lineFrom, int lineTo) Gets contents of default log file (GRIDGAIN_HOME/work/log/gridgain.log).
List<String>	log(String path, int lineFrom, int lineTo) Gets contents of custom log file, i.e.
GridClientFuture<List<String>>	logAsync(int lineFrom, int lineTo) Asynchronously gets contents of default log file (GRIDGAIN_HOME/work/log/gridgain.log).
GridClientFuture<List<String>>	logAsync(String path, int lineFrom, int lineTo) Asynchronously gets contents of custom log file.
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.

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.

log

List<String> log(int lineFrom,
               int lineTo)
                 throws GridClientException

Gets contents of default log file (GRIDGAIN_HOME/work/log/gridgain.log). Note that backward reading (with negative line indexes) supported for only 8-bit character encodings.

Parameters:

lineFrom - Index of line from which log is get, inclusive. Negative values mean line numbers from the end of the file.

lineTo - Index of line to which log is get, inclusive. Negative values mean line numbers from the end of the file.

Returns:

Log contents.

Throws:

GridClientException - In case of error.

GridServerUnreachableException - If none of the servers can be reached.

GridClientClosedException - If client was closed manually.

logAsync

GridClientFuture<List<String>> logAsync(int lineFrom,
                                      int lineTo)

Asynchronously gets contents of default log file (GRIDGAIN_HOME/work/log/gridgain.log). Note that backward reading (with negative line indexes) supported for only 8-bit character encodings.

Parameters:

lineFrom - Index of line from which log is get, inclusive. Negative values mean line numbers from the end of the file.

lineTo - Index of line to which log is get, inclusive. Negative values mean line numbers from the end of the file.

Returns:

Future for this operation.

log

List<String> log(String path,
               int lineFrom,
               int lineTo)
                 throws GridClientException

Gets contents of custom log file, i.e. log file in a non-default location. Note that backward reading (with negative line indexes) supported for only 8-bit character encodings.

Parameters:

path - Log file path. Can be absolute or relative to GRIDGAIN_HOME.

lineFrom - Index of line from which log is get, inclusive. Negative values mean line numbers from the end of the file.

lineTo - Index of line to which log is get, inclusive. Negative values mean line numbers from the end of the file.

Returns:

Log contents.

Throws:

GridClientException - In case of error.

GridServerUnreachableException - If none of the servers can be reached.

GridClientClosedException - If client was closed manually.

logAsync

GridClientFuture<List<String>> logAsync(String path,
                                      int lineFrom,
                                      int lineTo)

Asynchronously gets contents of custom log file. Note that backward reading (with negative line indexes) supported for only 8-bit character encodings.

Parameters:

path - Log file path. Can be absolute or relative to GRIDGAIN_HOME.

lineFrom - Index of line from which log is get, inclusive. Negative values mean line numbers from the end of the file.

lineTo - Index of line to which log is get, inclusive. Negative values mean line numbers from the end of the file.

Returns:

Future.