This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

Transaction Lifecycle

A session is associated with exactly one transaction at the same time. It is however possible to run several transactions consecutively in the same session. A transaction is only required for write operations.


There are several ways to start a transaction:

Independently of how the transaction was started, in the background an instance of TransactionControl will be created. No matter through which API the transaction is accessed, always the same transaction control instance is used per transaction.

The transaction control has the following responsibilities:

  • it encapsulates the actual Hibernate Transaction

  • commit or rollback of the transaction

  • firing of commit listeners

  • handling of created and deleted entities

  • mapping from JPA to our custom exception (for example OptimisticLockException is mapped to OutdatedException. All exceptions that inherit from BaseRuntimeException will be thrown again without wrapping them - this is used for example for InformationExceptions

Commit Listeners


A CommitListener can be registered with the EntityFacadeListenerManager for a specific session.

Commit listeners implemented using the interface of the old API (CommitListener) are registered by the Context using an adapter class.

These listeners are meant to be used by the business code to run actions before or after a commit (or rollback).


The TransactionListener can be registered directly on the transaction control and is meant to be used by internal code and are used to clean up the transaction.

TransactionAware instances which are registered on the TransactionAdapter are also added as TransactionListener using an adapter class.

Transaction context

The EntityTransactionContext keeps track of all entities that are created or deleted during the transaction and executes these changes before the transaction is committed.

See Transaction context for more details.


Entities that have been created or modified during a transaction will be validated before the transaction is committed.

The validation for new entities is started in EntityTransactionContext#executeEntityOperations() just before Session#save() is called. ValidationContext.Operation.INSERT is passed to the validation context for newly created entities.

The validation of updated entities is started by the ValidationInterceptor (which is a Hibernate Interceptor).

All modified entities are validated by the preFlush() event that is called for all entities which are in the Hibernate session before the changes are flushed to the database. Only dirty entities will be validated. ValidationContext.Operation.UPDATE is passed to the validation context for updated entities.

Advisory locks

TransactionControl#lock() can be used to create an advisory lock (pg_advisory_xact_lock()) which uses the database to create an application-level lock (which is independent of any database tables) based on a specific key. The lock is released automatically after the transaction is finished.

Transaction attributes

TransactionControl#setAttribute() and TransactionControl#getAttribute() can be used by the business logic to store and retrieve transaction-scoped data.