Package org.nuxeo.ecm.core.work

Class AbstractWork

java.lang.Object
org.nuxeo.ecm.core.work.AbstractWork
All Implemented Interfaces:
Serializable, Work
Direct Known Subclasses:
AsyncEventExecutor.ListenerWork, BaseIndexingWorker, BatchFinderWork, BatchProcessorWork, BinaryMetadataUpdateWork, BinaryMetadataWork, BlobProviderDocumentsUpdateWork, ComputeDigestWork, DocumentRoutingEscalationServiceImpl.EscalationRuleWork, DuplicateCollectionMemberWork, ESAuditMigrationWork, FulltextExtractorWork, ImagingRecomputeWork, PictureViewsGenerationWork, PreviewWork, QuotaMaxSizeSetterWork, QuotaStatsInitialWork, RemovedAbstractWork, RemoveFromCollectionWork, RenditionWork, SleepWork, ThreeDBatchUpdateWork, ThumbnailRecomputeWork, TransiantStorageGCWork, TransientStoreWork, UpdateACEStatusWork, UserProfileImporterWork, VideoConversionWork, VideoInfoWork, VideoStoryboardWork
public abstract class AbstractWork extends Object implements Work
A base implementation for a Work instance, dealing with most of the details around state change.

It also deals with transaction management, and prevents running work instances that are suspending.

Actual implementations must at a minimum implement the work() method. A method cleanUp(boolean, java.lang.Exception) is available.

To deal with suspension, work() should periodically check for isSuspending() and if true save its state and call suspended().

Specific information about the work can be returned by getDocument() or getDocuments().

Since:
5.6
See Also:

  • Field Details

    • RANDOM

      protected static final Random RANDOM

    • WORK_FAILED_EVENT

      public static final String WORK_FAILED_EVENT
      See Also:

    • WORK_INSTANCE

      public static final String WORK_INSTANCE
      See Also:

    • FAILURE_MSG

      public static final String FAILURE_MSG
      See Also:

    • FAILURE_EXCEPTION

      public static final String FAILURE_EXCEPTION
      See Also:

    • id

      protected String id

    • suspending

      protected transient volatile boolean suspending
      Suspend requested by the work manager.

    • suspended

      protected transient volatile boolean suspended
      Suspend acknowledged by the work instance.

    • state

      protected Work.State state

    • progress

      protected Work.Progress progress

    • repositoryName

      protected String repositoryName
      Repository name for the Work instance, if relevant.

    • docId

      protected String docId
      Doc id for the Work instance, if relevant. This describes for the WorkManager a document on which this Work instance will act.

      Either docId or docIds is set. Not both.

    • docIds

      protected List<String> docIds
      Doc ids for the Work instance, if relevant. This describes for the WorkManager the documents on which this Work instance will act.

      Either docId or docIds is set. Not both.

    • isTree

      protected boolean isTree
      If true, the docId is only the root of a set of documents on which this Work instance will act.

    • originatingUsername

      protected String originatingUsername
      The originating username to use when opening the CoreSession.
      Since:
      8.1

    • status

      protected String status

    • schedulingTime

      protected long schedulingTime

    • startTime

      protected long startTime

    • completionTime

      protected long completionTime

    • session

      protected transient CoreSession session

    • loginContext

      protected transient NuxeoLoginContext loginContext

    • schedulePath

      protected WorkSchedulePath schedulePath

    • callerThread

      protected String callerThread

    • GLOBAL_DLQ_COUNT_REGISTRY_NAME

      public static final String GLOBAL_DLQ_COUNT_REGISTRY_NAME

    • traceContext

      protected byte[] traceContext

  • Constructor Details

    • AbstractWork

      public AbstractWork()
      Constructs a Work instance with a unique id.

    • AbstractWork

      public AbstractWork(String id)

  • Method Details

    • getId

      public String getId()
      Description copied from interface: Work
      The work id.

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

      Specified by:
      getId in interface Work
      Returns:
      the work id, which must not be null

    • getSchedulePath

      public WorkSchedulePath getSchedulePath()
      Description copied from interface: Work
      Returns the schedule path
      Specified by:
      getSchedulePath in interface Work

    • setSchedulePath

      public void setSchedulePath(WorkSchedulePath path)
      Description copied from interface: Work
      Set the schedule path, internal usage
      Specified by:
      setSchedulePath in interface Work

    • setDocument

      public void setDocument(String repositoryName, String docId, boolean isTree)

    • setDocument

      public void setDocument(String repositoryName, String docId)

    • setDocuments

      public void setDocuments(String repositoryName, List<String> docIds)

    • setOriginatingUsername

      public void setOriginatingUsername(String originatingUsername)
      Since:
      8.1

    • setWorkInstanceSuspending

      public void setWorkInstanceSuspending()
      Description copied from interface: Work
      CALLED BY THE WORK MANAGER (not user code) when it requests that this work instance be suspended.
      Specified by:
      setWorkInstanceSuspending in interface Work

    • isSuspending

      public boolean isSuspending()
      Description copied from interface: Work
      Checks if a suspend has been requested for this work instance by the work manager.

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

      Specified by:
      isSuspending in interface Work

    • suspended

      public void suspended()
      Description copied from interface: Work
      Must be called by Work implementations to advertise that state saving is done, when Work.isSuspending() returned true. After this is called, the Work.work() method should return.
      Specified by:
      suspended in interface Work

    • isWorkInstanceSuspended

      public boolean isWorkInstanceSuspended()
      Description copied from interface: Work
      CALLED BY THE WORK MANAGER (not user code) to check if this work instance really suspended.
      Specified by:
      isWorkInstanceSuspended in interface Work

    • setWorkInstanceState

      public void setWorkInstanceState(Work.State state)
      Description copied from interface: Work
      CALLED BY THE WORK MANAGER (not user code) to set this work instance's state.
      Specified by:
      setWorkInstanceState in interface Work

    • getWorkInstanceState

      public Work.State getWorkInstanceState()
      Description copied from interface: Work
      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.

      Specified by:
      getWorkInstanceState in interface Work

    • setProgress

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

    • getProgress

      public Work.Progress getProgress()
      Description copied from interface: Work
      Gets a progress report for this work instance.
      Specified by:
      getProgress in interface Work
      Returns:
      a progress report, not null

    • setStatus

      public void setStatus(String status)
      Sets a human-readable status for this work instance.
      Parameters:
      status - the status

    • getStatus

      public String getStatus()
      Description copied from interface: Work
      Gets a human-readable status for this work instance.
      Specified by:
      getStatus in interface Work
      Returns:
      a human-readable status

    • openSystemSession

      public void openSystemSession()
      May be called by implementing classes to open a System session on the repository.
      Since:
      8.1

    • openUserSession

      public void openUserSession()
      May be called by implementing classes to open a Use session on the repository.

      It uses the set originatingUsername to open the session.

      Since:
      8.1

    • closeSession

      public void closeSession()
      Closes the session that was opened by openSystemSession() or openUserSession().
      Since:
      5.8

    • run

      public void run()
      Description copied from interface: Work
      Runs the work instance and does all the transaction management and retry.
      Specified by:
      run in interface Work

    • getSpanFromContext

      protected io.opencensus.trace.Span getSpanFromContext(byte[] traceContext)

    • buildWorkFailureEventProps

      public Map<String,Serializable> buildWorkFailureEventProps(RuntimeException exception)
      Builds failure event properties. Work implementations can override this method to inject more event properties than the default.
      Since:
      10.1

    • workFailed

      public void workFailed(RuntimeException exception)
      Called when the worker failed to run successfully even after retrying.
      Parameters:
      exception - the exception that occurred
      Since:
      10.1

    • appendWorkToDeadLetterQueue

      protected void appendWorkToDeadLetterQueue()

    • runWorkWithTransaction

      protected void runWorkWithTransaction()
      Does work under a transaction.
      Since:
      5.9.4

    • work

      public abstract void work()
      Description copied from interface: Work
      This method should implement the actual work done by the Work instance.

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

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

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

      Specified by:
      work in interface Work
      See Also:

    • getRetryCount

      public int getRetryCount()
      Gets the number of times that this Work instance can be retried in case of concurrent update exceptions.
      Returns:
      0 for no retry, or more if some retries are possible
      Since:
      5.8
      See Also:

    • cleanUp

      public 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.
      Specified by:
      cleanUp in interface Work
      Parameters:
      ok - true if the work completed normally
      e - the exception, if available

    • getOriginatingUsername

      public String getOriginatingUsername()
      Description copied from interface: Work
      Gets the user on behalf of which this work is done.
      Specified by:
      getOriginatingUsername in interface Work
      Returns:
      the originating username, or null

    • getSchedulingTime

      public long getSchedulingTime()
      Description copied from interface: Work
      Gets the time at which this work instance was first scheduled.
      Specified by:
      getSchedulingTime in interface Work
      Returns:
      the scheduling time (milliseconds since epoch)

    • getStartTime

      public long getStartTime()
      Description copied from interface: Work
      Gets the time at which this work instance was first started.
      Specified by:
      getStartTime in interface Work
      Returns:
      the start time (milliseconds since epoch), or 0 if not stated

    • getCompletionTime

      public long getCompletionTime()
      Description copied from interface: Work
      Gets the time at which this work instance was completed, suspended or failed.
      Specified by:
      getCompletionTime in interface Work
      Returns:
      the completion time (milliseconds since epoch), or 0 if not completed

    • setStartTime

      public void setStartTime()
      Description copied from interface: Work
      CALLED BY THE WORK MANAGER (not user code) to set the start time on the work instance.
      Specified by:
      setStartTime in interface Work

    • setCompletionTime

      protected void setCompletionTime()

    • getCategory

      public String getCategory()
      Description copied from interface: Work
      Gets the category for this work.

      Used to choose an execution queue.

      Specified by:
      getCategory in interface Work
      Returns:
      the category, or null for the default

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getDocument

      public DocumentLocation getDocument()
      Description copied from interface: Work
      Gets the document impacted by the work.

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

      Specified by:
      getDocument in interface Work
      Returns:
      the document, or null. This is always a DocumentLocation with an IdRef

    • getDocuments

      public List<DocumentLocation> getDocuments()
      Description copied from interface: Work
      Gets the documents impacted by the work.

      Returns null if the work isn't about documents.

      Specified by:
      getDocuments in interface Work
      Returns:
      the documents, or an empty list. List elements are always a DocumentLocation with an IdRef

    • newDocumentLocation

      protected DocumentLocation newDocumentLocation(String docId)

    • isDocumentTree

      public boolean isDocumentTree()
      Description copied from interface: Work
      Returns true if Work.getDocument() is only the root of a set of documents on which this Work instance will act.
      Specified by:
      isDocumentTree in interface Work
      Returns:
      true if a whole tree is impacted

    • commitOrRollbackTransaction

      public void commitOrRollbackTransaction()
      Releases the transaction resources by committing the existing transaction (if any). This is recommended before running a long process.

    • startTransaction

      public boolean startTransaction()
      Starts a new transaction.

      Usually called after commitOrRollbackTransaction(), for instance for saving back the results of a long process.

      Returns:
      true if a new transaction was started

    • equals

      public boolean equals(Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • getPartitionKey

      public String getPartitionKey()
      Description copied from interface: Work
      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.
      Specified by:
      getPartitionKey in interface Work