Add docs for cluster state update task batching

core/src/main/java/org/elasticsearch/cluster/ClusterService.java

@@ -100,8 +100,22 @@ public interface ClusterService extends LifecycleComponent<ClusterService> {
     void add(@Nullable TimeValue timeout, TimeoutClusterStateListener listener);
 
     /**
-     * Submits a task that will update the cluster state, using the given config. result will communicated
-     * to the given listener
+     * Submits a cluster state update task; submitted updates will be
+     * batched across the same instance of executor. The exact batching
+     * semantics depend on the underlying implementation but a rough
+     * guideline is that if the update task is submitted while there
+     * are pending update tasks for the same executor, these update
+     * tasks will all be executed on the executor in a single batch
+     *
+     * @param source   the source of the cluster state update task
+     * @param task     the state needed for the cluster state update task
+     * @param config   the cluster state update task configuration
+     * @param executor the cluster state update task executor; tasks
+     *                 that share the same executor will be executed
+     *                 batches on this executor
+     * @param listener callback after the cluster state update task
+     *                 completes
+     * @param <T>      the type of the cluster state update task state
      */
     <T> void submitStateUpdateTask(final String source, final T task,
                                    final ClusterStateTaskConfig config,
@@ -109,7 +123,12 @@ public interface ClusterService extends LifecycleComponent<ClusterService> {
                                    final ClusterStateTaskListener listener);
 
     /**
-     * Submits a task that will update the cluster state;
+     * Submits a cluster state update task; unlike {@link #submitStateUpdateTask(String, Object, ClusterStateTaskConfig, ClusterStateTaskExecutor, ClusterStateTaskListener)},
+     * submitted updates will not be batched.
+     *
+     * @param source     the source of the cluster state update task
+     * @param updateTask the full context for the cluster state update
+     *                   task
      */
     void submitStateUpdateTask(final String source, final ClusterStateUpdateTask updateTask);
 

core/src/main/java/org/elasticsearch/cluster/ClusterStateTaskConfig.java

@@ -22,26 +22,54 @@ import org.elasticsearch.common.Nullable;
 import org.elasticsearch.common.Priority;
 import org.elasticsearch.common.unit.TimeValue;
 
-public interface ClusterStateTaskConfig {
-
 /**
-     * If the cluster state update task wasn't processed by the provided timeout, call
-     * {@link ClusterStateTaskListener#onFailure(String, Throwable)}. May return null to indicate no timeout is needed (default).
+ * Cluster state update task configuration for timeout and priority
+ */
+public interface ClusterStateTaskConfig {
+    /**
+     * The timeout for this cluster state update task configuration. If
+     * the cluster state update task isn't processed within this
+     * timeout, the associated {@link ClusterStateTaskListener#onFailure(String, Throwable)}
+     * is invoked.
+     *
+     * @return the timeout, or null if one is not set
      */
     @Nullable
     TimeValue timeout();
 
+    /**
+     * The {@link Priority} for this cluster state update task configuration.
+     *
+     * @return the priority
+     */
     Priority priority();
 
+    /**
+     * Build a cluster state update task configuration with the
+     * specified {@link Priority} and no timeout.
+     *
+     * @param priority the priority for the associated cluster state
+     *                 update task
+     * @return the resulting cluster state update task configuration
+     */
     static ClusterStateTaskConfig build(Priority priority) {
         return new Basic(priority, null);
     }
 
+    /**
+     * Build a cluster state update task configuration with the
+     * specified {@link Priority} and timeout.
+     *
+     * @param priority the priority for the associated cluster state
+     *                 update task
+     * @param timeout  the timeout for the associated cluster state
+     *                 update task
+     * @return the result cluster state update task configuration
+     */
     static ClusterStateTaskConfig build(Priority priority, TimeValue timeout) {
         return new Basic(priority, timeout);
     }
 
-
     class Basic implements ClusterStateTaskConfig {
         final TimeValue timeout;
         final Priority priority;

core/src/main/java/org/elasticsearch/cluster/ClusterStateTaskListener.java

@@ -18,8 +18,6 @@
  */
 package org.elasticsearch.cluster;
 
-import org.elasticsearch.common.util.concurrent.EsRejectedExecutionException;
-
 import java.util.List;
 
 public interface ClusterStateTaskListener {
@@ -42,7 +40,4 @@ public interface ClusterStateTaskListener {
      */
     default void clusterStateProcessed(String source, ClusterState oldState, ClusterState newState) {
     }
-
-    ;
-
 }