com.pega.pegarules.pub.database
Interface LockManager

public interface LockManager

Manages locking and unlocking. Either an instance or a generic string may be locked.

Version:

$Revision: 26815 $ $Date: 2012-05-03 15:18:14 -0400 (Thu, 03 May 2012) $

Author:

Jamie Gentry

Field Summary

static java.lang.String	COPYRIGHT
static int	LOCK_ACQUIRED This requestor has obtained the given lock
static int	LOCK_ALREADY_HELD This requestor already owns the given lock
static int	LOCK_HELD_BY_ANOTHER This requestor does not own the given lock; it is held by another
static java.lang.String	VERSION

Method Summary

int	acquireLock(java.lang.String aLockName, boolean aUnlockOnCommit, StringMap aInfo) Attempts to lock against a specific string, returning a specific return status.
void	checkRequiredLocks(java.util.Set keyset) Check that all keys in keyset are locked
java.lang.String	getLockHandle(StringMap aInstancePage) Gets the handle that would be used to lock an instance.
boolean	isLockable(java.lang.String aClassName) Check the definition of the indicated class to see if it supports locking.
boolean	isLocked(StringMap aLockPage, StringMap aInfo) Check to see if an instance is locked, based on the locking information available in its class definition's "Locking" tab.
boolean	isLocked(java.lang.String aLockName, StringMap aInfo) Check to see if a string is locked.
boolean	lock(java.lang.String aLockName, boolean aUnlockOnCommit) Locks a generic string.
boolean	lock(java.lang.String aLockName, boolean aUnlockOnCommit, StringMap aInfo) Locks a generic string.
boolean	lock(StringMap aInstancePage, boolean aUnlockOnCommit) Locks an instance.
boolean	lock(StringMap aInstancePage, boolean aUnlockOnCommit, StringMap aInfo) Locks an instance.
boolean	lockOnNode(java.lang.String aLockName) Obtain a node-level lock, using the given key
boolean	lockOnNode(java.lang.String aLockName, StringMap aInfo) Obtain a node-level lock, using the given key
boolean	unlock(java.lang.String aLockName, boolean aInDifferentRequestor) Unlocks a generic string.
boolean	unlock(StringMap aInstancePage, boolean aInDifferentRequestor) Unlocks an instance.
int	unlockAllForOperator() Deprecated. As of version 6.3, use unlockForRequestor() instead.
int	unlockForRequestor() Unlocks all locks held by the current requestor.
boolean	unlockOnNode(java.lang.String aLockName, boolean aInDifferentRequestor) Release a node-level lock
int	unlockOnNodeForRequestor() Release all of the node-level locks for the given requestor.

Field Detail

COPYRIGHT

static final java.lang.String COPYRIGHT

See Also:

Constant Field Values

VERSION

static final java.lang.String VERSION

See Also:

Constant Field Values

LOCK_ACQUIRED

static final int LOCK_ACQUIRED

This requestor has obtained the given lock

See Also:

Constant Field Values

LOCK_ALREADY_HELD

static final int LOCK_ALREADY_HELD

This requestor already owns the given lock

See Also:

Constant Field Values

LOCK_HELD_BY_ANOTHER

static final int LOCK_HELD_BY_ANOTHER

This requestor does not own the given lock; it is held by another

See Also:

Constant Field Values

Method Detail

lock

boolean lock(StringMap aInstancePage,
             boolean aUnlockOnCommit)
             throws DatabaseException

Locks an instance.

Parameters:

aInstancePage - the page containing the instance to lock

aUnlockOnCommit - whether we should unlock the page when the current transcation is committed

Returns:

true if the Requestor is left holding the lock, false otherwise

Throws:

DatabaseException - if something goes wrong

lock

boolean lock(StringMap aInstancePage,
             boolean aUnlockOnCommit,
             StringMap aInfo)
             throws DatabaseException

Locks an instance.

Parameters:

aInstancePage - the page containing the instance to lock

aUnlockOnCommit - whether we should unlock the page when the current transcation is committed

aInfo - if the lock attempt is unsuccessful, this is filled in with information about the attempt. The value of ErrorMessage is the name of a Rule-Message that describes the problem. In addition, these other keys might be set

pxOwnerId

The ID of the Requestor that currently owns the requested lock

pxExpireDateTime

The date and time that the requested lock expires

pxUpdateOperator

The ID of the operator that currently owns the requested lock

pxUpdateOpName

The name of the operator that currently owns the requested lock

pxLockHandle

The lock key that was requested

Returns:

true if the Requestor is left holding the lock, false otherwise

Throws:

DatabaseException - if something goes wrong

lock

boolean lock(java.lang.String aLockName,
             boolean aUnlockOnCommit)
             throws DatabaseException

Locks a generic string.

Parameters:

aLockName - the string to lock

aUnlockOnCommit - whether we should unlock when the current transcation is committed

Returns:

true if the Requestor is left holding the lock, false otherwise

Throws:

DatabaseException - if something goes wrong

lock

boolean lock(java.lang.String aLockName,
             boolean aUnlockOnCommit,
             StringMap aInfo)
             throws DatabaseException

Locks a generic string.

Parameters:

aLockName - the string to lock

aUnlockOnCommit - whether we should unlock when the current transcation is committed

aInfo - a StringMap to fill in with owner and expiration info from an existing lock. This is only filled in when lock() returns false.

Returns:

true if the Requestor is left holding the lock, false otherwise

Throws:

DatabaseException - if something goes wrong

acquireLock

int acquireLock(java.lang.String aLockName,
                boolean aUnlockOnCommit,
                StringMap aInfo)
                throws DatabaseException

Attempts to lock against a specific string, returning a specific return status.

Parameters:

aLockName - the string to lock

aUnlockOnCommit - whether we should unlock when the current transcation is committed

aInfo - if the lock attempt is unsuccessful, this is filled in with information about the attempt. The value of ErrorMessage is the name of a Rule-Message that describes the problem. In addition, these other keys might be set

pxOwnerId

The ID of the Requestor that currently owns the requested lock

pxExpireDateTime

The date and time that the requested lock expires

pxUpdateOperator

The ID of the operator that currently owns the requested lock

pxUpdateOpName

The name of the operator that currently owns the requested lock

pxLockHandle

The lock key that was requested

Returns:

one of the LockManager constants: LOCK_ACQUIRED, LOCK_ALREADY_HELD, LOCK_HELD_BY_ANOTHER

Throws:

DatabaseException - if something goes wrong

checkRequiredLocks

void checkRequiredLocks(java.util.Set keyset)
                        throws DatabaseException

Check that all keys in keyset are locked

Parameters:

keyset - - Set of key strings to check

Throws:

DatabaseException

unlock

boolean unlock(StringMap aInstancePage,
               boolean aInDifferentRequestor)
               throws DatabaseException

Unlocks an instance.

Parameters:

aInstancePage - the page containing the instance to unlock

aInDifferentRequestor - if true, then the instance is unlocked even if it is in a different requestor

Returns:

true if the lock was unlocked, or if the lock does not exist. Returns false if the lock could not be unlocked because it had been stolen by a different Requestor.

Throws:

DatabaseException - if something goes wrong

unlock

boolean unlock(java.lang.String aLockName,
               boolean aInDifferentRequestor)
               throws DatabaseException

Unlocks a generic string.

Parameters:

aLockName - the string to unlock

aInDifferentRequestor - if true, then the instance is unlocked even if it is in a different requestor

Returns:

true if the lock was unlocked, or if the lock does not exist. Returns false if the lock could not be unlocked because it had been stolen by a different Requestor.

Throws:

DatabaseException - if something goes wrong

unlockAllForOperator

int unlockAllForOperator()
                         throws DatabaseException

Deprecated. As of version 6.3, use unlockForRequestor() instead.

Unlocks all locks held by the current operator. If the current Requestor is not associated with an operator name, then this method unlocks all the locks held by the current Requestor.

Returns:

number of locks released

Throws:

DatabaseException - if something goes wrong

unlockForRequestor

int unlockForRequestor()
                       throws DatabaseException

Unlocks all locks held by the current requestor.

Returns:

number of locks released

Throws:

DatabaseException - if something goes wrong

getLockHandle

java.lang.String getLockHandle(StringMap aInstancePage)
                               throws DatabaseException

Gets the handle that would be used to lock an instance.

Parameters:

aInstancePage - the page containing the instance

Returns:

the lock handle, null if this page's class does not allow locking

Throws:

BadInputException - if aInstancePage is not a valid instance page

BadClassDefinitionException - if aInstancePage has a bad instance class (pxObjClass)

DatabaseException - if something goes wrong

lockOnNode

boolean lockOnNode(java.lang.String aLockName)

Obtain a node-level lock, using the given key

Parameters:

aLockName - the string to lock on

Returns:

true if the lock was obtained, false if not.

lockOnNode

boolean lockOnNode(java.lang.String aLockName,
                   StringMap aInfo)

Obtain a node-level lock, using the given key

Parameters:

aLockName - the string to lock on

aInfo - if the lock is unsuccessful, this is filled in with information about the attempt. The value of ErrorMessage is the name of a Rule-Message that describes the problem. In addition, these other keys might be set

pxOwnerId

The ID of the Requestor that currently owns the requested lock

pxExpireDateTime

The date and time that the requested lock expires

pxUpdateOperator

The ID of the operator that currently owns the requested lock

pxUpdateOpName

The name of the operator that currently owns the requested lock

pxLockHandle

The lock key that was requested

Returns:

true if the lock was obtained, false if not.

unlockOnNode

boolean unlockOnNode(java.lang.String aLockName,
                     boolean aInDifferentRequestor)

Release a node-level lock

Parameters:

aLockName - the string to lock on

aInDifferentRequestor -

Returns:

true if the lock was returned, false if it does not exist

unlockOnNodeForRequestor

int unlockOnNodeForRequestor()

Release all of the node-level locks for the given requestor.

Returns:

the number of locks released

isLockable

boolean isLockable(java.lang.String aClassName)
                   throws BadClassDefinitionException

Check the definition of the indicated class to see if it supports locking. This is controlled by the setting of the "Allow Locking" checkbox on the locking tab of the class's Rule-Obj-Class instance.

Parameters:

aClassName - name of the class to check

Returns:

true if the class allows locking, false>/code> otherwise.

Throws:

BadClassDefinitionException - if the aClassName parameter is blank or null.

isLocked

boolean isLocked(StringMap aLockPage,
                 StringMap aInfo)
                 throws DatabaseException

Check to see if an instance is locked, based on the locking information available in its class definition's "Locking" tab. If this requestor owns the lock, then the lock expiration time is reset.

Parameters:

aLockPage - the page of the instance to be locked on.

aInfo - a Map object which will be populated when lock info is available. This object will be populated when either the lock is refreshed (because the current requestor owns it) or the lock is held by some other requestor

Returns:

true if the lock is held by this requestor (or locking cannot be performed), false if another requestor holds onto the lock, or no lock has been taken

Throws:

DatabaseException - when a problem occurs manipulating the locks

isLocked

boolean isLocked(java.lang.String aLockName,
                 StringMap aInfo)
                 throws DatabaseException

Check to see if a string is locked. If this requestor owns the lock, then the lock expiration time is reset.

Parameters:

aLockName - the string to be locked on.

aInfo - a Map object which will be populated when lock info is available. This object will be populated when either the lock is refreshed (because the current requestor owns it) or the lock is held by some other requestor

Returns:

true if the lock is held by this requestor (or locking cannot be performed), false if another requestor holds onto the lock, or no lock has been taken

Throws:

DatabaseException - when a problem occurs manipulating the locks