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

Custom persisters

Custom entity persister

The EntityPersister interface contains information how to map an entity to the database table. There is one instance per mapped class. We extend Hibernate’s default implementations to achieve some custom behaviour (CustomEntityPersister).

Lazy initialization of UniqueEntityLoader cache

Hibernate initializes an instance of UniqueEntityLoader per LockMode. This can use quite a lot of memory if there are a lot of entity classes. Since we almost exclusively use the standard lock mode a lot of these loaders will never be used. In addition, these loaders are primarily used to load an entity by primary key, which we rarely use because we almost always use the query builder (to make sure business unit and security conditions are added).

To avoid wasting memory for unnecessary loaders they are instantiated lazily when they are used for the first time. A second reason for the lazy initialization is to optimize the startup performance, so that the application is ready as soon as possible.


This can perhaps be removed when Hibernate is upgraded to 5.3+ (see HHH-12558).

Entity instantiation

By default Hibernate instantiates entity classes by invoking their default constructor. Entity instantiation is intercepted by overriding EntityPersister#instantiate(); the instantiation itself is then delegated to the EntityFactory. The EntityFactory injects services into the created entities, tracks new entities and invokes listeners.

Before the entity factory is called it is verified whether the entity to be created belongs to the current Session/Context. This is important as otherwise the wrong Session/Context would be injected by the entity factory.

Custom collection persister

There is an instance of a CollectionPersister for every collection. Like with the entity persister, a customized implementation is used.

Filtered collections

By always returning true from isAffectedByEnabledFilters() Hibernate assumes that the collection might be filtered. Even though we do not use Hibernate’s filter feature we use a similar concept (see Collections). When filters are enabled certain shortcuts cannot be used by Hibernate (for example removing all entries in a n:n mapping table, which might wrongfully remove filtered data from the database).

Lazy initialization of CollectionInitializer

The CollectionInitializer instances are also lazily initialized for the same reasons as above (memory usage and startup performance).