org.gridgain.client.GridClientCompute Maven / Gradle / Ivy
/*
Copyright (C) GridGain Systems. All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
/* _________ _____ __________________ _____
* __ ____/___________(_)______ /__ ____/______ ____(_)_______
* _ / __ __ ___/__ / _ __ / _ / __ _ __ `/__ / __ __ \
* / /_/ / _ / _ / / /_/ / / /_/ / / /_/ / _ / _ / / /
* \____/ /_/ /_/ \_,__/ \____/ \__,_/ /_/ /_/ /_/
*/
package org.gridgain.client;
import org.gridgain.client.balancer.*;
import org.jetbrains.annotations.*;
import java.util.*;
/**
* 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 {@link GridClient#compute()} method. Further sub-projections may be created via
* any of the {@code 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 {@code 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
* {@code 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 {@code refreshNode(...)} or {@code 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 {@link GridClientNode} instances automatically if {@link GridClientConfiguration#isEnableMetricsCache()}
* or {@link GridClientConfiguration#isEnableAttributesCache()} property is set to {@code true}.
*
* Compute client also allows fetching contents of remote log files (including backwards mode) via any of
* the provided {@code 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
* {@link #affinityExecute(String, String, Object, Object)} and
* {@link #affinityExecuteAsync(String, String, Object, Object)} to synchronously
* or asynchronously execute remote tasks on affinity nodes based on provided
* affinity keys.
*/
public interface GridClientCompute {
/**
* 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.
*
* @param node Single node to which this projection will be restricted.
* @return Resulting static projection that is bound to a given node.
* @throws GridClientException If resulting projection is empty.
*/
public GridClientCompute projection(GridClientNode node) 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.
*
* @param filter Filter that will select nodes for projection. If {@code null},
* then no filter would be applied to nodes in projection.
* @return Resulting projection (static or dynamic, depending in parent projection type).
* @throws GridClientException If resulting projection is empty.
*/
public GridClientCompute projection(GridClientPredicate filter) 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.
*
* @param nodes Collection of nodes to which this projection will be restricted. If {@code null},
* created projection is dynamic and will take nodes from topology.
* @return Resulting static projection that is bound to a given nodes.
* @throws GridClientException If resulting projection is empty.
*/
public GridClientCompute projection(Collection nodes) 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.
*
* @param filter Filter that will select nodes for projection. If {@code null},
* then no filter would be applied to nodes in projection.
* @param balancer Balancer that will select balanced node in resulting projection. If {@code null},
* then balancer which was specified while projection construction will be used.
* @return Resulting projection (static or dynamic, depending in parent projection type).
* @throws GridClientException If resulting projection is empty.
*/
public GridClientCompute projection(GridClientPredicate filter,
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.
*
* @param nodes Collection of nodes to which this projection will be restricted. If {@code null},
* then no filter would be applied to nodes in projection.
* @param balancer Balancer that will select nodes in resulting projection. If {@code null},
* then balancer which was specified while projection construction will be used.
* @return Resulting static projection that is bound to a given nodes.
* @throws GridClientException If resulting projection is empty.
*/
public GridClientCompute projection(Collection nodes, GridClientLoadBalancer balancer)
throws GridClientException;
/**
* Gets load balancer used by this projection. By default, the balancer specified
* in {@link GridClientConfiguration#getBalancer()} property is used. User can
* provide custom balancers for different projections via
* {@link #projection(GridClientPredicate, GridClientLoadBalancer)} method.
*
* @return Instance of {@link GridClientLoadBalancer} used by this projection.
*/
public GridClientLoadBalancer balancer();
/**
* 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.
*
* @param taskName Task name or task class name.
* @param taskArg Optional task argument.
* @return Task execution result.
* @throws GridClientException In case of error.
* @throws GridServerUnreachableException If none of the servers can be reached.
* @throws GridClientClosedException If client was closed manually.
*/
public R execute(String taskName, Object taskArg) throws GridClientException;
/**
* 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.
*
* @param taskName Task name or task class name.
* @param taskArg Optional task argument.
* @return Future for remote execution.
*/
public GridClientFuture executeAsync(String taskName, Object taskArg);
/**
* 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.
*
* @param taskName Task name or task class name.
* @param cacheName Name of the cache on which affinity should be calculated. If {@code null},
* then default cache will be used.
* @param affKey Affinity key.
* @param taskArg Optional task argument.
* @return Task execution result.
* @throws GridClientException In case of error.
* @throws GridServerUnreachableException If none of the servers can be reached.
* @throws GridClientClosedException If client was closed manually.
*/
public R affinityExecute(String taskName, String cacheName, Object affKey, Object taskArg)
throws GridClientException;
/**
* 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.
*
* @param taskName Task name or task class name.
* @param cacheName Name of the cache on which affinity should be calculated. If {@code null},
* then balancer which was specified while projection construction will be used.
* @param affKey Affinity key.
* @param taskArg Optional task argument.
* @return Future for the remote execution.
*/
public GridClientFuture affinityExecuteAsync(String taskName, String cacheName, Object affKey,
Object taskArg);
/**
* 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.
*
* @return Most recently refreshed topology.
* @throws GridClientException If client doesn't have an actual topology version.
*/
public Collection nodes() throws GridClientException;
/**
* Gets cached node with given id from most recently refreshed topology.
*
* @param id Node ID.
* @return Node for given ID or {@code null} if node with given id was not found.
* @throws GridClientException If client doesn't have an actual topology version.
*/
public GridClientNode node(UUID id) 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.
*
* @param ids Node IDs.
* @return Collection of nodes for provided IDs.
* @throws GridClientException If client doesn't have an actual topology version.
*/
public Collection nodes(Collection ids) 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.
*
* @param filter Node filter.
* @return Collection of nodes that satisfy provided filter.
* @throws GridClientException If client doesn't have an actual topology version.
*/
public Collection nodes(GridClientPredicate filter)
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.
*
* @return Daemon nodes in most recently refreshed topology.
* @throws GridClientException If client doesn't have an actual topology version.
*/
public Collection daemonNodes() throws GridClientException;
/**
* Refreshes and returns node by its ID from remote grid. Use {@code includeAttrs} and
* {@code includeMetrics} parameters to automatically fetch remote node attributes and
* metrics.
*
* Note that fetched attributes and metrics may or may note be cached in {@link GridClientNode}
* based on {@link GridClientConfiguration#isEnableMetricsCache()} and
* {@link GridClientConfiguration#isEnableAttributesCache()} parameters. Even though topology
* is refreshed automatically every {@link GridClientConfiguration#getTopologyRefreshFrequency()}
* interval, node metrics and attributes will be fetched in background only if
* {@link GridClientConfiguration#isAutoFetchMetrics()} or
* {@link GridClientConfiguration#isAutoFetchAttributes()} set to true.
*
* Also note that node attributes are static and, if cached, there is no need
* to refresh them again.
*
* @param id Node ID.
* @param includeAttrs Whether to include node attributes.
* @param includeMetrics Whether to include node metrics.
* @return Node descriptor or {@code null} if node doesn't exist.
* @throws GridClientException In case request failed.
* @throws GridServerUnreachableException If none of the servers can be reached.
* @throws GridClientClosedException If client was closed manually.
*/
public GridClientNode refreshNode(UUID id, boolean includeAttrs, boolean includeMetrics) throws GridClientException;
/**
* Asynchronously refreshes and returns node by its ID from remote grid. Use {@code includeAttrs} and
* {@code includeMetrics} parameters to automatically fetch remote node attributes and
* metrics.
*
* Note that fetched attributes and metrics may or may note be cached in {@link GridClientNode}
* based on {@link GridClientConfiguration#isEnableMetricsCache()} and
* {@link GridClientConfiguration#isEnableAttributesCache()} parameters. Even though topology
* is refreshed automatically every {@link GridClientConfiguration#getTopologyRefreshFrequency()}
* interval, node metrics and attributes will be fetched in background only if
* {@link GridClientConfiguration#isAutoFetchMetrics()} or
* {@link GridClientConfiguration#isAutoFetchAttributes()} set to true.
*
* Also note that node attributes are static and, if cached, there is no need
* to refresh them again.
*
* @param id Node ID.
* @param includeAttrs Whether to include node attributes.
* @param includeMetrics Whether to include node metrics.
* @return Future for the refresh
*/
public GridClientFuture refreshNodeAsync(UUID id, boolean includeAttrs, boolean includeMetrics);
/**
* 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 {@code includeAttrs} and
* {@code includeMetrics} parameters to automatically fetch remote node attributes and
* metrics.
*
* Note that fetched attributes and metrics may or may note be cached in {@link GridClientNode}
* based on {@link GridClientConfiguration#isEnableMetricsCache()} and
* {@link GridClientConfiguration#isEnableAttributesCache()} parameters. Even though topology
* is refreshed automatically every {@link GridClientConfiguration#getTopologyRefreshFrequency()}
* interval, node metrics and attributes will be fetched in background only if
* {@link GridClientConfiguration#isAutoFetchMetrics()} or
* {@link GridClientConfiguration#isAutoFetchAttributes()} set to true.
*
* Also note that node attributes are static and, if cached, there is no need
* to refresh them again.
*
* @param ip IP address.
* @param includeAttrs Whether to include node attributes.
* @param includeMetrics Whether to include node metrics.
* @return Node descriptor or {@code null} if node doesn't exist.
* @throws GridClientException In case of error.
* @throws GridServerUnreachableException If none of the servers can be reached.
* @throws GridClientClosedException If client was closed manually.
*/
@Nullable public GridClientNode refreshNode(String ip, boolean includeAttrs, boolean includeMetrics)
throws GridClientException;
/**
* 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 {@code includeAttrs} and
* {@code includeMetrics} parameters to automatically fetch remote node attributes and
* metrics.
*
* Note that fetched attributes and metrics may or may note be cached in {@link GridClientNode}
* based on {@link GridClientConfiguration#isEnableMetricsCache()} and
* {@link GridClientConfiguration#isEnableAttributesCache()} parameters. Even though topology
* is refreshed automatically every {@link GridClientConfiguration#getTopologyRefreshFrequency()}
* interval, node metrics and attributes will be fetched in background only if
* {@link GridClientConfiguration#isAutoFetchMetrics()} or
* {@link GridClientConfiguration#isAutoFetchAttributes()} set to true.
*
* Also note that node attributes are static and, if cached, there is no need
* to refresh them again.
*
* @param ip IP address.
* @param includeAttrs Whether to include node attributes.
* @param includeMetrics Whether to include node metrics.
* @return Future for the refresh operation.
*/
public GridClientFuture refreshNodeAsync(String ip, boolean includeAttrs, boolean includeMetrics);
/**
* Refreshes and returns all nodes within topology. Use {@code includeAttrs} and
* {@code includeMetrics} parameters to automatically fetch remote node attributes and
* metrics.
*
* Note that fetched attributes and metrics may or may note be cached in {@link GridClientNode}
* based on {@link GridClientConfiguration#isEnableMetricsCache()} and
* {@link GridClientConfiguration#isEnableAttributesCache()} parameters. Even though topology
* is refreshed automatically every {@link GridClientConfiguration#getTopologyRefreshFrequency()}
* interval, node metrics and attributes will be fetched in background only if
* {@link GridClientConfiguration#isAutoFetchMetrics()} or
* {@link GridClientConfiguration#isAutoFetchAttributes()} set to {@code true}.
*
* Also note that node attributes are static and, if cached, there is no need
* to refresh them again.
*
* @param includeAttrs Whether to include node attributes.
* @param includeMetrics Whether to include node metrics.
* @return Node descriptors.
* @throws GridClientException In case of error.
* @throws GridServerUnreachableException If none of the servers can be reached.
* @throws GridClientClosedException If client was closed manually.
*/
public List refreshTopology(boolean includeAttrs, boolean includeMetrics)
throws GridClientException;
/**
* Asynchronously refreshes and returns all nodes within topology. Use {@code includeAttrs} and
* {@code includeMetrics} parameters to automatically fetch remote node attributes and
* metrics.
*
* Note that fetched attributes and metrics may or may note be cached in {@link GridClientNode}
* based on {@link GridClientConfiguration#isEnableMetricsCache()} and
* {@link GridClientConfiguration#isEnableAttributesCache()}parameters. Even though topology
* is refreshed automatically every {@link GridClientConfiguration#getTopologyRefreshFrequency()}
* interval, node metrics and attributes will be fetched in background only if
* {@link GridClientConfiguration#isAutoFetchMetrics()} or
* {@link GridClientConfiguration#isAutoFetchAttributes()} set to {@code true}.
*
* Also note that node attributes are static and, if cached, there is no need
* to refresh them again.
*
* @param includeAttrs Whether to include node attributes.
* @param includeMetrics Whether to include node metrics.
* @return Future.
*/
public GridClientFuture> refreshTopologyAsync(boolean includeAttrs, boolean includeMetrics);
/**
* Gets contents of default log file ({@code GRIDGAIN_HOME/work/log/gridgain.log}).
* Note that backward reading (with negative line indexes) supported for only 8-bit character encodings.
*
* @param lineFrom Index of line from which log is get, inclusive. Negative values mean line numbers
* from the end of the file.
* @param lineTo Index of line to which log is get, inclusive. Negative values mean line numbers
* from the end of the file.
* @return Log contents.
* @throws GridClientException In case of error.
* @throws GridServerUnreachableException If none of the servers can be reached.
* @throws GridClientClosedException If client was closed manually.
*/
public List log(int lineFrom, int lineTo) throws GridClientException;
/**
* Asynchronously gets contents of default log file
* ({@code GRIDGAIN_HOME/work/log/gridgain.log}).
* Note that backward reading (with negative line indexes) supported for only 8-bit character encodings.
*
* @param lineFrom Index of line from which log is get, inclusive. Negative values mean line numbers
* from the end of the file.
* @param lineTo Index of line to which log is get, inclusive. Negative values mean line numbers
* from the end of the file.
* @return Future for this operation.
*/
public GridClientFuture> logAsync(int lineFrom, int lineTo);
/**
* 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.
*
* @param path Log file path. Can be absolute or relative to GRIDGAIN_HOME.
* @param lineFrom Index of line from which log is get, inclusive. Negative values mean line numbers
* from the end of the file.
* @param lineTo Index of line to which log is get, inclusive. Negative values mean line numbers
* from the end of the file.
* @return Log contents.
* @throws GridClientException In case of error.
* @throws GridServerUnreachableException If none of the servers can be reached.
* @throws GridClientClosedException If client was closed manually.
*/
public List log(String path, int lineFrom, int lineTo) throws GridClientException;
/**
* Asynchronously gets contents of custom log file.
* Note that backward reading (with negative line indexes) supported for only 8-bit character encodings.
*
* @param path Log file path. Can be absolute or relative to GRIDGAIN_HOME.
* @param lineFrom Index of line from which log is get, inclusive. Negative values mean line numbers
* from the end of the file.
* @param lineTo Index of line to which log is get, inclusive. Negative values mean line numbers
* from the end of the file.
* @return Future.
*/
public GridClientFuture> logAsync(String path, int lineFrom, int lineTo);
}