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

New Persistence API

In addition to the current persistence API (based on the Context class) there is a new API that offers features that are not available in the old API.


As of version 3.2 the new API is mostly finished and all features should be accessible through the new API.


The PersistenceService is the core of the new API and provides type safe access to the persistence layer. In contrast to the Context of the old API that only works with entity names, the PersistenceService also accepts entity classes and returns an entity instance of the given class. This cannot be used directly yet, because all entity classes are generated at startup and therefore cannot be referenced by the code. However this functionality is currently used by the QueryExecutor that is available in groovy scripted listeners to provide statically compiled, type safe access to the entities.

In addition the PersistenceService provides access to the different query builder implementations. In addition to the standard query builder that returns Entity instances, there are other query builders that can select sub-paths directly and efficiently.

See Query Builder for more information about this topic.


The current PersistenceSession can be obtained from the PersistenceService and roughly corresponds to a concrete Context instance (not the ContextService!).

It enables access to session-scoped functionality (like adding listeners for the duration of the session).


The PrimaryKeyLoader is used to load an entity by primary key. It is used when PersistenceService#retrieve() or EntityManager#get() is called.

The default implementation DefaultPrimaryKeyLoader uses the query builder to load the entity. This makes sure that the security conditions are always applied when an entity is loaded.

We cannot use Hibernate’s Session#get() directly (even is we use a custom event listener that adds security conditions), because it caches the results for the duration of the session. So if an entity is loaded in privileged mode first, it will always remain accessible even if the privileged mode has ended.

There is also a special implementation for entity-docs (EntityDocsPrimaryKeyLoader). They need to be treated separately, as there are no ACL rules for them.


The Metamodel provides additional information about the data model that is not available in the DataModel.

Currently the only functionality is to get the sql type of an entity field. This is used by the SchemaModelValidatorTask which checks if the database schema is compatible with the JPA schema.