public interface TaskManager
Task Manager Interface.
Status: public Stability: DRAFT
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.
Modifier and Type | Method and Description |
---|---|
String |
addTask(PrismObject<TaskType> taskPrism,
OperationResult parentResult)
Add new task.
|
void |
cleanupTasks(CleanupPolicyType closedTasksPolicy,
OperationResult opResult)
Deletes obsolete tasks, as specified in the policy.
|
int |
countNodes(ObjectQuery query,
OperationResult result)
Returns the number of nodes satisfying given query.
|
int |
countTasks(ObjectQuery query,
OperationResult result)
Returns the number of tasks satisfying given query.
|
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 nodeIdentifier,
OperationResult result)
Deletes a node from the repository.
|
void |
deleteTask(String oid,
OperationResult parentResult)
Deletes task with provided OID.
|
List<String> |
getAllTaskCategories()
Gets a list of all task categories.
|
String |
getHandlerUriForCategory(String category)
Returns a default handler URI for a given task category.
|
Set<Task> |
getLocallyRunningTasks(OperationResult parentResult)
Returns tasks that currently run on this node.
|
Long |
getNextRunStartTime(String oid,
OperationResult result)
Gets next scheduled execution time for a given task.
|
String |
getNodeId()
Returns identifier for current node.
|
ClusterStatusInformation |
getRunningTasksClusterwide(long allowedAge,
OperationResult parentResult)
As above; with the difference that this method fetches new information only if after last query
elapsed at least 'allowedAge' milliseconds.
|
ClusterStatusInformation |
getRunningTasksClusterwide(OperationResult result)
Returns the cluster state, including tasks that execute on particular nodes.
|
boolean |
getServiceThreadsActivationState()
Returns true if the service threads are running.
|
Task |
getTask(String taskOid,
OperationResult parentResult)
Returns a task with specified OID.
|
Task |
getTaskByIdentifier(String identifier,
OperationResult parentResult)
Returns a task with a given identifier.
|
boolean |
isCurrentNode(PrismObject<NodeType> node)
Checks whether supplied node is the current node.
|
List<Task> |
listTasksRelatedToObject(String oid,
ClusterStatusInformation clusterStatusInformation,
OperationResult result)
Returns tasks that are related to an object with a given OID.
|
void |
modifyTask(String oid,
Collection<? extends ItemDelta> modifications,
OperationResult parentResult)
Modifies task using relative change description.
|
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)
Post initialization, e.g.
|
void |
reactivateServiceThreads(OperationResult parentResult)
Re-activates the service threads after they have been deactivated.
|
void |
registerHandler(String uri,
TaskHandler handler)
Registers a handler for a specified handler URI.
|
void |
resumeTask(Task task,
OperationResult parentResult)
Resume suspended task.
|
void |
scheduleTaskNow(Task task,
OperationResult parentResult)
Schedules a RUNNABLE task to be run immediately.
|
List<Node> |
searchNodes(ObjectQuery query,
ClusterStatusInformation clusterStatusInformation,
OperationResult result)
Returns relevant nodes satisfying given query.
|
List<Task> |
searchTasks(ObjectQuery query,
ClusterStatusInformation clusterStatusInformation,
OperationResult result)
Returns tasks satisfying given query.
|
void |
shutdown()
Shuts down current node.
|
void |
startScheduler(String nodeIdentifier,
OperationResult parentResult)
Starts the scheduler on a given node.
|
void |
stopScheduler(String nodeIdentifier,
OperationResult parentResult)
Stops the scheduler on a given node.
|
boolean |
stopSchedulersAndTasks(List<String> nodeList,
long waitTime,
OperationResult parentResult)
Stops a set of schedulers (on their nodes) and tasks that are executing on these nodes.
|
void |
suspendAndDeleteTasks(List<String> taskOidList,
long suspendTimeout,
boolean alsoSubtasks,
OperationResult parentResult)
Suspends tasks and deletes them.
|
boolean |
suspendTask(Task task,
long waitTime,
OperationResult parentResult)
Suspend a task.
|
boolean |
suspendTasks(Collection<Task> tasks,
long waitTime,
boolean doNotStop,
OperationResult parentResult)
Suspends a set of tasks.
|
boolean |
suspendTasks(Collection<Task> tasks,
long waitTime,
OperationResult parentResult)
Suspend a set of tasks.
|
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.
|
ParseException |
validateCronExpression(String cron)
Validates a cron expression for scheduling tasks - without context of any given task.
|
Task createTaskInstance()
Task createTaskInstance(PrismObject<TaskType> taskPrism, OperationResult parentResult) throws SchemaException
taskPrism
- JAXB (XML) representation of the taskSchemaException
- The provided taskType is not compliant to schemaTask createTaskInstance(String operationName)
operationName
- operation name to use as a root for new result in taskTask createTaskInstance(PrismObject<TaskType> taskPrism, String operationName, OperationResult parentResult) throws SchemaException
taskPrism
- Prism representation of the taskoperationName
- operation name to use as a root for new result in taskSchemaException
- The provided taskType is not compliant to schemaTask getTask(String taskOid, OperationResult parentResult) throws ObjectNotFoundException, SchemaException
taskOid
- OID of the persistent task.SchemaException
- error dealing with resource schemaObjectNotFoundException
- wrong OID format, etc.Task getTaskByIdentifier(String identifier, OperationResult parentResult) throws SchemaException, ObjectNotFoundException
identifier
- task identifier to search forparentResult
- SchemaException
ObjectNotFoundException
String addTask(PrismObject<TaskType> taskPrism, OperationResult parentResult) throws ObjectAlreadyExistsException, SchemaException
taskPrism
- object to createparentResult
- parent OperationResult (in/out)ObjectAlreadyExistsException
- object with specified identifiers already exists, cannot addSchemaException
- error dealing with storage schema, e.g. schema violationIllegalArgumentException
- wrong OID format, etc.void modifyTask(String oid, Collection<? extends ItemDelta> modifications, OperationResult parentResult) throws ObjectNotFoundException, SchemaException, ObjectAlreadyExistsException
oid
- OID of the task to be changedmodifications
- specification of object changesparentResult
- parent OperationResult (in/out)ObjectNotFoundException
- specified object does not existSchemaException
- resulting object would violate the schemaIllegalArgumentException
- wrong OID format, described change is not applicableObjectAlreadyExistsException
void deleteTask(String oid, OperationResult parentResult) throws ObjectNotFoundException, SchemaException
oid
- OID of object to deleteparentResult
- parent OperationResult (in/out)ObjectNotFoundException
- specified object does not existIllegalArgumentException
- wrong OID format, described change is not applicableSchemaException
void cleanupTasks(CleanupPolicyType closedTasksPolicy, OperationResult opResult) throws SchemaException
closedTasksPolicy
- specifies which tasks are to be deleted, e.g. how old they have to beopResult
- SchemaException
void onTaskCreate(String oid, OperationResult parentResult)
oid
- void onTaskDelete(String oid, OperationResult parentResult)
oid
- List<Task> searchTasks(ObjectQuery query, ClusterStatusInformation clusterStatusInformation, OperationResult result) throws SchemaException
query
- Search queryclusterStatusInformation
- 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
- SchemaException
int countTasks(ObjectQuery query, OperationResult result) throws SchemaException
query
- search queryresult
- SchemaException
List<Task> listTasksRelatedToObject(String oid, ClusterStatusInformation clusterStatusInformation, OperationResult result) throws SchemaException
oid
- object OID to be searched forclusterStatusInformation
- runtime information to be used (if not null)result
- SchemaException
Set<Task> getLocallyRunningTasks(OperationResult parentResult) throws TaskManagerException
TaskManagerException
ClusterStatusInformation getRunningTasksClusterwide(OperationResult result)
result
- ClusterStatusInformation getRunningTasksClusterwide(long allowedAge, OperationResult parentResult)
allowedAge
- boolean suspendTasks(Collection<Task> tasks, long waitTime, boolean doNotStop, OperationResult parentResult)
tasks
- a set of tasks to be suspendedwaitTime
- how long (in milliseconds) to wait for stopping the execution of tasks;
0 means wait indefinitely
-1 means stop the task but do not wait for finishing their executiondoNotStop
- if true, the task execution will not be stopped. They will only be put into SUSPENDED state, and
their executions (if any) will be left as they areparentResult
- boolean suspendTasks(Collection<Task> tasks, long waitTime, OperationResult parentResult)
boolean suspendTask(Task task, long waitTime, OperationResult parentResult)
void suspendAndDeleteTasks(List<String> taskOidList, long suspendTimeout, boolean alsoSubtasks, OperationResult parentResult)
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?parentResult
- void resumeTask(Task task, OperationResult parentResult) throws ObjectNotFoundException, SchemaException
task
- task instance to be resumed.SchemaException
ObjectNotFoundException
void pauseTask(Task task, TaskWaitingReason reason, OperationResult parentResult) throws ObjectNotFoundException, SchemaException
task
- a runnable/running taskreason
- the reason for waiting, which is stored into the repositoryparentResult
- ObjectNotFoundException
SchemaException
void unpauseTask(Task task, OperationResult parentResult) throws ObjectNotFoundException, SchemaException
task
- parentResult
- ObjectNotFoundException
SchemaException
void switchToBackground(Task task, OperationResult parentResult)
task
- task to switch to background.void scheduleTaskNow(Task task, OperationResult parentResult)
task
- parentResult
- List<Node> searchNodes(ObjectQuery query, ClusterStatusInformation clusterStatusInformation, OperationResult result) throws SchemaException
query
- search queryclusterStatusInformation
- The same as in searchTasks.result
- SchemaException
int countNodes(ObjectQuery query, OperationResult result) throws SchemaException
query
- search queryresult
- SchemaException
String getNodeId()
boolean isCurrentNode(PrismObject<NodeType> node)
node
- void deleteNode(String nodeIdentifier, OperationResult result)
nodeIdentifier
- result
- void shutdown()
boolean deactivateServiceThreads(long timeToWait, OperationResult parentResult)
void reactivateServiceThreads(OperationResult parentResult)
boolean getServiceThreadsActivationState()
void stopScheduler(String nodeIdentifier, OperationResult parentResult)
nodeIdentifier
- Node on which the scheduler should be stopped. Null means current node.boolean stopSchedulersAndTasks(List<String> nodeList, long waitTime, OperationResult parentResult)
nodeList
- list of node identifierswaitTime
- how long to wait for task shutdown, in milliseconds
0 = indefinitely
-1 = do not wait at allparentResult
- void startScheduler(String nodeIdentifier, OperationResult parentResult)
nodeIdentifier
- Node on which the scheduler should be started. Null means current node.void postInit(OperationResult result)
void synchronizeTasks(OperationResult parentResult)
parentResult
- Long getNextRunStartTime(String oid, OperationResult result)
oid
- OID of the taskresult
- List<String> getAllTaskCategories()
String getHandlerUriForCategory(String category)
category
- ParseException validateCronExpression(String cron)
cron
- expression to validatevoid registerHandler(String uri, TaskHandler handler)
uri
- URI of the handler, e.g. http://midpoint.evolveum.com/xml/ns/public/model/cleanup/handler-2handler
- instance of the handlerCopyright © 2013 evolveum. All rights reserved.