Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.alfresco.repo.lock
Interface JobLockService

@org.alfresco.api.AlfrescoPublicApi
public interface JobLockService
Service interface for managing job locks.

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.

Since:
3.2
Author:
Derek Hulley

Nested Class Summary
static interface
JobLockService.JobLockRefreshCallback
          Interface for implementations that need a timed callback in order to refresh the lock.
Method Summary
getLock(QName lockQName, long timeToLive)
          Take a manually-managed lock.
getLock(QName lockQName, long timeToLive, JobLockService.JobLockRefreshCallback callback)
          Take a manually-managed lock and provide a callback to refresh it periodically.
getLock(QName lockQName, long timeToLive, long retryWait, int retryCount)
          Take a manually-managed lock.
void
getTransactionalLock(QName lockQName, long timeToLive)
          Take a transactionally-managed lock.
void
getTransactionalLock(QName lockQName, long timeToLive, long retryWait, int retryCount)
          Take a transactionally-managed lock.
void
refreshLock(String lockToken, QName lockQName, long timeToLive)
          Refresh the lock using a valid lock token.
void
refreshLock(String lockToken, 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, QName lockQName)
          Release the lock using a valid lock token.
boolean
releaseLockVerify(String lockToken, QName lockQName)
          Release the lock using a valid lock token.
Method Detail
getTransactionalLock
void getTransactionalLock(QName lockQName,
                          long timeToLive)
Take a transactionally-managed lock. This method can be called repeatedly to both initially acquire the lock as well as to maintain the lock. This method should be called repeatedly during the transaction to ensure that the lock remains refreshed. DO NOT use a long-lived lock to avoid calling this method at intervals; long-lived locks get left behind during server crashes, amongst other things.

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.

Parameters:
lockQName - the name of the lock to acquire
timeToLive - 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.
Throws:
LockAcquisitionException - if the lock could not be acquired
IllegalStateException - if a transaction is not active

getTransactionalLock
void getTransactionalLock(QName lockQName,
                          long timeToLive,
                          long retryWait,
                          int retryCount)
Take a transactionally-managed lock. This method can be called repeatedly to both initially acquire the lock as well as to maintain the lock. This method should be called repeatedly during the transaction to ensure that the lock remains refreshed. DO NOT use a long-lived lock to avoid calling this method at intervals; long-lived locks get left behind during server crashes, amongst other things.

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.

Parameters:
lockQName - the name of the lock to acquire
timeToLive - 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 again
retryCount - the maximum number of times to attempt the lock acquisition
Throws:
LockAcquisitionException - if the lock could not be acquired
IllegalStateException - if a transaction is not active

getLock
String getLock(QName lockQName,
               long timeToLive)
Take a manually-managed lock. The lock current thread or transaction will not be tagged - the returned lock token must be used for further management of the lock.

No lock management is provided: the lock must be released manually or will only become available by expiry. No deadlock management is provided, either.

Parameters:
lockQName - the name of the lock to acquire
timeToLive - 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.
Returns:
Returns the newly-created lock token
Throws:
LockAcquisitionException - if the lock could not be acquired

getLock
String getLock(QName lockQName,
               long timeToLive,
               long retryWait,
               int retryCount)
Take a manually-managed lock. The lock current thread or transaction will not be tagged - the returned lock token must be used for further management of the lock.

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.

Parameters:
lockQName - the name of the lock to acquire
timeToLive - 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 again
retryCount - the maximum number of times to attempt the lock acquisition
Throws:
LockAcquisitionException - if the lock could not be acquired

getLock
String getLock(QName lockQName,
               long timeToLive,
               JobLockService.JobLockRefreshCallback callback)
Take a manually-managed lock and provide a callback to refresh it periodically. A convenience wrapper around getLock(QName,long) and refreshLock(String,QName,long,JobLockRefreshCallback).
Parameters:
lockQName - the name of the lock to acquire
timeToLive - 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)
Returns:
Returns the newly-created lock token, or null if callback not active.
Throws:
LockAcquisitionException - if the lock could not be acquired

refreshLock
void refreshLock(String lockToken,
                 QName lockQName,
                 long timeToLive)
Refresh the lock using a valid lock token.
Parameters:
lockQName - the name of the previously-acquired lock
timeToLive - the time (in milliseconds) for the lock to remain valid
Throws:
LockAcquisitionException - if the lock could not be refreshed or acquired

refreshLock
void refreshLock(String lockToken,
                 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. This method should only be called once for a given lock token to prevent unnecessary refreshing.

Since the lock is not actually refreshed by this method, there will be no LockAcquisitionException.

The TTL (time to live) will be divided by two and the result used to trigger a timer thread to initiate the callback. The first refresh will occur after TTL/2 and no significant work should be done between acquiring a lock and calling this method, to prevent expiration.

Parameters:
lockToken - the lock token returned when the lock was acquired
lockQName - the name of the previously-acquired lock
timeToLive - the time (in milliseconds) for the lock to remain valid
callback - the object that will be called at intervals of timeToLive/2 (about)
Since:
3.4.0a

releaseLock
void releaseLock(String lockToken,
                 QName lockQName)
Release the lock using a valid lock token.
Parameters:
lockToken - the lock token returned when the lock was acquired
lockQName - the name of the previously-acquired lock
Throws:
LockAcquisitionException - if the lock has been taken over by another process

releaseLockVerify
boolean releaseLockVerify(String lockToken,
                          QName lockQName)
Release the lock using a valid lock token. The lock can have been taken by another process (i.e. the lock token will no longer be valid); none of this will prevent the method from succeeding.
Parameters:
lockToken - the lock token returned when the lock was acquired
lockQName - the name of the previously-acquired lock
Returns:
true if the lock was valid and released otherwise false if the lock was already held by another token

Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

Copyright © 2005–2018 Alfresco Software. All rights reserved.

Java API documentation generated with DocFlex/Javadoc 1.6.1 using JavadocPro template set.