Package org.elasticsearch.cluster

Interface ClusterStateTaskExecutor<T extends ClusterStateTaskListener>

Type Parameters:
T - The type of tasks to execute.
All Known Implementing Classes:
DesiredNodesClusterStateTaskExecutor, JoinTaskExecutor, NodeRemovalClusterStateTaskExecutor, ShardStateAction.ShardFailedClusterStateTaskExecutor, ShardStateAction.ShardStartedClusterStateTaskExecutor
public interface ClusterStateTaskExecutor<T extends ClusterStateTaskListener>
An executor for batches of cluster state update tasks.

  • Method Details

    • execute

      ClusterState execute(ClusterState currentState, List<ClusterStateTaskExecutor.TaskContext<T>> taskContexts) throws Exception
      Update the cluster state based on the current state and the given tasks. Return the *same instance* if no update should be published.

      If this method throws an exception then the cluster state is unchanged and every task's ClusterStateTaskListener.onFailure(java.lang.Exception) method is called.

      A common implementation pattern is to iterate through the tasks, constructing a new and updated ClusterState for each one. This works ok but beware that constructing a whole new ClusterState can be somewhat expensive, and there may sometimes be surprisingly many tasks to process in the batch. If it's possible to accumulate the effects of the tasks at a lower level then you should do that instead.

      Parameters:
      currentState - The initial cluster state on which the tasks should be executed.
      taskContexts - A ClusterStateTaskExecutor.TaskContext for each task in the batch. Implementations must complete every context in the list.
      Returns:
      The resulting cluster state after executing all the tasks. If {code currentState} is returned then no update is published.
      Throws:
      Exception

    • runOnlyOnMaster

      default boolean runOnlyOnMaster()
      Returns:
      true iff this executor should only run on the elected master.

    • clusterStatePublished

      default void clusterStatePublished(ClusterState newClusterState)
      Callback invoked after new cluster state is published. Note that this method is not invoked if the cluster state was not updated. Note that this method will be executed using system context.
      Parameters:
      newClusterState - The new state which was published.

    • describeTasks

      default String describeTasks(List<T> tasks)
      Builds a concise description of a list of tasks (to be used in logging etc.). Note that the tasks given are not necessarily the same as those that will be passed to execute(ClusterState, List). but are guaranteed to be a subset of them. This method can be called multiple times with different lists before execution.
      Parameters:
      tasks - the tasks to describe.
      Returns:
      A string which describes the batch of tasks.

    • unbatched

      static <T extends ClusterStateUpdateTask> ClusterStateTaskExecutor<T> unbatched()
      Creates a task executor that only executes a single task. Use a new instance of this executor to specifically submit a cluster state update task that should be executed in isolation and not be batched with other state updates.

      This executor exists for legacy reasons but is forbidden in new production code because unbatched tasks are a source of performance and stability bugs. You should instead implement your update logic in a dedicated ClusterStateTaskExecutor which is reused across multiple task instances. The task itself is typically just a collection of parameters consumed by the executor, together with any listeners to be notified when execution completes.

      Type Parameters:
      T - The type of task to execute
      Returns:
      A single-use executor to execute a single task.