public interface Work extends Serializable
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
.
AbstractWork
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. |
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 |
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 |
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. |
void work() throws Exception
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()
.
Exception
isSuspending()
,
suspended()
,
cleanUp(boolean, java.lang.Exception)
String getId()
The id is used for equality comparisons, and as a key in persistent queues.
null
void cleanUp(boolean ok, Exception e)
work()
is done, in a finally block,
whether work completed normally or was in error or was interrupted.ok
- true
if the work completed normallye
- the exception, if availablevoid setWorkInstanceSuspending()
boolean isSuspending()
If true
, then state should be saved, suspended()
should
be called, and the work()
method should return.
void suspended()
Work
implementations to advertise that state
saving is done, when isSuspending()
returned true
. After
this is called, the work()
method should return.boolean isWorkInstanceSuspended()
void setWorkInstanceState(Work.State state)
Work.State getWorkInstanceState()
Used only to get the final state of a completed instance (
Work.State.COMPLETED
, Work.State.FAILED
or Work.State.CANCELED
).
@Deprecated Work.State getState()
WorkManager.getWorkState(java.lang.String)
insteadThis 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.
String getCategory()
Used to choose an execution queue.
null
for the defaultString getTitle()
String getStatus()
long getSchedulingTime()
long getStartTime()
0
if not
statedlong getCompletionTime()
0
if
not completedvoid setProgress(Work.Progress progress)
progress
- the progressProgress#Progress(float)
,
Progress#Progress(long, long)
Work.Progress getProgress()
null
String getUserId()
This is informative only.
null
DocumentLocation getDocument()
Returns null
if the work isn't about a single document.
null
. This is always a
DocumentLocation
with an IdRef
List<DocumentLocation> getDocuments()
Returns null
if the work isn't about documents.
DocumentLocation
with an IdRef
boolean isDocumentTree()
true
if getDocument()
is only the root of a set of
documents on which this Work instance will act.true
if a whole tree is impactedWorkSchedulePath getSchedulePath()
void setSchedulePath(WorkSchedulePath path)
Copyright © 2014 Nuxeo SA. All Rights Reserved.