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.
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:
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
|
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:
- Assembles the key to the object instance using information in the class instance.
- Acquires a lock on the object.
- 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.
- 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
Failstatus.
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.OpenerPrevious topic Obj-Open-By-Handle method Next topic Obj-Save method