42.2 Lock Modes

42.2.1 Setting the Lock Mode

To specify the lock mode, use one of the following techniques.

• Call the EntityManager.lock method, passing in one of the lock modes:

  EntityManager em = ...;
  Person person = ...;
  em.lock(person, LockModeType.OPTIMISTIC);
  

• Call one of the EntityManager.find methods that take the lock mode as a parameter:

  EntityManager em = ...;
  String personPK = ...;
  Person person = em.find(Person.class, personPK, 
      LockModeType.PESSIMISTIC_WRITE);
  

• Call one of the EntityManager.refresh methods that take the lock mode as a parameter:

  EntityManager em = ...;
  String personPK = ...;
  Person person = em.find(Person.class, personPK);
  ...
  em.refresh(person, LockModeType.OPTIMISTIC_FORCE_INCREMENT);
  

• Call the Query.setLockMode or TypedQuery.setLockMode method, passing the lock mode as the parameter:

  Query q = em.createQuery(...);
  q.setLockMode(LockModeType.PESSIMISTIC_FORCE_INCREMENT);
  

• Add a lockMode element to the @NamedQuery annotation:

  @NamedQuery(name="lockPersonQuery",
    query="SELECT p FROM Person p WHERE p.name LIKE :name",
    lockMode=PESSIMISTIC_READ)
  

42.2.2 Using Pessimistic Locking

Versioned entities, as well as entities that do not have version attributes, can be locked pessimistically.

To lock entities pessimistically, set the lock mode to PESSIMISTIC_READ, PESSIMISTIC_WRITE, or PESSIMISTIC_FORCE_INCREMENT.

If a pessimistic lock cannot be obtained on the database rows, and the failure to lock the data results in a transaction rollback, a PessimisticLockException is thrown. If a pessimistic lock cannot be obtained, but the locking failure doesn't result in a transaction rollback, a LockTimeoutException is thrown.

Pessimistically locking a versioned entity with PESSIMISTIC_FORCE_INCREMENT results in the version attribute being incremented even if the entity data is unmodified. When pessimistically locking a versioned entity, the persistence provider will perform the version checks that occur during optimistic locking, and if the version check fails, an OptimisticLockException will be thrown. An attempt to lock a non-versioned entity with PESSIMISTIC_FORCE_INCREMENT is not portable and may result in a PersistenceException if the persistence provider does not support optimistic locks for non-versioned entities. Locking a versioned entity with PESSIMISTIC_WRITE results in the version attribute being incremented if the transaction was successfully committed.