org.nuxeo.ecm.core.work.api

Interface Work

All Superinterfaces:

Serializable

All Known Implementing Classes:

AbstractIndexingWorker, AbstractRenditionBuilderWork, AbstractWork, AclAuditWork, AutomationRenditionBuilder, BaseIndexingWorker, BinaryMetadataWork, BucketIndexingWorker, ChildrenIndexingWorker, CSVImporterWork, DBSFulltextExtractorWork, DocumentRoutingEscalationServiceImpl.EscalationRuleWork, DuplicateCollectionMemberWork, FulltextExtractorWork, FulltextUpdaterWork, ImagingRecomputeWork, IndexingWorker, PictureViewsGenerationWork, QuotaMaxSizeSetterWork, QuotaStatsInitialWork, RemovedAbstractWork, RemovedCollectionMemberWork, RemovedCollectionWork, ScrollingIndexingWorker, SleepWork, SQLFulltextExtractorWork, TransiantStorageGCWork, 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

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.
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.
Work.State	getState() Deprecated. since 5.8, use WorkManager.getWorkState(java.lang.String) instead
String	getStatus() Gets a human-readable status for this work instance.
String	getTitle() Gets a human-readable name for this work instance.
String	getUserId() Gets the user on behalf of which this work is done.
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 ( Work.State.COMPLETED, Work.State.FAILED or Work.State.CANCELED).

Since:

5.8

getState

@Deprecated
Work.State getState()

Deprecated. since 5.8, use WorkManager.getWorkState(java.lang.String) instead

DO NOT USE THIS - gets the state of this work instance.

This should not be used because for non in-memory persistence, the work instance gets serialized and deserialized for running and when retrieved after completion, and therefore the original instance cannot get updated after the original scheduling.

Returns:

the state

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

getUserId

String getUserId()

Gets the user on behalf of which this work is done.

This is informative only.

Returns:

the user id, or null

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