Package com.evolveum.midpoint.task.api

Interface Task

  • All Superinterfaces:
    DebugDumpable, StatisticsCollector
    All Known Subinterfaces:
    RunningTask
    All Known Implementing Classes:
    NullTaskImpl
    public interface Task
extends DebugDumpable, StatisticsCollector
    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. 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 persistent. 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 flushPendingModifications 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, Pavol Mederly

    • Field Detail

      • DOT_INTERFACE

        static final String DOT_INTERFACE

    • Method Detail

      • getTaskIdentifier

        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

      • getOid

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

      • getOwner

        PrismObject<? extends FocusType> 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<? extends FocusType> owner)
        Sets the task owner. BEWARE: sets the owner only for in-memory information. So do not call this method for persistent tasks! (until fixed)

      • getName

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

      • setName

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

      • setName

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

      • getDescription

        String getDescription()
        Returns task description.

      • setDescription

        void setDescription​(String value)
        Sets task description.

      • getPolicyRule

        PolicyRuleType getPolicyRule()
        Gets the policy rule defined for the task (for running task the returned value is a clone).

      • makeWaiting

        void makeWaiting()
        Status-changing method. It changes task's execution status to WAITING. Currently use only on transient tasks, on suspended tasks or from within task handler.

      • makeWaiting

        void makeWaiting​(TaskWaitingReason reason)
        Changes exec status to WAITING, with a given waiting reason. Currently use only on transient tasks or from within task handler.

      • makeRunnable

        void makeRunnable()
        Status-changing method. It changes task's execution status to RUNNABLE. Currently use ONLY on transient tasks.

      • setInitialExecutionStatus

        void setInitialExecutionStatus​(TaskExecutionStatus value)
        Sets task execution status. Can be used only for transient tasks (for safety reasons). However, it is better to use specific state-changing methods (makeWaiting, makeRunnable, ...).
        Parameters:
        value - new task execution status.
        See Also:
        TaskExecutionStatus

      • isClosed

        boolean isClosed()
        Returns true if the task is closed.

      • getCompletionTimestamp

        Long getCompletionTimestamp()
        Returns the completion timestamp - time when the task was closed (or null if it is not closed).

      • getWaitingReason

        TaskWaitingReason getWaitingReason()
        Returns the task waiting reason for a WAITING task.

      • getNode

        String getNode()
        Returns the node the task is currently executing at, based on repository information. This is present in all cases, however, it might be out-of-date, e.g. when node crashes.

      • getNodeAsObserved

        String getNodeAsObserved()

      • isTransient

        boolean isTransient()
        Returns true if task is transient (i.e. not stored in repository).

      • isPersistent

        boolean isPersistent()
        Returns true if task is persistent (i.e. stored in repository).

      • 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. Usually, asynchronous means the same as persistent. However, there can are lightweight tasks that are asynchronous but not stored in repository.
        Returns:
        true if the task is asynchronous.

      • getRecurrenceStatus

        TaskRecurrence getRecurrenceStatus()
        Returns task recurrence status.
        Returns:
        task recurrence status

      • isSingle

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

      • isRecurring

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

      • makeRecurring

        void makeRecurring​(ScheduleType schedule)
        Makes a task recurring, with a given schedule.

      • makeRecurringSimple

        void makeRecurringSimple​(int interval)
        Makes a task recurring, running in a fixed time intervals.
        Parameters:
        interval - interval to run the task (in seconds)

      • makeRecurringCron

        void makeRecurringCron​(String cronLikeSpecification)
        Makes a task recurring, running according to a cron-like schedule.
        Parameters:
        cronLikeSpecification - schedule specification

      • makeSingle

        void makeSingle()
        Makes a task single-run, with no particular schedule.

      • makeSingle

        void makeSingle​(ScheduleType schedule)
        Makes a task single-run, with a given schedule.

      • getGroupsWithLimits

        @NotNull
@NotNull Map<String,​Integer> getGroupsWithLimits()

      • getSchedule

        ScheduleType getSchedule()
        Returns the schedule.

      • getScheduleInterval

        Integer getScheduleInterval()

      • hasScheduleInterval

        boolean hasScheduleInterval()

      • getLastRunStartTimestamp

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

      • getLastRunFinishTimestamp

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

      • getNextRunStartTime

        Long getNextRunStartTime​(OperationResult parentResult)
        Returns the time when the task should start again.

      • getThreadStopAction

        ThreadStopActionType getThreadStopAction()
        Returns thread stop action (what happens when the task thread is stopped e.g. because of node going down).

      • setThreadStopAction

        void setThreadStopAction​(ThreadStopActionType value)
        Sets the thread stop action for this task.

      • isResilient

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

      • getBinding

        TaskBinding getBinding()
        Returns task binding.

      • isTightlyBound

        boolean isTightlyBound()
        Returns true if the task is tightly bound.

      • isLooselyBound

        boolean isLooselyBound()
        Returns true if the task is loosely bound.

      • setBinding

        void setBinding​(TaskBinding value)
        Sets the binding for this task.

      • getHandlerUri

        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​(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

      • 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.

      • pushHandlerUri

        void pushHandlerUri​(String uri,
                    ScheduleType schedule,
                    TaskBinding binding,
                    Collection<ItemDelta<?,​?>> extensionDeltas)
        Pushes a new handler URI onto the stack of handlers. This means that the provided handler URI becomes the current one. Current one becomes the first one on the stack of other handlers, etc. So the newly added handler will be started FIRST. Care must be taken not to interfere with the execution of a task handler. It is recommended to call this method when it is sure that no handler is executing. Alongwith URI, other information are set, namely schedule, binding, and parameters that will be put into task extension when the handler URI will be invoked.
        Parameters:
        uri - Handler URI to be put onto the stack.
        schedule - Schedule to be used to run the handler.
        binding - Binding to be used to run the handler.
        extensionDeltas - The feature is EXPERIMENTAL, do not use if not absolutely necessary.

      • pushHandlerUri

        void pushHandlerUri​(String uri,
                    ScheduleType schedule,
                    TaskBinding binding,
                    ItemDelta<?,​?> delta)
        Same as above, with one extension delta (not a collection of them).
        Parameters:
        delta - EXPERIMENTAL, do not use if not absolutely necessary.

      • getCategory

        String getCategory()
        Task category is a user-oriented term, hinting on what 'kind' of task is the one being considered (system task, workflow, live sync, ...). In most cases, category can be derived from the task handler. Category can be set directly; but if not set directly, it is set automatically on first task execution, determined based on task handler URI. List of categories is in the TaskCategory class.

      • setCategory

        void setCategory​(String category)
        Sets the task category.

      • addArchetypeInformation

        @Experimental
void addArchetypeInformation​(String archetypeOid)
        Adds an archetype for the task. Assumes that the task will NOT undergo full model processing, so this method will do everything by itself: creates an assignment, roleMembershipRef and archetypeRef. Throws an exception if an archetype is already assigned. This is temporary/experimental implementation. It was not tested for persistent tasks (although it should work also for them).

      • getExtensionOrClone

        PrismContainer<? extends ExtensionType> getExtensionOrClone()
        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. To maintain thread safety, for RunningTask this method returns extension clone. (So don't use the return value to modify the task extension if not sure whether the task is running.)
        Returns:
        task extension

      • hasExtension

        boolean hasExtension()

      • getExtensionPropertyOrClone

        <T> PrismProperty<T> getExtensionPropertyOrClone​(ItemName propertyName)
        Returns specified property from the extension
        Returns:
        null if extension or property does not exist.

      • getExtensionPropertyRealValue

        <T> T getExtensionPropertyRealValue​(ItemName propertyName)
        Returns specified single-valued property real value from the extension
        Returns:
        null if extension or property does not exist.

      • getExtensionContainerRealValueOrClone

        <T extends Containerable> T getExtensionContainerRealValueOrClone​(ItemName containerName)
        Returns specified single-valued container real value from the extension To ensure thread safety, in the case of running tasks the returned value is a clone of the live one.
        Returns:
        null if extension or container does not exist.

      • getExtensionReferenceOrClone

        PrismReference getExtensionReferenceOrClone​(ItemName name)
        Returns specified reference from the extension.
        Returns:
        null if extension or reference does not exist.

      • getExtensionItemOrClone

        <IV extends PrismValue,​ID extends ItemDefinition> Item<IV,​ID> getExtensionItemOrClone​(ItemName itemName)
        Returns specified item (property, reference or container) from the extension.
        Returns:
        null if extension or item does not exist To maintain thread safety, for running tasks returns a clone of the original item.

      • setExtensionProperty

        void setExtensionProperty​(PrismProperty<?> property)
                   throws SchemaException
        Sets a property in the extension - replaces existing value(s), if any, by the one(s) provided.
        Throws:
        SchemaException

      • setExtensionPropertyValue

        <T> void setExtensionPropertyValue​(QName propertyName,
                                   T value)
                            throws SchemaException
        Sets (i.e., replaces) the value of the given property in task extension.
        Parameters:
        propertyName - name of the property
        value - value of the property
        Throws:
        SchemaException

      • setExtensionPropertyValueTransient

        <T> void setExtensionPropertyValueTransient​(QName propertyName,
                                            T value)
                                     throws SchemaException
        Sets (i.e., replaces) the value of the given property in task extension - without writing to repo.
        Parameters:
        propertyName - name of the property
        value - value of the property
        Throws:
        SchemaException

      • setExtensionReference

        void setExtensionReference​(PrismReference reference)
                    throws SchemaException
        Sets a reference in the extension - replaces existing value(s), if any, by the one(s) provided.
        Throws:
        SchemaException

      • setExtensionContainer

        <C extends Containerable> void setExtensionContainer​(PrismContainer<C> item)
                                              throws SchemaException
        Sets a container in the extension - replaces existing value(s), if any, by the one(s) provided.
        Parameters:
        item - Container with value(s) to be put into task extension.
        Throws:
        SchemaException

      • setExtensionContainerValue

        <T extends Containerable> void setExtensionContainerValue​(QName containerName,
                                                          T value)
                                                   throws SchemaException
        Sets a container value in the extension - replaces existing value(s), if any, by the one provided.
        Parameters:
        containerName - name of the container
        value - value to be put into extension
        Throws:
        SchemaException

      • addExtensionProperty

        void addExtensionProperty​(PrismProperty<?> property)
                   throws SchemaException
        Adds value(s) to a given extension property.
        Parameters:
        property - holder of the value(s) to be added into task extension property
        Throws:
        SchemaException

      • addExtensionReference

        void addExtensionReference​(PrismReference reference)
                    throws SchemaException
        Adds value(s) to a given extension reference.
        Parameters:
        reference - holder of the value(s) to be added into task extension reference
        Throws:
        SchemaException

      • getObject

        <T extends ObjectType> PrismObject<T> getObject​(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). User approval and modification task may be associated with that user. 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 getObjectRefOrClone instead. Optional. May return null.
        Throws:
        ObjectNotFoundException
        SchemaException

      • getObjectRefOrClone

        ObjectReferenceType getObjectRefOrClone()
        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.

      • setObjectRef

        void setObjectRef​(ObjectReferenceType objectRef)
        Sets the object reference.

      • setObjectRef

        void setObjectRef​(String oid,
                  QName type)
        Sets the object reference.

      • setObjectTransient

        void setObjectTransient​(PrismObject object)
        Sets the "task object" in the in-memory task representation (i.e. not in the repo).

      • getObjectOid

        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. Beware of thread safety. This is a live object!
        Returns:
        task operation result.

      • getResultStatus

        OperationResultStatusType getResultStatus()
        Returns the status of top-level OperationResult stored in the task.
        Returns:
        task operation result status

      • setResult

        void setResult​(OperationResult result)
        Sets the top-level OperationResult stored in the task.

      • getProgress

        long getProgress()
        Returns task progress, as reported by task handler.

      • setProgress

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

      • setProgressTransient

        void setProgressTransient​(Long value)

      • getExpectedTotal

        @Nullable
@Nullable Long getExpectedTotal()
        Returns expected total progress.

      • setExpectedTotal

        void setExpectedTotal​(Long value)
        Stores expected total progress of the task, storing it persistently if needed.

      • createSubtask

        Task createSubtask()
        Creates a transient subtask. Owner is inherited from parent task to subtask.

      • getParent

        String getParent()
        Returns the identifier of the task's parent (or null of there is no parent task).

      • listSubtasksDeeply

        default List<Task> listSubtasksDeeply​(OperationResult result)
                               throws SchemaException
        List all the subtasks of a given task, i.e. whole task tree rooted at the current task. Current task is not contained in the returned list.
        Throws:
        SchemaException

      • getDependents

        List<String> getDependents()
        Lists all explicit dependents' identifiers.

      • addDependent

        void addDependent​(String taskIdentifier)
        Add a task as this task's dependent, i.e. the task denoted by taskIdentifier DEPENDS ON (waits for completion of) this task.

      • deleteDependent

        void deleteDependent​(String taskIdentifier)
        Deletes a task from the list of dependents of this task.

      • listPrerequisiteTasks

        List<Task> listPrerequisiteTasks​(OperationResult parentResult)
                          throws SchemaException
        List all prerequisite tasks for the current tasks, i.e. tasks that must complete before this one can proceed. If A is on the list of prerequisites of B (THIS), it means that B is on list of dependents of A (i.e. B waits for A to complete). Again, implicit prerequisites (children) are not listed here.
        Throws:
        SchemaException

      • startWaitingForTasksImmediate

        void startWaitingForTasksImmediate​(OperationResult result)
                            throws SchemaException,
                                   ObjectNotFoundException
        Starts "passive" waiting for other tasks. Precondition: The task must already be in WAITING state. Postcondition: If there are any tasks to wait for, task remains in WAITING/OTHER_TASKS state. However, if there are no tasks to wait for, task is either unpaused (if there is any handler) or closed (if there is not). Passive waiting consists of putting the task into WAITING/OTHER_TASKS state. Unpausing it is the responsibility of task manager - it does it when any of prerequisite tasks closes. At that moment, task manager checks all dependent tasks (explicit or implicit) of the closing task, and unpauses these, which can be unpaused.
        Throws:
        SchemaException
        ObjectNotFoundException

      • getChannel

        String getChannel()
        Returns change channel URI.

      • setChannel

        void setChannel​(String channelUri)
        Sets change channel URI.

      • getRequestee

        PrismObject<UserType> getRequestee()
        Gets the requestee OID - typically an identification of account owner (for notifications). Serves for communication between model and provisioning. It is a temporary feature - will be removed in midPoint 2.3.

      • getUpdatedOrClonedTaskObject

        @NotNull
@NotNull PrismObject<TaskType> getUpdatedOrClonedTaskObject()
        Returns backing task prism object. AVOID use of this method if possible. - for regular tasks it has to update operation result in the prism object (might be costly) - for running tasks it provides a clone of the actual prism object (even more costly and leads to lost changes if the returned value is changed)

      • getUpdatedTaskObject

        @NotNull
@NotNull PrismObject<TaskType> getUpdatedTaskObject()
        Returns backing task prism object, provided that task is not running. Beware that the task operation result is updated (might be costly).
        Throws:
        IllegalStateException - if task is running

      • getClonedTaskObject

        @NotNull
@NotNull PrismObject<TaskType> getClonedTaskObject()
        Returns cloned task object.

      • getPendingModifications

        Collection<ItemDelta<?,​?>> getPendingModifications()
        Returns a list of pending modifications for this task.

      • isPartitionedMaster

        boolean isPartitionedMaster()

      • getExecutionGroup

        String getExecutionGroup()

      • getAggregatedLiveOperationStats

        OperationStatsType getAggregatedLiveOperationStats()
        Gets information from the current task and - for running task - its transient subtasks (aka worker threads).

      • getVersion

        String getVersion()

      • getTriggers

        Collection<? extends TriggerType> getTriggers()
        NEVER modify objects returned in multithreaded environments!

      • getAssignments

        Collection<? extends AssignmentType> getAssignments()
        NEVER modify objects returned in multithreaded environments!

      • hasAssignments

        default boolean hasAssignments()

      • getOperationResultHandlingStrategyName

        String getOperationResultHandlingStrategyName()

      • isScavenger

        boolean isScavenger()

      • removeTracingRequests

        void removeTracingRequests()