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

Introduction

Originally the Persistence API was a completely self-made framework.

This implementation has now been replaced by Hibernate (currently version 6.5.x), due to the following reasons:

  • Lack of documentation and test coverage

  • Lost knowledge (original developers no longer work here)

  • Missing features (complex queries, typed entities)

In particular it was crucial to be able to execute queries that select (multiple) simple properties instead of entire entities to improve the performance of multiple aspects of nice2.

This document describes…

  • how the existing API has been implemented using Hibernate as backend (necessary to support existing code)

  • the new API

This document does not describe the usage of the old Persistence API or Hibernate itself.

At first it is described how Hibernate is initialized (Hibernate Setup) and how the XML entity definitions are converted into Java classes (Entity class generation).

Next it is explained how the automatically generated Java classes implement the functionality of the Entity interface (Abstract entity base class) and how the Relation interface is mapped to the JPA associations (Collections).

There is additional in depth information available about the mapping of the data:

The next chapters describes the lifecycle of the Context (Session Lifecycle) and the Transaction (Transaction Lifecycle and Transaction context).

It is also explained how the different kind of listeners are integrated into the persistence layer (Listeners).

Probably the most significant improvement is the new query builder (Query Builder) that allows much more efficient queries than before. The query builder is part of the new persistence API (New Persistence API).

Finally there are chapter about a few specific topics: