Package org.infinispan.manager

Interface ClusterExecutor

All Superinterfaces:
Executor
public interface ClusterExecutor extends Executor
A cluster executor that can be used to invoke a given command across the cluster. Note this executor is not tied to any cache.

This executor also implements Executor so that it may be used with methods such as CompletableFuture.runAsync(Runnable, Executor) or CompletableFuture.supplyAsync(Supplier, Executor). Unfortunately though these invocations do not have explicitly defined Serializable Runnable or Supplier arguments and manual casting is required when using a lambda. Something like the following: CompletableFuture.runAsync((Serializable && Runnable)() -> doSomething(), clusterExecutor). Although note that the submit(SerializableRunnable) does this automatically for you.

Any method that returns a value should make sure the returned value is properly serializable or else it will be replaced with a NotSerializableException

Since:
8.2
Author:
wburns

  • Method Details

    • execute

      default void execute(Runnable command)

      This command will be ran in the desired nodes, but no result is returned to notify the user of completion or failure. This command will return immediately while the runnable is processed asynchronously.

      Specified by:
      execute in interface Executor
      Parameters:
      command - the command to execute

    • execute

      default void execute(SerializableRunnable command)
      The same as Executor.execute(Runnable), except the Runnable must also implement Serializable.

      This method will be used automatically by lambdas, which prevents users from having to manually cast to a Serializable lambda.

      Parameters:
      command - the command to execute

    • submit

      CompletableFuture<Void> submit(Runnable command)
      Submits the runnable to the desired nodes and returns a CompletableFuture that will be completed when all desired nodes complete the given command

      If a node encounters an exception, the first one to respond with such an exception will set the responding future to an exceptional state passing the given exception.

      Parameters:
      command - the command to execute.
      Returns:
      a completable future that will signify the command is finished on all desired nodes when completed

    • submit

      default CompletableFuture<Void> submit(SerializableRunnable command)
      The same as submit(Runnable), except the Runnable must also implement Serializable.

      This method will be used automatically by lambdas, which prevents users from having to manually cast to a Serializable lambda.

      Parameters:
      command - the command to execute
      Returns:
      a completable future that will signify the command is finished on all desired nodes when completed

    • submitConsumer

      <V> CompletableFuture<Void> submitConsumer(Function<? super EmbeddedCacheManager,? extends V> callable, TriConsumer<? super Address,? super V,? super Throwable> triConsumer)
      Submits the given command to the desired nodes and allows for handling of results as they return. The user provides a TriConsumer which will be called back each time for each desired node. Note that these callbacks can be called from different threads at the same time. A completable future is returned to the caller used for the sole purpose of being completed when all nodes have sent responses back.

      If this cluster executor is running in failover mode via singleNodeSubmission(int) the triConsumer will be called back each time a failure occurs as well. To satisfy ordering a retry is not resubmitted until after the callback has completed.

      Note the TriConsumer is only ran on the node where the task was submitted and thus doesn't need to be serialized.

      Type Parameters:
      V - the type of the task's result
      Parameters:
      callable - the task to execute
      triConsumer - the tri-consumer to be called back upon for each node's result
      Returns:
      a completable future that will be completed after all results have been processed

    • submitConsumer

      default <V> CompletableFuture<Void> submitConsumer(SerializableFunction<? super EmbeddedCacheManager,? extends V> callable, TriConsumer<? super Address,? super V,? super Throwable> triConsumer)
      The same as submitConsumer(Function, TriConsumer), except the Callable must also implement Serializable.

      This method will be used automatically by lambdas, which prevents users from having to manually cast to a Serializable lambda.

      Type Parameters:
      V - the type of the task's result
      Parameters:
      callable - the task to execute
      triConsumer - the tri-consumer to be called back upon for each node's result
      Returns:
      a completable future that will be completed after all results have been processed

    • timeout

      ClusterExecutor timeout(long time, TimeUnit unit)
      Sets a duration after which a command will timeout. This will cause the command to return a TimeoutException as the throwable.

      The timeout parameter is used for both local and remote nodes. There are no guarantees as to whether the timed out command is interrupted.

      Parameters:
      time - the duration for the timeout
      unit - what unit the duration is in
      Returns:
      a cluster executor with a timeout applied for remote commands

    • singleNodeSubmission

      ClusterExecutor singleNodeSubmission()
      When a command is submitted it will only be submitted to one node of the available nodes, there is no strict requirements as to which node is chosen and is implementation specific. Fail over is not used with the returned executor, if you desire to use fail over you should invoke singleNodeSubmission(int) instead.
      Returns:
      a cluster executor with commands submitted to a single node

    • singleNodeSubmission

      ClusterExecutor singleNodeSubmission(int failOverCount)
      When a command is submitted it will only be submitted to one node of the available nodes, there is no strict requirements as to which node is chosen and is implementation specific. However if a command were to fail either by the command itself or via network issues then the command will fail over, that is that it will retried up to the provided number of times using an available node until an exception is not met or the number of fail over counts has been reached. If a TimeoutException is throwing, this will not be retried as this is the same exception that is thrown when using timeout(long, TimeUnit). Each time the fail over occurs any available node is chosen, there is no requirement as to which can be chosen and is left up to the implementation to decide.
      Parameters:
      failOverCount - how many times this executor will attempt a failover
      Returns:
      a cluster executor with fail over retries applied

    • allNodeSubmission

      ClusterExecutor allNodeSubmission()
      When a command is submitted it will submit this command to all of the available nodes that pass the provided filter. Fail over is not supported with this configuration. This is the default submission method.
      Returns:
      a cluster executor with commands submitted to all nodes

    • filterTargets

      ClusterExecutor filterTargets(Predicate<? super Address> predicate)
      Allows for filtering of address nodes dynamically per invocation. The predicate is applied to each member in the cluster at invocation to determine which targets to contact. Note that this method overrides any previous filtering that was done (ie. calling filterTargets(Collection)).
      Parameters:
      predicate - the dynamic predicate applied each time an invocation is done
      Returns:
      an executor with the predicate filter applied to determine which nodes are contacted

    • filterTargets

      ClusterExecutor filterTargets(ClusterExecutionPolicy policy) throws IllegalStateException
      Allows for filtering of address nodes by only allowing addresses that match the given execution policy to be used. Note this method overrides any previous filtering that was done (ie. calling filterTargets(Collection)).

      The execution policy is only used if the addresses are configured to be topology aware. That is that the TransportConfiguration.hasTopologyInfo() method returns true. If this is false this method will throw an IllegalStateException.

      Parameters:
      policy - the policy to determine which nodes can be used
      Returns:
      an executor with the execution policy applied to determine which nodes are contacted
      Throws:
      IllegalStateException - thrown if topology info isn't available

    • filterTargets

      ClusterExecutor filterTargets(ClusterExecutionPolicy policy, Predicate<? super Address> predicate) throws IllegalStateException
      Allows for filtering of address nodes dynamically per invocation. The predicate is applied to each member that is part of the execution policy. Note that this method overrides any previous filtering that was done (ie. calling filterTargets(Collection)).

      The execution policy is only used if the addresses are configured to be topology aware. That is that the TransportConfiguration.hasTopologyInfo() method returns true. If this is false this method will throw an IllegalStateException.

      Parameters:
      policy - the execution policy applied before predicate to allow only nodes in that group
      predicate - the dynamic predicate applied each time an invocation is done
      Returns:
      an executor with the execution policy and predicate both applied to determine which nodes are contacted
      Throws:
      IllegalStateException - thrown if topology info isn't available

    • filterTargets

      ClusterExecutor filterTargets(Collection<Address> addresses)
      Allows for filtering of address nodes by only allowing addresses in this collection from being contacted. Note that this method overrides any previous filtering that was done (ie. calling filterTargets(Predicate).
      Parameters:
      addresses - which nodes the executor invocations should go to
      Returns:
      an executor which will only contact nodes whose address are in the given collection

    • noFilter

      ClusterExecutor noFilter()
      Applies no filtering and will send any invocations to any/all current nodes.
      Returns:
      an executor with no filtering applied to target nodes