public abstract class AbstractWork extends Object implements Work
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()
.
Work.Progress, Work.State
Modifier and Type | Field and Description |
---|---|
protected long |
completionTime |
protected String |
docId
Doc id for the Work instance, if relevant.
|
protected List<String> |
docIds
Doc ids for the Work instance, if relevant.
|
protected String |
id |
protected boolean |
isTree
If
true , the docId is only the root of a set of documents on which this Work instance will act. |
protected Work.Progress |
progress |
protected static Random |
RANDOM |
protected String |
repositoryName
Repository name for the Work instance, if relevant.
|
protected WorkSchedulePath |
schedulePath |
protected long |
schedulingTime |
protected CoreSession |
session |
protected long |
startTime |
protected Work.State |
state |
protected String |
status |
protected boolean |
suspended
Suspend acknowledged by the work instance.
|
protected boolean |
suspending
Suspend requested by the work manager.
|
Constructor and Description |
---|
AbstractWork()
Constructs a
Work instance with a unique id. |
AbstractWork(String id) |
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. |
void |
closeSession()
Closes the session that was opened by
initSession() . |
void |
commitOrRollbackTransaction()
Releases the transaction resources by committing the existing transaction (if any).
|
boolean |
equals(Object other) |
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.
|
int |
getRetryCount()
Gets the number of times that this Work instance can be retried in case of concurrent update exceptions.
|
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.
|
String |
getStatus()
Gets a human-readable status for this work instance.
|
String |
getUserId()
Gets the user on behalf of which this work is done.
|
String |
getWorkInstanceResult()
CALLED BY THE WORK MANAGER (not user code) to get this work instance's result.
|
Work.State |
getWorkInstanceState()
CALLED BY THE WORK MANAGER (not user code) to get this work instance's state.
|
int |
hashCode() |
CoreSession |
initSession()
May be called by implementing classes to open a session on the repository.
|
CoreSession |
initSession(String repositoryName)
May be called by implementing classes to open a session on the given repository.
|
boolean |
isDocumentTree()
Returns
true if Work.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.
|
protected DocumentLocation |
newDocumentLocation(String docId) |
void |
run()
Runs the work instance and does all the transaction management and retry.
|
protected void |
runWorkWithTransaction()
Does work under a transaction.
|
protected Exception |
runWorkWithTransactionAndCheckExceptions()
Does work under a transaction, and collects exception and suppressed exceptions that may lead to a retry.
|
protected void |
setCompletionTime() |
void |
setDocument(String repositoryName,
String docId) |
void |
setDocument(String repositoryName,
String docId,
boolean isTree) |
void |
setDocuments(String repositoryName,
List<String> docIds) |
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 |
setStatus(String status)
Sets a human-readable status for this 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.
|
boolean |
startTransaction()
Starts a new transaction.
|
void |
suspended()
Must be called by
Work implementations to advertise that state saving is done, when
Work.isSuspending() returned true . |
String |
toString() |
abstract void |
work()
This method should implement the actual work done by the
Work instance. |
protected transient volatile boolean suspending
protected transient volatile boolean suspended
protected transient Work.State state
protected transient Work.Progress progress
protected String repositoryName
protected String docId
Either docId or docIds is set. Not both.
protected List<String> docIds
Either docId or docIds is set. Not both.
protected boolean isTree
true
, the docId is only the root of a set of documents on which this Work instance will act.protected long schedulingTime
protected long startTime
protected long completionTime
protected transient CoreSession session
protected WorkSchedulePath schedulePath
public AbstractWork()
Work
instance with a unique id.public AbstractWork(String id)
public String getId()
Work
The id is used for equality comparisons, and as a key in persistent queues.
public WorkSchedulePath getSchedulePath()
Work
getSchedulePath
in interface Work
public void setSchedulePath(WorkSchedulePath path)
Work
setSchedulePath
in interface Work
public void setDocument(String repositoryName, String docId, boolean isTree)
public void setDocument(String repositoryName, String docId)
public void setDocuments(String repositoryName, List<String> docIds)
public void setWorkInstanceSuspending()
Work
setWorkInstanceSuspending
in interface Work
public boolean isSuspending()
Work
If true
, then state should be saved, Work.suspended()
should be called, and the Work.work()
method should return.
isSuspending
in interface Work
public void suspended()
Work
Work
implementations to advertise that state saving is done, when
Work.isSuspending()
returned true
. After this is called, the Work.work()
method should return.public boolean isWorkInstanceSuspended()
Work
isWorkInstanceSuspended
in interface Work
public void setWorkInstanceState(Work.State state)
Work
setWorkInstanceState
in interface Work
public Work.State getWorkInstanceState()
Work
Used only to get the final state of a completed instance ( Work.State.COMPLETED
, Work.State.FAILED
or
Work.State.CANCELED
).
getWorkInstanceState
in interface Work
@Deprecated public Work.State getState()
Work
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.
public void setProgress(Work.Progress progress)
Work
setProgress
in interface Work
progress
- the progressProgress#Progress(float)
,
Progress#Progress(long, long)
public Work.Progress getProgress()
Work
getProgress
in interface Work
null
public void setStatus(String status)
status
- the statuspublic String getStatus()
Work
public CoreSession initSession()
session
field)public CoreSession initSession(String repositoryName)
repositoryName
- the repository namesession
field)public void closeSession()
initSession()
.public void run()
Work
Usually only implemented by AbstractWork
, which should be subclassed instead of implementing Work.run()
.
protected Exception runWorkWithTransactionAndCheckExceptions()
protected void runWorkWithTransaction() throws ConcurrentUpdateException
ConcurrentUpdateException,
- TransactionRuntimeExceptionConcurrentUpdateException
public abstract void work()
Work
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 #cleanUp()
.
work
in interface Work
Work.isSuspending()
,
Work.suspended()
,
Work.cleanUp(boolean, java.lang.Exception)
public int getRetryCount()
work()
public void cleanUp(boolean ok, Exception e)
work()
is done in a finally block, whether work completed normally or was in
error or was interrupted.public String getUserId()
Work
This is informative only.
public long getSchedulingTime()
Work
getSchedulingTime
in interface Work
public long getStartTime()
Work
getStartTime
in interface Work
0
if not statedpublic long getCompletionTime()
Work
getCompletionTime
in interface Work
0
if not completedpublic void setStartTime()
Work
setStartTime
in interface Work
protected void setCompletionTime()
public String getCategory()
Work
Used to choose an execution queue.
getCategory
in interface Work
null
for the defaultpublic DocumentLocation getDocument()
Work
Returns null
if the work isn't about a single document.
getDocument
in interface Work
null
. This is always a DocumentLocation
with an IdRef
public List<DocumentLocation> getDocuments()
Work
Returns null
if the work isn't about documents.
getDocuments
in interface Work
DocumentLocation
with an
IdRef
protected DocumentLocation newDocumentLocation(String docId)
public boolean isDocumentTree()
Work
true
if Work.getDocument()
is only the root of a set of documents on which this Work instance
will act.isDocumentTree
in interface Work
true
if a whole tree is impactedpublic String getWorkInstanceResult()
Work
getWorkInstanceResult
in interface Work
public void commitOrRollbackTransaction()
public boolean startTransaction()
Usually called after commitOrRollbackTransaction()
, for instance for saving back the results of a long
process.
Copyright © 2015 Nuxeo SA. All rights reserved.