com.evolveum.midpoint.task.api
Interface Task

All Superinterfaces:
Dumpable
All Known Implementing Classes:
TaskImpl

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. TODO: change model. How to propagate task changes down to the repository. attached or detached?

Author:
Radovan Semancik

Method Summary
 boolean canRun()
          Returns true if the task can run (was not interrupted).
 void close(OperationResult parentResult)
          Close the task.
 java.lang.String dump()
          Return human-readable representation of the task content.
 TaskExclusivityStatus getExclusivityStatus()
          Returns task exclusivity status.
 TaskExecutionStatus getExecutionStatus()
          Returns execution status.
 PropertyContainer getExtension()
          Returns task extension.
 Property getExtension(javax.xml.namespace.QName propertyName)
           
 java.lang.String getHandlerUri()
          Returns handler URI.
 java.lang.Long getLastRunFinishTimestamp()
           
 java.lang.Long getLastRunStartTimestamp()
           
 java.lang.String getName()
          Returns human-readable name of the task.
<T extends ObjectType>
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.
 TaskPersistenceStatus getPersistenceStatus()
          Returns task persistence status.
 long getProgress()
           
 OperationResult getResult()
          Returns a top-level OperationResult stored in the task.
 ScheduleType getSchedule()
           
 TaskType getTaskTypeObject()
           
 boolean isAsynchronous()
          Returns true if the task is asynchronous.
 boolean isCycle()
           
 boolean isSingle()
           
 void modifyExtension(java.util.List<PropertyModification> modifications, OperationResult parentResult)
          TODO The modification path is relative to the extension, therefore it will almost always be "." (or null).
 void recordProgress(long progress, OperationResult parentResult)
          Record progress of the task, storing it persistently if needed.
 void recordRunFinish(TaskRunResult runResult, OperationResult parentResult)
          Record finish of the last "run" of the task TODO: better documentation
 void recordRunStart(OperationResult parentResult)
           
 void refresh(OperationResult parentResult)
          Re-reads the task state from the persistent storage.
 void setExclusivityStatus(TaskExclusivityStatus exclusivityStatus)
          Sets task exclusivity status.
 void setExecutionStatus(TaskExecutionStatus executionStatus)
          Sets task execution status.
 void setHandlerUri(java.lang.String handlerUri)
          Sets handler URI.
 void setName(java.lang.String name)
          Sets the human-readable name of the task.
 void setObjectRef(ObjectReferenceType objectRef)
           
 void setOid(java.lang.String oid)
          Sets task OID.
 void setPersistenceStatus(TaskPersistenceStatus persistenceStatus)
          Sets task persistence status.
 void shutdown()
          Signal the task to shut down.
 

Method Detail

getExecutionStatus

TaskExecutionStatus getExecutionStatus()
Returns execution status.

Returns:
execution status.
See Also:
TaskExecutionStatus

setExecutionStatus

void setExecutionStatus(TaskExecutionStatus executionStatus)
Sets task execution status.

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

getPersistenceStatus

TaskPersistenceStatus getPersistenceStatus()
Returns task persistence status.

Returns:
task persistence status.
See Also:
TaskPersistenceStatus

setPersistenceStatus

void setPersistenceStatus(TaskPersistenceStatus persistenceStatus)
Sets task persistence status.

Parameters:
persistenceStatus - new task persistence status.
See Also:
TaskPersistenceStatus

getExclusivityStatus

TaskExclusivityStatus getExclusivityStatus()
Returns task exclusivity status.

Returns:
task exclusivity status.
See Also:
TaskExclusivityStatus

setExclusivityStatus

void setExclusivityStatus(TaskExclusivityStatus exclusivityStatus)
Sets task exclusivity status.

Parameters:
exclusivityStatus - new task exclusivity status.
See Also:
TaskExclusivityStatus

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 handlerUri)
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:
handlerUri - new handler URI

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.

getTaskTypeObject

TaskType getTaskTypeObject()

getOid

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

Returns:
task OID

setOid

void setOid(java.lang.String oid)
Sets task OID. This method should not be used outside task manager. The OID should be considered read-only. TODO: be stricter and maybe do not publish this method at all.

Parameters:
oid - new task OID.

getObject

<T extends ObjectType> 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.

getLastRunStartTimestamp

java.lang.Long getLastRunStartTimestamp()

getLastRunFinishTimestamp

java.lang.Long getLastRunFinishTimestamp()

getName

java.lang.String getName()
Returns human-readable name of the task.

Returns:
human-readable name of the task.

setName

void setName(java.lang.String name)
Sets the human-readable name of the task.

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

getProgress

long getProgress()

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:
result -
Throws:
SchemaException
ObjectNotFoundException

getExtension

PropertyContainer 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). Returned list should be regarded as immutable. In case that the client does any change, weird things may happen.

Returns:
task extension

getExtension

Property getExtension(javax.xml.namespace.QName propertyName)

modifyExtension

void modifyExtension(java.util.List<PropertyModification> modifications,
                     OperationResult parentResult)
                     throws ObjectNotFoundException,
                            SchemaException
TODO The modification path is relative to the extension, therefore it will almost always be "." (or null).

Parameters:
modification -
Throws:
SchemaException
ObjectNotFoundException

recordRunFinish

void recordRunFinish(TaskRunResult runResult,
                     OperationResult parentResult)
                     throws ObjectNotFoundException,
                            SchemaException
Record finish of the last "run" of the task TODO: better documentation

Parameters:
runResult - result of the run to record
Throws:
SchemaException
ObjectNotFoundException

recordRunStart

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

recordProgress

void recordProgress(long progress,
                    OperationResult parentResult)
                    throws ObjectNotFoundException,
                           SchemaException
Record progress of the task, storing it persistently if needed.

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

close

void close(OperationResult parentResult)
           throws ObjectNotFoundException,
                  SchemaException
Close the task. This will NOT release the task. TODO

Parameters:
runnerRunOpResult -
Throws:
ObjectNotFoundException
SchemaException

isSingle

boolean isSingle()

isCycle

boolean isCycle()

getSchedule

ScheduleType getSchedule()

shutdown

void shutdown()
Signal the task to shut down. It may not stop immediately, but it should stop eventually.


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


Copyright © 2011 evolveum. All Rights Reserved.