org.nuxeo.ecm.core.work

Class AbstractWork

java.lang.Object

org.nuxeo.ecm.core.work.AbstractWork

All Implemented Interfaces:

Serializable, Work

Direct Known Subclasses:

AclAuditWork, CSVImporterWork, DocumentRoutingEscalationServiceImpl.EscalationRuleWork, FulltextExtractorWork, FulltextUpdaterWork, PictureViewsGenerationWork, QuotaMaxSizeSetterWork, QuotaStatsInitialWork, SleepWork, VideoConversionWork

public abstract class AbstractWork
extends Object
implements Work

A base implementation for a Work instance, dealing with most of the details around state change.

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:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface org.nuxeo.ecm.core.work.api.Work

Work.Progress, Work.State

Constructor Summary

Constructors

Constructor and Description
AbstractWork() Constructs a Work instance with a unique id.
AbstractWork(String id)

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.
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.
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.
void	retryableWork() This method, along with getRetryCount(), should be implemented if the work instance can be retried in case of concurrent update exceptions.
void	rollbackAndRetryTransaction() Rolls back the transaction and starts another one.
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	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()
void	work() This method should implement the actual work done by the Work instance.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.nuxeo.ecm.core.work.api.Work

getTitle

Constructor Detail

AbstractWork

public AbstractWork()

Constructs a Work instance with a unique id.

AbstractWork

public AbstractWork(String id)

Method Detail

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)

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 ( Work.State.COMPLETED, Work.State.FAILED or Work.State.CANCELED).

Specified by:

getWorkInstanceState in interface Work

getState

@Deprecated
public Work.State getState()

Deprecated.

Description copied from interface: Work

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.

Specified by:

getState in interface Work

Returns:

the state

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:

Progress#Progress(float), Progress#Progress(long, long)

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

initSession

public CoreSession initSession()
                        throws Exception

May be called by implementing classes to open a session on the repository.

Returns:

the session (also available in session field)

Throws:

Exception

initSession

public CoreSession initSession(String repositoryName)
                        throws Exception

May be called by implementing classes to open a session on the given repository.

Parameters:

repositoryName - the repository name

Returns:

the session (also available in session field)

Throws:

Exception

closeSession

public void closeSession()

Closes the session that was opened by initSession().

Since:

5.8

work

public void work()
          throws Exception

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 #cleanUp().

Specified by:

work in interface Work

Throws:

Exception

See Also:

Work.isSuspending(), Work.suspended(), Work.cleanUp(boolean, java.lang.Exception)

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:

retryableWork()

retryableWork

public void retryableWork()
                   throws Exception

This method, along with getRetryCount(), should be implemented if the work instance can be retried in case of concurrent update exceptions.

Throws:

Exception

Since:

5.8

See Also:

getRetryCount()

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

getUserId

public String getUserId()

Description copied from interface: Work

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

This is informative only.

Specified by:

getUserId in interface Work

Returns:

the user id, 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

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

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

rollbackAndRetryTransaction

public void rollbackAndRetryTransaction()

Rolls back the transaction and starts another one. Closes the session as well.

Since:

5.8

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