Use this method to assure that the contents of the step page are
current and a lock is held on the corresponding object. C-1804 CLINB
4/22/05
- 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.
Locking an object from an external class
prevents only updates by other Process Commander requestors. Locking does
not prevent changes to the external database — including
changes to a row that is open in Process Commander — by other
systems.
Parameters
This method has two parameters. SR-3117 B-19433 other parameters
removedB-16732 added back?
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. GAGNJ 04-02-41 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. BUG-6144
MARIK TURBT 2/24/06 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 rule Work-.LockInfo (or a similar
harness rule incorporating the standard section rule
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.
SDAS/OLSOK 12/05/05 and SR-210 and B-15556 rejected
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 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.
B-17033 rejected
- 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
Pega Developer Network article PRKB-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
:
- 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
B-11491 This method cannot be used in a step that involves
iteration.
Do not use this method to open and acquire locks on rule instances.
PRKB-19165
Debugging PRKB-19165
To debug this method, use the Logging Level Settings tool with the
following Java class:
com.pega.pegarules.engine.database.Opener
Methods and instructions by function