Package org.nuxeo.ecm.core.work.api

Interface Work

All Superinterfaces:
Serializable
All Known Implementing Classes:
AbstractIndexingWorker, AbstractRenditionBuilderWork, AbstractWork, AsyncEventExecutor.ListenerWork, AutomationRenditionBuilder, BaseIndexingWorker, BatchFinderWork, BatchProcessorWork, BinaryMetadataUpdateWork, BinaryMetadataWork, BlobListZipWork, BlobProviderDocumentsUpdateWork, BucketIndexingWorker, ChildrenIndexingWorker, ComputeDigestWork, ConversionWork, CSVImporterWork, DBSTransactionState.FindReadAclsWork, DBSTransactionState.UpdateReadAclsWork, DocumentRoutingEscalationServiceImpl.EscalationRuleWork, DuplicateCollectionMemberWork, ESAuditMigrationWork, FulltextExtractorWork, ImagingRecomputeWork, IndexingWorker, PermissionsPurgeWork, PictureViewsGenerationWork, PreviewWork, QuotaMaxSizeSetterWork, QuotaStatsInitialWork, RemovedAbstractWork, RemovedCollectionMemberWork, RemovedCollectionWork, RemoveFromCollectionWork, RenditionWork, ScrollingIndexingWorker, SleepWork, ThreeDBatchUpdateWork, ThumbnailRecomputeWork, TransiantStorageGCWork, TransientStoreWork, UpdateACEStatusWork, UserProfileImporterWork, VideoConversionWork, VideoInfoWork, VideoStoryboardWork
public interface Work extends Serializable
A Work instance gets scheduled and executed by a WorkManager .

Its work() method runs when a slot in a queue becomes available, note however that it can be suspended at any time (before initial execution, or during execution).

A Work instance has an id that is used by the queuing mechanisms to determine uniqueness. It also has a category that is used to choose which queue should execute it. It can report its status and progress.

A Work instance is Serializable because it must be able to save its computation state on interruption, and be reconstructed again with the saved state to continue execution at a later time. Because of this, the instance itself may change over time and be executed on a different JVM than the one that constructed it initially.

A Work instance must have an id, which is used for equality comparisons and as a key for persistent queues.

Implementors are strongly advised to inherit from AbstractWork.

Since:
5.6
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    Work.Progress
    A progress report about a work instance.
    static enum 
    Work.State
    The running state of a Work instance.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    cleanUp(boolean ok, Exception e)
    This method is called after work() is done, in a finally block, whether work completed normally or was in error or was interrupted.
    String
    getCategory()
    Gets the category for this work.
    long
    getCompletionTime()
    Gets the time at which this work instance was completed, suspended or failed.
    DocumentLocation
    getDocument()
    Gets the document impacted by the work.
    List<DocumentLocation>
    getDocuments()
    Gets the documents impacted by the work.
    String
    getId()
    The work id.
    String
    getOriginatingUsername()
    Gets the user on behalf of which this work is done.
    default String
    getPartitionKey()
    Returns a key that can be used by the WorkManager implementation to guarantee that works with the same partition key will be executed in the order they are submitted.
    Work.Progress
    getProgress()
    Gets a progress report for this work instance.
    WorkSchedulePath
    getSchedulePath()
    Returns the schedule path
    long
    getSchedulingTime()
    Gets the time at which this work instance was first scheduled.
    long
    getStartTime()
    Gets the time at which this work instance was first started.
    String
    getStatus()
    Gets a human-readable status for this work instance.
    String
    getTitle()
    Gets a human-readable name for this work instance.
    Work.State
    getWorkInstanceState()
    CALLED BY THE WORK MANAGER (not user code) to get this work instance's state.
    default boolean
    isCoalescing()
    When setting the coalescing flag to true you indicate to the work manager that if multiple works with the same id are scheduled you only care about the lastest execution.
    boolean
    isDocumentTree()
    Returns true if getDocument() is only the root of a set of documents on which this Work instance will act.
    default boolean
    isGroupJoin()
    When true the Work is part of a group, Works of the group have the same getPartitionKey().
    default boolean
    isIdempotent()
    Returns true if a work with a given getId() should always produce the same result.
    boolean
    isSuspending()
    Checks if a suspend has been requested for this work instance by the work manager.
    boolean
    isWorkInstanceSuspended()
    CALLED BY THE WORK MANAGER (not user code) to check if this work instance really suspended.
    default void
    onGroupJoinCompletion()
    Called when isGroupJoin() returns true and after the last Work of the group.
    void
    run()
    Runs the work instance and does all the transaction management and retry.
    void
    setProgress(Work.Progress progress)
    This method should be called periodically by the actual work method when it knows of its progress.
    void
    setSchedulePath(WorkSchedulePath path)
    Set the schedule path, internal usage
    void
    setStartTime()
    CALLED BY THE WORK MANAGER (not user code) to set the start time on the work instance.
    void
    setWorkInstanceState(Work.State state)
    CALLED BY THE WORK MANAGER (not user code) to set this work instance's state.
    void
    setWorkInstanceSuspending()
    CALLED BY THE WORK MANAGER (not user code) when it requests that this work instance be suspended.
    void
    suspended()
    Must be called by Work implementations to advertise that state saving is done, when isSuspending() returned true.
    void
    work()
    This method should implement the actual work done by the Work instance.

  • Method Details

    • run

      void run()
      Runs the work instance and does all the transaction management and retry.
      Implementation Note:
      Usually only implemented by AbstractWork, which should be subclassed instead of implementing this method.

    • work

      void work()
      This method should implement the actual work done by the Work instance.

      It should periodically update its progress through setProgress(org.nuxeo.ecm.core.work.api.Work.Progress).

      To allow for suspension by the WorkManager, it should periodically call isSuspending(), and if true call suspended() return early with saved state data.

      Clean up can by implemented by cleanUp(boolean, Exception).

      See Also:

    • getId

      String getId()
      The work id.

      The id is used for equality comparisons, and as a key in persistent queues.

      Returns:
      the work id, which must not be null
      Since:
      5.8

    • cleanUp

      void cleanUp(boolean ok, Exception e)
      This method is called after work() is done, in a finally block, whether work completed normally or was in error or was interrupted.
      Parameters:
      ok - true if the work completed normally
      e - the exception, if available

    • setWorkInstanceSuspending

      void setWorkInstanceSuspending()
      CALLED BY THE WORK MANAGER (not user code) when it requests that this work instance be suspended.
      Since:
      5.8

    • isSuspending

      boolean isSuspending()
      Checks if a suspend has been requested for this work instance by the work manager.

      If true, then state should be saved, suspended() should be called, and the work() method should return.

      Since:
      5.8

    • suspended

      void suspended()
      Must be called by Work implementations to advertise that state saving is done, when isSuspending() returned true. After this is called, the work() method should return.
      Since:
      5.8

    • isWorkInstanceSuspended

      boolean isWorkInstanceSuspended()
      CALLED BY THE WORK MANAGER (not user code) to check if this work instance really suspended.
      Since:
      5.8

    • setWorkInstanceState

      void setWorkInstanceState(Work.State state)
      CALLED BY THE WORK MANAGER (not user code) to set this work instance's state.
      Since:
      5.8

    • getWorkInstanceState

      Work.State getWorkInstanceState()
      CALLED BY THE WORK MANAGER (not user code) to get this work instance's state.

      Used only to get the final state of a completed instance.

      Since:
      5.8

    • getCategory

      String getCategory()
      Gets the category for this work.

      Used to choose an execution queue.

      Returns:
      the category, or null for the default

    • getTitle

      String getTitle()
      Gets a human-readable name for this work instance.
      Returns:
      a human-readable name

    • getStatus

      String getStatus()
      Gets a human-readable status for this work instance.
      Returns:
      a human-readable status

    • getSchedulingTime

      long getSchedulingTime()
      Gets the time at which this work instance was first scheduled.
      Returns:
      the scheduling time (milliseconds since epoch)

    • getStartTime

      long getStartTime()
      Gets the time at which this work instance was first started.
      Returns:
      the start time (milliseconds since epoch), or 0 if not stated

    • getCompletionTime

      long getCompletionTime()
      Gets the time at which this work instance was completed, suspended or failed.
      Returns:
      the completion time (milliseconds since epoch), or 0 if not completed

    • setStartTime

      void setStartTime()
      CALLED BY THE WORK MANAGER (not user code) to set the start time on the work instance.
      Since:
      5.9.2

    • setProgress

      void setProgress(Work.Progress progress)
      This method should be called periodically by the actual work method when it knows of its progress.
      Parameters:
      progress - the progress
      See Also:

    • getProgress

      Work.Progress getProgress()
      Gets a progress report for this work instance.
      Returns:
      a progress report, not null

    • getOriginatingUsername

      String getOriginatingUsername()
      Gets the user on behalf of which this work is done.
      Returns:
      the originating username, or null
      Since:
      8.1

    • getDocument

      DocumentLocation getDocument()
      Gets the document impacted by the work.

      Returns null if the work isn't about a single document.

      Returns:
      the document, or null. This is always a DocumentLocation with an IdRef
      Since:
      5.8

    • getDocuments

      List<DocumentLocation> getDocuments()
      Gets the documents impacted by the work.

      Returns null if the work isn't about documents.

      Returns:
      the documents, or an empty list. List elements are always a DocumentLocation with an IdRef
      Since:
      5.8

    • isDocumentTree

      boolean isDocumentTree()
      Returns true if getDocument() is only the root of a set of documents on which this Work instance will act.
      Returns:
      true if a whole tree is impacted
      Since:
      5.8

    • getSchedulePath

      WorkSchedulePath getSchedulePath()
      Returns the schedule path
      Since:
      5.8

    • setSchedulePath

      void setSchedulePath(WorkSchedulePath path)
      Set the schedule path, internal usage
      Since:
      5.8

    • getPartitionKey

      default String getPartitionKey()
      Returns a key that can be used by the WorkManager implementation to guarantee that works with the same partition key will be executed in the order they are submitted.
      Since:
      9.3

    • isIdempotent

      default boolean isIdempotent()
      Returns true if a work with a given getId() should always produce the same result. The WorkManager implementation can safely skip duplicate executions of idempotent work.
      Since:
      10.1

    • isCoalescing

      default boolean isCoalescing()
      When setting the coalescing flag to true you indicate to the work manager that if multiple works with the same id are scheduled you only care about the lastest execution. The goal is to skip useless executions to save resources, It is up to the work manager implementation to support or not this optimization.
      Since:
      10.3

    • isGroupJoin

      default boolean isGroupJoin()
      When true the Work is part of a group, Works of the group have the same getPartitionKey(). When all Works of the group are done the onGroupJoinCompletion() hook is called.
      Since:
      11.1

    • onGroupJoinCompletion

      default void onGroupJoinCompletion()
      Called when isGroupJoin() returns true and after the last Work of the group.
      Since:
      11.1