Work (Nuxeo ECM Projects 9.10-SNAPSHOT API)

All Superinterfaces:

Serializable

All Known Implementing Classes:

AbstractIndexingWorker, AbstractRenditionBuilderWork, AbstractWork, AsyncEventExecutor.ListenerWork, AutomationRenditionBuilder, BaseIndexingWorker, BatchFinderWork, BatchProcessorWork, BinaryMetadataWork, BlobListZipWork, BlobProviderDocumentsUpdateWork, BucketIndexingWorker, ChildrenIndexingWorker, ConversionWork, CSVImporterWork, DBSFulltextExtractorWork, DBSTransactionState.FindReadAclsWork, DBSTransactionState.UpdateReadAclsWork, DocumentRoutingEscalationServiceImpl.EscalationRuleWork, DuplicateCollectionMemberWork, ESAuditMigrationWork, ExtractXmlAttributesWorker, FulltextExtractorWork, FulltextUpdaterWork, ImagingRecomputeWork, IndexingWorker, MediaPublishingUploadWork, PermissionsPurgeWork, PictureViewsGenerationWork, QuotaMaxSizeSetterWork, QuotaStatsInitialWork, RemovedAbstractWork, RemovedCollectionMemberWork, RemovedCollectionWork, RemoveFromCollectionWork, ScrollingIndexingWorker, SleepWork, SQLFulltextExtractorWork, ThreeDBatchUpdateWork, TransiantStorageGCWork, TransientStoreWork, UpdateACEStatusWork, UserProfileImporterWork, VideoConversionWork
```
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:

AbstractWork

Nested Class Summary

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

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and 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.
`boolean`	`isDocumentTree()` Returns `true` if `getDocument()` is only the root of a set of documents on which this Work instance will act.
`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.
`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 Detail
  - run
```
void run()
```
    Runs the work instance and does all the transaction management and retry.
    Usually only implemented by AbstractWork, which should be subclassed instead of implementing run() .
  - 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().
    
    See Also:
    
    isSuspending(), suspended(), cleanUp(boolean, java.lang.Exception)
  - 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 ( State#COMPLETED, State#FAILED or State#CANCELED).
    
    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:
    
    Progress#Progress(float), Progress#Progress(long, long)
  - 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

Interface Work

Nested Class Summary

Method Summary

Method Detail

run

work

getId

cleanUp

setWorkInstanceSuspending

isSuspending

suspended

isWorkInstanceSuspended

setWorkInstanceState

getWorkInstanceState

getCategory

getTitle

getStatus

getSchedulingTime

getStartTime

getCompletionTime

setStartTime

setProgress

getProgress

getOriginatingUsername

getDocument

getDocuments

isDocumentTree

getSchedulePath

setSchedulePath

getPartitionKey