org.jboss.cache.lock
Interface LockManager

All Known Implementing Classes:

NodeBasedLockManager, PessimisticNodeBasedLockManager

public interface LockManager

An interface to deal with all aspects of acquiring and releasing locks for nodes in the cache.

Since:

2.2.0

Author:

Manik Surtani (manik@jboss.org)

Method Summary

Object	getLockOwner(InvocationContext ctx) Determines the owner to be used when obtaining locks, given an invocation context.
Collection<Object>	getReadOwners(Fqn f) Retrieves the read lock owners, if any, for the current Fqn.
Collection<Object>	getReadOwners(NodeSPI node) Retrieves the read lock owners, if any, for the current Fqn.
Object	getWriteOwner(Fqn f) Retrieves the write lock owner, if any, for the current Fqn.
Object	getWriteOwner(NodeSPI node) Retrieves the write lock owner, if any, for the current Fqn.
boolean	isLocked(NodeSPI n) Returns true if the node is locked (either for reading or writing) by anyone, and false otherwise.
boolean	isLocked(NodeSPI n, LockType lockType) Returns true if the node is locked (either for reading or writing) by anyone, and false otherwise.
boolean	lock(Fqn fqn, LockType lockType, Object owner) Acquires a lock of type lockType, for a given owner, on a specific Node in the cache, denoted by fqn.
boolean	lock(Fqn fqn, LockType lockType, Object owner, long timeout) Acquires a lock of type lockType, for a given owner, on a specific Node in the cache, denoted by fqn.
boolean	lock(NodeSPI node, LockType lockType, Object owner) As lock(org.jboss.cache.Fqn, LockType, Object) except that a NodeSPI is passed in instead of an Fqn.
boolean	lock(NodeSPI node, LockType lockType, Object owner, long timeout) As lock(org.jboss.cache.Fqn, LockType, Object, long) except that a NodeSPI is passed in instead of an Fqn.
boolean	lockAll(NodeSPI node, LockType lockType, Object owner) Locks the node and all child nodes, acquiring lock of type specified for the owner specified.
boolean	lockAll(NodeSPI node, LockType lockType, Object owner, long timeout) Locks the node and all child nodes, acquiring lock of type specified for the owner specified.
boolean	lockAll(NodeSPI node, LockType lockType, Object owner, long timeout, boolean excludeInternalFqns) Locks the node and all child nodes, acquiring lock of type specified for the owner specified.
boolean	lockAllAndRecord(Fqn fqn, LockType lockType, InvocationContext ctx) Locks the node and all child nodes, acquiring lock of type specified for the owner specified.
boolean	lockAllAndRecord(NodeSPI node, LockType lockType, InvocationContext ctx) Locks the node and all child nodes, acquiring lock of type specified for the owner specified.
boolean	lockAndRecord(Fqn fqn, LockType lockType, InvocationContext ctx) Acquires a lock of type lockType, on a specific Node in the cache, denoted by fqn.
boolean	lockAndRecord(NodeSPI node, LockType lockType, InvocationContext ctx) Acquires a lock of type lockType, on a specific Node in the cache, denoted by fqn.
boolean	ownsLock(Fqn fqn, LockType lockType, Object owner) Tests whether a given owner owns a lock of lockType on a particular Fqn.
boolean	ownsLock(Fqn fqn, Object owner) Tests whether a given owner owns any sort of lock on a particular Fqn.
boolean	ownsLock(NodeSPI node, Object owner) Tests whether a given owner owns any sort of lock on a particular Fqn.
String	printLockInfo(NodeSPI node) Prints lock information about a node (and it's children) to a String.
void	unlock(Fqn fqn, Object owner) Releases the lock passed in, held by the specified owner
void	unlock(InvocationContext ctx) Releases locks present in an invocation context and transaction entry, if one is available.
void	unlock(NodeSPI node, Object owner) Releases the lock passed in, held by the specified owner
void	unlockAll(NodeSPI node) Releases locks on a given node and all children for all owners.
void	unlockAll(NodeSPI node, Object owner) Releases locks on a given node and all children for a given owner.

Method Detail

getLockOwner

Object getLockOwner(InvocationContext ctx)

Determines the owner to be used when obtaining locks, given an invocation context. This is typically a GlobalTransaction if one is present in the context, or Thread.currentThread() if one is not present.

Parameters:

ctx - invocation context

Returns:

owner to be used for acquiring locks.

lock

boolean lock(Fqn fqn,
             LockType lockType,
             Object owner)

Acquires a lock of type lockType, for a given owner, on a specific Node in the cache, denoted by fqn. This method will try for Configuration.getLockAcquisitionTimeout() milliseconds and give up if it is unable to acquire the required lock.

Parameters:

fqn - Fqn to lock

lockType - type of lock to acquire

owner - owner to acquire the lock for

Returns:

true if the lock was acquired, false otherwise.

lock

boolean lock(Fqn fqn,
             LockType lockType,
             Object owner,
             long timeout)

Acquires a lock of type lockType, for a given owner, on a specific Node in the cache, denoted by fqn. This method will try for timeout milliseconds and give up if it is unable to acquire the required lock.

Parameters:

fqn - Fqn to lock

lockType - type of lock to acquire

owner - owner to acquire the lock for

timeout - maximum length of time to wait for (in millis)

Returns:

true if the lock was acquired, false otherwise.

lock

boolean lock(NodeSPI node,
             LockType lockType,
             Object owner)

As lock(org.jboss.cache.Fqn, LockType, Object) except that a NodeSPI is passed in instead of an Fqn.

Parameters:

node - node to lock

lockType - type of lock to acquire

owner - owner to acquire the lock for

Returns:

true if the lock was acquired, false otherwise.

lock

boolean lock(NodeSPI node,
             LockType lockType,
             Object owner,
             long timeout)

As lock(org.jboss.cache.Fqn, LockType, Object, long) except that a NodeSPI is passed in instead of an Fqn.

Parameters:

node - node to lock

lockType - type of lock to acquire

owner - owner to acquire the lock for

timeout - maximum length of time to wait for (in millis)

Returns:

true if the lock was acquired, false otherwise.

lockAndRecord

boolean lockAndRecord(Fqn fqn,
                      LockType lockType,
                      InvocationContext ctx)

Acquires a lock of type lockType, on a specific Node in the cache, denoted by fqn. This method will try for a period of time and give up if it is unable to acquire the required lock. The period of time is specified in Option.getLockAcquisitionTimeout() and, if this is unset, the default timeout set in Configuration.getLockAcquisitionTimeout() is used.

In addition, any locks acquired are added to the context using InvocationContext.addInvocationLockAcquired(NodeLock) if you are not running in a transaction, or using TransactionEntry.addLock(NodeLock) if you are.

The owner for the lock is determined by passing the invocation context to getLockOwner(org.jboss.cache.InvocationContext).

Parameters:

fqn - Fqn to lock

lockType - type of lock to acquire

ctx - invocation context associated with this invocation

Returns:

true if the lock was acquired, false otherwise.

lockAndRecord

boolean lockAndRecord(NodeSPI node,
                      LockType lockType,
                      InvocationContext ctx)

Acquires a lock of type lockType, on a specific Node in the cache, denoted by fqn. This method will try for a period of time and give up if it is unable to acquire the required lock. The period of time is specified in Option.getLockAcquisitionTimeout() and, if this is unset, the default timeout set in Configuration.getLockAcquisitionTimeout() is used.

In addition, any locks acquired are added to the context using InvocationContext.addInvocationLockAcquired(NodeLock) if you are not running in a transaction, or using TransactionEntry.addLock(NodeLock) if you are.

The owner for the lock is determined by passing the invocation context to getLockOwner(org.jboss.cache.InvocationContext).

Parameters:

node - Fqn to lock

lockType - type of lock to acquire

ctx - invocation context associated with this invocation

Returns:

true if the lock was acquired, false otherwise.

unlock

void unlock(Fqn fqn,
            Object owner)

Releases the lock passed in, held by the specified owner

Parameters:

fqn - Fqn of the node to unlock

owner - lock owner

unlock

void unlock(NodeSPI node,
            Object owner)

Releases the lock passed in, held by the specified owner

Parameters:

node - Node to unlock

owner - lock owner

unlock

void unlock(InvocationContext ctx)

Releases locks present in an invocation context and transaction entry, if one is available.

Locks are released in reverse order of which they are acquired and registered.

Lock owner is determined by passing the invocation context to getLockOwner(org.jboss.cache.InvocationContext)

Parameters:

ctx - invocation context to inspect

lockAll

boolean lockAll(NodeSPI node,
                LockType lockType,
                Object owner)

Locks the node and all child nodes, acquiring lock of type specified for the owner specified. If only some locks are acquired, all locks are released and the method returns false.

This method will try for Configuration.getLockAcquisitionTimeout() milliseconds and give up if it is unable to acquire the required lock.

Parameters:

node - Node to lock

lockType - type of lock to acquire

owner - owner to acquire the lock for

Returns:

true if the lock was acquired, false otherwise.

lockAll

boolean lockAll(NodeSPI node,
                LockType lockType,
                Object owner,
                long timeout)

Locks the node and all child nodes, acquiring lock of type specified for the owner specified. If only some locks are acquired, all locks are released and the method returns false. Internal Fqns are included as well.

Parameters:

node - Node to lock

lockType - type of lock to acquire

owner - owner to acquire the lock for

timeout - maximum length of time to wait for (in millis)

Returns:

true if all locks were acquired, false otherwise.

lockAll

boolean lockAll(NodeSPI node,
                LockType lockType,
                Object owner,
                long timeout,
                boolean excludeInternalFqns)

Locks the node and all child nodes, acquiring lock of type specified for the owner specified. If only some locks are acquired, all locks are released and the method returns false.

Parameters:

node - Node to lock

lockType - type of lock to acquire

owner - owner to acquire the lock for

timeout - maximum length of time to wait for (in millis)

excludeInternalFqns - if true, any Fqns that are internal are excluded.

Returns:

true if all locks were acquired, false otherwise.

lockAllAndRecord

boolean lockAllAndRecord(NodeSPI node,
                         LockType lockType,
                         InvocationContext ctx)

Locks the node and all child nodes, acquiring lock of type specified for the owner specified. If only some locks are acquired, all locks are released and the method returns false.

In addition, any locks acquired are added to the context using InvocationContext.addInvocationLockAcquired(NodeLock) if you are not running in a transaction, or using TransactionEntry.addLock(NodeLock) if you are.

The owner for the lock is determined by passing the invocation context to getLockOwner(org.jboss.cache.InvocationContext).

Parameters:

node - Node to lock

lockType - type of lock to acquire

ctx - invocation context associated with this invocation

Returns:

true if all locks were acquired, false otherwise.

lockAllAndRecord

boolean lockAllAndRecord(Fqn fqn,
                         LockType lockType,
                         InvocationContext ctx)

Locks the node and all child nodes, acquiring lock of type specified for the owner specified. If only some locks are acquired, all locks are released and the method returns false.

In addition, any locks acquired are added to the context using InvocationContext.addInvocationLockAcquired(NodeLock) if you are not running in a transaction, or using TransactionEntry.addLock(NodeLock) if you are.

The owner for the lock is determined by passing the invocation context to getLockOwner(org.jboss.cache.InvocationContext).

Parameters:

fqn - Node to lock

lockType - type of lock to acquire

ctx - invocation context associated with this invocation

Returns:

true if all locks were acquired, false otherwise.

unlockAll

void unlockAll(NodeSPI node,
               Object owner)

Releases locks on a given node and all children for a given owner.

Parameters:

node - node to unlock

owner - lock owner

unlockAll

void unlockAll(NodeSPI node)

Releases locks on a given node and all children for all owners. Use with care.

Parameters:

node - node to unlock

ownsLock

boolean ownsLock(Fqn fqn,
                 LockType lockType,
                 Object owner)

Tests whether a given owner owns a lock of lockType on a particular Fqn.

Parameters:

fqn - fqn to test

lockType - type of lock to test for

owner - owner

Returns:

true if the owner does own the specified lock type on the specified node, false otherwise.

ownsLock

boolean ownsLock(Fqn fqn,
                 Object owner)

Tests whether a given owner owns any sort of lock on a particular Fqn.

Parameters:

fqn - fqn to test

owner - owner

Returns:

true if the owner does own the specified lock type on the specified node, false otherwise.

ownsLock

boolean ownsLock(NodeSPI node,
                 Object owner)

Tests whether a given owner owns any sort of lock on a particular Fqn.

Parameters:

node - to test

owner - owner

Returns:

true if the owner does own the specified lock type on the specified node, false otherwise.

isLocked

boolean isLocked(NodeSPI n)

Returns true if the node is locked (either for reading or writing) by anyone, and false otherwise.

Parameters:

n - node to inspect

Returns:

true of locked; false if not.

isLocked

boolean isLocked(NodeSPI n,
                 LockType lockType)

Returns true if the node is locked (either for reading or writing) by anyone, and false otherwise.

Parameters:

n - node to inspect

lockType - lockType to test for

Returns:

true of locked; false if not.

getWriteOwner

Object getWriteOwner(Fqn f)

Retrieves the write lock owner, if any, for the current Fqn.

Parameters:

f - Fqn to inspect

Returns:

the owner of the lock, or null if not locked.

getReadOwners

Collection<Object> getReadOwners(Fqn f)

Retrieves the read lock owners, if any, for the current Fqn.

Parameters:

f - Fqn to inspect

Returns:

a collection of read lock owners, or an empty collection if not locked.

getWriteOwner

Object getWriteOwner(NodeSPI node)

Retrieves the write lock owner, if any, for the current Fqn.

Parameters:

node - the node to inspect

Returns:

the owner of the lock, or null if not locked.

getReadOwners

Collection<Object> getReadOwners(NodeSPI node)

Retrieves the read lock owners, if any, for the current Fqn.

Parameters:

node - the node to inspect

Returns:

a collection of read lock owners, or an empty collection if not locked.

printLockInfo

String printLockInfo(NodeSPI node)

Prints lock information about a node (and it's children) to a String.

Parameters:

node - node to inspect