Lock by key
Event action – Abstract
Purpose: The Event handling can achieve a sequencing of competing processes in different transactions in event handling by checking and, if necessary, setting a lock key.
The Lock by key event action can be used in Event handling to control the sequencing of competing processes in different transactions.
When the Lock by key event action is executed, the system checks whether a lock has already been registered by another transaction on the server for the specified Lock key value.
If there is a lock for the Lock key value, event processing (for its own transaction) is temporarily stopped until the other transaction has been completed.
If there is not yet a lock for the Lock key value, a lock is registered so that other transactions relating to the same Lock key value will have to wait until its own transaction is completed, whose event processing continues without any interruption.
If several transactions execute the Lock by key event action with the same Lock key value while a lock already exists for this key, waiting transactions are processed in a sequential manner according to the ‘first come, first served’ principle.
The Lock by key event action is typically used to prevent different, simultaneous transactions from attempting to execute an action with the same content, e.g. creating an entity for the ‘same’ master data record.
However, this option should be used sparingly and always in conjunction with a suitable Lock key value that is as specific as possible to avoid creating a ‘bottleneck’ in event processing.
What about deadlocks?
As soon as several lock key values are in play, a deadlock can occur between two transactions, in which they block each other because each of them are waiting for the other.
Example:
An event handling (I) starts with a Lock by key event action for the lock key value ‘X’ and then starts a lengthy database operation (Execute SQL query).
This is followed by another Lock by key event action for the lock key value ‘O’ before the results are reported via Show alert.
Another event handling (II) begins with a Lock by key event action for the lock key value ‘O’.
This is followed by another Lock by key event action for the lock key value ‘X’ before a return value is reported via Hinweis anzeige.
If the first event handling (I) is triggered at runtime and the second event handling (II) is also started while the database operation is in progress, the following happens:
(II) immediately sets a lock for the lock key value ‘O’ and then waits for the lock initiated by (I) for the lock key value ‘X’ to be cancelled.
As soon as (I) completes the database operation, a deadlock is imminent since (I) then has to wait for the lock for the lock key value ‘O’, which has been initiated by (II) in the meantime, to be lifted, which is not expected until the completion of (I) due to the lock for the lock key value ‘X’. This completes the ‘circle’.
To prevent an acute deadlock from irrevocably ‘sending both transactions nowhere’, Lobster Data Platform / Orchestration intercepts the impending deadlock at runtime and triggers an error message when the Lock by key event action that would close the loop is executed.
The triggered error message (Deadlock detected) names the lock key values involved and cancels one of the transactions.
The other transaction will then be continued.
Configuration
Event handling does not require a reference object. However, an existing reference object is available as an input value for the value configuration in the Lock key value parameter.
A text value is expected for the Lock key value parameter, which can be provided either by direct input (default) or – after clicking on the small grey arrow at the bottom left of the Text field – via a value configuration.
If a value configuration does not return a text value at runtime, the server-side string image of the return value is used as the Lock key value.
If there is no input or value configuration or a value configuration for the Lock key value returns ‘No value’ ($null) at runtime, the event action has no effect.
If a value configuration returns a list as the Lock key value that contains the dynamic enumeration value for the Country ‘France’ (FR) as the only entry, this has the same effect as entering the character string ‘[FR]’.
The identifier adopted as the Lock key value is trimmed on both sides to generate the effective key value for the lock.
The input of marginal whitespace characters has no effect on the effective key value. Character strings such as ‘A51’, ‘A51' or 'A51’ always effectively address the key value ‘A51’.
Blocking only takes place if the string contains at least one character after trimming.
The string defined as the Lock key value is processed in a case-sensitive manner.
The strings ‘eMail’ and ‘Email’ generate different effective lock key values.
Example
Simple scenario to experiment
►IMPORTANT◄ The following scenario is not a typical use case but is well suited to familiarise users with the effect of the Lock by key event action with little effort in an experiment. It is expressly not a recommended procedure for solving the task described.
A Custom action event (LOCK_FILE_FOR_APPEND) is triggered via a ribbon macro that can be 'attached’ to the ribbon of various views.
In this way, authorised users should be able to attach a text entry to a server-side file of their choice:
Firstly, the user is asked for the name of the target file using the User prompt resolver. Whether the file already exists or has to be created during the subsequent write access should not play a role here.
As a second step, the text to be added is again queried using the User prompt resolver.
The file is then updated.
As soon as a user has named a specific target file in the first step, further write access to the same file should be restricted until the file update has been completed.
For a simple test, it is sufficient to open two views (or two instances of the same view) alongside each other that offer the ribbon button. Two concurrent transactions can then be started within the same session, in which the file name can either be the same or different.
Configuration:
The following screenshot on the right shows the configuration for the only event handling required for this demonstration.
|
A Custom action event (LOCK_FILE_FOR_APPEND) serves as the Triggering event. The data context is irrelevant for the demonstration. The Validating rule is implemented here as a Role rule in order to restrict the user group. The Action on passed rule should be executed if an authorised user has triggered the Triggering event via the ribbon:
►NOTE◄ The input text here is unchecked and used directly as a Lock key value to create a lock under the name of the addressed file or to determine whether a lock already exists. If the user names a file via User prompt that is already locked by an ongoing transaction, event processing is paused until this has been completed. This happens after the input dialogue has been closed and without any further feedback apart from the waiting cursor.
|
|
Runtime example:
The view on the left shows a transaction in the second step (text input) after a notepad file has been named for the output.
In this state, a lock with the lock key value notepad has been set up for this transaction.
After entering the text and clicking OK, the entry is saved and the transaction ends. This cancels the notepad lock.
The view on the right shows a transaction started later in the first step (file selection), which attempts to access the same file as the transaction on the left.
Clicking OK executes the Lock by key event action, which is paused until the transaction on the left ends. The dialogue for text inputting only appears on the right once the left-hand transaction has ended.
If a different file name (e.g. notepad2) is entered before clicking OK on the right, which is not yet used as a lock key value for an active lock, the dialogue for text input appears immediately.