Object locking
Locks are implemented separately from the locking mechanism supplied by the database software (such as Oracle) that supports the PegaRULES database. Locks are exclusive to one thread, and operate system-wide in a multinode system.
Basics
A requestor can lock an open instance if all of the following are true:
- The instance belongs to a concrete class that has Allow Locking
selected in the class rule.
AND
- The instance has ever been saved and committed to the PegaRULES database.
- The requestor has an access role that conveys the privilege needed.
Properties identified on the Locking tab of the Class rule form together define the lock identity. (If the Locking tab contains no property names, the properties that form a lock definition are the same as those that form the external key that is defined on the General tab.) All classes in one class group (which corresponds to one database table) have the same properties in the lock definition.
Viewing locks — Standard reports
To view locks held by your own requestor session, select
.To view all locks held by any requestor, select
All Locks, and drill down to identify the details of the locked object. Hold the mouse pointer over a row of the drill-down detail to identify the Operator ID of the requestor holding the lock.
These two reports present instances of the
System-Locks
class,
corresponding to the
pr_sys_locks
table of the PegaRULES database.
Viewing locks — In an activity or flow
Locks are acquired by activities, using one of three methods: Obj-Open,
Obj-Open-by-Handle, or Obj-Refresh-and-Lock. Optionally, each of these methods can store
detailed results in a page of class System-Locks. If a method failed to
acquire a lock because the object is already locked, information on this page identifies the
current requestor session that holds the lock. By convention, this page is named
LockInfo
in standard rules.
As a debugging aid, the standard section System-Locks.LockInfo and the standard harness Work-.LockInfo can present information from that page to an application user. The LockInfo page contains these properties:
- pxExpireDateTime
- pxLockHandle
- pxOwnerID
- pxUpdateOperator
- pxCreateDateTime
The lock string
A lock string uniquely identifies a lock. For instances that belong to classes not associated with a class group, the text string consists of the class name concatenated with the key parts of the object (determined on the Keys area of the Basics tab of the Class form, or the Locking tab of the Class form).
For an object that is within the scope of a class group, the lock string consists of the class group name concatenated with the value of the key properties identified on the Keys tab of the Class Group form. For example, for the Sample Work application, the class group is named PegaSample and work items in the PegaSample-Task class are identified with a W- prefix. The lock string for work item W-43 is thus:
PEGASAMPLE-TASK W-43
Expired ("soft") locks
Generally, a thread that acquires a lock retains it until the instance is saved again with a Commit method (which may complete an Obj-Save or Obj-Delete method). However the system automatically expires locks held longer than a specified timeout period. You can change the default timeout interval of 30 minutes to a longer or shorter period. This value is stored in the Data-Admin-System data instance.
An expired or "soft" lock remains held by a requestor session until the session releases it or until the requestor session ends, but a soft lock can be stolen — broken and acquired — by another requestor who opens the instance. In that case, any updates by the first user that are not committed are lost.
Releasing locks
Except as described below, a requestor can only release locks held by its own session. A Commit method releases all the locks held by a requestor Thread that were acquired with the ReleaseOnCommit box checked when the object was opened.
When a user signs off, any locks held by that requestor are released.
In contrast, locks are not released when a user closes a browser session by clicking the Windows close box (rather than by logging out). The locks may be needed by another Thread of the same operator, or by another operator or process. Encourage users to log off through a button or link rather than closing the window.
Releasing locks of other sessions
Lock information is held in the memory of each node, rather than in the database, for improved performance. However, even in a multinode system, a requestor can force the release of locks held by any session with the same Operator ID and same user name ( pyUserName ) through the PublicAPI method:
LockManager.unlock(StringMap, boolean)
This method communicates through the system pulse across all nodes. On each node, the system searches existing requestors (including passivated ones) using the supplied requestor ID. If a session is found, the system checks that the user names ( pyUserName ) also match before attempting to terminate the other session. If a session is found that matches the requestor ID, but the user names do not match, the system generates a SECU007 security alert and lists the corresponding requestor ID and user name in the logs.
Testing for locks
To test whether a work item is locked, an activity can call the standard activity
Work-.WorkLock, which tries to lock the work item. If it fails to
acquire a lock, the
SuccessInfo
parameter is negative, indicating that the
work item is already locked. The
FailureInfo
parameter provides additional
detail.
To test whether a lock is held on a page already on your own clipboard, call the function rule isPageLocked(tools, pagename).
To test whether an object other than a work item is locked, use one of several methods in the PublicAPI LockManagerInterface.
Debugging
To add detailed lock manager information to the Pega log, set the Logging Level Settings
tool with this category to Debug
:
com.pega.pegarules.engine.database.LockManagerImpl
To trace locking events from the application, add locking to the list of event types tracked by Tracer:
- Open Tracer.
- In the Settings tab, Event Types section, select Locking.
Previous topic Locking tab on the Class form Next topic Advanced tab on the Class form