Back Forward Obj-Refresh-and-Lock method

Methods and instructions by function

Use this method to assure that the contents of the step page are current and a lock is held on the corresponding object.

This is useful if you are not certain whether the contents of the step page are current or whether your requestor session already holds a lock on the page.

CautionLocking an object from an external class prevents only updates by other PRPC requestors. Locking does not prevent changes to the external database   — including changes to a row that is open in PRPC — by other systems.

Parameters

This method has two parameters.

Parameter

Description

ReleaseonCommit

Select this box if you want the system to release the lock when the next Commit method occurs for this instance.

In the unusual case that you want to retain the lock after Commit — perhaps because additional changes are expected — your activity can later use the Page-Unlock method to release the lock.

LockInfoPage

Optional. As a debugging aid, identify the name of a page to be created by this method to hold the results of the locking attempt when it fails. The page, of class System-Locks, contains the following properties:

  • pxOwnerID — Requestor who holds the lock
  • pxExpireDateTime — Date and time the lock will expire, or become "soft"
  • pxUpdateOperatorpyUserIdentifier value for the requestor who holds the lock
  • pxLockHandle — Text string that defines the lock

If the Obj-Refresh-and-Lock fails to acquire a lock, this page is created and can be viewed with the Clipboard tool or the Tracer.

By convention, this page is named LockInfo in standard rules. When a lock failure occurs during a flow execution, the flow can display the standard harness Work-.LockInfo (or a similar harness incorporating the standard section System-Locks.LockInfo) to report the situation. If the lock that was requested but not acquired is held by the same Operator ID in a separate requestor session, that user can click the  Release Lock    button to release the lock.

Results

The system checks whether the object on the step page is locked and the lock has not expired. If the lock is held, the method creates the results page as specified in the LockInfoPage parameter, but no further processing occurs.

If the step page does not exist, the system creates a new page.

If no lock is held, the system:

  1. Assembles the key to the object instance using information in the class instance.
  2. Acquires a lock on the object.
  3. Determines whether the current clipboard page is stale, meaning that the PegaRULES database row is newer. To make this determination, it:
    • Compares the last update timestamp of the instance on the step page on the clipboard (property pxUpdateDateTime) with the pxUpdateDateTime timestamp of the instance on the database. If the times are the same, the clipboard copy is not stale; if they differ, the clipboard copy is stale.
    • If the pxUpdateDateTime property has no value in both cases, it performs a similar comparison is based on the pxCreateDateTime properties.
    • If the instance was saved recently but not yet committed, the comparisons are made with the pxUpdateDateTime or pxCreateDateTime in the saved copy, not the database row.
  4. If the clipboard copy is stale, it reloads the step page from the current database instance.

DateTime values are captured to the nearest millisecond. However, for certain database software products, the values are rounded when saved. The comparisons described above consider such rounding. See PDN article PDN 19165 Understanding the Obj-Lock-And-Refresh method for details.

Fail and Warn conditions

These situations cause the method status to be Fail or Warn:

Checking the method status

This method updates the pxMethodStatus property. See How to test method results using a transition.

Restrictions

This method cannot be used in a step that involves iteration.

Do not use this method to open and acquire locks on rule instances.

Debugging

To debug this method, use the Logging Level Settings tool with the following Java class:

com.pega.pegarules.engine.database.Opener

Definitions external class, internal class
Related topics Page-Unlock method

UpMethods and instructions by function