com.evolveum.midpoint.task.api
Interface TaskManager

All Known Implementing Classes:

TaskManagerImpl

public interface TaskManager

Task Manager Interface.

Status: public Stability: DRAFT, work in progress

Version:

0.1

Author:

Radovan Semancik

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

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.

Method Summary

java.lang.String	addTask(TaskType taskType, OperationResult parentResult) Add new task.
void	claimTask(Task task, OperationResult parentResult) Claim task exclusively for this node.
Task	createTaskInstance() Creates new transient, running, claimed task instance.
Task	createTaskInstance(TaskType taskType) Creates task instance from the XML task representation.
void	deactivateServiceThreads() Deactivate service threads (temporarily).
void	deleteTask(java.lang.String oid, OperationResult parentResult) Deletes task with provided OID.
java.util.Set<Task>	getRunningTasks() Returns tasks that currently run on this node.
boolean	getServiceThreadsActivationState() Returns true if the service threads are running.
Task	getTask(java.lang.String taskOid, OperationResult parentResult) Returns a task with specified OID.
java.util.Set<Task>	listTasks() Lists all tasks.
void	modifyTask(ObjectModificationType objectChange, OperationResult parentResult) Modifies task using relative change description.
void	reactivateServiceThreads() Re-activate the service threads after they have been deactivated.
void	registerHandler(java.lang.String uri, TaskHandler handler) Register a handler for a specified handler URI.
void	releaseTask(Task task, OperationResult parentResult) Release a claimed task.
void	shutdown() Make sure all processes are stopped properly.
void	switchToBackground(Task task, OperationResult parentResult) Switches the provided task to background, making it asynchronous.

Method Detail

createTaskInstance

Task createTaskInstance()

Creates new transient, running, claimed 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, claimed task instance

createTaskInstance

Task createTaskInstance(TaskType taskType)

Creates task instance from the XML task representation.

Parameters:

taskType - JAXB (XML) representation of the task

Returns:

new Java representation of the task

getTask

Task getTask(java.lang.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.

addTask

java.lang.String addTask(TaskType taskType,
                         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:

object - object to create

scripts - scripts to execute before/after the operation

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

java.lang.IllegalArgumentException - wrong OID format, etc.

modifyTask

void modifyTask(ObjectModificationType objectChange,
                OperationResult parentResult)
                throws ObjectNotFoundException,
                       SchemaException

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. TODO: optimistic locking

Parameters:

objectChange - specification of object changes

scripts - scripts that should be executed before of after operation

parentResult - parent OperationResult (in/out)

Throws:

ObjectNotFoundException - specified object does not exist

SchemaException - resulting object would violate the schema

java.lang.IllegalArgumentException - wrong OID format, described change is not applicable

deleteTask

void deleteTask(java.lang.String oid,
                OperationResult parentResult)
                throws ObjectNotFoundException

Deletes task with provided OID. Must fail if object with specified OID does not exists. Should be atomic.

Parameters:

oid - OID of object to delete

parentResult - parent OperationResult (in/out)

Throws:

ObjectNotFoundException - specified object does not exist

java.lang.IllegalArgumentException - wrong OID format, described change is not applicable

claimTask

void claimTask(Task task,
               OperationResult parentResult)
               throws ObjectNotFoundException,
                      ConcurrencyException,
                      SchemaException

Claim task exclusively for this node. The operation will try to claim a task for this node. The operation will normally return, switching the task to a claimed state. Or it may throw exception if the task "claiming" failed. Claiming will only work on released tasks. But even if this node considers task to be released, it might have been claimed by another node in the meantime. This operation guarantees atomicity. It will claim task only on a single node. This method is in the TaskManager instead of Task, so the Task can stay free of RepositoryService dependency. TODO: EXCEPTIONS

Parameters:

task - task instance to claim

Throws:

SchemaException

ConcurrencyException

ObjectNotFoundException

releaseTask

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

Release a claimed task. The task is released for other nodes to work on it. The task state is saved to the repository before release, if necessary. If a transient task is provided as an argument, the task will be made persistent during this call. Release only works on claimed tasks. This method is in the TaskManager instead of Task, so the Task can stay free of RepositoryService dependency.

Parameters:

task - task instance to release

Throws:

ObjectNotFoundException

SchemaException

java.lang.IllegalArgumentException - attempt to release a task that is not claimed.

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. If the task execution state is "running" the method also tries to make sure that the task will be immediately execute (e.g. by allocating a thread). However, the nodes may compete for the tasks or there may be explicit limitations. Therefore 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.

listTasks

java.util.Set<Task> listTasks()

Lists all tasks. This method is not very useful for normal operation, but may be useful for diagnostics. May list persistent and also transient tasks. Depends on implementation.

Returns:

list of all known tasks

registerHandler

void registerHandler(java.lang.String uri,
                     TaskHandler handler)

Register a handler for a specified handler URI.

shutdown

void shutdown()

Make sure all processes are stopped properly. Will block until all processes are shut down.

getRunningTasks

java.util.Set<Task> getRunningTasks()

Returns tasks that currently run on this node. E.g. tasks that have allocated threads. It should be a different view than looking for a claimed tasks in the repository, although normally it should return the same data. This should look at the real situation (e.g. threads) and should be used to troubleshoot task management problems.

Returns:

tasks that currently run on this node.

deactivateServiceThreads

void deactivateServiceThreads()

Deactivate 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.

reactivateServiceThreads

void reactivateServiceThreads()

Re-activate 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.