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 Summary

Modifier and Type	Method and Description
ClusterExecutor	allNodeSubmission() When a command is submitted it will submit this command to all of the available nodes that pass the provided filter.
default void	execute(Runnable command)
default void	execute(SerializableRunnable command) The same as Executor.execute(Runnable), except the Runnable must also implement Serializable.
ClusterExecutor	filterTargets(ClusterExecutionPolicy policy) Allows for filtering of address nodes by only allowing addresses that match the given execution policy to be used.
ClusterExecutor	filterTargets(ClusterExecutionPolicy policy, Predicate<? super Address> predicate) Allows for filtering of address nodes dynamically per invocation.
ClusterExecutor	filterTargets(Collection<Address> addresses) Allows for filtering of address nodes by only allowing addresses in this collection from being contacted.
ClusterExecutor	filterTargets(Predicate<? super Address> predicate) Allows for filtering of address nodes dynamically per invocation.
ClusterExecutor	noFilter() Applies no filtering and will send any invocations to any/all current nodes.
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.
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.
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
default CompletableFuture<Void>	submit(SerializableRunnable command) The same as submit(Runnable), except the Runnable must also implement Serializable.
<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.
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.
ClusterExecutor	timeout(long time, TimeUnit unit) Sets a duration after which a command will timeout.

Method Detail

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