// 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> {
    /**
     *  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 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`.
     *
     * converge() is not thread safe: The caller must ensure there is at most one invocation
     * of converge() at any given time.
     *
     * @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);

    /**
     * Converge the task towards some some state where it can be suspended. The
     * TaskContext should provide enough to determine what kind of suspend is wanted, e.g.
     * suspension of only the task, or the task and the resources/processes it manages.
     *
     * suspendConverge() must be idempotent: it may be called any number of times, or
     * interrupted at any time e.g. by `kill -9`.
     *
     * suspendConverge() is not thread safe: The caller must ensure there is at most one
     * invocation of suspendConverge() at any given time.
     *
     * @return false if already converged, i.e. was a no-op
     * @throws RuntimeException (or a subclass) if the task is unable to suspend.
     */
    default boolean suspendConverge(T context) {
        return false;
    }
}

@@ -173,16 +173,19 @@
 %0A/**%0A * 
+%3Cp%3E
 This cla
@@ -259,15 +259,33 @@
 zed.
+%3C/p%3E
 %0A *%0A * 
+%3Cdl%3E%0A *   %3Cdt%3E
 In a
@@ -369,21 +369,31 @@
 Context:
-%0A *  
+%3C/dt%3E%0A *   %3Cdd%3E
 - Define
@@ -455,21 +455,31 @@
 onality.
+%3C/dd%3E
 %0A *  
+ 
+%3Cdd%3E
 - Define
@@ -531,16 +531,30 @@
 t;T&gt;.
+%3C/dd%3E%0A * %3C/dl%3E
 %0A */%0Apub
@@ -623,16 +623,19 @@
      *  
+%3Cp%3E
 A short 
@@ -686,16 +686,20 @@
 the log.
+%3C/p%3E
 %0A     *%0A
@@ -706,16 +706,19 @@
      *  
+%3Cp%3E
 Prefer P
@@ -751,16 +751,20 @@
 e-space.
+%3C/p%3E
 %0A     *%0A
@@ -771,16 +771,19 @@
      *  
+%3Cp%3E
 Example:
@@ -797,16 +797,20 @@
 eDocker%22
+%3C/p%3E
 %0A     */
@@ -891,16 +891,19 @@
 %0A     * 
+%3Cp%3E
 Execute 
@@ -1021,16 +1021,20 @@
 a state.
+%3C/p%3E
 %0A     *%0A
@@ -1032,32 +1032,35 @@
 %3E%0A     *%0A     * 
+%3Cp%3E
 converge() must 
@@ -1156,32 +1156,36 @@
 g. by %60kill -9%60.
+%3C/p%3E
 %0A     *%0A     * c
@@ -1183,16 +1183,19 @@
 %0A     * 
+%3Cp%3E
 converge
@@ -1303,32 +1303,36 @@
  any given time.
+%3C/p%3E
 %0A     *%0A     * @
@@ -1966,16 +1966,19 @@
 %0A     * 
+%3Cp%3E
 Converge
@@ -2000,21 +2000,16 @@
 ds some 
-some 
 state wh
@@ -2215,16 +2215,20 @@
 manages.
+%3C/p%3E
 %0A     *%0A
@@ -2226,32 +2226,35 @@
 %3E%0A     *%0A     * 
+%3Cp%3E
 suspendConverge(
@@ -2365,16 +2365,20 @@
 ill -9%60.
+%3C/p%3E
 %0A     *%0A
@@ -2380,24 +2380,27 @@
    *%0A     * 
+%3Cp%3E
 suspendConve
@@ -2526,16 +2526,20 @@
 en time.
+%3C/p%3E
 %0A     *%0A

Fix javadoc