// Copyright 2018 Yahoo Holdings. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.vespa.hosted.node.admin.component;

/**
 * This class is thread unsafe: All method calls MUST be exclusive and serialized.
 *
 * In a specialized environment it is possible to provide a richer context than TaskContext:
 *  - Define a subclass T of TaskContext with the additional functionality.
 *  - Define task classes that implement IdempotentTask&lt;T&gt;.
 */
public interface IdempotentTask<T extends TaskContext> {
    String name();

    /**
     * Execute an administrative task to converge the system towards some ideal 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.
     *
     * @return false if the system was already converged, i.e. converge() was a no-op.
     * @throws RuntimeException (or a subclass) if the task is unable to converge.
     */
    boolean converge(T context);
}

@@ -560,111 +560,387 @@
     
-String name();%0A%0A    /**%0A     * Execute an administrative task to converge the system towards some ideal
+/**%0A     *  A short id of the task to e.g. identify the task in the log.%0A     *%0A     *  Prefer PascalCase and without white-space.%0A     *%0A     *  Example: %22EnableDocker%22%0A     */%0A    default String name() %7B return getClass().getSimpleName(); %7D%0A%0A    /**%0A     * Execute an administrative task to converge towards some ideal state, whether it is%0A     * system state or in-memory Java
  sta
@@ -1078,16 +1078,61 @@
 ill -9%60.
+%0A     *%0A     * converge() is not thread safe:
  The cal
@@ -1158,23 +1158,16 @@
 re is at
-%0A     *
  most on
@@ -1178,16 +1178,23 @@
 vocation
+%0A     *
  of conv
@@ -1203,25 +1203,8 @@
 ge()
- on this instance
  at 
@@ -1254,70 +1254,486 @@
  if 
-the system was already converged, i.e. converge() was a no-op.
+already converged, i.e. was a no-op. A typical sequence of converge()%0A     *         calls on a IdempotentTask will consist of:%0A     *          - Any number of calls that throws an exception due to some issues. Assuming%0A     *            no exceptions were thrown, or the issue eventually resolved itself...%0A     *            (convergence failure)%0A     *          - Returns true once (converged just now)%0A     *          - Returns false for all further calls (already converged)
 %0A   

Document IdempotentTask::name