com.evolveum.midpoint.task.api
Interface TaskManager

All Known Implementing Classes:
TaskManagerQuartzImpl

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(PrismObject<TaskType> taskPrism, OperationResult parentResult)
          Add new task.
 int countNodes(ObjectQuery query, OperationResult result)
           
 int countTasks(ObjectQuery query, OperationResult result)
           
 Task createTaskInstance()
          Creates new transient, running, claimed task instance.
 Task createTaskInstance(PrismObject<TaskType> taskPrism, OperationResult parentResult)
          Creates task instance from the XML task representation.
 Task createTaskInstance(PrismObject<TaskType> taskPrism, java.lang.String operationName, OperationResult parentResult)
          Creates task instance from the XML task representation.
 Task createTaskInstance(java.lang.String operationName)
          Creates new transient, running, claimed task instance.
 boolean deactivateServiceThreads(long timeToWait, OperationResult parentResult)
          Deactivate service threads (temporarily).
 void deleteNode(java.lang.String nodeIdentifier, OperationResult result)
           
 void deleteTask(java.lang.String oid, OperationResult parentResult)
          Deletes task with provided OID.
 java.util.List<java.lang.String> getAllTaskCategories()
           
 java.lang.String getHandlerUriForCategory(java.lang.String category)
           
 java.lang.Long getNextRunStartTime(java.lang.String oid, OperationResult result)
           
 java.lang.String getNodeId()
           
 java.util.Set<Task> getRunningTasks()
          Deprecated. 
 ClusterStatusInformation getRunningTasksClusterwide(long allowedAge, OperationResult parentResult)
          Returns running tasks; fetches new information only if after last query elapsed at least 'allowedAge' milliseconds.
 ClusterStatusInformation getRunningTasksClusterwide(OperationResult result)
           
 boolean getServiceThreadsActivationState()
          Returns true if the service threads are running.
 Task getTask(java.lang.String taskOid, OperationResult parentResult)
          Returns a task with specified OID.
 boolean isCurrentNode(PrismObject<NodeType> node)
           
 void modifyTask(java.lang.String oid, java.util.Collection<? extends ItemDelta> modifications, OperationResult parentResult)
          Deprecated. 
 void onTaskCreate(java.lang.String oid, OperationResult parentResult)
          This is a signal to task manager that a new task was created in the repository.
 void onTaskDelete(java.lang.String oid, OperationResult parentResult)
          This is a signal to task manager that a task was removed from the repository.
 void postInit(OperationResult result)
          Post initialization, e.g.
 void reactivateServiceThreads(OperationResult parentResult)
          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 resumeTask(Task task, OperationResult parentResult)
          Resume suspended task.
 void scheduleTaskNow(Task task, OperationResult parentResult)
           
 java.util.List<Node> searchNodes(ObjectQuery query, ClusterStatusInformation clusterStatusInformation, OperationResult result)
          Returns relevant nodes (w.r.t query and paging specification).
 java.util.List<Task> searchTasks(ObjectQuery query, ClusterStatusInformation clusterStatusInformation, OperationResult result)
          Returns relevant tasks (w.r.t.
 void shutdown()
          Make sure all processes are stopped properly.
 void startScheduler(java.lang.String nodeIdentifier, OperationResult parentResult)
          Starts the scheduler on a given node.
 void stopScheduler(java.lang.String nodeIdentifier, OperationResult parentResult)
          Stops the scheduler on a given node.
 boolean stopSchedulersAndTasks(java.util.List<java.lang.String> nodeList, long waitTime, OperationResult parentResult)
           
 boolean suspendTask(Task task, long waitTime, OperationResult parentResult)
          Suspend task.
 boolean suspendTasks(java.util.Collection<Task> tasks, long waitTime, boolean doNotStop, OperationResult parentResult)
           
 boolean suspendTasks(java.util.Collection<Task> tasks, long waitTime, OperationResult parentResult)
           
 void switchToBackground(Task task, OperationResult parentResult)
          Switches the provided task to background, making it asynchronous.
 void synchronizeTasks(OperationResult parentResult)
           
 void unpauseTask(Task task, OperationResult parentResult)
           
 java.text.ParseException validateCronExpression(java.lang.String cron)
           
 

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(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(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(PrismObject<TaskType> taskPrism,
                        java.lang.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

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(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
java.lang.IllegalArgumentException - wrong OID format, etc.

modifyTask

@Deprecated
void modifyTask(java.lang.String oid,
                           java.util.Collection<? extends ItemDelta> modifications,
                           OperationResult parentResult)
                throws ObjectNotFoundException,
                       SchemaException
Deprecated. 

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:
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
java.lang.IllegalArgumentException - wrong OID format, described change is not applicable

deleteTask

void deleteTask(java.lang.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
java.lang.IllegalArgumentException - wrong OID format, described change is not applicable
SchemaException

suspendTask

boolean suspendTask(Task task,
                    long waitTime,
                    OperationResult parentResult)
Suspend task. TODO This method does not throw exceptions; it records its result in OperationResult.

Parameters:
task - task instance to claim

resumeTask

void resumeTask(Task task,
                OperationResult parentResult)
                throws ObjectNotFoundException,
                       SchemaException
Resume suspended task. TODO TODO: EXCEPTIONS

Parameters:
task - task instance to claim
Throws:
SchemaException
ConcurrencyException
ObjectNotFoundException

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.

searchTasks

java.util.List<Task> searchTasks(ObjectQuery query,
                                 ClusterStatusInformation clusterStatusInformation,
                                 OperationResult result)
                                 throws SchemaException
Returns relevant tasks (w.r.t. query and paging specification). Comparing to searchObjects(TaskType) in repo, there are the following differences: (1) This method combines information from the repository with run-time information obtained from cluster nodes (clusterStatusInformation), mainly to tell what tasks are really executing at this moment. The repository contains 'node' attribute (telling on which node task runs), which may be out-of-date for nodes which crashed recently. (2) this method returns Tasks, not TaskTypes - a Task provides some information (e.g. getNextRunStartTime()) that is not stored in repository; Task object can be directly used as an input to several methods, like suspendTask() or releaseTask(). However, the reason (2) is only of a technical character. So, if necessary, this method can be changed to return a list of TaskTypes instead of Tasks.

Parameters:
query - Search query
paging - Paging specification
clusterStatusInformation - If null, the method will query cluster nodes to get up-to-date runtime information. If non-null, the method will use the provided information. Used to optimize network traffic in case of repeating calls to searchTasks/searchNodes (e.g. when displaying them on one page).
result -
Returns:
Throws:
SchemaException

countTasks

int countTasks(ObjectQuery query,
               OperationResult result)
               throws SchemaException
Throws:
SchemaException

searchNodes

java.util.List<Node> searchNodes(ObjectQuery query,
                                 ClusterStatusInformation clusterStatusInformation,
                                 OperationResult result)
                                 throws SchemaException
Returns relevant nodes (w.r.t query and paging specification). Similar to searchTasks, this method adds some information to the one returned from repository. (Mainly concerned with Node status and error status.)

Parameters:
query -
paging -
clusterStatusInformation - The same as in searchTasks.
result -
Returns:
Throws:
SchemaException

countNodes

int countNodes(ObjectQuery query,
               OperationResult result)
               throws SchemaException
Throws:
SchemaException

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

@Deprecated
java.util.Set<Task> getRunningTasks()
                                    throws TaskManagerException
Deprecated. 

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.
Throws:
TaskManagerException

deactivateServiceThreads

boolean deactivateServiceThreads(long timeToWait,
                                 OperationResult parentResult)
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. 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-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.

stopScheduler

void stopScheduler(java.lang.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.

startScheduler

void startScheduler(java.lang.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.

onTaskCreate

void onTaskCreate(java.lang.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.

Parameters:
oid -

onTaskDelete

void onTaskDelete(java.lang.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.

Parameters:
oid -

getNextRunStartTime

java.lang.Long getNextRunStartTime(java.lang.String oid,
                                   OperationResult result)

getRunningTasksClusterwide

ClusterStatusInformation getRunningTasksClusterwide(OperationResult result)

getNodeId

java.lang.String getNodeId()

isCurrentNode

boolean isCurrentNode(PrismObject<NodeType> node)

getAllTaskCategories

java.util.List<java.lang.String> getAllTaskCategories()

postInit

void postInit(OperationResult result)
Post initialization, e.g. starts the actual scheduling of tasks on this node.


suspendTasks

boolean suspendTasks(java.util.Collection<Task> tasks,
                     long waitTime,
                     OperationResult parentResult)

suspendTasks

boolean suspendTasks(java.util.Collection<Task> tasks,
                     long waitTime,
                     boolean doNotStop,
                     OperationResult parentResult)

getRunningTasksClusterwide

ClusterStatusInformation getRunningTasksClusterwide(long allowedAge,
                                                    OperationResult parentResult)
Returns running tasks; fetches new information only if after last query elapsed at least 'allowedAge' milliseconds.

Parameters:
allowedAge -
Returns:

stopSchedulersAndTasks

boolean stopSchedulersAndTasks(java.util.List<java.lang.String> nodeList,
                               long waitTime,
                               OperationResult parentResult)

synchronizeTasks

void synchronizeTasks(OperationResult parentResult)

deleteNode

void deleteNode(java.lang.String nodeIdentifier,
                OperationResult result)

scheduleTaskNow

void scheduleTaskNow(Task task,
                     OperationResult parentResult)

getHandlerUriForCategory

java.lang.String getHandlerUriForCategory(java.lang.String category)

validateCronExpression

java.text.ParseException validateCronExpression(java.lang.String cron)

unpauseTask

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


Copyright © 2012 evolveum. All Rights Reserved.