Package com.evolveum.midpoint.task.api

Interface Task

  • All Superinterfaces:
    DebugDumpable, IterativeOperationCollector, MappingStatisticsCollector, NotificationStatisticsCollector, ObjectActionsCollector, ProvisioningStatisticsCollector, StatisticsCollector, SynchronizationInformationCollector
    All Known Subinterfaces:
    RunningLightweightTask, RunningTask
    All Known Implementing Classes:
    NullTaskImpl
    public interface Task
extends DebugDumpable, StatisticsCollector
    Task instance - a logical unit of work. It is executed either synchronously or asynchronously. When running asynchronously, it can be scheduled, suspended, or resumed. 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 (getItemName) reads data from the in-memory representation of a task. - A setter (setItemName) writes data to the in-memory representation, and (for persistent tasks) prepares a delta to be written into repository later. The deltas should be then written by calling flushPendingModifications(OperationResult) method. In case you want to write property change into the repository immediately, you have to use setItemNameImmediate method. In that case, the 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.

      • getOid

        String getOid()
        Returns task OID. Only persistent tasks have OID. So this method returns null if the task is not persistent.

      • getOwner

        PrismObject<? extends FocusType> getOwner​(OperationResult result)
        Returns object 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. The object is lazily fetched from repository.

      • getOwnerRef

        ObjectReferenceType getOwnerRef()
        Returns a reference to the task owner. (Cloned if the task is running.)

      • setOwner

        void setOwner​(PrismObject<? extends FocusType> owner)
        Sets the task owner. Precondition: Task is transient.

      • setOwnerRef

        void setOwnerRef​(ObjectReferenceType ownerRef)
        Sets the task owner reference. Precondition: Task is transient.

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

      • isRunnable

        default boolean isRunnable()

      • isRunning

        default boolean isRunning()

      • isClosed

        default boolean isClosed()
        Returns true if the task is closed. (Refers to the scheduling state.)

      • isReady

        default boolean isReady()
        Returns true if the task is ready. (Refers to the scheduling state.)

      • isWaiting

        default boolean isWaiting()
        Returns true if the task is waiting. (BEWARE: Refers to the scheduling state.)

      • isSuspended

        default boolean isSuspended()
        Returns true if the task is suspended. (BEWARE: Refers to the scheduling state.)

      • getWaitingReason

        TaskWaitingReasonType 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()
        Returns the node as really observed. This is a transient information that has to be requested explicitly.

      • setInitialExecutionAndScheduledState

        void setInitialExecutionAndScheduledState​(TaskExecutionStateType executionState,
                                          TaskSchedulingStateType schedulingState)
        Sets initial task execution and scheduled state. It will be used when the task is made persistent. Precondition: Task is transient.

      • setInitiallyRunnable

        default void setInitiallyRunnable()
        Sets the initial task execution and scheduling state to allow the task to run.

      • setInitiallySuspended

        default void setInitiallySuspended()
        Sets the initial task execution and scheduling state to make task suspended.

      • setInitiallyWaitingForPrerequisites

        void setInitiallyWaitingForPrerequisites()
        Sets the initial task execution and scheduling state to make task waiting (for prerequisite tasks).

      • getPersistenceStatus

        @NotNull
@NotNull TaskPersistenceStatus getPersistenceStatus()
        Returns task persistence status.

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

      • isRecurring

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

      • isSingle

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

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

      • getGroup

        String getGroup()
        Sets the execution group name (i.e. executionConstraints/group).

      • getGroups

        @NotNull
@NotNull Collection<String> getGroups()
        Returns names of all groups (primary plus all secondary ones).

      • getGroupsWithLimits

        @NotNull
@NotNull Map<String,​Integer> getGroupsWithLimits()
        Returns all groups (primary plus all secondary ones) along with task count limits.

      • getSchedule

        ScheduleType getSchedule()
        Returns the schedule.

      • getScheduleInterval

        Integer getScheduleInterval()
        Returns the schedule interval.

      • hasScheduleInterval

        boolean hasScheduleInterval()
        Returns true if the schedule interval is set.

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

      • getLastRunStartTimestamp

        Long getLastRunStartTimestamp()
        Returns the time when the task last run was started (or null if the task was never started). This is set only for asynchronously executing tasks. And it is set also for the current execution.

      • getLastRunFinishTimestamp

        Long getLastRunFinishTimestamp()
        Returns the time when the task last run was finished (or null if the task was not finished yet). This is set only for asynchronously executing tasks.

      • getNextRunStartTime

        Long getNextRunStartTime​(OperationResult result)
        Returns the time when the task should start again. This is transient property, present only if explicitly requested.

      • getCompletionTimestamp

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

      • isLooselyBound

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

      • isTightlyBound

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

      • getHandlerUri

        String getHandlerUri()
        Returns handler URI. It 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.

      • setHandlerUri

        void setHandlerUri​(String value)
        Sets handler URI.

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

      • getExtensionClone

        PrismContainer<? extends ExtensionType> getExtensionClone()
        Gets extension clone, or null if there is no extension.

      • getExtensionPropertyOrClone

        <T> PrismProperty<T> getExtensionPropertyOrClone​(ItemName propertyName)
        Returns specified property from the extension; or null if extension or property does not exist. Cloned if task is running.

      • getExtensionPropertyRealValue

        <T> T getExtensionPropertyRealValue​(ItemName propertyName)
        Returns specified single-valued property real value from the extension (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. Cloned if running task. 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. Cloned if running task. Null if extension or item does not exist.

      • 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

      • 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 result)
                                         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. If the task contains a reference without full object, the object is fetched from the repository. (Authorizations are *not* checked.)
        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.

      • getObjectOid

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

      • setObjectRef

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

      • setObjectRef

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

      • getResult

        OperationResult getResult()
        Returns a top-level OperationResult stored in the task. Beware of thread safety. This is a live object!

      • getResultStatus

        OperationResultStatusType getResultStatus()
        Returns the status of top-level OperationResult stored in the task. If "live" operation result is present, the status it taken from it. Otherwise, resultStatus from task prism is fetched. TODO reconsider this method

      • setResult

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

      • getProgress

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

      • setProgress

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

      • incrementProgressTransient

        void incrementProgressTransient()
        Increments legacy progress without creating a pending modification.

      • getStoredOperationStatsOrClone

        OperationStatsType getStoredOperationStatsOrClone()
        Returns operation statistics from the task prism object (i.e. not the live ones). Clones if running task.

      • getAggregatedLiveOperationStats

        OperationStatsType getAggregatedLiveOperationStats()
        Gets information from the current task and - for running task - its transient subtasks (aka worker threads). Clients beware: Update thread-local statistics before! They are not updated inside this method.

      • 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

        List<? extends 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

      • listSubtasksDeeply

        List<? extends Task> listSubtasksDeeply​(boolean persistentOnly,
                                        OperationResult result)
                                 throws SchemaException
        Lists all tasks in subtasks tree.
        Parameters:
        persistentOnly - If true, transient subtasks (i.e. lightweight asynchronous tasks) are ignored.
        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.

      • listPrerequisiteTasks

        List<? extends 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

      • getRawTaskObjectClonedIfNecessary

        @NotNull
@NotNull PrismObject<TaskType> getRawTaskObjectClonedIfNecessary()
        Returns backing task prism object without updating with current operation result. If the task is running, a clone is returned.

      • getRawTaskObjectClone

        @NotNull
@NotNull PrismObject<TaskType> getRawTaskObjectClone()
        Returns CLONE of backing task prism object without updating with current operation result.

      • getUpdatedTaskObject

        @NotNull
@NotNull PrismObject<TaskType> getUpdatedTaskObject()
        Returns backing task prism object UPDATED with current operation result. Assumes that task is not running. (Otherwise IllegalStateException is thrown.)

      • getSelfReference

        @NotNull
@NotNull ObjectReferenceType getSelfReference()
        Returns a reference to the task prism. Precondition: Task must be persistent.

      • getVersion

        String getVersion()
        Returns the version of underlying prism object.

      • getWorkManagement

        TaskWorkManagementType getWorkManagement()
        Gets work management information. NOT THREAD SAFE!

      • getWorkState

        TaskWorkStateType getWorkState()
        Gets task work state. NOT THREAD SAFE!

      • getKind

        TaskKindType getKind()
        Gets task kind (related to work management)

      • isScavenger

        boolean isScavenger()
        Returns true if the task is a scavenger (workManagement/scavenger).

      • addTracingRequest

        @Experimental
void addTracingRequest​(TracingRootType point)
        Requests (future) tracing for given tracing point - for this task.

      • removeTracingRequests

        @Experimental
void removeTracingRequests()
        Removes all tracing requests for this task.

      • getTracingProfile

        @Experimental
TracingProfileType getTracingProfile()
        Returns (reference to tracing profile) that was defined for the tracing started by this task. NOT THREAD SAFE!

      • setTracingProfile

        @Experimental
void setTracingProfile​(TracingProfileType tracingProfile)
        Sets the profile to be used for future tracing within this task.

      • getChannel

        String getChannel()
        Returns channel URI associated with this task.

      • setChannel

        void setChannel​(String channelUri)
        Sets 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.

      • getModelOperationContext

        LensContextType getModelOperationContext()
        Gets model operation context stored in task. NOT THREAD SAFE!

      • getExecutionEnvironment

        TaskExecutionEnvironmentType getExecutionEnvironment()
        Gets the execution environment configuration. Cloned if running task.

      • getCachingProfiles

        @NotNull
@NotNull Collection<String> getCachingProfiles()
        Returns an immutable collection of caching profiles. (From execution environment.)

      • setExecutionEnvironment

        void setExecutionEnvironment​(TaskExecutionEnvironmentType value)
        Sets the execution environment configuration.

      • getErrorHandlingStrategy

        TaskErrorHandlingStrategyType getErrorHandlingStrategy()
        Gets error handling strategy. NOT THREAD SAFE! Use only for reading.

      • hasAssignments

        boolean hasAssignments()
        Returns true if the task has any assignments.

      • getPolicyRule

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