com.evolveum.midpoint.task.api
Interface TaskManager

All Known Implementing Classes:
TaskManagerImpl

public interface TaskManager

Task Manager Interface.

Status: public Stability: DRAFT

Version:
0.1
Author:
Radovan Semancik

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.


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(java.lang.String operationName)
          Creates new transient, running, claimed task instance.
 Task createTaskInstance(TaskType taskType)
          Creates task instance from the XML task representation.
 Task createTaskInstance(TaskType taskType, java.lang.String operationName)
          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

createTaskInstance

Task createTaskInstance(java.lang.String operationName)
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. 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

Task createTaskInstance(TaskType taskType,
                        java.lang.String operationName)
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:
taskType - JAXB (XML) representation of the task
operationName - operation name to use as a root for new result in 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.


Copyright © 2011 evolveum. All Rights Reserved.