Understanding the Obj-Refresh-And-Lock method
How does the Obj-Refresh-And-Lock activity method work, and what benefit does it provide over Obj-Open?
Use Obj-Refresh-And-Lock when you have a clipboard page containing an instance that you do not have a lock on, and you decide to update the instance. It may also be used in cases where you are not sure whether the instance is locked (such as in utility activities that may be called in various places).
Obj-Refresh-And-Lock locks the instance and ensures that the version you have on a clipboard page is the same as or newer than the version currently in the database. This ensures that you will not overwrite anyone else’s changes when you ultimately save the instance, and it also ensures that nobody else will overwrite any of your changes.
You can use this method, for example, after displaying an instance to a user in read-only mode, when that user indicates that he would like to update the instance.
Calling Obj-Refresh-And-Lock is similar to, but not identical to, calling Obj-Open with the Lock parameter set to true. The difference is that Obj-Refresh-And-Lock does not read the instance from the database if the version of the instance on the clipboard is the same as or newer than the version in the database. So if any changes were made to the instance on the clipboard page since it was previously opened, they are preserved.
On the other hand, when you call Obj-Open, it always overwrites the instance on the clipboard page with the version from the database — even if this means overwriting changes that you had made to the clipboard page.
Because of these differences, Obj-Refresh-And-Lock is in many cases more efficient than Obj-Open, and it is safer.
To determine whether the version of an instance on a clipboard page is the same as the version in the database, Obj-Refresh-And-Lock compares the values of the pxCreateDateTime and pxUpdateDateTime properties on the clipboard page to the values of the pxCreateDateTime and pxUpdateDateTime columns of the corresponding database record.
When to use Obj-Refresh-And-Lock
- Use Obj-Refresh-And-Lock when you have a lockable instance but you do not know whether it is locked, and you need to update that instance. Use Obj-Refresh-And-Lock only if there’s a good chance that the version you have on the clipboard is the most up-to-date.
- For this activity method to work correctly, follow these best practices:
Do not update clipboard pages containing instances that come from the database unless you hold a lock on the instance.
Also, be sure that the pxCreateDateTime and/or the pxUpdateDateTime properties of an instance are correct before you save the instance..
Finally, do not take out locks by directly calling a lock API method. You should always use Obj-Refresh-And-Lock or another Open-* method to lock instances.
Note that this method does not work with instances of classes that use rule resolution.
Obj-Refresh-And-Lock is called on the clipboard page containing the instance that you wish to ensure is current.
First, the Obj-Refresh-And-Lock method checks to see if its caller already holds a lock on this instance. If this is the case (and assuming that the best practices have been followed) then it must be true that the version of the instance on the caller’s clipboard page is already the most up-to-date — otherwise the caller would not have been able to lock the instance. In this case, Obj-Refresh-And-Lock does not need to read the instance from the database.
If the instance is not already locked by the caller, then Obj-Refresh-And-Lock attempts to lock the instance. If it cannot do so because the instance is locked by someone else, then Obj-Refresh-And-Lock indicates failure: the instance is still read from the database, but the processing status is set to
Error with message
Database-LockFailure-LockHeldByAnother. Additionally, the lock status page specified in the LockInfoPage parameter identified which requestor currently owns the lock. The caller must detect this failure..
If Obj-Refresh-And-Lock is able to lock the instance, then it compares pxCreateDateTime and pxUpdateDateTime of the version of the instance on the clipboard page with pxCreateDateTime and pxUpdateDateTime of the version of the instance in the database, to see which is newer. It compares dates as follows:
- It compares the pxUpdateDateTime of the clipboard page with the pxUpdateDateTime column of the instance in the database. If pxUpdateDateTime is not set on either, then it goes on to compare pxCreateDateTime. If pxUpdateDateTime is the same in both versions (within a tolerance that accounts for rounding in the database column), then Obj-Refresh-And-Lock knows that the version of the instance on the clipboard page is the most up-to-date—so Obj-Refresh-And-Lock does not need to read the instance from the database. If pxUpdateDateTime is different in the two versions, then it must be the case that the instance in the database has been updated since the instance on the clipboard page was read—so Obj-Refresh-And-Lock reads the entire instance from the database.
Note on the rounding: Since different databases round date/time amounts to different precisions, the value of a date/time database column may not always be exactly equal to the value in the corresponding database column in the storage stream. For this reason, when comparing date/times from a clipboard page to date/times in a database column, Process Commander cannot expect an exact match.
- If pxUpdateDateTime is not set on either version of the instance, then Obj-Refresh-And-Lock compares the pxCreateDateTime of the two versions. If pxCreateDateTime is the same in each version (within a tolerance), then Obj-Refresh-And-Lock knows that the version of the instance on the clipboard page is the most up-to-date, so it does not need to read the instance from the database. If pxCreateDateTime is different in the two versions, then the instance in the database must have been updated since the instance on the clipboard page was read—so Obj-Refresh-And-Lock reads the entire instance from the database.
If the instance being opened is on the deferred operation list—that is, the instance has previously been saved by the caller but the Commit method has not yet been called—then the timestamps on the version of the instance on the clipboard page are compared with the timestamps of the version of the instance on the deferred operation list, not the version in the database, in the manner described above.
Diagnostics for Obj-Refresh-And-Lock
You can get diagnostic information for Obj-Refresh-And-Lock by setting to debug the log4j diagnostic level for the following Java class: