com.pega.pegarules.pub.database

Interface LockManager

public interface LockManager

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

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	LockManager.Junit

Field Summary

Fields

Modifier and Type	Field and Description
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 int	LOCK_HELD_BY_NOBODY This lock is not held by any requestor.
static java.lang.String	VERSION

Method Summary

Modifier and Type	Method and Description
int	acquireLock(java.lang.String aLockName, boolean aUnlockOnCommit, StringMap aInfo) Attempts to lock against a specific string, returning a specific return status.
void	changeDBLocksToHazelCastLocks(Database aDB)
void	checkRequiredLocks(java.util.Set keyset) Check that all keys in keyset are locked
int	expireRequestorLocks() When current requestor times out expire all locks held by him by moving the expiration date to now
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) Deprecated. As of version 7.1.9, use lockExists(String, StringMap) instead.
boolean	isLocked(java.lang.String aLockName, StringMap aInfo) Deprecated. As of version 7.1.9, use lockExists(String, StringMap) instead.
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.
int	lockExists(java.lang.String aLockName, StringMap aLockInfoReturned) Check if active lock is held by a user.
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
int	removeExpiredLocks(int aDays) Remove the lock entries, which are going to expire in @param aDays days.
boolean	unlock(java.lang.String aLockName, boolean aInDifferentRequestor) Unlocks a generic string.
boolean	unlock(StringMap aInstancePage, boolean aInDifferentRequestor) Unlocks a generic string.
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

VERSION

static final java.lang.String VERSION

COPYRIGHT

static final java.lang.String COPYRIGHT

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

LOCK_HELD_BY_NOBODY

static final int LOCK_HELD_BY_NOBODY

This lock is not held by any requestor.

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

expireRequestorLocks

int expireRequestorLocks()
                  throws DatabaseException

When current requestor times out expire all locks held by him by moving the expiration date to now

Returns:

number of locks expired

Throws:

DatabaseException - if there is a database problem

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 a generic string. If lock is held by a different requestor and aInDifferentRequestor is true, this method terminates the other requestor and thus releases the lock.

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. This method attempts an asynchronous unlock(through requestor termination) if aInDifferentRequestor is true and the lock-holding requestor is on a different node and always returns false in this case

Throws:

DatabaseException - if something goes wrong

unlock

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

Unlocks a generic string. If lock is held by a different requestor and aInDifferentRequestor is true, this method terminates the other requestor and thus releases the lock.

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. This method attempts an asynchronous unlock(through requestor termination) if aInDifferentRequestor is true and the lock-holding requestor is on a different node and always returns false in this case

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

Deprecated. As of version 7.1.9, use lockExists(String, StringMap) instead.

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

Deprecated. As of version 7.1.9, use lockExists(String, StringMap) instead.

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

lockExists

int lockExists(java.lang.String aLockName,
               StringMap aLockInfoReturned)
        throws LockFailureException

Check if active lock is held by a user.

Parameters:

aLockName - the string to be locked on

aLockInfoReturned - the Map object which will be populated when lock info is available. This object will not be populated if no users hold the lock.

Returns:

one of the LockManager constants: LOCK_ALREADY_HELD, LOCK_HELD_BY_ANOTHER, LOCK_HELD_BY_NOBODY

Throws:

LockFailureException

changeDBLocksToHazelCastLocks

void changeDBLocksToHazelCastLocks(Database aDB)

removeExpiredLocks

int removeExpiredLocks(int aDays)

Remove the lock entries, which are going to expire in @param aDays days. This will remove the lock entries only in lock cache, Doesn't do anything with database entries. Examples: 1. removeExpiredLocks(0) will remove all the entries expired before current time. 2. removeExpiredLocks(-3) will remove all the entries expired before 3 days.

Parameters:

aDays - Days to purge

Returns:

number of cache entries removed