Document IdempotentTask::name
@@ -9,16 +9,32 @@ package com.yahoo.vespa.hosted.node.admin.component;
* - Define task classes that implement IdempotentTask&lt;T&gt;.
*/
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);
