Package org.apache.ignite.maintenance

## Interface MaintenanceRegistry

-     public interface MaintenanceRegistry

  `MaintenanceRegistry` is a service local to each Ignite node that allows to request performing maintenance actions on that particular node.

  When a node gets into a situation when some specific actions are required it enters the special mode called maintenance mode. In maintenance mode it doesn't join to the rest of the cluster but still allows to connect to it with control.{sh|bat} script or via JXM interface and perform needed actions.

  Implementing new task for maintenance mode requires several pieces of code.

  - First, component requiring Maintenance Mode should be able to register new `MaintenanceTask` with `registerMaintenanceTask(MaintenanceTask)` method. Registration could happen automatically (e.g. if component detects some emergency situation that requires user intervention) or by user request (e.g. for a planned maintenance that requires detaching node from the rest of the cluster).
  - Component responsible for handling this `MaintenanceTask` on startup checks if the task is registered (thus it should go to Maintenance Mode). If task is found component provides to `MaintenanceRegistry` its own implementation of `MaintenanceWorkflowCallback` interface via method `registerWorkflowCallback(String, MaintenanceWorkflowCallback)`.
  - `MaintenanceWorkflowCallback` should provide `MaintenanceRegistry` with `MaintenanceAction`s that are able to resolve maintenance task, get information about it and so on. Logic of these actions is completely up to the component providing it and depends only on particular maintenance task.
  - When maintenance task is fixed, it should be removed from `MaintenanceRegistry` with call `unregisterMaintenanceTask(String)`.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `List<MaintenanceAction<?>>` | `actionsForMaintenanceTask​(String maintenanceTaskName)` | All `MaintenanceAction`s provided by a component for `MaintenanceTask` with a given name.
    `@Nullable MaintenanceTask` | `activeMaintenanceTask​(String maintenanceTaskName)` | Returns active `MaintenanceTask` by its name.
    `boolean` | `isMaintenanceMode()` |
    `void` | `prepareAndExecuteMaintenance()` | Examine all components if they need to execute maintenance actions.
    `@Nullable MaintenanceTask` | `registerMaintenanceTask​(MaintenanceTask task)` | Method to register `MaintenanceTask` locally on the node where method is called.
    `void` | `registerMaintenanceTask​(MaintenanceTask task, UnaryOperator<MaintenanceTask> remappingFunction)` | Method to register `MaintenanceTask` locally on the node where method is called.
    `void` | `registerWorkflowCallback​(@NotNull String maintenanceTaskName, @NotNull MaintenanceWorkflowCallback cb)` | Registers `MaintenanceWorkflowCallback` for a `MaintenanceTask` with a given name.
    `default void` | `registerWorkflowCallbackIfTaskExists​(@NotNull String maintenanceTaskName, @NotNull org.apache.ignite.internal.util.lang.IgniteThrowableFunction<MaintenanceTask,​MaintenanceWorkflowCallback> workflowCalProvider)` | Call the `registerWorkflowCallback(String, MaintenanceWorkflowCallback)` if the active maintenance task with given name exists.
    `@Nullable MaintenanceTask` | `requestedTask​(String maintenanceTaskName)` |
    `boolean` | `unregisterMaintenanceTask​(String maintenanceTaskName)` | Deletes `MaintenanceTask` of given ID from maintenance registry.

- - ### Method Detail

    - #### isMaintenanceMode

          boolean isMaintenanceMode()

      Returns:
        `True` if any maintenance task was found.

    - #### registerMaintenanceTask

          @Nullable
          @Nullable MaintenanceTask registerMaintenanceTask​(MaintenanceTask task)
                                                     throws IgniteCheckedException

      Method to register `MaintenanceTask` locally on the node where method is called.

      For now it is not allowed to register new Maintenance Tasks in Maintenance Mode so this method should be called only when node operates normally. This may change in the future so it will become possible to create other maintenance tasks on node that is already entered Maintenance Mode.

      When task is registered node continues to operate normally and will enter Maintenance Mode only after restart.

      Parameters:
        `task` - `MaintenanceTask` object with maintenance information that needs to be stored to maintenance registry.
      Returns:
        Previously registered `MaintenanceTask` with the same ID or null if no tasks were registered for this ID.
      Throws:
        `IgniteCheckedException` - If handling or storing maintenance task failed.

    - #### registerMaintenanceTask

          void registerMaintenanceTask​(MaintenanceTask task,
                                       UnaryOperator<MaintenanceTask> remappingFunction)
                                throws IgniteCheckedException

      Method to register `MaintenanceTask` locally on the node where method is called. If an old task with the same name exists, applies remapping function to compute a new task. Has the same restrictions as the `registerMaintenanceTask(MaintenanceTask)`.
      Parameters:
        `task` - `MaintenanceTask` object with maintenance information that needs to be stored to maintenance registry.
        `remappingFunction` - Function to compute a task if an old `MaintenanceTask` with the same name exists.
      Throws:
        `IgniteCheckedException` - If handling or storing maintenance task failed.

    - #### unregisterMaintenanceTask

          boolean unregisterMaintenanceTask​(String maintenanceTaskName)

      Deletes `MaintenanceTask` of given ID from maintenance registry.
      Parameters:
        `maintenanceTaskName` - name of `MaintenanceTask` to be deleted.
      Returns:
        `true` if existing task has been deleted.

    - #### activeMaintenanceTask

          @Nullable
          @Nullable MaintenanceTask activeMaintenanceTask​(String maintenanceTaskName)

      Returns active `MaintenanceTask` by its name. There are active tasks only when node entered Maintenance Mode. `MaintenanceTask` becomes active when node enters Maintenance Mode and doesn't resolve the task during maintenance prepare phase.
      Parameters:
        `maintenanceTaskName` - Maintenance Task name.
      Returns:
        `MaintenanceTask` object for given name or null if no maintenance task was found.

    - #### registerWorkflowCallback

          void registerWorkflowCallback​(@NotNull
                                        @NotNull String maintenanceTaskName,
                                        @NotNull
                                        @NotNull MaintenanceWorkflowCallback cb)

      Registers `MaintenanceWorkflowCallback` for a `MaintenanceTask` with a given name. Component registered `MaintenanceTask` automatically or by user request is responsible for providing `MaintenanceRegistry` with an implementation of `MaintenanceWorkflowCallback` where registry obtains `MaintenanceAction`s to be executed for this task and does a preliminary check before starting maintenance.
      Parameters:
        `maintenanceTaskName` - name of `MaintenanceTask` this callback is registered for.
        `cb` - `MaintenanceWorkflowCallback` interface used by MaintenanceRegistry to execute maintenance steps by workflow.

    - #### actionsForMaintenanceTask

          List<MaintenanceAction<?>> actionsForMaintenanceTask​(String maintenanceTaskName)

      All `MaintenanceAction`s provided by a component for `MaintenanceTask` with a given name.
      Parameters:
        `maintenanceTaskName` - name of Maintenance Task.
      Returns:
        `List` of all available `MaintenanceAction`s for given Maintenance Task.
      Throws:
        `IgniteException` - if no Maintenance Tasks are registered for provided name.

    - #### prepareAndExecuteMaintenance

          void prepareAndExecuteMaintenance()

      Examine all components if they need to execute maintenance actions. As user may resolve some maintenance situations by hand when the node was turned off, component may find out that no maintenance is needed anymore. `Maintenance tasks` for these components are removed and their `maintenance actions` are not executed.

    - #### registerWorkflowCallbackIfTaskExists

          default void registerWorkflowCallbackIfTaskExists​(@NotNull
                                                            @NotNull String maintenanceTaskName,
                                                            @NotNull
                                                            @NotNull org.apache.ignite.internal.util.lang.IgniteThrowableFunction<MaintenanceTask,​MaintenanceWorkflowCallback> workflowCalProvider)
                                                     throws IgniteCheckedException

      Call the `registerWorkflowCallback(String, MaintenanceWorkflowCallback)` if the active maintenance task with given name exists.
      Parameters:
        `maintenanceTaskName` - name of `MaintenanceTask` this callback is registered for.
        `workflowCalProvider` - provider of `MaintenanceWorkflowCallback` which construct the callback by given task.
      Throws:
        `IgniteCheckedException`

    - #### requestedTask

          @Nullable
          @Nullable MaintenanceTask requestedTask​(String maintenanceTaskName)

      Parameters:
        `maintenanceTaskName` - Task's name.
      Returns:
        Requested maintenance task or `null`.