@AlfrescoPublicApi
public interface JobLockService
Locks are identified by a fully qualified name (QName
) and follow a hierarchical
naming convention i.e. locks higher up a hierarchy can be shared but will prevent explicit
(exclusive) locks from being taken. For example: If exclusive lock a.a.a has been
taken, then a.a and a are all implicitly taken as shared locks. Exclusive lock
a.a.b can be taken by another process and will share locks a.a and a
with the first process. It will not be possible for a third process to take a lock on
a.a, however.
LOCK ORDERING:
The transactional locks will be applied in strict alphabetical order. A very basic deadlock
prevention system (at least) must be in place when applying or reapplying locks and be biased
against locks applied non-alphabetically.
Modifier and Type | Interface and Description |
---|---|
static interface |
JobLockService.JobLockRefreshCallback
Interface for implementations that need a timed callback in order to refresh the lock.
|
Modifier and Type | Method and Description |
---|---|
String |
getLock(org.alfresco.service.namespace.QName lockQName,
long timeToLive)
Take a manually-managed lock.
|
String |
getLock(org.alfresco.service.namespace.QName lockQName,
long timeToLive,
JobLockService.JobLockRefreshCallback callback)
Take a manually-managed lock and provide a callback to refresh it periodically.
|
String |
getLock(org.alfresco.service.namespace.QName lockQName,
long timeToLive,
long retryWait,
int retryCount)
Take a manually-managed lock.
|
void |
getTransactionalLock(org.alfresco.service.namespace.QName lockQName,
long timeToLive)
Take a transactionally-managed lock.
|
void |
getTransactionalLock(org.alfresco.service.namespace.QName lockQName,
long timeToLive,
long retryWait,
int retryCount)
Take a transactionally-managed lock.
|
void |
refreshLock(String lockToken,
org.alfresco.service.namespace.QName lockQName,
long timeToLive)
Refresh the lock using a valid lock token.
|
void |
refreshLock(String lockToken,
org.alfresco.service.namespace.QName lockQName,
long timeToLive,
JobLockService.JobLockRefreshCallback callback)
Provide a callback to refresh a lock using a valid lock token, pushing responsibility
for regular lock refreshing onto the service implementation code.
|
void |
releaseLock(String lockToken,
org.alfresco.service.namespace.QName lockQName)
Release the lock using a valid lock token.
|
boolean |
releaseLockVerify(String lockToken,
org.alfresco.service.namespace.QName lockQName)
Release the lock using a valid lock token.
|
void getTransactionalLock(org.alfresco.service.namespace.QName lockQName, long timeToLive)
The following rules apply to taking and releasing locks:
- Expired locks can be taken by any process
- Lock expiration does not prevent a lock from being refreshed or released
- Only locks that were manipulated using another token will cause failure
The locks are automatically released when the transaction is terminated.
Any failure to acquire the lock (after retries), refresh the lock or subsequently release the owned locks will invalidate the transaction and cause rollback.
lockQName
- the name of the lock to acquiretimeToLive
- the time (in milliseconds) for the lock to remain valid.
This value must not be larger than either the anticipated
operation time or a server startup time. Typically, it should be
a few seconds.LockAcquisitionException
- if the lock could not be acquiredIllegalStateException
- if a transaction is not activevoid getTransactionalLock(org.alfresco.service.namespace.QName lockQName, long timeToLive, long retryWait, int retryCount)
The following rules apply to taking and releasing locks:
- Expired locks can be taken by any process
- Lock expiration does not prevent a lock from being refreshed or released
- Only locks that were manipulated using another token will cause failure
The locks are automatically released when the transaction is terminated.
Any failure to acquire the lock (after retries), refresh the lock or subsequently release the owned locks will invalidate the transaction and cause rollback.
If the lock cannot be immediately acquired, the process will wait and retry. Note that second and subsequent attempts to get the lock during a transaction cannot make use of retrying; the lock is actually being refreshed and will therefore never become valid if it doesn't refresh directly.
lockQName
- the name of the lock to acquiretimeToLive
- the time (in milliseconds) for the lock to remain valid.
This value must not be larger than either the anticipated
operation time or a server startup time. Typically, it should be
a few seconds.retryWait
- the time (in milliseconds) to wait before trying againretryCount
- the maximum number of times to attempt the lock acquisitionLockAcquisitionException
- if the lock could not be acquiredIllegalStateException
- if a transaction is not activeString getLock(org.alfresco.service.namespace.QName lockQName, long timeToLive)
No lock management is provided: the lock must be released manually or will only become available by expiry. No deadlock management is provided, either.
lockQName
- the name of the lock to acquiretimeToLive
- the time (in milliseconds) for the lock to remain valid.
This value must not be larger than either the anticipated
operation time or a server startup time. Typically, it should be
a few seconds.LockAcquisitionException
- if the lock could not be acquiredString getLock(org.alfresco.service.namespace.QName lockQName, long timeToLive, long retryWait, int retryCount)
No lock management is provided: the lock must be released manually or will only become available by expiry. No deadlock management is provided, either.
If the lock cannot be immediately acquired, the process will wait and retry.
lockQName
- the name of the lock to acquiretimeToLive
- the time (in milliseconds) for the lock to remain valid.
This value must not be larger than either the anticipated
operation time or a server startup time. Typically, it should be
a few seconds.retryWait
- the time (in milliseconds) to wait before trying againretryCount
- the maximum number of times to attempt the lock acquisitionLockAcquisitionException
- if the lock could not be acquiredString getLock(org.alfresco.service.namespace.QName lockQName, long timeToLive, JobLockService.JobLockRefreshCallback callback)
getLock(QName,long)
and refreshLock(String,QName,long,JobLockRefreshCallback)
.lockQName
- the name of the lock to acquiretimeToLive
- the time (in milliseconds) for the lock to remain valid.
This value must not be larger than either the anticipated
operation time or a server startup time. Typically, it should be
a few seconds.callback
- the object that will be called at intervals of timeToLive/2 (about)LockAcquisitionException
- if the lock could not be acquiredvoid refreshLock(String lockToken, org.alfresco.service.namespace.QName lockQName, long timeToLive)
lockQName
- the name of the previously-acquired locktimeToLive
- the time (in milliseconds) for the lock to remain validLockAcquisitionException
- if the lock could not be refreshed or acquiredvoid refreshLock(String lockToken, org.alfresco.service.namespace.QName lockQName, long timeToLive, JobLockService.JobLockRefreshCallback callback)
lockToken
- the lock token returned when the lock was acquiredlockQName
- the name of the previously-acquired locktimeToLive
- the time (in milliseconds) for the lock to remain validcallback
- the object that will be called at intervals of timeToLive/2 (about)void releaseLock(String lockToken, org.alfresco.service.namespace.QName lockQName)
lockToken
- the lock token returned when the lock was acquiredlockQName
- the name of the previously-acquired lockLockAcquisitionException
- if the lock has been taken over by another processboolean releaseLockVerify(String lockToken, org.alfresco.service.namespace.QName lockQName)
lockToken
- the lock token returned when the lock was acquiredlockQName
- the name of the previously-acquired lockCopyright © 2005–2017 Alfresco Software. All rights reserved.