modules/core/src/main/java/org/apache/ignite/internal/client/GridClientCompute.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.apache.ignite.internal.client;

import java.util.Collection;
import java.util.List;
import java.util.UUID;
import org.apache.ignite.internal.client.balancer.GridClientLoadBalancer;
import org.jetbrains.annotations.Nullable;

/**
 * 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.
 * <p>
 * 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.
 * <p>
 * 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.
 * <p>
 * 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}.
 * <p>
 * Compute client also allows fetching contents of remote log files (including backwards mode) via any of
 * the provided {@code log(...)} methods.
 * <h1 class="header">Affinity Awareness</h1>
 * 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
 * {@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.
     * <p>
     * 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.
     * <p>
     * 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<? super GridClientNode> 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.
     * <p>
     * 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<GridClientNode> 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.
     * <p>
     * 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<? super GridClientNode> 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..
     * <p>
     * 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<GridClientNode> 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> 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 <R> GridClientFuture<R> 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> 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 <R> GridClientFuture<R> 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<GridClientNode> 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<GridClientNode> nodes(Collection<UUID> 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<GridClientNode> nodes(GridClientPredicate<GridClientNode> 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<GridClientNode> 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.
     * <p>
     * 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.
     * <p>
     * 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.
     * <p>
     * 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.
     * <p>
     * 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<GridClientNode> 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.
     * <p>
     * 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.
     * <p>
     * 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.
     * <p>
     * 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.
     * <p>
     * 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<GridClientNode> 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.
     * <p>
     * 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}.
     * <p>
     * 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<GridClientNode> 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.
     * <p>
     * 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}.
     * <p>
     * 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<List<GridClientNode>> refreshTopologyAsync(boolean includeAttrs, boolean includeMetrics);

    /**
     * Sets keep binary flag for the next task execution in the current thread.
     */
    public GridClientCompute withKeepBinaries();
}