Pessimistic Locking

Pessimistic locking can be used when there is a high probability of simultaneous editing of a single entity instance. In such cases the optimistic locking, based on entity versioning, usually creates too many collisions.

Pessimistic locking explicitly locks an entity instance when it is opened in the UI edit screen or Flow UI detail view. As a result, only one user can edit this particular entity instance in a given moment of time.

The Jmix pessimistic locking mechanism can also be used to manage simultaneous execution of arbitrary processes. The key benefit is that the locks are distributed, since they are replicated in the cluster. More information is available in Javadocs of the LockManager interface.

To enable pessimistic locking for any entity, add the @PessimisticLock annotation to the entity class, for example:

@PessimisticLock(timeoutSec = 120)
@JmixEntity
@Table(name = "DOCUMENT")
@Entity
public class Document {
// ...

The timeoutSec annotation attribute defines the lock expiration timeout in seconds. It is 300 sec by default.

The automatic lock expiration requires the Quartz job scheduler. You can provide it by including the Quartz add-on in your project.

The following application properties control the expiration mechanism:

  • Set jmix.core.pessimistic-lock.use-default-quartz-configuration to false if you want to disable the default expiration mechanism. This property is true by default.

  • Use jmix.core.pessimistic-lock.expiration-cron to set a Cron expression for expiration schedule. This property has 0 * * * * ? value by default, which means "every minute".

Current state of locks can be tracked through the Administration → Locks screen of Classic UI and the System → Locks screen of Flow UI. This screen also enables unlocking of any object.