Obj-Refresh-and-Lock method

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

  • If the object is locked and the lock has not expired, this method has no effect.
  • If the object is not locked, this method acquires a lock and if necessary replaces the step page contents with the current value of an object instance.

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.

CAUTION:
Locking an object from an external class prevents only updates by other Pega Platform 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"
  • pxUpdateOperator — pyUserIdentifier 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 time stamp of the instance on the step page on the clipboard (property pxUpdateDateTime ) with the pxUpdateDateTime time stamp 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.
  5. 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 the Pega Community article Understanding the Obj-Lock-And-Refresh method for details.

Fail and Warn conditions

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

  • If the instance is locked by another requestor, the method returns a Fail status.
  • If the key supplied does not match the key of any instance in the database, the system creates a page of the indicated class that is empty except for the pxObjClass property, and returns a Fail status.

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