com.evolveum.midpoint.task.api
Interface Task

All Superinterfaces:
Dumpable
All Known Implementing Classes:
TaskQuartzImpl

public interface Task
extends Dumpable

Task instance - a logical unit of work that is either done synchronously, asynchronously, it is deferred, scheduled, etc. The classes that implement this interface hold a "java" task state. They represent the in-memory task data structure. The instances must be able to serialize the state to the repository object (TaskType) when needed. This usually happens on task "release". The task implementation should be simple Java objects (POJOs). They are created also for a synchronous tasks, which means they are created frequently. We want a low overhead for task management until the task is made asynchronous. API for modifying task properties works like this: - A getter (get) reads data from the in-memory representation of a task. - A setter (set) writes data to the in-memory representation, and prepares a PropertyDelta to be written into repository later (of course, only for persistent tasks). PropertyDeltas should be then written by calling savePendingModifications method. In case you want to write property change into the repository immediately, you have to use setImmediate method. In that case, the property change does not go into the list of pending modifications, but it is instantly written into the repository (so the method uses OperationResult as parameter, and can throw relevant exceptions as well).

Author:
Radovan Semancik

Method Summary
 void addExtensionProperty(PrismProperty<?> property)
           
 boolean canRun()
          Returns true if the task can run (was not interrupted).
 ItemDelta<?> createExtensionDelta(PrismPropertyDefinition definition, java.lang.Object realValue)
           
 Task createSubtask()
          Creates a subtask
 Node currentlyExecutesAt()
          Returns the node the task is currently executing at, based on real run-time information.
 void deleteExtensionProperty(PrismProperty<?> property)
          Removes specified VALUES of this extension property (not all of its values).
 java.lang.String dump()
          Return human-readable representation of the task content.
 void finishHandler(OperationResult parentResult)
           
 TaskBinding getBinding()
           
 java.lang.String getCategory()
          Categories are treated in a special way.
 java.lang.String getChannel()
          Returns change channel URI.
 java.lang.String getDescription()
           
 TaskExecutionStatus getExecutionStatus()
          Returns execution status.
 PrismContainer<?> getExtension()
          Returns task extension.
 PrismProperty<?> getExtension(javax.xml.namespace.QName propertyName)
           
 java.lang.String getHandlerUri()
          Returns handler URI.
 java.lang.Long getLastRunFinishTimestamp()
          Returns the time when the task last run was finished (or null if the task was not finished yet).
 java.lang.Long getLastRunStartTimestamp()
          Returns the time when the task last run was started (or null if the task was never started).
 ModelOperationStateType getModelOperationState()
           
 PolyStringType getName()
          Returns human-readable name of the task.
 java.lang.Long getNextRunStartTime(OperationResult parentResult)
          Returns the time when the task should start again.
 java.lang.String getNode()
           
<T extends ObjectType>
PrismObject<T>
getObject(java.lang.Class<T> type, OperationResult parentResult)
          Returns object that the task is associated with.
 java.lang.String getObjectOid()
          Returns OID of the object that the task is associated with.
 ObjectReferenceType getObjectRef()
          Returns reference to the object that the task is associated with.
 java.lang.String getOid()
          Returns task OID.
 UriStack getOtherHandlersUriStack()
          Returns the stack of other handlers URIs.
 PrismObject<UserType> getOwner()
          Returns user that owns this task.
 java.lang.String getParent()
           
 TaskPersistenceStatus getPersistenceStatus()
          Returns task persistence status.
 long getProgress()
           
 TaskRecurrence getRecurrenceStatus()
          Returns task recurrence status.
 OperationResult getResult()
          Returns a top-level OperationResult stored in the task.
 OperationResultStatusType getResultStatus()
           
 ScheduleType getSchedule()
          Returns the schedule.
 java.lang.String getTaskIdentifier()
          Returns task (lightweight) identifier.
 PrismObject<TaskType> getTaskPrismObject()
           
 ThreadStopActionType getThreadStopAction()
           
 boolean isAsynchronous()
          Returns true if the task is asynchronous.
 boolean isCycle()
          Checks whether the task is a cyclic (recurrent) one.
 boolean isLooselyBound()
           
 boolean isPersistent()
           
 boolean isResilient()
          Resilient tasks are those that survive node shutdown.
 boolean isSingle()
          Checks whether the task is single-run.
 boolean isTightlyBound()
           
 boolean isTransient()
           
 void makeRecurrent(ScheduleType schedule)
           
 void makeRecurrentCron(java.lang.String cronLikeSpecification)
           
 void makeRecurrentSimple(int interval)
           
 void makeRunnable()
          Status-changing method.
 void makeSingle()
           
 void makeSingle(ScheduleType schedule)
           
 void makeWaiting()
          Status-changing method.
 void modifyExtension(ItemDelta itemDelta)
           
 void pushHandlerUri(java.lang.String uri, ScheduleType schedule, TaskBinding binding)
           
 void pushHandlerUri(java.lang.String uri, ScheduleType schedule, TaskBinding binding, java.util.Collection<ItemDelta<?>> extensionDeltas)
           
 void pushHandlerUri(java.lang.String uri, ScheduleType schedule, TaskBinding binding, ItemDelta<?> delta)
           
 void refresh(OperationResult parentResult)
          Re-reads the task state from the persistent storage.
 void savePendingModifications(OperationResult parentResult)
          Marks current handler as finished, and removes it from the handler stack.
 void setBinding(TaskBinding value)
           
 void setBindingImmediate(TaskBinding value, OperationResult parentResult)
           
 void setCategory(java.lang.String category)
           
 void setChannel(java.lang.String channelUri)
          Sets change channel URI.
 void setDescription(java.lang.String value)
           
 void setDescriptionImmediate(java.lang.String value, OperationResult parentResult)
           
 void setExtensionProperty(PrismProperty<?> property)
           
 void setExtensionPropertyImmediate(PrismProperty<?> property, OperationResult parentResult)
           
 void setHandlerUri(java.lang.String value)
          Sets handler URI.
 void setHandlerUriImmediate(java.lang.String value, OperationResult parentResult)
           
 void setInitialExecutionStatus(TaskExecutionStatus value)
          Sets task execution status.
 void setModelOperationState(ModelOperationStateType state)
           
 void setName(PolyStringType value)
          Sets the human-readable name of the task.
 void setNameImmediate(PolyStringType value, OperationResult parentResult)
           
 void setObjectRef(ObjectReferenceType objectRef)
           
 void setOwner(PrismObject<UserType> owner)
           
 void setProgress(long value)
          Record progress of the task, storing it persistently if needed.
 void setProgressImmediate(long progress, OperationResult parentResult)
           
 void setResult(OperationResult result)
           
 void setResultImmediate(OperationResult result, OperationResult parentResult)
           
 void setThreadStopAction(ThreadStopActionType value)
           
 TaskRunResult waitForSubtasks(java.lang.Integer interval, java.util.Collection<ItemDelta<?>> extensionDeltas, OperationResult parentResult)
           
 TaskRunResult waitForSubtasks(java.lang.Integer interval, OperationResult parentResult)
          Waits for subtasks to finish.
 

Method Detail

isAsynchronous

boolean isAsynchronous()
Returns true if the task is asynchronous. The asynchronous task is not executing in foreground. Therefore any thread that is not explicitly allocated for the task can be discarded. E.g. if a GUI thread detects that the task is asynchronous it knows that there is no point in waiting for the task result. It can just display appropriate message to the user (e.g. "please come back later") and return control back to the web container.

Returns:
true if the task is asynchronous.

getExecutionStatus

TaskExecutionStatus getExecutionStatus()
Returns execution status.

Returns:
execution status.
See Also:
TaskExecutionStatus

makeWaiting

void makeWaiting()
Status-changing method. It changes task's execution status to WAITING. Use with care, currently only on transient tasks.


makeRunnable

void makeRunnable()
Status-changing method. It changes task's execution status to RUNNABLE. Use with care, currently only on transient tasks.


currentlyExecutesAt

Node currentlyExecutesAt()
Returns the node the task is currently executing at, based on real run-time information. BEWARE, this information is valid only when returned from searchTasks (not e.g. when got via getTask).

Returns:

setInitialExecutionStatus

void setInitialExecutionStatus(TaskExecutionStatus value)
Sets task execution status. Can be used only for transient tasks (for safety reasons).

Parameters:
value - new task execution status.
See Also:
TaskExecutionStatus

getPersistenceStatus

TaskPersistenceStatus getPersistenceStatus()
Returns task persistence status.

Returns:
task persistence status.
See Also:
TaskPersistenceStatus

isTransient

boolean isTransient()

isPersistent

boolean isPersistent()

getRecurrenceStatus

TaskRecurrence getRecurrenceStatus()
Returns task recurrence status.

Returns:
task recurrence status

isSingle

boolean isSingle()
Checks whether the task is single-run.


isCycle

boolean isCycle()
Checks whether the task is a cyclic (recurrent) one.


getSchedule

ScheduleType getSchedule()
Returns the schedule. Note that if the task is 'single-run' (not recurrent), the schedule is ignored. And the other way around, if the task is recurrent, the schedule must be present (otherwise the results are unpredictable).


getBinding

TaskBinding getBinding()

isTightlyBound

boolean isTightlyBound()

isLooselyBound

boolean isLooselyBound()

setBinding

void setBinding(TaskBinding value)

setBindingImmediate

void setBindingImmediate(TaskBinding value,
                         OperationResult parentResult)
                         throws ObjectNotFoundException,
                                SchemaException
Throws:
ObjectNotFoundException
SchemaException

getHandlerUri

java.lang.String getHandlerUri()
Returns handler URI. Handler URI indirectly specifies which class is responsible to handle the task. The handler will execute reaction to a task lifecycle events such as executing the task, task heartbeat, etc.

Returns:
handler URI

setHandlerUri

void setHandlerUri(java.lang.String value)
Sets handler URI. Handler URI indirectly specifies which class is responsible to handle the task. The handler will execute reaction to a task lifecycle events such as executing the task, task heartbeat, etc.

Parameters:
value - new handler URI

setHandlerUriImmediate

void setHandlerUriImmediate(java.lang.String value,
                            OperationResult parentResult)
                            throws ObjectNotFoundException,
                                   SchemaException
Throws:
ObjectNotFoundException
SchemaException

getOtherHandlersUriStack

UriStack getOtherHandlersUriStack()
Returns the stack of other handlers URIs. The idea is that a task may have a chain of handlers, forming a stack. After a handler at the top of the stack finishes its processing, TaskManager will remove it from the stack and invoke the then-current handler. After that finishes, the next handler will be called, and so on, until the stack is empty.

Returns:

getTaskIdentifier

java.lang.String getTaskIdentifier()
Returns task (lightweight) identifier. This is an unique identification of any task, regardless whether it is persistent or transient (cf. OID). Therefore this can be used to identify all tasks, e.g. for the purposes of auditing and logging. Task identifier is assigned automatically when the task is created. It is immutable.

Returns:
task (lightweight) identifier

getOwner

PrismObject<UserType> getOwner()
Returns user that owns this task. It usually means the user that started the task or a system used that is used to execute the task. The owner will be used to determine access rights of the task, will be used for auditing, etc.

Returns:
task owner

setOwner

void setOwner(PrismObject<UserType> owner)

getChannel

java.lang.String getChannel()
Returns change channel URI.


setChannel

void setChannel(java.lang.String channelUri)
Sets change channel URI.


getOid

java.lang.String getOid()
Returns task OID. Only persistent tasks have OID. This returns null if the task is not persistent.

Returns:
task OID

getObject

<T extends ObjectType> PrismObject<T> getObject(java.lang.Class<T> type,
                                                OperationResult parentResult)
                                            throws ObjectNotFoundException,
                                                   SchemaException
Returns object that the task is associated with. Tasks may be associated with a particular objects. For example a "import from resource" task is associated with the resource definition object that it imports from. Similarly for synchronization and reconciliation tasks (cycles). This is an optional property. The object will only be returned if the task really contains an object without OID (e.g. unfinished account shadow). In all other cases this method may return null. Use getObjectRef instead. Optional. May return null.

Throws:
SchemaException
ObjectNotFoundException

getObjectRef

ObjectReferenceType getObjectRef()
Returns reference to the object that the task is associated with. Tasks may be associated with a particular objects. For example a "import from resource" task is associated with the resource definition object that it imports from. Similarly for synchronization and reconciliation tasks (cycles). This is an optional property.

Returns:

setObjectRef

void setObjectRef(ObjectReferenceType objectRef)

getObjectOid

java.lang.String getObjectOid()
Returns OID of the object that the task is associated with. Convenience method. This will get the OID from the objectRef.


getResult

OperationResult getResult()
Returns a top-level OperationResult stored in the task.

Returns:
task operation result.

setResult

void setResult(OperationResult result)

setResultImmediate

void setResultImmediate(OperationResult result,
                        OperationResult parentResult)
                        throws ObjectNotFoundException,
                               SchemaException
Throws:
ObjectNotFoundException
SchemaException

getLastRunStartTimestamp

java.lang.Long getLastRunStartTimestamp()
Returns the time when the task last run was started (or null if the task was never started).


getLastRunFinishTimestamp

java.lang.Long getLastRunFinishTimestamp()
Returns the time when the task last run was finished (or null if the task was not finished yet).


getNextRunStartTime

java.lang.Long getNextRunStartTime(OperationResult parentResult)
Returns the time when the task should start again. (For non-recurrent tasks it is ignored. For recurrent tasks, null value means 'start immediately', if missed schedule tolerance does not prevent it.)


getName

PolyStringType getName()
Returns human-readable name of the task.

Returns:
human-readable name of the task.

setName

void setName(PolyStringType value)
Sets the human-readable name of the task.

Parameters:
value - new human-readable name of the task.

setNameImmediate

void setNameImmediate(PolyStringType value,
                      OperationResult parentResult)
                      throws ObjectNotFoundException,
                             SchemaException,
                             ObjectAlreadyExistsException
Throws:
ObjectNotFoundException
SchemaException
ObjectAlreadyExistsException

getExtension

PrismContainer<?> getExtension()
Returns task extension. The extension is a part of task that can store arbitrary data. It usually holds data specific to a task type, internal task state, business state or similar data that are out of scope of this interface definition. Although this methods returns list, it should be rather regarded as set. The list is used to avoid unnecessary reordering of properties in the storage (in case store is ordering-sensitive).

Returns:
task extension

getExtension

PrismProperty<?> getExtension(javax.xml.namespace.QName propertyName)

setExtensionProperty

void setExtensionProperty(PrismProperty<?> property)
                          throws SchemaException
Throws:
SchemaException

setExtensionPropertyImmediate

void setExtensionPropertyImmediate(PrismProperty<?> property,
                                   OperationResult parentResult)
                                   throws ObjectNotFoundException,
                                          SchemaException
Throws:
ObjectNotFoundException
SchemaException

getProgress

long getProgress()

setProgress

void setProgress(long value)
Record progress of the task, storing it persistently if needed.

Throws:
SchemaException
ObjectNotFoundException

setProgressImmediate

void setProgressImmediate(long progress,
                          OperationResult parentResult)
                          throws ObjectNotFoundException,
                                 SchemaException
Throws:
ObjectNotFoundException
SchemaException

getTaskPrismObject

PrismObject<TaskType> getTaskPrismObject()

refresh

void refresh(OperationResult parentResult)
             throws ObjectNotFoundException,
                    SchemaException
Re-reads the task state from the persistent storage. The task state may be synchronized with the repository all the time. But the specified timing is implementation-specific. Call to this method will make sure that the task contains fresh data. This has no effect on transient tasks.

Parameters:
parentResult -
Throws:
SchemaException
ObjectNotFoundException

dump

java.lang.String dump()
Return human-readable representation of the task content. Useful for diagnostics. May return multi-line string.

Specified by:
dump in interface Dumpable
Returns:
human-readable representation of the task content

canRun

boolean canRun()
Returns true if the task can run (was not interrupted). Will return false e.g. if shutdown was signaled.

Returns:
true if the task can run

savePendingModifications

void savePendingModifications(OperationResult parentResult)
                              throws ObjectNotFoundException,
                                     SchemaException,
                                     ObjectAlreadyExistsException
Marks current handler as finished, and removes it from the handler stack. This method *probably* should be called either implicitly by SingleRunner (after a handler returns from run() method) or explicitly by task handler, in case of CycleRunner. TODO this has to be thought out a bit.

Throws:
ObjectNotFoundException
SchemaException
ObjectAlreadyExistsException

getCategory

java.lang.String getCategory()
Categories are treated in a special way. They can be set directly. But if not set directly, they are set on first task execution - determined based on task handler URI. List of categories is in the

Returns:
See Also:

makeRecurrentSimple

void makeRecurrentSimple(int interval)

makeRecurrentCron

void makeRecurrentCron(java.lang.String cronLikeSpecification)

makeSingle

void makeSingle()

getNode

java.lang.String getNode()

getResultStatus

OperationResultStatusType getResultStatus()

getThreadStopAction

ThreadStopActionType getThreadStopAction()

isResilient

boolean isResilient()
Resilient tasks are those that survive node shutdown. I.e. their ThreadStopAction is either 'restart' or 'reschedule'.

Returns:

getModelOperationState

ModelOperationStateType getModelOperationState()

setCategory

void setCategory(java.lang.String category)

setDescriptionImmediate

void setDescriptionImmediate(java.lang.String value,
                             OperationResult parentResult)
                             throws ObjectNotFoundException,
                                    SchemaException
Throws:
ObjectNotFoundException
SchemaException

setDescription

void setDescription(java.lang.String value)

getDescription

java.lang.String getDescription()

addExtensionProperty

void addExtensionProperty(PrismProperty<?> property)
                          throws SchemaException
Throws:
SchemaException

modifyExtension

void modifyExtension(ItemDelta itemDelta)
                     throws SchemaException
Throws:
SchemaException

deleteExtensionProperty

void deleteExtensionProperty(PrismProperty<?> property)
                             throws SchemaException
Removes specified VALUES of this extension property (not all of its values).

Parameters:
property -
Throws:
SchemaException

setModelOperationState

void setModelOperationState(ModelOperationStateType state)

setThreadStopAction

void setThreadStopAction(ThreadStopActionType value)

makeRecurrent

void makeRecurrent(ScheduleType schedule)

makeSingle

void makeSingle(ScheduleType schedule)

createSubtask

Task createSubtask()
Creates a subtask

Returns:

waitForSubtasks

TaskRunResult waitForSubtasks(java.lang.Integer interval,
                              OperationResult parentResult)
                              throws ObjectNotFoundException,
                                     SchemaException,
                                     ObjectAlreadyExistsException
Waits for subtasks to finish. Executes a special task handler which periodically tests for the completion of this tasks' children. SHOULD BE USED ONLY FROM A TASK HANDLER. Returns a TaskRunResult that should the task handler immediately return (in order to activate newly created 'waiting' task handler).

Throws:
ObjectNotFoundException
SchemaException
ObjectAlreadyExistsException

waitForSubtasks

TaskRunResult waitForSubtasks(java.lang.Integer interval,
                              java.util.Collection<ItemDelta<?>> extensionDeltas,
                              OperationResult parentResult)
                              throws ObjectNotFoundException,
                                     SchemaException,
                                     ObjectAlreadyExistsException
Throws:
ObjectNotFoundException
SchemaException
ObjectAlreadyExistsException

getParent

java.lang.String getParent()

pushHandlerUri

void pushHandlerUri(java.lang.String uri,
                    ScheduleType schedule,
                    TaskBinding binding)

pushHandlerUri

void pushHandlerUri(java.lang.String uri,
                    ScheduleType schedule,
                    TaskBinding binding,
                    java.util.Collection<ItemDelta<?>> extensionDeltas)

createExtensionDelta

ItemDelta<?> createExtensionDelta(PrismPropertyDefinition definition,
                                  java.lang.Object realValue)

pushHandlerUri

void pushHandlerUri(java.lang.String uri,
                    ScheduleType schedule,
                    TaskBinding binding,
                    ItemDelta<?> delta)

finishHandler

void finishHandler(OperationResult parentResult)
                   throws ObjectNotFoundException,
                          SchemaException
Throws:
ObjectNotFoundException
SchemaException


Copyright © 2012 evolveum. All Rights Reserved.