Merge pull request #5036 from vespa-engine/hakonhall/document-idempotenttaskname

Document IdempotentTask::name

1 files changed, 21 insertions, 5 deletions

diff --git a/node-admin/src/main/java/com/yahoo/vespa/hosted/node/admin/component/IdempotentTask.java b/node-admin/src/main/java/com/yahoo/vespa/hosted/node/admin/component/IdempotentTask.java
index a1cc192be2a..d2c09aae22a 100644
--- a/node-admin/src/main/java/com/yahoo/vespa/hosted/node/admin/component/IdempotentTask.java
+++ b/node-admin/src/main/java/com/yahoo/vespa/hosted/node/admin/component/IdempotentTask.java
@@ -9,16 +9,32 @@ package com.yahoo.vespa.hosted.node.admin.component;
  *  - Define task classes that implement IdempotentTask<T>.
  */
 public interface IdempotentTask<T extends TaskContext> {
-    String name();
+    /**
+     *  A short id of the task to e.g. identify the task in the log.
+     *
+     *  Prefer PascalCase and without white-space.
+     *
+     *  Example: "EnableDocker"
+     */
+    default String name() { return getClass().getSimpleName(); }
 
     /**
-     * Execute an administrative task to converge the system towards some ideal state.
+     * Execute an administrative task to converge towards some ideal state, whether it is
+     * system state or in-memory Java state.
      *
      * converge() must be idempotent: it may be called any number of times, or
-     * interrupted at any time e.g. by `kill -9`. The caller must ensure there is at
-     * most one invocation of converge() on this instance at any given time.
+     * interrupted at any time e.g. by `kill -9`.
+     *
+     * converge() is not thread safe: The caller must ensure there is at most one invocation
+     * of converge() at any given time.
      *
-     * @return false if the system was already converged, i.e. converge() was a no-op.
+     * @return false if already converged, i.e. was a no-op. A typical sequence of converge()
+     *         calls on a IdempotentTask will consist of:
+     *          - Any number of calls that throws an exception due to some issues. Assuming
+     *            no exceptions were thrown, or the issue eventually resolved itself...
+     *            (convergence failure)
+     *          - Returns true once (converged just now)
+     *          - Returns false for all further calls (already converged)
      * @throws RuntimeException (or a subclass) if the task is unable to converge.
      */
     boolean converge(T context);