net.sf.sasl.distributed.lock
Interface ILockSequence

All Superinterfaces:

ILockContainer

All Known Implementing Classes:

DefaultLockSession.LockSequence

public interface ILockSequence
extends ILockContainer

A lock sequence is a collection of acquired locks. A sequence makes sure that all acquired locks get unlocked and released when the sequence is released. How a sequence is working depends on the implementation of the sequence and its super container - a lock session. If the sequence supports for example the "two phase lock protocol" than it should forbid to acquire locks and lock locks, if already one acquired lock was unlocked at the sequence. Implementations must be not thread-safe. Parts of the contract may differ in different lock sequence implementations, those changes should be documented.
A lock sequence should be used in a short running "transaction" way, if the probability for simultaneous locks for the same lock key is high.

Since:

0.0.1 (sasl-distributed-lock-library)

Author:

Philipp Förmer

Method Summary

IMutex	acquireMutex(Object lockKey) Acquires a mutex for the given lock key and returns it.
boolean	detach(IMutex mutex) Detaches the mutex immediately from the sequence and releases the lock, if it was locked over the sequence.
IMutex	getMutex(Object lockKey) Returns the corresponding mutex to the lockKey, null if there exists no such mutex for the lockKey at the sequence.
IMutex	lock(Object lockKey) Acquires a mutex for the given lock key and locks it initial.
IMutex	lockInterruptibly(Object lockKey) Tries to acquire a mutex and do trie to do a lock on it as long as the current thread is not interrupted.
IMutex	tryLock(Object lockKey) Tries to acquire a mutex and do a tryLock on it.
IMutex	tryLock(Object lockKey, long maxWaitTime, TimeUnit timeUnit) Tries to acquire a mutex and do a timed wait tryLock on it.
IMutex	unlock(Object lockKey) Unlocks the mutex for the given lockKey, so that the mutex could be locked by another thread.

Methods inherited from interface net.sf.sasl.distributed.lock.ILockContainer

clear, getName, isActive, release

Method Detail

acquireMutex

IMutex acquireMutex(Object lockKey)
                    throws LockOperationException

Acquires a mutex for the given lock key and returns it. The mutex is not locked. If there exists already an attached mutex for the lock key at the sequence, than that instance must be returned.

Parameters:

lockKey - non null

Returns:

non null

Throws:

LockOperationException - if any exception occurs during trying to acquire a mutex for the lock key.

Since:

0.0.1 (sasl-distributed-lock-library)

getMutex

IMutex getMutex(Object lockKey)
                throws LockOperationException

Returns the corresponding mutex to the lockKey, null if there exists no such mutex for the lockKey at the sequence.

Parameters:

lockKey - non null

Returns:

null or non null

Throws:

LockOperationException - if the operation is not allowed.

Since:

0.0.1 (sasl-distributed-lock-library)

detach

boolean detach(IMutex mutex)
               throws LockOperationException

Detaches the mutex immediately from the sequence and releases the lock, if it was locked over the sequence. Returns true, if the detach was successful, false else.

Parameters:

mutex - non null

Returns:

true or false.

Throws:

LockOperationException - if the operation is not allowed.

Since:

0.0.1 (sasl-distributed-lock-library)

lock

IMutex lock(Object lockKey)
            throws LockOperationException,
                   DeadlockException

Acquires a mutex for the given lock key and locks it initial.

Parameters:

lockKey - non null.

Returns:

acquired and locked mutex.

Throws:

LockOperationException - if the mutex could not get acquired, for example because its held by another sequence (of the same session), or the operation is not allowed.

DeadlockException - if a deadlock scenario occurred.

Since:

0.0.1 (sasl-distributed-lock-library)

lockInterruptibly

IMutex lockInterruptibly(Object lockKey)
                         throws LockOperationException,
                                DeadlockException,
                                InterruptedException

Tries to acquire a mutex and do trie to do a lock on it as long as the current thread is not interrupted. The acquired mutex will be attached to the sequence.

Parameters:

lockKey - non null

Returns:

non null

Throws:

LockOperationException - if the mutex could not get acquired, for example because its held by another sequence (of the same session), or the operation is not allowed.

DeadlockException - if a deadlock scenario occurred.

InterruptedException - if the current thread was interrupted.

Since:

0.0.1 (sasl-distributed-lock-library)

tryLock

IMutex tryLock(Object lockKey)
               throws LockOperationException,
                      DeadlockException

Tries to acquire a mutex and do a tryLock on it. If the tryLock is successful, than the mutex is returned. Else null will be returned, but the acquired mutex will be attached to the sequence.

Parameters:

lockKey - non null

Returns:

null or non null

Throws:

LockOperationException - if the mutex could not get acquired, for example because its held by another sequence (of the same session), or the operation is not allowed.

DeadlockException - if a deadlock scenario occurred.

Since:

0.0.1 (sasl-distributed-lock-library)

tryLock

IMutex tryLock(Object lockKey,
               long maxWaitTime,
               TimeUnit timeUnit)
               throws LockOperationException,
                      DeadlockException,
                      InterruptedException

Tries to acquire a mutex and do a timed wait tryLock on it. If the timed waited tryLock is successful, than the mutex is returned. Else null will be returned, but the acquired mutex will be attached to the sequence.

Parameters:

lockKey - non null

maxWaitTime - positive long value.

timeUnit - non null, describing of what time unit the maxWaitTime is.

Returns:

null or non null.

Throws:

LockOperationException - if the mutex could not get acquired, for example because its held by another sequence (of the same session).

DeadlockException - if a deadlock scenario occurred.

InterruptedException

Since:

0.0.1 (sasl-distributed-lock-library)

unlock

IMutex unlock(Object lockKey)
              throws LockOperationException

Unlocks the mutex for the given lockKey, so that the mutex could be locked by another thread.

Parameters:

lockKey - non null.

Returns:

unlocked mutex.

Throws:

LockOperationException - if the mutex could not get unlocked, for example because it was never held by this sequence, or the operation is not allowed.

Since:

0.0.1 (sasl-distributed-lock-library)