Package com.evolveum.midpoint.task.api

Interface TaskManager

public interface TaskManager

Task Manager Interface.

Status: public Stability: DRAFT

Version:

0.1

Author:

Radovan Semancik, Pavol Mederly

Task manager provides controls task execution, coordination, distribution and failover between nodes, etc.

This interface is just a basic framework for task management now. Although we hope that this is roughly almost final shape of the interface, the implementation is not complete and some changes may happen.

This definition specifies interface of Task Manager - a component that controls (asynchronous) task execution.

The task manager can store the task for later execution, switch them to background resume execution of a task from a different node, etc. Generally speaking, task manager provides operation to manage tasks in the whole midPoint cluster of IDM nodes.

This interface partially adheres to [Common Interface Concepts], but the goals are slightly different. This interface should be conveniently used also for tasks that are not persistent (synchronous short tasks). Therefore some methods are made much more user-friendly while tolerating some redundancy in the interface.

Field Summary

Fields

Modifier and Type	Field	Description
static long	DO_NOT_STOP
static long	DO_NOT_WAIT
static long	WAIT_INDEFINITELY

Method Summary

Modifier and Type	Method	Description
String	addTask(PrismObject<TaskType> taskPrism, RepoAddOptions options, OperationResult parentResult)
default String	addTask(PrismObject<TaskType> taskPrism, OperationResult parentResult)	Add new task.
void	cleanupNodes(DeadNodeCleanupPolicyType deadNodesPolicy, RunningTask task, OperationResult opResult)	Deletes dead nodes, i.e.
void	cleanupTasks(CleanupPolicyType closedTasksPolicy, RunningTask task, OperationResult opResult)	Deletes obsolete tasks, as specified in the policy.
<T extends ObjectType> int	countObjects(Class<T> type, ObjectQuery query, OperationResult parentResult)	Counts the number of objects.
TaskHandler	createAndRegisterPartitioningTaskHandler(String handlerUri, Function<Task,TaskPartitionsDefinition> partitioningStrategy)
RunningTask	createFakeRunningTask(Task task)	Use only for tests.
Task	createTaskInstance()	Creates new transient, running task instance.
Task	createTaskInstance(PrismObject<TaskType> taskPrism, OperationResult parentResult)	Creates task instance from the XML task representation.
Task	createTaskInstance(PrismObject<TaskType> taskPrism, String operationName, OperationResult parentResult)	Creates task instance from the XML task representation.
Task	createTaskInstance(String operationName)	Creates new transient, running task instance.
boolean	deactivateServiceThreads(long timeToWait, OperationResult parentResult)	Deactivates service threads (temporarily).
void	deleteNode(String nodeOid, OperationResult result)	Deletes a node from the repository.
void	deleteTask(String oid, OperationResult parentResult)	Deletes task with provided OID.
void	deleteWorkersAndWorkState(String rootTaskOid, boolean deleteWorkers, long subtasksWaitTime, OperationResult parentResult)
List<String>	getAllTaskCategories()	Gets a list of all task categories.
CacheConfigurationManager	getCacheConfigurationManager()
TracingProfileType	getGlobalTracingProfile()
Collection<TracingRootType>	getGlobalTracingRequestedFor()
TaskHandler	getHandler(String handlerUri)
String	getHandlerUriForCategory(String category)	Returns a default handler URI for a given task category.
RunningTask	getLocallyRunningTaskByIdentifier(String lightweightIdentifier)	Returns locally-run task by identifier.
Collection<Task>	getLocallyRunningTasks(OperationResult parentResult)	Returns tasks that currently run on this node.
NodeType	getLocalNode()
SchedulerInformationType	getLocalSchedulerInformation(OperationResult parentResult)	Returns the local scheduler information.
Long	getNextRunStartTime(String oid, OperationResult result)	Gets next scheduled execution time for a given task.
String	getNodeId()	Returns identifier for current node.
<T extends ObjectType> PrismObject<T>	getObject(Class<T> clazz, String oid, Collection<SelectorOptions<GetOperationOptions>> options, OperationResult result)	TODO
String	getRunningTasksThreadsDump(OperationResult parentResult)
boolean	getServiceThreadsActivationState()	Returns true if the service threads are running.
Task	getTask(String taskOid, OperationResult parentResult)	Returns a task with specified OID.
Task	getTask(String taskOid, Collection<SelectorOptions<GetOperationOptions>> options, OperationResult parentResult)	BEWARE: This method does not obey taskManager-related options, e.g.
Task	getTaskByIdentifier(String identifier, OperationResult parentResult)	Returns a task with a given identifier.
String	getTaskThreadsDump(String taskOid, OperationResult parentResult)
PrismObject<TaskType>	getTaskTypeByIdentifier(String identifier, Collection<SelectorOptions<GetOperationOptions>> options, OperationResult parentResult)	TODO
Task	getTaskWithResult(String taskOid, OperationResult parentResult)
Tracer	getTracer()
Object	getWorkStateManager()
boolean	isCheckingIn(NodeType node)
boolean	isClustered()
boolean	isCurrentNode(PrismObject<NodeType> node)	Checks whether supplied node is the current node.
boolean	isDynamicProfilingEnabled()
boolean	isLocalNodeClusteringEnabled()	EXPERIMENTAL.
boolean	isTracingOverridden()
boolean	isUpAndAlive(NodeType node)
void	modifyTask(String oid, Collection<? extends ItemDelta> modifications, OperationResult parentResult)	Modifies task using relative change description.
ObjectQuery	narrowQueryForWorkBucket(ObjectQuery query, Class<? extends ObjectType> type, Function<ItemPath,ItemDefinition<?>> itemDefinitionProvider, Task workerTask, WorkBucketType workBucket, OperationResult opResult)	TODO.
void	onSystemStarted()	Called when the whole application is initialized.
void	onTaskCreate(String oid, OperationResult parentResult)	This is a signal to task manager that a new task was created in the repository.
void	onTaskDelete(String oid, OperationResult parentResult)	This is a signal to task manager that a task was removed from the repository.
void	pauseTask(Task task, TaskWaitingReason reason, OperationResult parentResult)	Puts a runnable/running task into WAITING state.
void	postInit(OperationResult result)	Currently not used.
void	reactivateServiceThreads(OperationResult parentResult)	Re-activates the service threads after they have been deactivated.
void	reconcileWorkers(String coordinatorOid, WorkersReconciliationOptions options, OperationResult parentResult)
String	recordRunningTasksThreadsDump(String cause, OperationResult parentResult)
String	recordTaskThreadsDump(String taskOid, String cause, OperationResult parentResult)
void	registerAdditionalHandlerUri(String uri, TaskHandler handler)	Registers additional handler URI for a given handler.
void	registerHandler(String uri, TaskHandler handler)	Registers a handler for a specified handler URI.
void	registerTaskDeletionListener(TaskDeletionListener listener)
void	registerTaskListener(TaskListener taskListener)	Registers a task listener that will be notified on task-related events.
void	removeGlobalTracingOverride()
void	resumeTask(Task task, OperationResult parentResult)	Resume suspended task.
void	resumeTask(String taskOid, OperationResult parentResult)
void	resumeTasks(Collection<String> taskOids, OperationResult parentResult)	Resume suspended tasks.
void	resumeTaskTree(String coordinatorOid, OperationResult parentResult)
void	scheduleCoordinatorAndWorkersNow(String coordinatorOid, OperationResult parentResult)	TODO is this method really necessary?
void	scheduleTaskNow(Task task, OperationResult parentResult)	Schedules a RUNNABLE task or CLOSED single-run task to be run immediately.
void	scheduleTaskNow(String taskOid, OperationResult parentResult)	The same as above.
void	scheduleTasksNow(Collection<String> taskOids, OperationResult parentResult)	Schedules RUNNABLE/CLOSED tasks to be run immediately.
<T extends ObjectType> SearchResultList<PrismObject<T>>	searchObjects(Class<T> type, ObjectQuery query, Collection<SelectorOptions<GetOperationOptions>> options, OperationResult parentResult)	Notes: Implemented options are: - noFetch: it causes task manager NOT to ask remote nodes about node/task status.
<T extends ObjectType> SearchResultMetadata	searchObjectsIterative(Class<T> type, ObjectQuery query, Collection<SelectorOptions<GetOperationOptions>> options, ResultHandler<T> handler, OperationResult parentResult)
void	setFreeBucketWaitInterval(long value)
void	setGlobalTracingOverride(Collection<TracingRootType> roots, TracingProfileType profile)
void	setWebContextPath(String path)	EXPERIMENTAL.
void	shutdown()	Shuts down current node.
void	startLocalScheduler(OperationResult parentResult)
void	startScheduler(String nodeIdentifier, OperationResult parentResult)	Starts the scheduler on a given node.
void	startSchedulers(Collection<String> nodeIdentifiers, OperationResult parentResult)
void	stopLocalScheduler(OperationResult parentResult)
void	stopLocalTask(String oid, OperationResult parentResult)
void	stopScheduler(String nodeIdentifier, OperationResult parentResult)	Stops the scheduler on a given node.
void	stopSchedulers(Collection<String> nodeIdentifiers, OperationResult parentResult)
boolean	stopSchedulersAndTasks(Collection<String> nodeIdentifiers, long waitTime, OperationResult parentResult)	Stops a set of schedulers (on their nodes) and tasks that are executing on these nodes.
boolean	suspendAndCloseTaskQuietly(Task task, long waitTime, OperationResult parentResult)	After stopping a task puts it into CLOSED state (not SUSPENDED one).
void	suspendAndDeleteTask(String taskOid, long suspendTimeout, boolean alsoSubtasks, OperationResult parentResult)	The same as above, but limited to a single task and throws the first exception encountered.
void	suspendAndDeleteTasks(Collection<String> taskOidList, long suspendTimeout, boolean alsoSubtasks, OperationResult parentResult)	Suspends tasks and deletes them.
boolean	suspendTask(Task task, long waitTime, OperationResult parentResult)	Suspends a task.
boolean	suspendTask(String taskOid, long waitTime, OperationResult parentResult)	Suspends a task.
boolean	suspendTaskQuietly(Task task, long waitTime, OperationResult parentResult)	Suspends a task.
boolean	suspendTasks(Collection<String> taskOids, long waitForStop, OperationResult parentResult)	Suspends a set of tasks.
boolean	suspendTaskTree(String coordinatorOid, long waitTime, OperationResult parentResult)
void	switchToBackground(Task task, OperationResult parentResult)	Switches the provided task to background, making it asynchronous.
void	synchronizeTasks(OperationResult parentResult)	Synchronizes information in midPoint repository and task scheduling database.
void	unpauseTask(Task task, OperationResult parentResult)	Puts a WAITING task back into RUNNABLE state.
void	unregisterTaskListener(TaskListener taskListener)	Unregisters a task listener.
ParseException	validateCronExpression(String cron)	Validates a cron expression for scheduling tasks - without context of any given task.
void	waitForTransientChildren(RunningTask task, OperationResult result)

Field Detail

WAIT_INDEFINITELY

static final long WAIT_INDEFINITELY

See Also:

Constant Field Values

DO_NOT_WAIT

static final long DO_NOT_WAIT

See Also:

Constant Field Values

DO_NOT_STOP

static final long DO_NOT_STOP

See Also:

Constant Field Values

Method Detail

searchObjects

<T extends ObjectType> SearchResultList<PrismObject<T>> searchObjects(Class<T> type,
                                                                      ObjectQuery query,
                                                                      Collection<SelectorOptions<GetOperationOptions>> options,
                                                                      OperationResult parentResult)
                                                               throws SchemaException

Notes: Implemented options are: - noFetch: it causes task manager NOT to ask remote nodes about node/task status. - (for tasks) TaskType.F_NEXT_RUN_START_TIMESTAMP: it can be used to disable asking Quartz for next run start time - other options that are passed down to repository

Throws:

SchemaException

searchObjectsIterative

<T extends ObjectType> SearchResultMetadata searchObjectsIterative(Class<T> type,
                                                                   ObjectQuery query,
                                                                   Collection<SelectorOptions<GetOperationOptions>> options,
                                                                   ResultHandler<T> handler,
                                                                   OperationResult parentResult)
                                                            throws SchemaException

Throws:

SchemaException

countObjects

<T extends ObjectType> int countObjects(Class<T> type,
                                        ObjectQuery query,
                                        OperationResult parentResult)
                                 throws SchemaException

Counts the number of objects.

Throws:

SchemaException

waitForTransientChildren

void waitForTransientChildren(RunningTask task,
                              OperationResult result)

getObject

<T extends ObjectType> PrismObject<T> getObject(Class<T> clazz,
                                                String oid,
                                                Collection<SelectorOptions<GetOperationOptions>> options,
                                                OperationResult result)
                                         throws ObjectNotFoundException,
                                                SchemaException

TODO

Throws:

ObjectNotFoundException

SchemaException

addTask

default String addTask(PrismObject<TaskType> taskPrism,
                       OperationResult parentResult)
                throws ObjectAlreadyExistsException,
                       SchemaException

Add new task. The OID provided in the task may be empty. In that case the OID will be assigned by the implementation of this method and it will be provided as return value. This operation should fail if such object already exists (if object with the provided OID already exists). The operation may fail if provided OID is in an unusable format for the storage. Generating own OIDs and providing them to this method is not recommended for normal operation. Should be atomic. Should not allow creation of two objects with the same OID (even if created in parallel). The operation may fail if the object to be created does not conform to the underlying schema of the storage system or the schema enforced by the implementation.

Parameters:

taskPrism - object to create

parentResult - parent OperationResult (in/out)

Returns:

OID assigned to the created object

Throws:

ObjectAlreadyExistsException - object with specified identifiers already exists, cannot add

SchemaException - error dealing with storage schema, e.g. schema violation

IllegalArgumentException - wrong OID format, etc.

addTask

String addTask(PrismObject<TaskType> taskPrism,
               RepoAddOptions options,
               OperationResult parentResult)
        throws ObjectAlreadyExistsException,
               SchemaException

Throws:

ObjectAlreadyExistsException

SchemaException

modifyTask

void modifyTask(String oid,
                Collection<? extends ItemDelta> modifications,
                OperationResult parentResult)
         throws ObjectNotFoundException,
                SchemaException,
                ObjectAlreadyExistsException

Modifies task using relative change description. Must fail if object with provided OID does not exists. Must fail if any of the described changes cannot be applied. Should be atomic. If two or more modify operations are executed in parallel, the operations should be merged. In case that the operations are in conflict (e.g. one operation adding a value and the other removing the same value), the result is not deterministic. The operation may fail if the modified object does not conform to the underlying schema of the storage system or the schema enforced by the implementation. HOWEVER, the preferred way of modifying tasks is to use methods in Task interface.

Parameters:

oid - OID of the task to be changed

modifications - specification of object changes

parentResult - parent OperationResult (in/out)

Throws:

ObjectNotFoundException - specified object does not exist

SchemaException - resulting object would violate the schema

IllegalArgumentException - wrong OID format, described change is not applicable

ObjectAlreadyExistsException

deleteTask

void deleteTask(String oid,
                OperationResult parentResult)
         throws ObjectNotFoundException,
                SchemaException

Deletes task with provided OID. Must fail if object with specified OID does not exists. Should be atomic. BEWARE: call this method only if you are pretty sure the task is not running. Otherwise the running thread will complain when it will try to store task result into repo. (I.e. it is a good practice to suspend the task before deleting.)

Parameters:

oid - OID of object to delete

parentResult - parent OperationResult (in/out)

Throws:

ObjectNotFoundException - specified object does not exist

IllegalArgumentException - wrong OID format, described change is not applicable

SchemaException

createTaskInstance

Task createTaskInstance()

Creates new transient, running task instance. This is fact creates usual "synchronous" task. This is useful for normal day-to-day tasks that are either synchronous or start as a synchronous and are switched to asynchronous task later.

Returns:

transient, running task instance

createTaskInstance

@NotNull
Task createTaskInstance(PrismObject<TaskType> taskPrism,
                        OperationResult parentResult)
                 throws SchemaException

Creates task instance from the XML task representation.

Parameters:

taskPrism - JAXB (XML) representation of the task

Returns:

new Java representation of the task

Throws:

SchemaException - The provided taskType is not compliant to schema

createTaskInstance

Task createTaskInstance(String operationName)

Creates new transient, running task instance. This is fact creates usual "synchronous" task. This is useful for normal day-to-day tasks that are either synchronous or start as a synchronous and are switched to asynchronous task later. The result inside the task will be initialized with specified operation name.

Parameters:

operationName - operation name to use as a root for new result in task

Returns:

new Java representation of the task

createTaskInstance

@NotNull
Task createTaskInstance(PrismObject<TaskType> taskPrism,
                        String operationName,
                        OperationResult parentResult)
                 throws SchemaException

Creates task instance from the XML task representation. If there is not a result inside the task, it will create the result with specified operation name.

Parameters:

taskPrism - Prism representation of the task

operationName - operation name to use as a root for new result in task

Returns:

new Java representation of the task

Throws:

SchemaException - The provided taskType is not compliant to schema

getTask

@NotNull
Task getTask(String taskOid,
             OperationResult parentResult)
      throws ObjectNotFoundException,
             SchemaException

Returns a task with specified OID. This operation will look up a task instance in the repository and return it in a form of Task object. Works only on persistent tasks.

Parameters:

taskOid - OID of the persistent task.

Returns:

Task instance

Throws:

SchemaException - error dealing with resource schema

ObjectNotFoundException - wrong OID format, etc.

getTaskWithResult

@NotNull
Task getTaskWithResult(String taskOid,
                       OperationResult parentResult)
                throws ObjectNotFoundException,
                       SchemaException

Throws:

ObjectNotFoundException

SchemaException

getTask

@NotNull
Task getTask(String taskOid,
             Collection<SelectorOptions<GetOperationOptions>> options,
             OperationResult parentResult)
      throws ObjectNotFoundException,
             SchemaException

BEWARE: This method does not obey taskManager-related options, e.g. retrieve(F_SUBTASK). If you need to apply them, use getTaskObject instead. See MID-5374.

Throws:

ObjectNotFoundException

SchemaException

getTaskByIdentifier

@NotNull
Task getTaskByIdentifier(String identifier,
                         OperationResult parentResult)
                  throws SchemaException,
                         ObjectNotFoundException

Returns a task with a given identifier. (NOTE: Currently finds only persistent tasks. In the future, we plan to support searching for transient tasks as well.)

Parameters:

identifier - task identifier to search for

Throws:

SchemaException

ObjectNotFoundException

getTaskTypeByIdentifier

@NotNull
PrismObject<TaskType> getTaskTypeByIdentifier(String identifier,
                                              Collection<SelectorOptions<GetOperationOptions>> options,
                                              OperationResult parentResult)
                                       throws SchemaException,
                                              ObjectNotFoundException

TODO

Throws:

SchemaException

ObjectNotFoundException

cleanupTasks

void cleanupTasks(CleanupPolicyType closedTasksPolicy,
                  RunningTask task,
                  OperationResult opResult)
           throws SchemaException

Deletes obsolete tasks, as specified in the policy. This method removes whole task trees, i.e. not single tasks. A task tree is deleted if the root task is closed (assuming all tasks in the tree are closed) and was closed before at least specified time.

Parameters:

closedTasksPolicy - specifies which tasks are to be deleted, e.g. how old they have to be

task - task, within which context the cleanup executes (used to test for interruptions)

Throws:

SchemaException

cleanupNodes

void cleanupNodes(DeadNodeCleanupPolicyType deadNodesPolicy,
                  RunningTask task,
                  OperationResult opResult)
           throws SchemaException

Deletes dead nodes, i.e. ones that were not checked-in for a given time period.

Throws:

SchemaException

onTaskCreate

void onTaskCreate(String oid,
                  OperationResult parentResult)

This is a signal to task manager that a new task was created in the repository. Task manager can react to it e.g. by creating shadow quartz job and trigger.

onTaskDelete

void onTaskDelete(String oid,
                  OperationResult parentResult)

This is a signal to task manager that a task was removed from the repository. Task manager can react to it e.g. by removing shadow quartz job and trigger.

getLocallyRunningTasks

Collection<Task> getLocallyRunningTasks(OperationResult parentResult)

Returns tasks that currently run on this node. E.g. tasks that have allocated threads. Does not look primarily into repository, but looks at runtime structures describing the task execution.

Returns:

tasks that currently run on this node.

getLocalSchedulerInformation

SchedulerInformationType getLocalSchedulerInformation(OperationResult parentResult)

Returns the local scheduler information.

stopLocalScheduler

void stopLocalScheduler(OperationResult parentResult)

startLocalScheduler

void startLocalScheduler(OperationResult parentResult)

stopLocalTask

void stopLocalTask(String oid,
                   OperationResult parentResult)

getLocallyRunningTaskByIdentifier

RunningTask getLocallyRunningTaskByIdentifier(String lightweightIdentifier)

Returns locally-run task by identifier. Returned instance is the same as is being used to carrying out operations. SO USE WITH CARE. EXPERIMENTAL. Should be replaced by something like "get operational information".

suspendTasks

boolean suspendTasks(Collection<String> taskOids,
                     long waitForStop,
                     OperationResult parentResult)

Suspends a set of tasks. Sets their execution status to SUSPENDED. Stops their execution (unless doNotStop is set).

Parameters:

taskOids - a collection of OIDs of tasks that have to be suspended

waitForStop - how long (in milliseconds) to wait for stopping the execution of tasks; WAIT_INDEFINITELY means wait indefinitely :) DO_NOT_WAIT means stop the tasks, but do not wait for finishing their execution DO_NOT_STOP means do not try to stop the task execution. Tasks will only be put into SUSPENDED state, and their executions (if any) will be left as they are. Use this option only when you know what you're doing.

Returns:

true if all the tasks were stopped, false if some tasks continue to run or if stopping was not requested (DO_NOT_STOP option) On error conditions does NOT throw an exception.

suspendTaskQuietly

boolean suspendTaskQuietly(Task task,
                           long waitTime,
                           OperationResult parentResult)
                    throws ObjectAlreadyExistsException,
                           ObjectNotFoundException,
                           SchemaException

Suspends a task. The same as above.

Throws:

ObjectAlreadyExistsException

ObjectNotFoundException

SchemaException

suspendTask

boolean suspendTask(Task task,
                    long waitTime,
                    OperationResult parentResult)
             throws ObjectNotFoundException,
                    SchemaException

Suspends a task. The same as above except that on error condition it DOES throw appropriate exception.

Throws:

ObjectNotFoundException

SchemaException

suspendTask

boolean suspendTask(String taskOid,
                    long waitTime,
                    OperationResult parentResult)
             throws SchemaException,
                    ObjectNotFoundException

Suspends a task. The same as above except that on error condition it DOES throw appropriate exception.

Throws:

SchemaException

ObjectNotFoundException

suspendAndCloseTaskQuietly

boolean suspendAndCloseTaskQuietly(Task task,
                                   long waitTime,
                                   OperationResult parentResult)

After stopping a task puts it into CLOSED state (not SUSPENDED one).

suspendAndDeleteTasks

void suspendAndDeleteTasks(Collection<String> taskOidList,
                           long suspendTimeout,
                           boolean alsoSubtasks,
                           OperationResult parentResult)

Suspends tasks and deletes them.

Parameters:

taskOidList - List of task OIDs to be suspended and deleted.

suspendTimeout - How long (in milliseconds) to wait for task suspension before proceeding with deletion.

alsoSubtasks - Should also subtasks be deleted?

suspendAndDeleteTask

void suspendAndDeleteTask(String taskOid,
                          long suspendTimeout,
                          boolean alsoSubtasks,
                          OperationResult parentResult)
                   throws SchemaException,
                          ObjectNotFoundException

The same as above, but limited to a single task and throws the first exception encountered.

Throws:

SchemaException

ObjectNotFoundException

resumeTask

void resumeTask(Task task,
                OperationResult parentResult)
         throws ObjectNotFoundException,
                SchemaException

Resume suspended task.

Parameters:

task - task instance to be resumed.

Throws:

ObjectNotFoundException

SchemaException

resumeTask

void resumeTask(String taskOid,
                OperationResult parentResult)
         throws ObjectNotFoundException,
                SchemaException

Throws:

ObjectNotFoundException

SchemaException

resumeTasks

void resumeTasks(Collection<String> taskOids,
                 OperationResult parentResult)

Resume suspended tasks.

Parameters:

taskOids - a collection of OIDs of tasks that have to be resumed

suspendTaskTree

boolean suspendTaskTree(String coordinatorOid,
                        long waitTime,
                        OperationResult parentResult)
                 throws SchemaException,
                        ObjectNotFoundException

Throws:

SchemaException

ObjectNotFoundException

resumeTaskTree

void resumeTaskTree(String coordinatorOid,
                    OperationResult parentResult)
             throws SchemaException,
                    ObjectNotFoundException

Throws:

SchemaException

ObjectNotFoundException

reconcileWorkers

void reconcileWorkers(String coordinatorOid,
                      WorkersReconciliationOptions options,
                      OperationResult parentResult)
               throws SchemaException,
                      ObjectNotFoundException,
                      ObjectAlreadyExistsException

Throws:

SchemaException

ObjectNotFoundException

ObjectAlreadyExistsException

deleteWorkersAndWorkState

void deleteWorkersAndWorkState(String rootTaskOid,
                               boolean deleteWorkers,
                               long subtasksWaitTime,
                               OperationResult parentResult)
                        throws SchemaException,
                               ObjectNotFoundException

Throws:

SchemaException

ObjectNotFoundException

scheduleCoordinatorAndWorkersNow

void scheduleCoordinatorAndWorkersNow(String coordinatorOid,
                                      OperationResult parentResult)
                               throws SchemaException,
                                      ObjectNotFoundException

TODO is this method really necessary?

Throws:

SchemaException

ObjectNotFoundException

pauseTask

void pauseTask(Task task,
               TaskWaitingReason reason,
               OperationResult parentResult)
        throws ObjectNotFoundException,
               SchemaException

Puts a runnable/running task into WAITING state.

Parameters:

task - a runnable/running task

reason - the reason for waiting, which is stored into the repository

Throws:

ObjectNotFoundException

SchemaException

unpauseTask

void unpauseTask(Task task,
                 OperationResult parentResult)
          throws ObjectNotFoundException,
                 SchemaException,
                 PreconditionViolationException

Puts a WAITING task back into RUNNABLE state.

Throws:

ObjectNotFoundException

SchemaException

PreconditionViolationException

switchToBackground

void switchToBackground(Task task,
                        OperationResult parentResult)

Switches the provided task to background, making it asynchronous. The provided task will be "released" to other nodes to execute. There is no guarantee that the task will execute on the same node that called the switchToBackground() method.

Parameters:

task - task to switch to background.

scheduleTasksNow

void scheduleTasksNow(Collection<String> taskOids,
                      OperationResult parentResult)

Schedules RUNNABLE/CLOSED tasks to be run immediately. (If a task will really start immediately, depends e.g. on whether a scheduler is started, whether there are available threads, and so on.)

Parameters:

taskOids - a collection of OIDs of tasks that have to be scheduled Proceeds quietly - i.e. on exception it simply logs it.

scheduleTaskNow

void scheduleTaskNow(Task task,
                     OperationResult parentResult)
              throws SchemaException,
                     ObjectNotFoundException

Schedules a RUNNABLE task or CLOSED single-run task to be run immediately. (If the task will really start immediately, depends e.g. on whether a scheduler is started, whether there are available threads, and so on.) Throws appropriate exceptions.

Throws:

SchemaException

ObjectNotFoundException

scheduleTaskNow

void scheduleTaskNow(String taskOid,
                     OperationResult parentResult)
              throws SchemaException,
                     ObjectNotFoundException

The same as above.

Throws:

SchemaException

ObjectNotFoundException

getNodeId

String getNodeId()

Returns identifier for current node.

isCurrentNode

boolean isCurrentNode(PrismObject<NodeType> node)

Checks whether supplied node is the current node.

Returns:

true if node is the current node

deleteNode

void deleteNode(String nodeOid,
                OperationResult result)
         throws SchemaException,
                ObjectNotFoundException

Deletes a node from the repository. (Checks whether the node is not up before deleting it.)

Throws:

SchemaException

ObjectNotFoundException

shutdown

void shutdown()

Shuts down current node. Stops all tasks and cluster manager thread as well. Waits until all tasks on this node finish.

deactivateServiceThreads

boolean deactivateServiceThreads(long timeToWait,
                                 OperationResult parentResult)

Deactivates service threads (temporarily). This will suspend all background activity such as scanning threads, heartbeats and similar mechanisms. Note: The threads are normally activated after task manager implementation starts. This methods should not be used in a normal case. WARNING: this feature is intended for development-time diagnostics and should not be used on production environments. Suspending the threads may affect correct behavior of the system (such as timeouts on heartbeats). Use this feature only if you really know what you are doing. timeToWait is only for orientation = it may be so that the implementation would wait 2 or 3 times this value (if it waits separately for several threads completion)

reactivateServiceThreads

void reactivateServiceThreads(OperationResult parentResult)

Re-activates the service threads after they have been deactivated.

getServiceThreadsActivationState

boolean getServiceThreadsActivationState()

Returns true if the service threads are running. This method returns true in a normal case. It returns false is the threads were temporarily suspended.

Returns:

true if the service threads are running.

stopScheduler

void stopScheduler(String nodeIdentifier,
                   OperationResult parentResult)

Stops the scheduler on a given node. This means that at that node no tasks will be started.

Parameters:

nodeIdentifier - Node on which the scheduler should be stopped. Null means current node.

stopSchedulers

void stopSchedulers(Collection<String> nodeIdentifiers,
                    OperationResult parentResult)

stopSchedulersAndTasks

boolean stopSchedulersAndTasks(Collection<String> nodeIdentifiers,
                               long waitTime,
                               OperationResult parentResult)

Stops a set of schedulers (on their nodes) and tasks that are executing on these nodes.

Parameters:

nodeIdentifiers - collection of node identifiers

waitTime - how long to wait for task shutdown, in milliseconds 0 = indefinitely -1 = do not wait at all

startScheduler

void startScheduler(String nodeIdentifier,
                    OperationResult parentResult)

Starts the scheduler on a given node. A prerequisite is that the node is running and its TaskManager is not in an error state.

Parameters:

nodeIdentifier - Node on which the scheduler should be started. Null means current node.

startSchedulers

void startSchedulers(Collection<String> nodeIdentifiers,
                     OperationResult parentResult)

registerTaskListener

void registerTaskListener(TaskListener taskListener)

Registers a task listener that will be notified on task-related events.

Parameters:

taskListener - listener to be registered

unregisterTaskListener

void unregisterTaskListener(TaskListener taskListener)

Unregisters a task listener.

Parameters:

taskListener - listener to be unregisteted

postInit

void postInit(OperationResult result)

Currently not used.

onSystemStarted

@EventListener(org.springframework.boot.context.event.ApplicationReadyEvent.class)
void onSystemStarted()

Called when the whole application is initialized. Here we make this node a real cluster member: We set the operational state to UP, enabling receiving cache invalidation events (among other effects). We also invalidate local caches - to begin with a clean slate - and start the scheduler. The postInit mechanism cannot be used for this purpose. The reason is that it is invoked shortly before the application is completely up. REST endpoints are not yet functional at that time. This means that some of the cache invalidation messages could be lost, and the other nodes could get error messages in the meanwhile. Unfortunately, REST endpoints are not initialized even when this event is emitted. There's a few seconds before they are really available. So the real action can be delayed by setting "nodeStartupDelay" configuration parameter. (This is a temporary solution until something better is found.)

synchronizeTasks

void synchronizeTasks(OperationResult parentResult)

Synchronizes information in midPoint repository and task scheduling database.

getNextRunStartTime

Long getNextRunStartTime(String oid,
                         OperationResult result)

Gets next scheduled execution time for a given task.

Parameters:

oid - OID of the task

Returns:

null if there's no next scheduled execution for a given task or if a task with given OID does not exist

getAllTaskCategories

List<String> getAllTaskCategories()

Gets a list of all task categories.

getHandlerUriForCategory

String getHandlerUriForCategory(String category)

Returns a default handler URI for a given task category.

validateCronExpression

ParseException validateCronExpression(String cron)

Validates a cron expression for scheduling tasks - without context of any given task.

Parameters:

cron - expression to validate

Returns:

an exception if there's something wrong with the expression (null if it's OK).

registerHandler

void registerHandler(String uri,
                     TaskHandler handler)

Registers a handler for a specified handler URI.

Parameters:

uri - URI of the handler, e.g. http://midpoint.evolveum.com/xml/ns/public/model/cleanup/handler-3

handler - instance of the handler

registerAdditionalHandlerUri

void registerAdditionalHandlerUri(String uri,
                                  TaskHandler handler)

Registers additional handler URI for a given handler. The difference from registerHandler() is that these additional URIs are not returned when searching for a handler matching a given task category.

registerTaskDeletionListener

void registerTaskDeletionListener(TaskDeletionListener listener)

narrowQueryForWorkBucket

ObjectQuery narrowQueryForWorkBucket(ObjectQuery query,
                                     Class<? extends ObjectType> type,
                                     Function<ItemPath,ItemDefinition<?>> itemDefinitionProvider,
                                     Task workerTask,
                                     WorkBucketType workBucket,
                                     OperationResult opResult)
                              throws SchemaException,
                                     ObjectNotFoundException

TODO. EXPERIMENTAL.

Throws:

SchemaException

ObjectNotFoundException

createAndRegisterPartitioningTaskHandler

TaskHandler createAndRegisterPartitioningTaskHandler(String handlerUri,
                                                     Function<Task,TaskPartitionsDefinition> partitioningStrategy)

setFreeBucketWaitInterval

void setFreeBucketWaitInterval(long value)

isLocalNodeClusteringEnabled

boolean isLocalNodeClusteringEnabled()

EXPERIMENTAL. Relaxes some assumptions on cluster structure e.g. that IP addresses of cluster members must be different. To be used for demonstration/testing only. Avoid using in production environments.

setWebContextPath

void setWebContextPath(String path)

EXPERIMENTAL. Used to provide midPoint URL path (typically "/midpoint") when determined by the web layer.

getRunningTasksThreadsDump

String getRunningTasksThreadsDump(OperationResult parentResult)

recordRunningTasksThreadsDump

String recordRunningTasksThreadsDump(String cause,
                                     OperationResult parentResult)
                              throws ObjectAlreadyExistsException

Throws:

ObjectAlreadyExistsException

getTaskThreadsDump

String getTaskThreadsDump(String taskOid,
                          OperationResult parentResult)
                   throws SchemaException,
                          ObjectNotFoundException

Throws:

SchemaException

ObjectNotFoundException

recordTaskThreadsDump

String recordTaskThreadsDump(String taskOid,
                             String cause,
                             OperationResult parentResult)
                      throws SchemaException,
                             ObjectNotFoundException,
                             ObjectAlreadyExistsException

Throws:

SchemaException

ObjectNotFoundException

ObjectAlreadyExistsException

createFakeRunningTask

RunningTask createFakeRunningTask(Task task)

Use only for tests. Otherwise considered to be an ugly hack.

getHandler

TaskHandler getHandler(String handlerUri)

getLocalNode

NodeType getLocalNode()

getWorkStateManager

Object getWorkStateManager()

getCacheConfigurationManager

CacheConfigurationManager getCacheConfigurationManager()

isDynamicProfilingEnabled

boolean isDynamicProfilingEnabled()

getTracer

Tracer getTracer()

isClustered

boolean isClustered()

isTracingOverridden

boolean isTracingOverridden()

getGlobalTracingRequestedFor

@NotNull
Collection<TracingRootType> getGlobalTracingRequestedFor()

getGlobalTracingProfile

TracingProfileType getGlobalTracingProfile()

setGlobalTracingOverride

void setGlobalTracingOverride(@NotNull
                              Collection<TracingRootType> roots,
                              @NotNull
                              TracingProfileType profile)

removeGlobalTracingOverride

void removeGlobalTracingOverride()

isUpAndAlive

boolean isUpAndAlive(NodeType node)

Returns:

true if we consider this node to be "up" (alive). This is determined by looking at operational state (should be UP) and last check-in information (should not be more than nodeTimeout ago).

isCheckingIn

boolean isCheckingIn(NodeType node)

Returns:

true if this node has recently checked in. It might be starting or up.