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 detail view. As a result, only one user can edit this particular entity instance in a given moment.

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


For automatic installation through Jmix Marketplace, follow instructions in the Add-ons section.

For manual installation, add the following dependencies to your build.gradle:

implementation 'io.jmix.pessimisticlock:jmix-pessimisticlock-starter'
implementation 'io.jmix.pessimisticlock:jmix-pessimisticlock-flowui-starter'


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

@PessimisticLock(timeoutSec = 120)
@Table(name = "DOCUMENT")
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.pslock.use-default-quartz-configuration to false if you want to disable the default expiration mechanism. This property is true by default.

  • Use jmix.pslock.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 Pessimistic Locking → Locks view. This view also enables unlocking of any object.