net.sf.sasl.distributed.lock.impl
Class DefaultLockSession

java.lang.Object
  net.sf.sasl.distributed.lock.impl.DefaultLockSession

All Implemented Interfaces:

ILockContainer, ILockSession

public class DefaultLockSession
extends Object
implements ILockSession

A non thread-safe lock session implementation with the following behavior:

• 1.)Nested lock sequences are allowed.
• 2.)A lock for a lock key can only be owned by one lock sequence of this session at the same time (otherwise the whole lock/unlock handling gets unclear).
• 3.)An acquired mutex can only get unlocked, if it was locked over a sequence. In the most cases this should reduce programming errors. An error message will be written to the log output in such a case.
• 4.)If acquiring two or more times a mutex for the same lock key over a sequence, than the mutex instance will be the same.
• 5.)If strict sequence mode is enabled for the session, than locks can only get acquired for the current sequence.
• 6.)If thread check mode is enabled for the session, than all thread-vulnerable operations will get checked if they are accessed from threads other than the owner thread. If a thread accesses a lock session he has never acquired, an exception will be thrown in such a case.
• 7.)If locks over a sequence were acquired in the following order: lock1, lock2, ..., lockN than they will be released in reverse order lockN, lockN-1, ..., lock1 if the sequence is cleared or released.
• 8.)Conditions on a mutex are currently not supported.
• 9.)Multiple locks like "mutex.lock(), mutex.lock(), mutex.lock()" on the same mutex will be tolerated (reentrant lock). A debug message will be written to the log output in such a case.

The lock session could be created in "strict mode" and "non strict mode". The difference of these two modes is shortly explained in the following.
Strict mode: The last started lock sequence is the lock sequence which is currently active, which means, that only over this lock sequence locks could get acquired, locked and unlocked. All other started lock sequences stay passive. This is equal to a stack over which only the top of the stack could be accessed.
Non strict mode: In non strict mode new created lock sequences are also nested in earlier created lock sequences like in the strict mode. The difference to the strict mode is, that all lock sequences connected to the session are active for lock operations at the same time. This is less restrictive, but should only be used, if a condition in some local code must set a lock for some other local code in an over spanning global lock sequence.

Since:

0.0.1 (sasl-distributed-lock-library)

Author:

Philipp Förmer

Nested Class Summary

protected class	DefaultLockSession.LockSequence Lock sequence which could have nested lock sequences.
protected class	DefaultLockSession.MutexDecorator

Constructor Summary

DefaultLockSession(LockSessionFactory lockSessionFactory, Thread ownerThread, boolean strictLockSequenceMode)

Method Summary

ILockSequence	beginLockSequence(String name) Starts a new lock sequence, which is owned by the session.
void	clear() Releases all locks that this lock container holds.
protected void	doRelease() Releases the lock session without doing any thread access check.
ILockSequence	getCurrentLockSequence() Returns the current active lock sequence of the session.
LockSessionFactory	getLockSessionFactory() Returns the lock session factory over which the session was created.
String	getName() Returns a name of the lock container, for example "lock-transaction-X".
boolean	isActive() Returns true if this lock container is active which means it was not yet released via ILockContainer.release().
boolean	isInvalid() Returns true if the session is invalid, possibly because of an irreparable occured error like a DeadLockException.
boolean	isLocalLockHeldByASequence(Object lockKey) Returns true, if for the given lockKey a local lock is held by one lock sequence.
boolean	isLockKeyOwnedByASequence(Object lockKey) Returns true, if for the given lockKey a mutex is acquired by a lock sequence.
void	release() Releases all resources associated with this lock container.
boolean	supportsNestedLockSequences() Returns true, if the session supports nested sequences, false else.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultLockSession

public DefaultLockSession(LockSessionFactory lockSessionFactory,
                          Thread ownerThread,
                          boolean strictLockSequenceMode)
                   throws IllegalArgumentException

Parameters:

lockSessionFactory - non null

ownerThread - null or non null thread over which the session was created. If non null thread check will be enabled.

strictLockSequenceMode - whether strict lock sequence mode should be enabled or not.

Throws:

IllegalArgumentException - if parameter lockSessionFactory is null.

Since:

0.0.1 (sasl-distributed-lock-library)

Method Detail

getLockSessionFactory

public LockSessionFactory getLockSessionFactory()

Description copied from interface: ILockSession

Returns the lock session factory over which the session was created.

Specified by:

getLockSessionFactory in interface ILockSession

Returns:

non null

See Also:

ILockSession.getLockSessionFactory()

beginLockSequence

public ILockSequence beginLockSequence(String name)
                                throws LockOperationException

Description copied from interface: ILockSession

Starts a new lock sequence, which is owned by the session. The sequence could be used to acquire new locks.

Specified by:

beginLockSequence in interface ILockSession

Parameters:

name - null or non null

Returns:

non null

Throws:

LockOperationException - in any exception case.

Since:

0.0.1 (sasl-distributed-lock-library)

See Also:

ILockSession.beginLockSequence(java.lang.String)

getCurrentLockSequence

public ILockSequence getCurrentLockSequence()
                                     throws LockOperationException

Description copied from interface: ILockSession

Returns the current active lock sequence of the session. If no sequence was started, than null will be returned.

Specified by:

getCurrentLockSequence in interface ILockSession

Returns:

null or non null

Throws:

LockOperationException - in any exception case.

Since:

0.0.1 (sasl-distributed-lock-library)

See Also:

ILockSession.getCurrentLockSequence()

clear

public void clear()
           throws LockOperationException

Description copied from interface: ILockContainer

Releases all locks that this lock container holds. If the container has nested lock containers than they will be released via ILockContainer.release(). The container stays active after the operation.

Specified by:

clear in interface ILockContainer

Throws:

LockOperationException - if an exception occurs during releasing locks and nested containers.

Since:

0.0.1 (sasl-distributed-lock-library)

See Also:

ILockContainer.clear()

release

public void release()
             throws LockOperationException

Description copied from interface: ILockContainer

Releases all resources associated with this lock container. If the container has got nested containers, than all nested containers of the container must get released and all locks, which are held by the container.
After the operation the lock element should be disconnected from all types of lock operations, which means it is inactive and garbage.

Specified by:

release in interface ILockContainer

Throws:

LockOperationException

Since:

0.0.1 (sasl-distributed-lock-library)

See Also:

ILockContainer.release()

doRelease

protected void doRelease()
                  throws LockOperationException

Releases the lock session without doing any thread access check. Should not be called on a session which is currently in active use as strange things may happen.

Throws:

LockOperationException - on any error case.

Since:

0.0.1 (sasl-distributed-lock-library)

supportsNestedLockSequences

public boolean supportsNestedLockSequences()

Description copied from interface: ILockSession

Returns true, if the session supports nested sequences, false else.

Specified by:

supportsNestedLockSequences in interface ILockSession

Returns:

true or false

Since:

0.0.1 (sasl-distributed-lock-library)

See Also:

ILockSession.supportsNestedLockSequences()

isLocalLockHeldByASequence

public boolean isLocalLockHeldByASequence(Object lockKey)
                                   throws IllegalArgumentException

Description copied from interface: ILockSession

Returns true, if for the given lockKey a local lock is held by one lock sequence. False, if the lockKey is not owned by a lock sequence or no sequence has acquired yet a lock for the given lock key. If there exists no actor in the system who unlocks locks he had never locked, a local lock implies a global lock.

Specified by:

isLocalLockHeldByASequence in interface ILockSession

Parameters:

lockKey - non null.

Returns:

true or false.

Throws:

IllegalArgumentException

Since:

0.0.1 (sasl-distributed-lock-library)

See Also:

ILockSession.isLocalLockHeldByASequence(java.lang.Object)

isLockKeyOwnedByASequence

public boolean isLockKeyOwnedByASequence(Object lockKey)
                                  throws IllegalArgumentException

Description copied from interface: ILockSession

Returns true, if for the given lockKey a mutex is acquired by a lock sequence. A value of true does not mean that the mutex is also locked by the session.

Specified by:

isLockKeyOwnedByASequence in interface ILockSession

Parameters:

lockKey - non null

Returns:

true or false.

Throws:

IllegalArgumentException

See Also:

ILockSession.isLockKeyOwnedByASequence(java.lang.Object)

getName

public String getName()

Description copied from interface: ILockContainer

Returns a name of the lock container, for example "lock-transaction-X".

Specified by:

getName in interface ILockContainer

Returns:

null or non null

Since:

0.0.1 (sasl-distributed-lock-library)

See Also:

ILockContainer.getName()

isActive

public boolean isActive()

Description copied from interface: ILockContainer

Returns true if this lock container is active which means it was not yet released via ILockContainer.release(). False else. An inactive lock container should be disconnected from all types of lock operations.

Specified by:

isActive in interface ILockContainer

Returns:

true or false.

Since:

0.0.1 (sasl-distributed-lock-library)

See Also:

ILockContainer.isActive()

isInvalid

public boolean isInvalid()

Description copied from interface: ILockSession

Returns true if the session is invalid, possibly because of an irreparable occured error like a DeadLockException. An invalid session can only be made valid again, by clearing it.

Specified by:

isInvalid in interface ILockSession

Returns:

true or false.

Since:

0.0.1 (sasl-distributed-lock-library)

See Also:

net.sf.sasl.distributed.lock.ILockContainer#isInvalid()