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 MaintenanceActions 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

Modifier and Type	Method and Description
List<MaintenanceAction<?>>	actionsForMaintenanceTask(String maintenanceTaskName) All MaintenanceActions 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 MaintenanceActions 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 MaintenanceActions provided by a component for MaintenanceTask with a given name.

Parameters:

maintenanceTaskName - name of Maintenance Task.

Returns:

List of all available MaintenanceActions 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.