Skip to content

11. Hibernate

Das vorherige Kapitel hat gezeigt, wie eine Kotlin-Anwendung über einen JDBC-Treiber mit einer Datenbank interagiert: Es wird eine Verbindung geöffnet, SQL-Befehle werden ausgeführt, die Ergebniszeilen werden Spalte für Spalte gelesen und in Objekte kopiert. Dieser Kopiervorgang – von Zeilen zu Objekten und von Objekten zu den [INSERT], [UPDATE] und [DELETE]-Befehlen – ist repetitiv. Er lässt sich mit einem Werkzeug automatisieren: einem „Object-Relational Mapper“ (ORM). Dieses Kapitel stellt den am weitesten verbreiteten ORM der Java-Welt vor, Hibernate, und den Standard, den er implementiert, Jakarta Persistence. Kotlin hat keinen eigenen ORM dieses Kalibers: Es verwendet direkt die der Java-Plattform – allen voran Hibernate –, so wie es auch andere Java-Bibliotheken verwendet. Sie müssen nur einige Regeln kennen, um Kotlin-Entitäten zu schreiben, die mit Hibernate funktionieren: Dieses Kapitel stellt sie nach und nach vor.

Das Kapitel greift den Beispielcode der Artikel aus Kapitel 10 wieder auf und endet mit Version 7 der Anwendung zur Steuerberechnung, deren [dao]-Schicht Hibernate verwendet.

11.1. Was ist ein ORM?

11.1.1. Objekte und Tabellen

Eine Kotlin-Anwendung arbeitet mit Objekten: Ein Artikel hat einen Namen, einen Preis und einen Lagerbestand; eine Bestellung hat einen Kunden und eine Liste von Bestellpositionen, von denen jede auf einen Artikel verweist. Eine relationale Datenbank speichert dieselben Informationen in Tabellen: eine Zeile in der Tabelle [articles] pro Artikel, eine Zeile in der Tabelle [orders] pro Bestellung, wobei die Beziehungen zwischen den Zeilen durch Fremdschlüssel ausgedrückt werden. Die beiden Welten passen nicht ganz zusammen:

  • Ein Objekt verweist direkt auf andere Objekte ([order.client]); eine Zeile enthält den Primärschlüsselwert einer anderen Zeile ([client_id]);
  • Ein Objekt kann eine Collection enthalten ([order.lines]); eine Tabelle enthält nur einzelne Werte; die Collection wird durch die Zeilen einer anderen Tabelle dargestellt, die auf die Bestellung verweisen;
  • Die Kotlin-Typen ([String], [BigDecimal], [LocalDate], [Boolean]) und die SQL-Typen ([varchar(30)], [decimal(10,2)], [date], [bit]) sind nicht dieselben;
  • Objekte werden mit Kotlin abgefragt (die Operationen [filter], [map]... auf Collections) und Tabellen werden mit SQL abgefragt.

Ein ORM überbrückt die beiden Welten. Wir definieren die Zuordnung zwischen Klassen und Tabellen (das Modell bzw. das „Mapping“) ein für alle Mal; er übernimmt dann:

  • die Übersetzung von Abfragen, die in einer objektorientierten Sprache (HQL) geschrieben oder mit Code (Criteria-API) konstruiert wurden, in SQL- und [SELECT]-Befehle;
  • das Erzeugen von Objekten aus den gelesenen Zeilen (dies wird Materialisierung genannt);
  • das Speichern der gelesenen Objekte und das Erkennen derjenigen, die geändert, hinzugefügt oder gelöscht wurden;
  • das Generieren der [INSERT], [UPDATE], und [DELETE]-Befehle, die diese Änderungen in der Datenbank abbilden;
  • und bei Bedarf das Erstellen und Aktualisieren des Datenbankschemas (Tabellen, Spalten, Indizes) anhand der Klassen.

Die Architektur einer Anwendung, die Hibernate mit MySQL verwendet, sieht wie folgt aus:

Image

  • [1]: die Anwendung. Ihre [dao]-Schicht kommuniziert nicht mehr direkt mit dem JDBC-Treiber, sondern mit Hibernate, über ein [Session]-Objekt und HQL-Abfragen;
  • [2]: Hibernate, DBMS-unabhängig: Modell, Abfrageübersetzung, Änderungsverfolgung, Schemagenerierung;
  • [3]: der Dialekt des DBMS (hier [MySQLDialect]): Er kennt die SQL-Syntax des DBMS, seine Spaltentypen und seine Funktionen. Die Dialekte der wichtigsten DBMS sind Teil von Hibernate selbst: Dem Projekt muss nichts hinzugefügt werden;
  • [4]: der JDBC-Treiber für das DBMS, derjenige aus Kapitel 10 (MySQL Connector/J): Hibernate ersetzt JDBC nicht, sondern verwendet es;
  • [5]: das DBMS.

Ob die Anwendung in Java oder Kotlin geschrieben ist, ändert nichts an diesem Schema: Hibernate ist eine Java-Bibliothek, die Kotlin-Code wie jede andere Java-Bibliothek aufruft (Kapitel 5), und die kompilierten Kotlin-Klassen sind für Hibernate Java-Klassen wie alle anderen.

11.1.2. Jakarta Persistence und Hibernate

Hibernate wurde 2001 von Gavin King als Reaktion auf die Schwerfälligkeit der „Entity Beans“ der damaligen Java Platform EE geschaffen. Sein Erfolg war so groß, dass seine Ideen in einen Standard einflossen, JPA (Java Persistence API), der 2006 mit Java EE 5 veröffentlicht wurde. Als Java EE an die Eclipse Foundation übertragen und in Jakarta EE umbenannt wurde, wurde JPA zu Jakarta Persistence, und seine Pakete wechselten von [javax.persistence] zu [jakarta.persistence] (Version 3.0, 2020). Die aktuelle Version ist Jakarta Persistence 3.2 (2024).

Jakarta Persistence ist eine Spezifikation: eine Menge von Interfaces ([EntityManagerFactory], [EntityManager] ...), Annotationen ([@Entity], [@Id], [@Column] ...) und eine Abfragesprache, JPQL. Sie wird von mehreren Produkten implementiert: Hibernate ORM (das am weitesten verbreitete, in Spring Boot und Quarkus verwendet), EclipseLink (die Referenzimplementierung) ... Dieser Kurs verwendet Hibernate ORM 7.4.5, das Jakarta Persistence 3.2 implementiert.

Hibernate bietet zwei Möglichkeiten der Nutzung:

  • ausschließlich über die Standard-Interfaces: In diesem Fall hängt der Code nur von [jakarta.persistence] ab, und ein Wechsel der Implementierung wäre prinzipiell möglich;
  • über seine eigene („native“) API, die funktionsreicher ist und deren Interfaces die des Standards erweitern : eine [SessionFactory] ist eine [EntityManagerFactory], und eine [Session] ist ein [EntityManager].

Wir verwenden die eigene API von Hibernate, wie in dessen Dokumentation empfohlen: Sie bietet alle Standardmethoden ([persist], [find], [merge], [remove] ...) sowie die Erweiterungen von Hibernate. Die Annotationen sind jedoch stets die vom Standard definierten. Die folgende Tabelle zeigt die Entsprechungen:

Jakarta Persistence
Hibernate
Rolle
[EntityManagerFactory]
[SessionFactory]
Hibernate-Konfiguration für eine Datenbank: ein schwergewichtiges Objekt, das einmal erstellt und von der gesamten Anwendung gemeinsam genutzt wird
[EntityManager]
[Session]
Eine Datenbanksitzung: ein leichtgewichtiges, kurzlebiges Objekt
[EntityTransaction]
[Transaction]
eine Transaktion
JPQL
HQL
die Abfragesprache; HQL ist eine Obermenge von JPQL
[CriteriaBuilder]
[HibernateCriteriaBuilder]
Abfragekonstruktion per Code

Im Kotlin-Ökosystem begegnen Ihnen auch Datenzugriffsbibliotheken anderer Art, etwa Exposed (von JetBrains), mit dem Sie SQL-Abfragen in einer dedizierten Kotlin-Sprache schreiben können. Diese sind leichtgewichtiger als ein vollständiger ORM; Hibernate bleibt der Standard für Spring-Anwendungen, sowohl in Java als auch in Kotlin, und ihn untersuchen wir.

11.1.3. Bibliotheken

Die in diesem Kapitel verwendeten Bibliotheken lauten wie folgt (sie sind im Anhang zu den Abhängigkeiten zusammengefasst):

Gradle-Abhängigkeit
Rolle
[org.hibernate.orm:hibernate-core] 7.4.5.Final
Hibernate selbst; es enthält die API von Jakarta Persistence 3.2 ([jakarta.persistence-api]) und seine eigenen Abhängigkeiten (Byte Buddy zur Klassengenerierung, ANTLR zur Abfrageanalyse, JBoss Logging für das Logging usw.)
[com.mysql:mysql-connector-j] 9.7.0
der JDBC-Treiber für MySQL, derjenige aus Kapitel 10
[ch.qos.logback:logback-classic] 1.5.38
Logback, das das Log von Hibernate empfängt

Hibernate schreibt sein Log (ausgeführte SQL-Befehle, Warnungen usw.) über JBoss Logging, eine kleine Bibliothek, die Meldungen einfach an das im Klassenpfad gefundene Logging-System weiterleitet: Log4j 2 oder Logback (über SLF4J) oder, falls keines vorhanden ist, das des JDK bzw. [java.util.logging]. Ohne Konfiguration zeigt Letzteres jede Meldung auf zwei Zeilen an, in den meisten Konsolen in Rot, was die Ausgabe des Programms schwer lesbar macht. Wir fügen daher Logback zu unseren Projekten hinzu und konfigurieren es mit einer Datei [logback.xml].

Zusätzlich zu diesen Bibliotheken gibt es zwei Kotlin-Compiler-Plugins, die Kotlin-Klassen an die Anforderungen von Hibernate anpassen: [kotlin("plugin.jpa")] und [kotlin("plugin.allopen")]. Warum sie notwendig sind, sehen wir bei der ersten Entität.

11.1.4. Code-First oder Database-First

Das Modell (die Zuordnung zwischen Klassen und Tabellen) kann auf zwei Arten aufgebaut werden:

  • Code-First: Sie schreiben die Kotlin-Klassen, und Hibernate leitet daraus das Datenbankschema ab, das es dann selbst erstellen kann. Dies ist der Ansatz, der in diesem Kapitel verfolgt wird;
  • Database-First: Die Datenbank existiert bereits, und die Klassen werden anhand ihres Schemas mit den Reverse-Engineering-Werkzeugen von Hibernate (Hibernate Tools) oder mit denen der Entwicklungsumgebungen generiert (IntelliJ IDEA kann Entitäten aus Datenbanktabellen sowohl in Java als auch in Kotlin erzeugen). Dieser Ansatz wird bei Anwendungen verwendet, die mit einer bestehenden Datenbank arbeiten müssen. Der generierte Code ähnelt dem, den wir von Hand schreiben würden.

11.2. Ein erstes Beispiel

11.2.1. Das Projekt

Die Beispiele dieses Kapitels sind Unterprojekte eines Gradle-Builds mit mehreren Projekten (siehe Kapitel 6) und befinden sich im Ordner [11-hibernate]:

11-hibernate/
  settings.gradle.kts     the list of the subprojects
  build.gradle.kts        the root project: the plugins and their versions
  gradlew, gradlew.bat    the Gradle wrapper
  tools/                  library: the compact SQL log
  articles/               library: the Article entity and the [hbarticles] database
  first/                  a first example
  model/                  the model: annotations, XML file, creation script
  crud/                   persist, find, merge, remove
  hql/                    HQL queries
  criteria/               Criteria API queries
  relations/              relationships between entities
  clients/                the evolution of the database schema
  async/                  Hibernate, virtual threads and coroutines
  transactions/           transactions
  concurrency/            optimistic concurrency
  rawsql/                 native SQL
  bulkupdate/             bulk updates
  injection/              Hibernate and Spring
  TaxV7/                  the tax calculation application, version 7

Die Datei [settings.gradle.kts] deklariert die Unterprojekte:

// Kapitel 11: Hibernate

// Gradle lädt das von jvmToolchain(25) angeforderte JDK selbst herunter, wenn es auf dem Rechner nicht gefunden wird
plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
}

rootProject.name = "hibernate"

// zwei Bibliotheken, die den Beispielen des Kapitels gemeinsam sind
include("tools", "articles")
// die Beispiele
include("first", "model", "crud", "hql", "criteria", "relations", "clients",
    "async", "transactions", "concurrency", "rawsql", "bulkupdate", "injection")
// Version 7 der [Tax]-Anwendung: eine mit Hibernate geschriebene [dao]-Schicht
include("TaxV7:tax-dao-hibernate", "TaxV7:tax-ui-hibernate")

// die [business]- und [ui]-Schichten von Version 5 (Kapitel 6) werden wiederverwendet: Composite Build
includeBuild("../06-architectures")
  • Zeilen 3–6: das Plugin, mit dem Gradle JDK 25 selbst herunterladen kann, wenn es auf dem Rechner nicht gefunden wird (Kapitel 2);
  • Zeile 8: der Name des Wurzelprojekts;
  • Zeile 11: die beiden Bibliotheken, die den Beispielen gemeinsam sind;
  • Zeilen 13–14: ein Unterprojekt, als Beispiel. Gradle verlangt nicht, dass sie in der Reihenfolge ihrer Abhängigkeiten aufgeführt werden; es leitet diese selbst aus den zwischen den Unterprojekten deklarierten Abhängigkeiten ab;
  • Zeile 16: die beiden Unterprojekte für Version 7 der Anwendung zur Steuerberechnung. Der Name [TaxV7:tax-dao-hibernate] bezeichnet den Ordner [TaxV7/tax-dao-hibernate];
  • Zeile 19: der Composite Build aus Kapitel 6, dessen Anwendung TaxV7 die Schichten [business] und [ui] wiederverwenden wird.

Das Wurzelprojekt deklariert zusammen mit ihren Versionen die Plugins, die von den Unterprojekten verwendet werden:

1
2
3
4
5
6
7
// Kapitel 11: Wurzelprojekt. Die Plugins werden hier (mit ihrer Version) deklariert und von den Unterprojekten angewendet
plugins {
    kotlin("jvm") version "2.4.20" apply false
    kotlin("plugin.jpa") version "2.4.20" apply false
    kotlin("plugin.allopen") version "2.4.20" apply false
    kotlin("plugin.spring") version "2.4.20" apply false
}
  • Zeile 3: das Kotlin-Plugin für die JVM;
  • Zeilen 4–5: die beiden Kotlin-Compiler-Plugins, die für die Entitäten erforderlich sind (weiter unten beschrieben);
  • Zeile 6: das für Spring konfigurierte „all-open“-Plugin (Kapitel 6), das vom Beispiel [injection] verwendet wird;
  • [apply false]: Die Plugins werden hier nur zusammen mit ihren Versionen deklariert; jedes Unterprojekt wendet die benötigten an, ohne die Version zu wiederholen.

Das erste Beispiel ist das Unterprojekt [first]. Es ist von den anderen unabhängig:

// ein erstes Beispiel: eine Entität, eine Datenbank, einige von Hibernate erzeugte SQL-Anweisungen
plugins {
    kotlin("jvm")
    // der parameterlose Konstruktor der Entitäten (Plugin "no-arg", für JPA konfiguriert)
    kotlin("plugin.jpa")
    // Entitäten und Eigenschaften werden open (nicht final) gemacht: Hibernate kann Proxys davon ableiten
    kotlin("plugin.allopen")
    application
}

repositories {
    mavenCentral()
}

dependencies {
    // Hibernate und der MySQL-JDBC-Treiber
    implementation("org.hibernate.orm:hibernate-core:7.4.5.Final")
    runtimeOnly("com.mysql:mysql-connector-j:9.7.0")
    // Logback: es empfängt das Hibernate-Log (nur zur Laufzeit)
    runtimeOnly("ch.qos.logback:logback-classic:1.5.38")
}

// die so annotierten Klassen werden vom Plugin [allopen] geöffnet
allOpen {
    annotation("jakarta.persistence.Entity")
    annotation("jakarta.persistence.MappedSuperclass")
    annotation("jakarta.persistence.Embeddable")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // das von [gradlew -q :first:run] ausgeführte Programm, gestartet im Ordner 11-hibernate
    mainClass = "first.MainKt"
}

// unter Windows wird die Bildschirmausgabe des von Gradle gestarteten Programms (run, bootRun ...) in UTF-8 kodiert,
// sonst werden Zeichen mit Akzenten in der IntelliJ-IDEA-Konsole oder im Terminal falsch dargestellt
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • Zeilen 3–8: die angewendeten Plugins: Kotlin, die beiden Entitäts-Plugins und [application] zum Ausführen des Programms;
  • Zeilen 17–20: Hibernate, der JDBC-Treiber für MySQL und Logback. Der Treiber und Logback werden nur zur Laufzeit verwendet ([runtimeOnly]): Der Programmcode referenziert keine ihrer Klassen;
  • Zeilen 24–27: die Konfiguration des Plugins [allopen] (weiter unten beschrieben);
  • Zeilen 31–34: die für den Kurs üblichen Kompilierungsoptionen (JDK 25, Warnungen werden als Fehler behandelt);
  • Zeile 40: die Hauptklasse des Unterprojekts. Eine Datei [Main.kt] aus dem [first]-Paket wird zu einer Klasse [first.MainKt] kompiliert (Kapitel 3);
  • Zeilen 43–46: Die von Gradle gestarteten Programme schreiben ihre Ausgabe in UTF-8, damit Zeichen mit Akzenten unter Windows korrekt angezeigt werden (Kapitel 2).

Um ein Beispiel auszuführen, wechseln Sie in den Ordner [11-hibernate] und geben die Aufgabe [run] des Unterprojekts über ihren Pfad an ([:first:run]); Gradle erstellt zuerst die Unterprojekte, von denen es abhängt (unter Linux und macOS geben Sie [./gradlew] ein):

> cd 11-hibernate
> gradlew -q :first:run

Das Programm wird im Ordner des Unterprojekts ausgeführt ([11-hibernate/first]). Verwendet wird die Datenbank [hbfirst] auf dem lokalen MySQL-Server, der der Laragon-Server ist (siehe Anhänge). Sie muss nicht existieren: MySQL legt sie an.

11.2.2. Die Entität [Article]

Eine Klasse, deren Objekte in einer Tabelle gespeichert werden, heißt Entität. Unsere erste Entität ist ein Artikel eines Geschäfts, wie in der Tabelle [articles] aus Kapitel 10:

package first

import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import java.math.BigDecimal

// ein Artikel des Shops: eine gewöhnliche Kotlin-Klasse, plus einige Annotationen
@Entity
class Article(
    // die Spalten der Tabelle, als Eigenschaften des Primärkonstruktors deklariert
    var name: String,
    var price: BigDecimal,
    var currentStock: Int,
    var minimumStock: Int,
) {
    // der vom DBMS erzeugte Primärschlüssel: null, solange der Artikel nicht gespeichert ist
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null

    // Anzeige
    override fun toString() = "[%d, %s, %.2f, %d, %d]".format(id, name, price, currentStock, minimumStock)
}
  • Zeile 10: Die Annotation [@Entity] (Paket [jakarta.persistence]) macht die Klasse zu einer Entität. Es handelt sich um eine gewöhnliche Kotlin-Klasse, die keine Hibernate-Klasse erweitert; man bezeichnet sie als POJO („Plain Old Java Object“);
  • Zeilen 13–16: die im primären Konstruktor deklarierten Eigenschaften (Kapitel 4). Es sind [var]: Hibernate muss ihre Werte ändern können, und die Anwendung ebenfalls (um einen Preis oder einen Lagerbestand zu ändern). Jede Eigenschaft wird zu einer Spalte mit demselben Namen;
  • Zeilen 19–21: Der Primärschlüssel wird durch die Annotation [@Id] gekennzeichnet. Es gibt keine Namenskonvention: Die Annotation ist erforderlich. [@GeneratedValue(strategy = GenerationType.IDENTITY)] gibt an, dass seine Werte vom DBMS generiert werden (die Spalte [AUTO_INCREMENT] von MySQL). Der Bezeichner ist kein Konstruktorparameter: Er wird vom DBMS geliefert. Sein Typ ist [Int?], und sein Anfangswert ist [null], was „noch nicht in der Datenbank gespeichert“ bedeutet. Der Typ [Int?] wird zu [java.lang.Integer] kompiliert und der Typ [Int] zu [int] (Kapitel 3);
  • Zeile 24: eine praktische Darstellung des Artikels. Das Format [%.2f] zeigt den Preis mit zwei Nachkommastellen an, entsprechend den jeweiligen kulturellen Konventionen (ein Komma in Frankreich, ein Punkt in der englischen Locale, die für die Ergebnisse verwendet wird).

Wohin gehören Annotationen? Im Bytecode entspricht eine Kotlin-Eigenschaft mehreren Java-Elementen: einem privaten Feld, einer Zugriffsmethode ([getX]), einer Änderungsmethode ([setX]) und im vorliegenden Fall einem Konstruktorparameter. Eine Annotation, die ohne weitere Angabe vor eine Eigenschaft gesetzt wird, platziert Kotlin 2.4 anhand der Ziele, die sie akzeptiert: auf dem Konstruktorparameter, wenn es sich um eine Konstruktoreigenschaft handelt und die Annotation dies zulässt, zusätzlich auf der Kotlin-Eigenschaft selbst, wenn die Annotation dies zulässt; andernfalls auf dem Feld. Die Annotationen von Jakarta Persistence ([@Id], [@Column] ...) gelten nicht für Kotlin-Parameter oder -Eigenschaften, sondern nur für Java-Felder und -Methoden: Sie werden daher auf dem Feld platziert. Genau das wollen wir: Da die Annotation [@Id] auf einem Feld sitzt, greift Hibernate direkt auf die Felder zu (es liest und schreibt sie per Reflection, auch wenn sie privat sind). Sie können dies mit dem Werkzeug [javap] des JDK überprüfen, das den Inhalt einer Datei [.class] anzeigt. Sie können das Ziel einer Annotation auch mit einem Präfix angeben: [@field:Column(length = 30)] platziert sie auf dem Feld, [@get:Transient] auf der Zugriffsmethode.

Jakarta Persistence verlangt zwei Dinge, die Kotlin-Klassen standardmäßig nicht bieten:

  • einen parameterlosen Konstruktor, den Hibernate verwendet, um aus der Datenbank gelesene Objekte zu erzeugen (anschließend füllt es deren Felder). Unsere Klasse hat nur einen Konstruktor mit vier Parametern. In Java fügt man manuell einen geschützten parameterlosen Konstruktor hinzu. In Kotlin übernimmt das das Compiler-Plugin [no-arg], konfiguriert für JPA ([kotlin("plugin.jpa")]), das ihn jeder Klasse hinzufügt, die mit [@Entity], [@Embeddable], oder [@MappedSuperclass] annotiert ist. Dieser Konstruktor existiert im Bytecode, wo Hibernate ihn per Reflection findet, ist aber im Kotlin-Code nicht sichtbar: [Article()] bleibt ein Kompilierungsfehler („[no value passed for parameter 'name'.]“). Beachten Sie, dass er keine Initialisierungen von Eigenschaften ausführt: Eine als [var x = "a"] deklarierte Eigenschaft hat in einem von Hibernate erzeugten Objekt den Wert [null] , solange Hibernate ihr keinen Wert zugewiesen hat (die Option [noArg { invokeInitializers = true }] in der Build-Datei ändert dieses Verhalten). Für in der Datenbank gespeicherte Eigenschaften ist das kein Problem, da Hibernate ihnen den gelesenen Wert zuweist;
  • nicht finale Klassen und Methoden. Um Lazy Loading zu implementieren (das wir bei den Beziehungen behandeln), erzeugt Hibernate zur Laufzeit Proxys: von den Entitäten abgeleitete Klassen, deren Methoden das Objekt beim ersten Aufruf aus der Datenbank laden. Damit das funktioniert, müssen die Klasse und ihre Methoden überschreibbar sein. In Java ist das die Voreinstellung; in Kotlin sind Klassen und ihre Member standardmäßig final (Kapitel 4). Das [all-open] ([kotlin("plugin.allopen")]) Plugin, das über den Block [allOpen] in der Build-Datei konfiguriert wird, macht Klassen, die eine der aufgeführten Annotationen tragen, sowie deren Eigenschaften und Methoden nicht final ([open]). Das [plugin.spring]-Plugin aus Kapitel 6 ist dasselbe Plugin, konfiguriert für Spring-Annotationen.

Mit diesen beiden Plugins wird die Entität als gewöhnliche Kotlin-Klasse geschrieben. Ohne sie müssten Sie [open class Article(...)] schreiben, für jede Eigenschaft [open] deklarieren und einen sekundären Konstruktor ohne Parameter hinzufügen: Das tun wir im folgenden Beispiel für eine Klasse ohne Annotationen.

Warum nicht eine Datenklasse ([data class], Kapitel 4) verwenden? Sie scheint ideal zu sein, um eine Tabellenzeile darzustellen. Für eine Entität ist das jedoch aus mehreren Gründen keine gute Idee:

  • Die generierten Methoden [equals] und [hashCode] vergleichen alle Eigenschaften des primären Konstruktors, die veränderbar sind. Der Hashcode einer Entität ändert sich daher, sobald ihr Preis geändert wird: Ein in einem [HashSet] gespeicherter Artikel oder ein Artikel, der als Schlüssel einer [HashMap] dient, ist nicht mehr auffindbar. Hibernate selbst speichert die Elemente von Beziehungssammlungen ([Set]) mithilfe dieser Methoden;
  • Zwei Objekte, die zwei verschiedene Zeilen (mit zwei verschiedenen Bezeichnern) darstellen, aber dieselben Werte haben, würden als gleich betrachtet, während ein aus der Datenbank gelesener und anschließend geänderter Artikel beim erneuten Lesen nicht mehr gleich sich selbst wäre;
  • die generierte Methode [toString] zeigt alle Eigenschaften an: Bei Beziehungen durchläuft sie die verknüpften Objekte, was dazu führen kann, dass diese aus der Datenbank geladen werden (unerwartete SQL-Abfragen), dass eine Ausnahme auftritt, wenn die Sitzung geschlossen ist, oder sogar dass eine Endlosrekursion zwischen zwei Entitäten entsteht, die aufeinander verweisen;
  • Die Methode [copy] erzeugt ein neues Objekt mit demselben Bezeichner, das der Sitzung unbekannt ist: Das führt zu zwei Objekten für dieselbe Zeile, was Verwechslungen nach sich ziehen kann;
  • Eine Datenklasse kann vom Programmierer nicht als offen ([open]) deklariert werden. Das Plugin [all-open] öffnet sie trotzdem, wodurch Proxys erzeugt werden können (das haben wir mit dem Werkzeug [javap] überprüft), behebt aber keines der vorherigen Probleme.

Eine Entität ist daher eine gewöhnliche Klasse: Ihre Identität ist die der Tabellenzeile, nicht der Wert ihrer Eigenschaften. Wie in Java behält sie die von [equals]/[hashCode] geerbten Implementierungen von [Any] (Objektidentität) bei, was in Ordnung ist, solange Sie keine Objekte aus verschiedenen Sitzungen mischen. Datenklassen bleiben mit Hibernate für Abfrageergebnisse, die keine Entitäten sind (Projektionen), sehr nützlich, wie wir sehen werden. Es ist dieselbe Regel wie in Java, wo eine Entität kein Record sein kann.

Eine letzte Bemerkung: Hibernate erkennt die nullbaren Typen von Kotlin nicht. Dass die Eigenschaft [name] den Typ [String] (nicht nullbar) hat, teilt Hibernate nicht mit, dass die Spalte erforderlich ist; das tut nur die Annotation [@Column(nullable = false)], wie wir bei den Ergebnissen sehen werden.

11.2.3. [SessionFactory] und [Session]

Das Programm verwendet drei Hibernate-Objekte:

  • Die [SessionFactory] repräsentiert Hibernate, konfiguriert für eine Datenbank: die Liste der Entitäten, die Datenbank und die Optionen. Ihre Erstellung ist ressourcenintensiv (Hibernate analysiert die Entitäten, verbindet sich mit dem Server, um dessen Version zu ermitteln, und bereitet das SQL für gängige Operationen vor): Pro Datenbank und Anwendung wird beim Start nur eine einzige erstellt. Sie ist threadsicher: Alle Threads der Anwendung können sie verwenden;
  • Die [Session] repräsentiert eine Arbeitssitzung mit der Datenbank. Sie bezieht bei Bedarf eine Verbindung, speichert die Entitäten, die sie gelesen oder gespeichert hat, und weiß, wie sie deren Änderungen in die Datenbank übernimmt. Sie ist ein leichtgewichtiges, kurzlebiges Objekt, das nicht threadsicher ist: Für jede Arbeitseinheit wird eine geöffnet und anschließend geschlossen;
  • [Transaction]: Mit Hibernate erfolgen alle Schreibvorgänge in die Datenbank innerhalb einer expliziten Transaktion, die durch [session.beginTransaction()] geöffnet und durch [commit] (Bestätigung) oder [rollback] (Zurückrollen) geschlossen wird.

[SessionFactory] und [Session] implementieren die Schnittstelle [AutoCloseable]: Sie werden mit der Kotlin-Funktion [use] verwendet (Kapitel 3), die sie am Ende des Blocks schließt, unabhängig davon, ob dieser normal oder mit einer Ausnahme endet (das Äquivalent der Anweisung [try] mit Ressourcen in Java).

11.2.4. Das Programm

package first

import org.hibernate.jpa.HibernatePersistenceConfiguration
import java.math.BigDecimal

fun main() {
    // die SessionFactory: Hibernate, für die Datenbank [hbfirst] konfiguriert
    HibernatePersistenceConfiguration("first")
        // die Entitäten
        .managedClass(Article::class.java)
        // die Datenbank; MySQL erstellt sie, falls sie nicht existiert
        .jdbcUrl("jdbc:mysql://localhost:3306/hbfirst?createDatabaseIfNotExist=true")
        .jdbcCredentials("root", "")
        // Anzeige der SQL-Anweisungen, formatiert, ohne Farben
        .showSql(true, true, false)
        .createEntityManagerFactory().use { sessionFactory ->

            // die Tabellen werden aus den Entitäten gelöscht und neu erstellt
            sessionFactory.schemaManager.drop(false)
            sessionFactory.schemaManager.create(false)

            // Hinzufügen von drei Artikeln, in einer Transaktion
            sessionFactory.openSession().use { session ->
                val transaction = session.beginTransaction()
                println("--- persist")
                session.persist(Article("bike", BigDecimal(500), 10, 5))
                session.persist(Article("pump", BigDecimal(10), 10, 2))
                session.persist(Article("bow", BigDecimal(600), 4, 1))
                println("--- commit")
                transaction.commit()
            }

            // Lesen der Tabelle, mit einer neuen Session
            println("--- reading the articles")
            sessionFactory.openSession().use { session ->
                val articles: List<Article> = session
                    .createSelectionQuery("from Article order by name", Article::class.java)
                    .resultList
                articles.forEach { println(it) }
            }
        }
}
  • Zeilen 8–16: Erstellung der [SessionFactory]. Hibernate lässt sich auf mehrere Arten konfigurieren (wir besprechen sie später); wir verwenden die Klasse [HibernatePersistenceConfiguration] aus Hibernate 7, eine erweiterte Version der mit Jakarta Persistence 3.2 eingeführten Klasse [PersistenceConfiguration], mit der sich alles per Code konfigurieren lässt. Ihr Parameter ist der Name der Persistenzeinheit – ein frei gewählter Name, der in Hibernate-Meldungen erscheint. Jede Methode gibt die Konfiguration selbst zurück, sodass sich Aufrufe verketten lassen;
  • Zeile 10: die Liste der Entitäten. [Article::class.java] ist das Java-Objekt [Class] (die Kotlin-Klasse [KClass] ist nicht geeignet: Hibernate ist eine Java-Bibliothek);
  • Zeilen 12–13: die JDBC-URL der Datenbank [hbfirst] im selben Format wie in Kapitel 10 und der Benutzer ([root], in Laragon ohne Passwort). Der Parameter [createDatabaseIfNotExist=true] der URL ist eine Option des MySQL-Treibers: Sie legt die Datenbank an, falls sie nicht existiert;
  • Zeile 15: [showSql(true, true, false)] weist Hibernate an, jeden ausgeführten SQL-Befehl auf der Konsole auszugeben, über mehrere Zeilen formatiert (zweiter Parameter) und ohne Farben (dritter Parameter). Das an den Server gesendete SQL zu betrachten, ist der beste Weg, um zu verstehen, was Hibernate tut: Das tun wir in allen Beispielen;
  • Zeile 16: [createEntityManagerFactory] erstellt die [SessionFactory] (der Methodenname folgt dem Standard; der zurückgegebene Typ ist der von Hibernate). Die Funktion [use] schließt sie am Ende des Programms; innerhalb des Blocks heißt sie [sessionFactory];
  • Zeilen 19–20: Das Objekt [SchemaManager] der [SessionFactory] (Jakarta Persistence 3.2) verwaltet die Tabellen der Entitäten: [drop(false)] löscht sie, falls sie existieren, während [create(false)] sie erstellt (der Parameter [false] legt fest, dass die Datenbank selbst weder gelöscht noch erstellt werden soll). Das ist praktisch für Beispiele und Tests; eine reale Anwendung verwaltet ihre Datenbank anders, wie wir sehen werden. Kotlin stellt die Java-Methode [getSchemaManager()] als Eigenschaft [schemaManager] dar (Kapitel 4);
  • Zeile 23: [openSession()] öffnet eine Sitzung, die am Ende des Blocks [use] geschlossen wird;
  • Zeile 24: der Beginn einer Transaktion;
  • Zeilen 26–28: [persist] fügt der Sitzung drei neue Artikel hinzu: Sie werden in der Datenbank gespeichert. Für den Bezeichner wird kein Wert angegeben; er wird vom DBMS generiert;
  • Zeile 30: [commit] bestätigt die Transaktion. Zuvor sendet die Sitzung die SQL-Befehle an den Server, die noch erforderlich sind, um die von ihr gespeicherten Änderungen zu sichern: Man spricht hier vom „Flushen“ der Sitzung in die Datenbank;
  • Zeilen 36–38: eine in HQL, der Abfragesprache von Hibernate, geschriebene Abfrage: die Artikel in alphabetischer Reihenfolge nach Namen. Sie bezieht sich auf die Entität [Article] und ihre Eigenschaft [name], nicht auf die Tabelle. Der zweite Parameter von [createSelectionQuery] ist der Ergebnistyp: Die Eigenschaft [resultList] (die Java-Methode [getResultList]) gibt eine [List<Article>] zurück;
  • Zeile 39: Anzeige der Artikel.

Würde zwischen [beginTransaction] und [commit] eine Ausnahme auftreten, würde die Transaktion von unserem Code weder bestätigt noch explizit zurückgerollt: Wir sehen später eine sicherere Art, eine Transaktion mithilfe einer Funktion höherer Ordnung zu schreiben.

Die Datei [src/main/resources/logback.xml] im Unterprojekt konfiguriert Logback. Sie zeigt die Hibernate-Meldungen der Stufe [INFO] oder höher an, eine pro Zeile (Stufe, Name des Logs, Meldung):

<?xml version="1.0" encoding="UTF-8"?>
<!-- Logback-Konfiguration: Hibernate-Informationsmeldungen, jeweils eine Zeile -->
<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%-5level %logger - %msg%n</pattern>
        </encoder>
    </appender>
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

Ergebnisse:

> gradlew -q :first:run
INFO  org.hibernate.orm.jpa - HHH008540: Processing PersistenceUnitInfo [name: first]
INFO  org.hibernate.orm.core - HHH000001: Hibernate ORM core version 7.4.5.Final
WARN  org.hibernate.orm.connections.pooling - HHH10001002: Using built-in connection pool (not intended for production use)
INFO  org.hibernate.orm.connections.pooling - HHH10001005: Database info:
    Database JDBC URL [jdbc:mysql://localhost:3306/hbfirst?createDatabaseIfNotExist=true]
    Database driver: MySQL Connector/J
    Database dialect: MySQLDialect
    Database version: 8.0.46
    Default catalog/schema: hbfirst/undefined
    Autocommit mode: false
    Isolation level: REPEATABLE_READ
    JDBC fetch size: none
    Pool: DriverManagerConnectionProvider
    Minimum pool size: 1
    Maximum pool size: 20
INFO  org.hibernate.orm.core - HHH000489: No JTA platform available (set 'hibernate.transaction.jta.platform' to enable JTA platform integration)
Hibernate:
    drop table if exists Article
Hibernate:
    create table Article (
        id integer not null auto_increment,
        currentStock integer not null,
        minimumStock integer not null,
        name varchar(255),
        price decimal(38,2),
        primary key (id)
    ) engine=InnoDB
--- persist
Hibernate:
    insert
    into
        Article
        (currentStock, minimumStock, name, price)
    values
        (?, ?, ?, ?)
Hibernate:
    insert
    into
        Article
        (currentStock, minimumStock, name, price)
    values
        (?, ?, ?, ?)
Hibernate:
    insert
    into
        Article
        (currentStock, minimumStock, name, price)
    values
        (?, ?, ?, ?)
--- commit
--- reading the articles
Hibernate:
    select
        a1_0.id,
        a1_0.currentStock,
        a1_0.minimumStock,
        a1_0.name,
        a1_0.price
    from
        Article a1_0
    order by
        a1_0.name
[1, bike, 500.00, 10, 5]
[3, bow, 600.00, 4, 1]
[2, pump, 10.00, 10, 2]

Kommentare:

  • Zeilen 2–17: Informationsmeldungen von Hibernate: der Name der Persistenzeinheit, die Hibernate-Version und die Merkmale der Datenbank (URL, Treiber, gewählter Dialekt, Serverversion, Transaktionsisolationsstufe, Größe des Verbindungspools). Hibernate hat den Server abgefragt, um den zu dessen Version passenden Dialekt [MySQLDialect] auszuwählen;
  • Zeile 4: eine Warnung. Hibernate verwaltet einen eigenen kleinen Verbindungspool, der nicht für eine Produktionsanwendung gedacht ist. Wir werden mit Spring sehen, wie man ihm den HikariCP-Pool aus Kapitel 10 zur Verfügung stellt; für unsere Beispiele genügt der integrierte Pool;
  • Zeilen 18–28: Löschen und anschließendes Erstellen der Tabelle [Article] auf Grundlage der Entität: Der Tabellenname entspricht dem Namen der Entität, die Spalten tragen die Namen der Eigenschaften, und die Spalte [id] ist der Primärschlüssel mit generiertem Wert ([auto_increment]). Die Spalten für Eigenschaften vom Typ [Int] sind [not null]: Sie werden zu [int] kompiliert; ein [Int] kann nicht [null] sein. Eigenschaften vom Typ [String] und [BigDecimal] akzeptieren den Wert [NULL], obwohl diese Typen in Kotlin nicht nullbar sind: Für Hibernate sind es Java-Referenzen ([java.lang.String], [java.math.BigDecimal]), die auf [null] gesetzt werden können;
  • Beachten Sie die Standardtypen: [varchar(255)] für eine Zeichenkette und [decimal(38,2)] für einen [BigDecimal] (38 Ziffern, davon 2 Nachkommastellen). Sie sind selten die gewünschten: Der folgende Abschnitt zeigt, wie man sie festlegt;
  • Zeilen 29–51: Die drei konfigurierten [INSERT]-Befehle wurden ausgeführt, sobald [persist] aufgerufen wurde, vor [commit]. Das ist eine Folge davon, dass der Schlüssel vom DBMS generiert wird ([IDENTITY]): Die Sitzung muss den Bezeichner einer Entität kennen, sobald sie diese übernimmt, und um ihn zu erhalten, muss sie das Einfügen ausführen (der JDBC-Treiber gibt den generierten Schlüssel zurück; siehe Kapitel 10). Bei anderen Generierungsmethoden werden die Einfügungen zurückgestellt, bis die Sitzung synchronisiert wird. Die Werte der Parameter ([?]) werden nicht angezeigt: Wir werden sehen, wie man sie sichtbar macht;
  • Zeilen 53–63: Die HQL-Abfrage [from Article order by name] wurde in eine Anweisung [SELECT ... ORDER BY] übersetzt. Hibernate hat der Tabelle den Alias [a1_0] zugewiesen und für jede gelesene Zeile ein Objekt [Article] erzeugt (Zeilen 64–66), und zwar mit dem parameterlosen Konstruktor, den das Plugin [no-arg] hinzugefügt hat.

Wir haben weder SQL-Anweisungen noch Code zum Lesen von Spalten geschrieben: Genau darin liegt der Sinn eines ORM. Wir sehen aber auch, dass dies das Verständnis von SQL nicht überflüssig macht: Um zu beurteilen, ob das generierte SQL korrekt und effizient ist, muss man es lesen können.

11.3. Das Modell

Hibernate baut sein Modell aus den Entitäten in drei Schritten auf:

  • Zunächst wendet es seine Standardregeln an: Alles, was nicht angegeben ist, erhält einen vernünftigen Wert (man spricht von „Konfiguration durch Ausnahme“);
  • anschließend ergänzt oder korrigiert es diese Werte mithilfe der Annotationen, die an den Entitäten angebracht sind;
  • schließlich wendet es die XML-Mapping-Dateien ([orm.xml]) an, die eine Klasse ohne Annotationen vollständig beschreiben oder das ändern können, was ihre Annotationen festlegen.

11.3.1. Standardregeln

Das Wesentliche davon haben wir im ersten Beispiel gesehen:

  • Eine Entität trägt die Annotation [@Entity] und hat einen durch [@Id] gekennzeichneten Bezeichner; beide Annotationen sind erforderlich;
  • Die Platzierung der Annotation [@Id] bestimmt den Zugriffsmodus: Steht sie auf einem Feld, liest und schreibt Hibernate die Felder direkt; steht sie auf einem Getter oder Setter ([getId]), erfolgt der Zugriff über die Getter und Setter ([getX]/[setX]). Der Zugriff über Felder ist der häufigste: Er erlaubt der Klasse, beliebige Methoden zu haben. In Kotlin wird eine vor eine Eigenschaft gesetzte Annotation auf das Feld angewendet (wie wir gesehen haben): Das ergibt den Feldzugriff ohne ausdrückliche Angabe. Für den Zugriff über Getter und Setter müssten Sie [@get:Id] schreiben;
  • Jede Eigenschaft mit einem Backing-Field wird in einer Spalte gespeichert, es sei denn, sie trägt die Jakarta-Persistence-Annotation [@Transient] oder die Annotation [@kotlin.jvm.Transient] (die dem Feld den Java-Modifizierer [transient] hinzufügt); eine berechnete Eigenschaft, deren benutzerdefinierte Zugriffsmethode [field] nicht verwendet (Kapitel 4), hat kein Feld: Sie wird nie gespeichert;
  • Der Tabellenname ist der Name der Entität (der einfache Klassenname), und der Spaltenname ist der Name der Eigenschaft. Diese Namen durchlaufen dann eine Namensstrategie: Die Strategie von Hibernate behält die Namen unverändert bei, während eine andere Strategie – die wir weiter unten ausprobieren – sie in „Snake Case“ umwandelt ([currentStock] wird zu [current_stock]). Spring Boot verwendet standardmäßig Letztere;
  • Eine Spalte eines Typs, der zu einem primitiven Typ kompiliert wird (nicht nullbare [Int], [Double], [Boolean]), wird zu [NOT NULL]; eine Spalte eines Typs, der zu einer Referenz kompiliert wird ([Int?], [String], [BigDecimal], [LocalDate], unabhängig davon, ob sie für Kotlin nullbar sind oder nicht), akzeptiert den Wert [NULL]. Um die Spalte einer Eigenschaft vom Typ [String] zur Pflichtspalte zu machen, müssen Sie daher die Annotation [@Column(nullable = false)] verwenden, auch wenn der Kotlin-Typ den Wert [null] bereits verbietet;
  • Die SQL-Typen werden anhand des Dialekts ausgewählt. Mit MySQL: [integer] für [Int], [bigint] für [Long], [bit] für [Boolean], [varchar(255)] für [String], [decimal(38,2)] für [BigDecimal], [date] für [LocalDate], [datetime(6)] (mikrosekundengenau) für [LocalDateTime]. Eine Aufzählung ([enum class]) wird standardmäßig über ihre Ordnungszahl gespeichert (siehe Kapitel 3); die Annotation [@Enumerated(EnumType.STRING)] speichert sie über ihren Namen, was zuverlässiger ist;
  • Eine Eigenschaft, die auf eine andere Entität oder auf eine Sammlung von Entitäten verweist, definiert eine Beziehung (dazu kommen wir später).

11.3.2. Die Annotationen und die XML-Mapping-Datei

Das Unterprojekt [model] definiert zwei Entitäten, die auf zwei verschiedene Arten konfiguriert sind. Seine Build-Datei entspricht der von [first], wobei die Abhängigkeit von Logback durch eine Abhängigkeit von der weiter unten beschriebenen Bibliothek [tools] ersetzt ist (die Logback und dessen Konfiguration bereitstellt). Die erste Entität wird mithilfe von Annotationen konfiguriert:

package model

import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.Table
import jakarta.persistence.Transient
import java.math.BigDecimal
import java.time.LocalDate

// eine durch Annotationen konfigurierte Entität
@Entity
@Table(name = "products")
class Product(
    // erforderlicher String von höchstens 50 Zeichen
    @Column(nullable = false, length = 50)
    var name: String,

    // Name und SQL-Typ der Spalte vorgegeben
    @Column(name = "price_excl_tax", nullable = false, precision = 10, scale = 2)
    var priceExclTax: BigDecimal,

    // optionaler String (NULL-Spalte) von höchstens 200 Zeichen
    @Column(length = 200)
    var description: String? = null,

    // ein optionales Datum: ein nullable Typ
    var withdrawalDate: LocalDate? = null,
) {
    // der Primärschlüssel: @Id, unabhängig von seinem Namen
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var code: Int? = null

    // eine Eigenschaft ohne Spalte
    @Transient
    var selected = false

    // eine berechnete Eigenschaft hat kein Feld: sie wird nie gespeichert
    val priceInclTax: BigDecimal
        get() = priceExclTax * BigDecimal("1.2")
}
  • Zeilen 3–9: die Annotationen von Jakarta Persistence. Der explizite Import von [jakarta.persistence.Transient] hat Vorrang vor der Annotation [kotlin.jvm.Transient], die denselben Namen trägt und die Kotlin standardmäßig importiert;
  • Zeile 15: [@Table] legt den Tabellennamen fest;
  • Zeilen 18–19: [@Column] legt die Spalte fest; [nullable = false] macht sie zur Pflichtspalte ([NOT NULL]); [length = 50] legt ihre Länge fest ([varchar(50)]);
  • Zeilen 22–23: [@Column] legt außerdem den Spaltennamen ([price_excl_tax]) und bei einer Dezimalzahl ihre Genauigkeit (die Gesamtzahl der Ziffern) sowie ihre Skalierung (die Anzahl der Ziffern nach dem Dezimalpunkt) fest: [decimal(10,2)];
  • Zeilen 26–27: eine optionale Beschreibung von höchstens 200 Zeichen: Die Spalte akzeptiert den Wert [NULL]. Die Eigenschaft hat den Typ [String?] mit dem Standardwert [null]: Der Kotlin-Typ entspricht der Spalte. Es ist empfehlenswert, den nullbaren oder nicht nullbaren Typ der Eigenschaft an den optionalen oder obligatorischen Charakter der Spalte anzupassen, auch wenn Hibernate nur die Annotation liest;
  • Zeile 30: ein optionales Datum. Der Typ [LocalDate] (Kapitel 5) stellt ein Datum ohne Uhrzeit dar: Er wird dem SQL-Typ [date] zugeordnet;
  • Zeilen 32–35: der Primärschlüssel, durch [@Id] gekennzeichnet, unabhängig von seinem Namen;
  • Zeilen 38–39: [@Transient] schließt eine Eigenschaft vom Modell aus: im vorliegenden Fall eine für die Benutzeroberfläche nützliche Information, die nicht in die Datenbank gehört;
  • Zeilen 42–43: eine berechnete Eigenschaft. Ihre Zugriffsmethode verwendet kein Feld: Es gibt nichts zu speichern, und Hibernate, das auf die Felder zugreift, ignoriert sie. Der Operator [*] zwischen zwei [BigDecimal] ist die Funktion [times] , die die Kotlin-Standardbibliothek zu [BigDecimal] hinzufügt (Kapitel 4, Operatorüberladung): Wir schreiben [priceExclTax * BigDecimal("1.2")] statt des Java-Ausdrucks [priceExclTax.multiply(new BigDecimal("1.2"))].

Die zweite Entität hat keine Annotationen:

package model

import java.time.LocalDateTime

// eine Klasse ohne jede Annotation: ihr Mapping wird in der Datei [supplier.orm.xml] beschrieben
// die Plugins [jpa] und [allopen] sehen sie nicht: sie wird als [open] deklariert
// und hat ihren eigenen parameterlosen Konstruktor
open class Supplier(
    private var companyName: String,
    private var phone: String?,
) {
    private var number: Int? = null
    private var creationDate: LocalDateTime? = null

    // der von Hibernate benötigte parameterlose Konstruktor
    protected constructor() : this("", null)
}
  • Zeile 8: Da die Klasse nicht mit [@Entity] annotiert ist, erkennen die Plugins [no-arg] und [all-open] sie nicht. Wir deklarieren sie daher selbst als [open], damit Hibernate Proxys von ihr ableiten kann;
  • Zeilen 9–13: private Eigenschaften: Kotlin generiert dafür weder Zugriffs- noch Änderungsmethoden, sondern nur ein privates Feld, das Hibernate lesen und beschreiben wird. Das ist das exakte Äquivalent privater Felder in einer Java-Klasse;
  • Zeile 16: der von Hibernate verlangte parameterlose Konstruktor, von Hand geschrieben: ein sekundärer Konstruktor, der den primären Konstruktor (Kapitel 4) mit beliebigen Werten aufruft, die Hibernate durch die aus der Datenbank gelesenen ersetzt. Er ist geschützt: Der Anwendungscode verwendet ihn nicht.

Ihre Zuordnung zur Tabelle wird durch eine XML-Datei beschrieben, die sich im Ordner [src/main/resources/META-INF] des Unterprojekts befindet (es ist dieselbe Datei wie in Java):

<?xml version="1.0" encoding="UTF-8"?>
<!-- das Mapping der Klasse [Supplier] auf ihre Tabelle, in XML beschrieben (Jakarta Persistence 3.2) -->
<entity-mappings xmlns="https://jakarta.ee/xml/ns/persistence/orm"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence/orm
                                     https://jakarta.ee/xml/ns/persistence/orm/orm_3_2.xsd"
                 version="3.2">
    <entity class="model.Supplier" access="FIELD">
        <table name="suppliers">
            <!-- ein eindeutiger Index: zwei Lieferanten können nicht denselben Firmennamen haben -->
            <index name="ix_suppliers_company_name" column-list="companyName" unique="true"/>
        </table>
        <attributes>
            <id name="number">
                <generated-value strategy="IDENTITY"/>
            </id>
            <basic name="companyName">
                <column nullable="false" length="60"/>
            </basic>
            <basic name="phone">
                <column name="tel" length="20"/>
            </basic>
            <!-- ein vom DBMS berechneter Standardwert: Hibernate schreibt diese Spalte nie -->
            <basic name="creationDate">
                <column nullable="false" insertable="false" updatable="false"
                        column-definition="datetime(6) default current_timestamp(6)"/>
            </basic>
        </attributes>
    </entity>
</entity-mappings>
  • Zeilen 3–7: das XML-Schema für die Mapping-Dateien von Jakarta Persistence 3.2;
  • Zeile 8: die beschriebene Klasse, mit Zugriff über Felder;
  • Zeilen 9–12: die Tabelle und ein eindeutiger Index auf dem Firmennamen: Zwei Lieferanten können nicht denselben haben. Die entsprechende Annotation lautet [@Table(name = "suppliers", indexes = [Index(...)])] (in Kotlin wird ein als Annotationsargument übergebenes Array in eckigen Klammern geschrieben);
  • Zeilen 14–16: der vom DBMS generierte Bezeichner;
  • Zeilen 17–18: eine Pflichtspalte mit höchstens 60 Zeichen;
  • Zeilen 20–21: Die Eigenschaft [phone] wird in der Spalte [tel] gespeichert;
  • Zeilen 24–26: Das Erstellungsdatum hat einen vom DBMS berechneten Standardwert. Das Attribut [column-definition] liefert den SQL-Text der Spaltendefinition, der unverändert in den Befehl [CREATE TABLE] übernommen wird; [insertable="false"] und [updatable="false"] geben an, dass Hibernate diese Spalte niemals beschreiben darf, sodass das DBMS [current_timestamp(6)] verwenden kann.

Alles, was Annotationen leisten, lässt sich auch in XML ausdrücken. Annotationen haben den Vorteil, die Konfiguration neben der Eigenschaft zu platzieren, und sind der gängigste Ansatz; die XML-Datei hingegen hält die Klassen unabhängig von Jakarta Persistence und bündelt die Konfiguration an einer einzigen Stelle. Beide Ansätze lassen sich kombinieren: Bei einem Konflikt hat die XML-Datei Vorrang. Jakarta Persistence unterstützt die Konfiguration des Modells per Code nicht, wie es andere ORM-Frameworks tun (zum Beispiel Entity Framework in C# oder Exposed in Kotlin).

Das Programm zeigt das von Hibernate aufgebaute Modell an, gefolgt vom SQL-Skript, das die Tabellen erstellen würde:

package model

import jakarta.persistence.metamodel.SingularAttribute
import org.hibernate.boot.model.naming.PhysicalNamingStrategySnakeCaseImpl
import org.hibernate.cfg.AvailableSettings
import org.hibernate.jpa.HibernatePersistenceConfiguration
import java.io.StringWriter

fun main() {
    // das Skript zur Tabellenerstellung wird in dieses Objekt geschrieben
    val script = StringWriter()
    // eine SessionFactory, die sich nie mit dem Server verbindet
    HibernatePersistenceConfiguration("model")
        // eine annotierte Entität und ein in XML beschriebenes Mapping
        .managedClass(Product::class.java)
        .mappingFile("META-INF/supplier.orm.xml")
        // keine Datenbank: das DBMS und seine Version werden für den SQL-Dialekt angegeben
        .property(AvailableSettings.JAKARTA_HBM2DDL_DB_NAME, "MySQL")
        .property(AvailableSettings.JAKARTA_HBM2DDL_DB_MAJOR_VERSION, "8")
        .property(AvailableSettings.ALLOW_METADATA_ON_BOOT, false)
        // die Spaltennamen in "Snake Case": companyName -> company_name
        .property(AvailableSettings.PHYSICAL_NAMING_STRATEGY,
            PhysicalNamingStrategySnakeCaseImpl::class.java.name)
        // das Skript zur Tabellenerstellung, ohne es auszuführen
        .property(AvailableSettings.JAKARTA_HBM2DDL_SCRIPTS_ACTION, "create")
        .property(AvailableSettings.JAKARTA_HBM2DDL_SCRIPTS_CREATE_TARGET, script)
        .property(AvailableSettings.HBM2DDL_DELIMITER, ";")
        .property(AvailableSettings.FORMAT_SQL, true)
        .createEntityManagerFactory().use { sessionFactory ->

            // das von Hibernate erstellte Modell: Entitäten und Attribute (Jakarta Persistence API)
            for (entity in sessionFactory.metamodel.entities) {
                println("entity ${entity.name} (${entity.javaType.name})")
                for (attribute in entity.attributes) {
                    val id = attribute is SingularAttribute<*, *> && attribute.isId
                    println("  %-14s %s%s".format(attribute.name, attribute.javaType.simpleName,
                        if (id) " (identifier)" else ""))
                }
            }
        }
    // das Skript zur Tabellenerstellung, ohne die Einrückung von 4 Leerzeichen seiner Zeilen
    println("--- creation script")
    script.toString().trim().lines()
        .map { it.removePrefix("    ") }
        .forEach { println(it.trimEnd()) }
}
  • Zeile 11: ein [StringWriter] (Paket [java.io]), ein Schreibstrom in eine Zeichenkette im Speicher, nimmt das SQL-Skript auf;
  • Zeilen 15–16: Die annotierte Entität wird durch [managedClass] deklariert und die XML-Datei durch [mappingFile];
  • Zeilen 18–20: Die Datenbank wird nie existieren: Diese [SessionFactory] dient ausschließlich dazu, das Modell zu untersuchen. Daher gibt es keine JDBC-URL. Um den SQL-Dialekt auszuwählen, ohne den Server abzufragen, benötigt Hibernate den Namen des DBMS und seine Version; die Eigenschaft [ALLOW_METADATA_ON_BOOT] ([hibernate.boot.allow_jdbc_metadata_access]) verhindert, dass es sich beim Start verbindet. Die Namen der Konfigurationseigenschaften sind Konstanten der Schnittstelle [AvailableSettings];
  • Zeile 22: die Namenskonvention „Snake Case“, bezeichnet durch den Namen ihrer Klasse ([::class.java.name]);
  • Zeilen 25–28: Hibernate schreibt das Skript zur Tabellenerstellung (["create"]) in das Objekt [script], ohne es auszuführen; die Befehle werden durch ein Semikolon abgeschlossen und über mehrere Zeilen formatiert;
  • Zeile 32: Die Eigenschaft [metamodel] (die Methode [getMetamodel] aus Jakarta Persistence) ermöglicht den Zugriff auf das Modell: seine Entitäten ([EntityType]) und für jede von ihnen ihre Attribute ([Attribute]);
  • Zeilen 33–37: Für jede Entität werden ihr Name und ihre Klasse angezeigt, für jedes Attribut sein Name, sein Java-Typ und ob es der Bezeichner ist. In Zeile 35 folgt auf den Test [attribute is SingularAttribute<*, *>] eine intelligente Typumwandlung (Kapitel 4): Im weiteren Verlauf des Ausdrucks [&&] ist [attribute] ein [SingularAttribute], von dem die Eigenschaft [isId] gelesen werden kann. Die Projektion [<*, *>] ersetzt das [<?, ?>] von Java;
  • Zeilen 42–45: das Skript, wie es angezeigt wird, ohne die vier Leerzeichen, die Hibernate seinen Zeilen hinzufügt ([removePrefix] entfernt das Präfix nur, wenn es vorhanden ist).

Ergebnisse:

> gradlew -q :model:run
WARN  connection - HHH102003: No appropriate connection provider encountered; client must supply connections
entity Product (model.Product)
  code           Integer (identifier)
  description    String
  name           String
  priceExclTax   BigDecimal
  withdrawalDate LocalDate
entity Supplier (model.Supplier)
  number         Integer (identifier)
  companyName    String
  creationDate   LocalDateTime
  phone          String
--- creation script
create table products (
    code integer not null auto_increment,
    price_excl_tax decimal(10,2) not null,
    withdrawal_date date,
    name varchar(50) not null,
    description varchar(200),
    primary key (code)
) engine=InnoDB;

create table suppliers (
    number integer not null auto_increment,
    creation_date datetime(6) default current_timestamp(6) not null,
    tel varchar(20),
    company_name varchar(60) not null,
    primary key (number)
) engine=InnoDB;

alter table suppliers
   add constraint ix_suppliers_company_name unique (company_name);
  • Zeile 2: Die Hibernate-Warnung bestätigt, dass es keine Möglichkeit hat, eine Verbindung herzustellen;
  • Zeilen 3–13: die beiden Entitäten und ihre Attribute (zuerst der Bezeichner, dann die übrigen in alphabetischer Reihenfolge; die Reihenfolge der Entitäten ist nicht von Bedeutung). Die Eigenschaft [selected] und die berechnete Eigenschaft [priceInclTax] erscheinen nicht im Modell. Die Typen sind die Java-Typen: [Integer] für [Int?];
  • Zeilen 15–21: die Tabelle [suppliers], beschrieben durch die XML-Datei. Die Namensstrategie hat [companyName] und [creationDate] in [company_name] und [creation_date] geändert; die Spalte [tel], deren Name festgelegt ist, bleibt unverändert. Die Definition der Spalte [creation_date] stammt aus der XML-Datei, ergänzt um [not null];
  • Zeilen 23–30: die Tabelle [products]. Die SQL-Typen stammen aus Annotationen ([varchar(50)], [decimal(10,2)]) oder aus dialektspezifischen Entscheidungen für einen Typ ([integer], [date]);
  • Zeilen 32–33: der eindeutige Index, der unter MySQL durch eine Eindeutigkeitsbedingung ([unique]) erstellt wird.

11.3.3. Generierte Bezeichner

Die Annotation [@GeneratedValue] gibt an, dass der Wert des Bezeichners generiert wird. Ihr Parameter [strategy] legt fest, wie:

Strategie
Generierung des Bezeichners
[IDENTITY]
durch das DBMS beim Einfügen der Zeile (Spalte [AUTO_INCREMENT] bei MySQL, [IDENTITY] bei SQL Server und PostgreSQL)
[SEQUENCE]
durch eine Sequenz des DBMS (PostgreSQL, Oracle), die Hibernate vor dem Einfügen abfragt
[TABLE]
durch eine von Hibernate verwaltete Zählertabelle
[UUID]
durch Hibernate: ein zufälliger universeller Bezeichner, etwa [java.util.UUID]
[AUTO] (Standard)
Hibernate entscheidet; bei MySQL, das keine Sequenzen kennt, simuliert es sie mithilfe einer Tabelle namens [<table>_SEQ]

Mit MySQL verwenden wir stets [IDENTITY], was dem natürlichen Verhalten der Spalte [AUTO_INCREMENT] entspricht. Das Ergebnis haben wir gesehen: Der Befehl [INSERT] wird ausgeführt, sobald [persist] aufgerufen wird, und Hibernate kann mehrere Einfügungen nicht zu einem Batch zusammenfassen (Batches besprechen wir später). Die Strategie [SEQUENCE], die es erlaubt, den Bezeichner vor dem Einfügen zu kennen, ist für DBMS vorzuziehen, die Sequenzen verwenden.

In Kotlin sollte der generierte Bezeichner vorzugsweise als [var id: Int? = null] deklariert werden: Der Wert [null] bedeutet eindeutig „noch nicht gespeichert“. Man begegnet auch [var id: Int = 0], wo der Wert 0 diesen Zweck erfüllt; Hibernate akzeptiert das (bei einem Bezeichner eines primitiven Typs behandelt es 0 als Wert „noch nicht gespeichert“), aber diese Konvention ist weniger gut lesbar.

11.3.4. Optionale Werte und Spalten [NULL]

Ob eine Spalte optional ist, wird also durch den Typ der Eigenschaft (kompiliert als primitiver Typ oder als Referenz) und durch das Attribut [nullable] von [@Column] bestimmt; in Kotlin gibt der Typ der Eigenschaft außerdem an, ob der Wert fehlen darf ([String?]) oder nicht ([String]). Sie müssen sorgfältig wählen und darauf achten, dass beides übereinstimmt: Die Regel drückt sowohl eine Code-Bedingung („dieser Wert darf fehlen“) als auch eine Datenbankbedingung aus. Einige Anmerkungen:

  • [@Column(nullable = false)] steht für die Bedingung [NOT NULL] im von Hibernate erstellten Schema, und Hibernate verwendet sie auch, bevor es einen Befehl [INSERT] oder [UPDATE] sendet: Ist das Feld [null], sendet es den Befehl nicht und löst einen [PropertyValueException] -Fehler aus („not-null property references a null or transient value“). Diese Hibernate-Prüfung ist standardmäßig deaktiviert, wenn Jakarta Validation (siehe unten) vorhanden ist: Die Validierung greift dann auf ihre Annotationen zurück oder, wenn es solche nicht gibt, auf das DBMS, das den Befehl ablehnt. In Kotlin kommt dieses Szenario seltener vor als in Java: Der Compiler verbietet es, [null] einer Eigenschaft vom Typ [String] zuzuweisen;
  • Für eine umfassendere Validierung vor jedem Datenbankzugriff verwenden wir Jakarta Validation (Bibliothek [hibernate-validator]) und ihre Annotationen [@NotNull], [@Size(max = 30)], [@Positive] ... Sind sie im Klassenpfad vorhanden, validiert Hibernate die Entitäten vor dem Speichern und verwendet diese Annotationen, um die Spalten zu erstellen. In Kotlin akzeptieren diese Annotationen auch Parameter als Ziele: Bei Anwendung auf eine Konstruktoreigenschaft wendet Kotlin 2.4 sie sowohl auf den Parameter als auch auf das Feld an, das der Validator liest. Frühere Versionen platzierten sie nur auf dem Parameter: Man musste das Feld als Ziel angeben, [@field:Size(max = 30)], eine Form, der man in vielen Beispielen noch begegnet;
  • Es ist nicht nötig, [Optional] zu verwenden (Kapitel 4): Der nullbare Typ von Kotlin ([var description: String? = null]) zeigt direkt an, dass ein Wert optional ist, und er wird mit den Operatoren [?.] und [?:] gelesen (Kapitel 3): [product.description ?: "(no description)"].

11.4. Die folgenden Beispiele: zwei gängige Bibliotheken

Die Beispiele der folgenden Abschnitte verwenden fast alle die Datenbank [hbarticles] und ihre Tabelle [articles], die mit den sechs Einträgen aus Kapitel 10 gefüllt ist. Statt die Hibernate-Entität und die Konfiguration in jedem Unterprojekt zu wiederholen, legen wir sie in eine Bibliothek – das Unterprojekt [articles] –, von der die anderen Unterprojekte abhängen. Außerdem ersetzen wir das SQL-Log von [showSql], das für unsere Beispiele zu ausführlich ist, durch ein kompakteres Log, das in einer zweiten Bibliothek liegt, dem Unterprojekt [tools].

11.4.1. Das kompakte SQL-Log

Statt direkt auf die Konsole zu schreiben ([showSql]), kann Hibernate seine Aktivität an das Logging-System (hier Logback) weiterleiten, wobei jede Meldungskategorie in ein eigenes Log geschrieben wird:

Log
Stufe
Meldungen
[org.hibernate.SQL]
[DEBUG]
ausgeführte SQL-Befehle
[org.hibernate.orm.jdbc.bind]
[TRACE]
der Wert jedes Parameters eines SQL-Befehls
[org.hibernate.orm.resource.jdbc]
[TRACE]
unter anderem der Beginn, die Bestätigung und der Abbruch von Transaktionen
[org.hibernate.orm.jdbc.batch]
[TRACE]
Ausführung von Batches von SQL-Befehlen
[org.hibernate.orm.jdbc.error]
[WARN]
vom DBMS gemeldete Fehler

Ein Log zeichnet nur Meldungen auf, deren Stufe gleich oder höher als seine eigene ist. Sie müssen daher in der Datei [logback.xml] lediglich die gewünschte Stufe für diese Logs festlegen, um diese Meldungen zu erfassen. Wir verarbeiten sie mit einer Layout-Klasse, die sie kompakter macht:

package tools

import ch.qos.logback.classic.Level
import ch.qos.logback.classic.Logger
import ch.qos.logback.classic.spi.ILoggingEvent
import ch.qos.logback.core.LayoutBase
import org.slf4j.LoggerFactory

// ein kompaktes Log der von Hibernate ausgeführten SQL-Anweisungen: ein Logback-Layout
class SqlLog : LayoutBase<ILoggingEvent>() {

    // Layout einer Meldung: der zu schreibende Text wird zurückgegeben ("": es wird nichts geschrieben)
    override fun doLayout(event: ILoggingEvent): String {
        val message = event.formattedMessage
        return when (event.loggerName) {
            SQL -> sqlStatement(message)
            PARAMETERS -> parameter(message)
            TRANSACTIONS -> transaction(message)
            ERRORS -> dbError(message)
            BATCHES -> batch(message)
            else -> ""
        }
    }

    companion object {
        // die verwendeten Hibernate-Logger
        const val SQL = "org.hibernate.SQL"
        const val PARAMETERS = "org.hibernate.orm.jdbc.bind"
        const val TRANSACTIONS = "org.hibernate.orm.resource.jdbc"
        const val ERRORS = "org.hibernate.orm.jdbc.error"
        const val BATCHES = "org.hibernate.orm.jdbc.batch"

        // die maximale Länge einer in einer einzigen Zeile geschriebenen Klausel
        private const val WIDTH = 100

        // die Ausführung eines Batches von SQL-Anweisungen: "Executing JDBC batch (3 / 3) - [...]"
        private val BATCH = Regex("""Executing JDBC batch \((\d+) / \d+\).*""")

        // ein an eine SQL-Anweisung gebundener Parameter: "binding parameter (1:VARCHAR) <- [bike]"
        private val PARAMETER = Regex("""binding parameter \((\d+):\w+\) <- \[(.*)]""")

        // die von Hibernate formatierte SQL-Anweisung, kompakter gemacht: eine Zeile pro Klausel (select, from...)
        private fun sqlStatement(sql: String): String {
            // die nicht leeren Zeilen, ohne die nachgestellten Leerzeichen
            val lines = sql.lines().map { it.trimEnd() }.filter { it.isNotBlank() }
            // die Klauseln: eine Zeile der obersten Ebene (die am wenigsten eingerückte) und die ihr folgenden Zeilen
            val indentation = lines.minOfOrNull { indentation(it) } ?: 0
            val clauses = mutableListOf<MutableList<String>>()
            for (line in lines) {
                if (clauses.isEmpty() || indentation(line) == indentation) clauses.add(mutableListOf())
                clauses.last().add(line.substring(indentation))
            }
            // jede Klausel wird in einer Zeile geschrieben, wenn sie nicht zu lang ist
            var start = ""
            return buildString {
                for (clause in clauses) {
                    val line = start + clause.joinToString(" ") { it.trim() }
                    if (line == "insert" || line == "delete") {
                        // [insert into ...], [delete from ...]: eine einzige Zeile
                        start = "$line "
                        continue
                    }
                    if (line.length <= WIDTH) {
                        append("    SQL> ").append(line).append('\n')
                    } else {
                        // Klausel zu lang: die Hibernate-Zeilen werden beibehalten
                        clause.forEachIndexed { i, l ->
                            append("    SQL> ").append(if (i == 0) start else "").append(l).append('\n')
                        }
                    }
                    start = ""
                }
            }
        }

        // die Anzahl der Leerzeichen am Zeilenanfang
        private fun indentation(line: String) = line.length - line.trimStart().length

        // der Wert eines Parameters der SQL-Anweisung
        private fun parameter(message: String): String =
            PARAMETER.matchEntire(message)
                ?.let { "    SQL> -- parameter ${it.groupValues[1]} = ${it.groupValues[2]}\n" } ?: ""

        // Beginn, Commit und Rollback der Transaktionen (die anderen Meldungen werden ignoriert)
        private fun transaction(message: String): String = when {
            message.startsWith("HHH10003002") -> "    SQL> -- start of transaction\n"
            message.startsWith("HHH10003004") -> "    SQL> -- transaction committed (COMMIT)\n"
            message.startsWith("HHH10003006") -> "    SQL> -- transaction rolled back (ROLLBACK)\n"
            else -> ""
        }

        // der vom DBMS gemeldete Fehler (die Zeile mit seinen Fehlercodes wird ignoriert)
        private fun dbError(message: String): String =
            if (message.startsWith("HHH000247")) "" else "    SQL> -- failure: $message\n"

        // die Ausführung eines Batches von SQL-Anweisungen (die anderen Meldungen werden ignoriert)
        private fun batch(message: String): String =
            BATCH.matchEntire(message)
                ?.let { "    SQL> -- execution of a batch of ${it.groupValues[1]} statement(s)\n" } ?: ""

        // führt eine Aktion ohne SQL-Log aus und gibt ihr Ergebnis zurück
        fun <T> withoutLog(action: () -> T): T {
            val loggers = listOf(SQL, PARAMETERS, TRANSACTIONS, ERRORS, BATCHES)
                .map { LoggerFactory.getLogger(it) as Logger }
            // die aktuellen Levels, am Ende wiederhergestellt
            val levels: List<Level?> = loggers.map { it.level }
            loggers.forEach { it.level = Level.OFF }
            try {
                return action()
            } finally {
                loggers.zip(levels).forEach { (logger, level) -> logger.level = level }
            }
        }
    }
}
  • Zeile 10: Ein Logback-Layout leitet sich von der Java-Klasse [LayoutBase<ILoggingEvent>] ab (beachten Sie die Klammern: der Aufruf des Konstruktors der Elternklasse, Kapitel 4); seine Methode [doLayout] (Zeilen 13–21) erhält jede Meldung (ein [ILoggingEvent]) und gibt den zu schreibenden Text zurück. Logback erzeugt das Objekt anhand des Klassennamens selbst per Reflection: Es benötigt einen parameterlosen Konstruktor, nämlich den impliziten primären Konstruktor der Klasse;
  • Zeilen 15–21: Die Verarbeitung hängt vom Log ab, das die Meldung gesendet hat (ein ***[when] auf einem Kanal, Kapitel 3). Die Zweige verwenden die Konstanten aus dem ***[companion object];
  • Zeile 25: Die „statischen“ Member der Klasse werden in ihrem Companion Object abgelegt (Kapitel 4);
  • Zeilen 27–31: die Namen der verwendeten Hibernate-Logs und die öffentlichen Kompilierungskonstanten ([const val]); andere Unterprojekte verweisen darauf als [SqlLog.SQL] ...;
  • Zeilen 37–40: zwei reguläre Ausdrücke (Kapitel 5), geschrieben als Raw Strings (["""..."""]), wodurch man die Backslashes nicht verdoppeln muss, wie es Java verlangt (["\\((\\d+)..."]);
  • Zeilen 43–71: der SQL-Befehl, wie ihn Hibernate formatiert ([format_sql]), verteilt auf viele Zeilen mit einer Spalte pro Zeile. Wir machen ihn kompakter. Nicht leere Zeilen werden zu Klauseln gruppiert (Zeilen 47–51): Eine Klausel beginnt mit einer Zeile der obersten Ebene ([select], [from], [where] ...) und umfasst die darauf folgenden eingerückten Zeilen. [minOfOrNull] liefert die kleinste Einrückung oder [null] , wenn es keine Zeile gibt; in diesem Fall wird sie mit dem Operator [?:] durch 0 ersetzt. Jede Klausel wird dann in einer einzigen Zeile ausgegeben, der [SQL>] vorangestellt ist, sofern sie 100 Zeichen nicht überschreitet (Zeilen 63–64); andernfalls bleiben ihre Zeilen erhalten (Zeilen 67–68). Die Klauseln [insert] und [delete] werden mit der folgenden zusammengefasst (Zeilen 58–61). Der Text wird von [buildString] (Kapitel 5) aufgebaut, dessen Block einen [StringBuilder] als Receiver hat: [append] wird dort ohne Präfix aufgerufen;
  • Zeilen 80–82: Die Hibernate-Meldung, die den Wert eines Parameters liefert, sieht so aus: [binding parameter (1:VARCHAR) <- [bike]]. [matchEntire] gibt ein [MatchResult] zurück, wenn die gesamte Meldung auf den regulären Ausdruck passt, andernfalls [null]; [?.let] baut den Text aus den erfassten Gruppen auf (der Parameternummer und seinem Wert), und [?: ""] liefert eine leere Zeichenkette, wenn es keinen Treffer gibt;
  • Zeilen 85–89: Von den vielen Meldungen des Logs [org.hibernate.orm.resource.jdbc] werden nur diejenigen beibehalten, die den Beginn, die Bestätigung und den Abbruch einer Transaktion anzeigen. Jede Hibernate-Meldung beginnt mit einem Code ([HHH10003002] ...), der sie eindeutig identifiziert. Ein [when] ohne Argumente (Kapitel 3) ersetzt die [if]-Folge von Java;
  • Zeilen 93–94: ein Fehler im DBMS. Hibernate schreibt ihn als zwei Meldungen: eine mit den Fehlercodes (die wir ignorieren) und eine mit dem Fehlertext;
  • Zeilen 97–99: die Ausführung eines Batches von SQL-Befehlen, dem wir am Ende des Kapitels begegnen werden;
  • Zeilen 102–111: Die Funktion [withoutLog] führt eine Aktion mit SQL ohne Log aus. Es ist eine Funktion höherer Ordnung (Kapitel 7): Ihr Parameter ist eine Funktion [() -> T], und sie gibt das Ergebnis der Aktion zurück (Java, das ein [Runnable] verwendet, erlaubt das nicht ganz so einfach). Sie verwendet die API von Logback: Jedes Log ([Logger]) hat eine Stufe, die zur Laufzeit geändert werden kann (die Eigenschaft [level], die den Java-Methoden [getLevel]/[setLevel] entspricht). Wir setzen die fünf Logs auf die Stufe [OFF], führen die Aktion aus und stellen dann in einer [finally]-Klausel die ursprünglichen Stufen wieder her, damit sie auch dann erhalten bleiben, wenn die Aktion eine Ausnahme auslöst. Die ursprüngliche Stufe kann [null] sein (ein Log, das seine Stufe von seinem Elternlog erbt), daher der Typ [List<Level?>]; [zip] ordnet jedem Log seine ursprüngliche Stufe zu, und die Dekomposition [(logger, level)] (Kapitel 3) benennt die beiden Elemente jedes Paares;
  • Zeile 104: [LoggerFactory] ist die SLF4J-Klasse, die ein Log zurückgibt; Da Logback die aktuelle Implementierung von SLF4J ist, ist das gelieferte Objekt ein [ch.qos.logback.classic.Logger], wie die Typumwandlung [as Logger] anzeigt.

Das Unterprojekt [tools] enthält außerdem die von den Beispielen verwendete Datei [logback.xml] (es ist dieselbe Datei wie in Java). Sie liegt im Wurzelverzeichnis des Klassenpfads ([src/main/resources]) und wird von Logback beim Start des Programms gefunden:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Logback-Konfiguration für die Beispiele des Kapitels -->
<configuration>

    <!-- das kompakte SQL-Log: Layout durch die Klasse [tools.SqlLog] -->
    <appender name="SQL" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
            <layout class="tools.SqlLog"/>
        </encoder>
    </appender>

    <!-- die anderen Meldungen: Level, Kurzname des Loggers, Text -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%-5level %logger{0} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- die SQL-Anweisungen (DEBUG), ihre Parameter, die Transaktionen, die Batches (TRACE) und die Fehler -->
    <logger name="org.hibernate.SQL" level="DEBUG" additivity="false">
        <appender-ref ref="SQL"/>
    </logger>
    <logger name="org.hibernate.orm.jdbc.bind" level="TRACE" additivity="false">
        <appender-ref ref="SQL"/>
    </logger>
    <logger name="org.hibernate.orm.resource.jdbc" level="TRACE" additivity="false">
        <appender-ref ref="SQL"/>
    </logger>
    <logger name="org.hibernate.orm.jdbc.batch" level="TRACE" additivity="false">
        <appender-ref ref="SQL"/>
    </logger>
    <logger name="org.hibernate.orm.jdbc.error" level="WARN" additivity="false">
        <appender-ref ref="SQL"/>
    </logger>

    <!-- der in Hibernate integrierte Verbindungspool genügt für unsere Beispiele: seine Warnung wird unterdrückt -->
    <logger name="org.hibernate.orm.connections.pooling" level="ERROR"/>

    <!-- das Löschen der Tabellen einer leeren Datenbank verursacht harmlose Fehler: sie werden unterdrückt -->
    <logger name="org.hibernate.tool.schema" level="OFF"/>

    <!-- alle anderen Logger: nur Warnungen und Fehler -->
    <root level="WARN">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>
  • Zeilen 6–10: Ein „Appender“ schreibt die Meldungen, hier auf die Konsole. Er verwendet unser Layout, das durch seinen Klassennamen ([tools.SqlLog]) angegeben wird;
  • Zeilen 13–17: ein zweiter „Appender“ für die übrigen Meldungen: Stufe, kurzer Name des Logs, Text;
  • Zeilen 20–34: die Hibernate-Logs aus der vorherigen Tabelle mit ihren Stufen. Ihre Meldungen werden an den „Appender“ [SQL] und nur an diesen gesendet ([additivity="false"]: Sie werden nicht zusätzlich an das Wurzel-Log weitergeleitet);
  • Zeile 37: Die Warnung zum integrierten Verbindungspool von Hibernate wird unterdrückt;
  • Zeile 40: Hibernate löscht Tabellen, indem es bei ihren Fremdschlüsseln beginnt; bei einer leeren Datenbank schlagen diese Löschungen folgenlos fehl, Hibernate protokolliert das jedoch ausführlich. Diese Meldungen werden unterdrückt;
  • Zeilen 43–45: Die übrigen Logs erfassen nur Warnungen und Fehler.

Die Build-Datei des Unterprojekts [tools] ist die einer Bibliothek (Kapitel 6):

// Bibliothek: das kompakte Log der von Hibernate ausgeführten SQL-Anweisungen
plugins {
    kotlin("jvm")
    // das Bibliotheks-Plugin: es fügt die Konfiguration [api] hinzu
    `java-library`
}

repositories {
    mavenCentral()
}

dependencies {
    // Logback, das das Hibernate-Log empfängt (JBoss Logging erkennt es);
    // [api]: die Klasse SqlLog leitet sich von einer Logback-Klasse ab, ihre Benutzer müssen sie sehen
    api("ch.qos.logback:logback-classic:1.5.38")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}
  • Zeile 5: das Bibliotheks-Plugin, das die Konfiguration [api] hinzufügt;
  • Zeile 15: die einzige Abhängigkeit, Logback. Sie wird mit [api] und nicht mit [implementation] deklariert: Die Klasse [SqlLog] leitet sich von einer Logback-Klasse ab, und die Unterprojekte, die sie verwenden, müssen diese Elternklasse zur Kompilierzeit sehen können. Eine Abhängigkeit vom Typ [api] wird den Nutzern der Bibliothek sowohl für die Kompilierung als auch für die Laufzeit zur Verfügung gestellt.

Eine Bibliothek zwingt den Anwendungen, die sie verwenden, normalerweise nicht ihre Logging-Konfiguration auf; wir tun es hier, um zu vermeiden, diese Datei in jedem Beispiel zu wiederholen.

11.4.2. Die Entität und die Datenbank der Artikel

Die Entität [Article] im Unterprojekt [articles] verwendet die Annotationen aus dem vorherigen Abschnitt:

package articles

import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.Table
import jakarta.persistence.UniqueConstraint
import java.math.BigDecimal

// ein Artikel des Shops, mit den Annotationen, die seine Tabelle festlegen
// eine gewöhnliche Klasse (keine Data-Klasse); das Plugin [jpa] fügt ihr einen parameterlosen Konstruktor hinzu,
// das Plugin [allopen] macht sie open (nicht final), ebenso ihre Eigenschaften
@Entity
@Table(
    name = "articles",
    uniqueConstraints = [UniqueConstraint(name = "uk_articles_name", columnNames = ["name"])]
)
class Article(
    // Name des Artikels: obligatorisch, höchstens 30 Zeichen, eindeutig (siehe @Table)
    @Column(nullable = false, length = 30)
    var name: String,
    // Preis: 10 Stellen, davon 2 Nachkommastellen
    @Column(nullable = false, precision = 10, scale = 2)
    var price: BigDecimal,
    // aktueller Bestand und Mindestbestand, unterhalb dessen aufgefüllt werden muss
    var currentStock: Int,
    var minimumStock: Int,
) {
    // Primärschlüssel, vom DBMS erzeugt (AUTO_INCREMENT): null, solange der Artikel nicht gespeichert ist
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        // keine Änderung durch die Anwendung: der Bezeichner wird von Hibernate verwaltet
        protected set

    // Anzeige
    override fun toString() = "[%d, %s, %.2f, %d, %d]".format(id, name, price, currentStock, minimumStock)
}
  • Zeilen 13–14: eine Erinnerung daran, was die Plugins [jpa] und [allopen] für diese Klasse leisten;
  • Zeilen 16–18: Die Tabelle heißt [articles], wie in Kapitel 10. Der Parameter [uniqueConstraints] deklariert eine Eindeutigkeitsbedingung mit dem Namen [uk_articles_name] für die Spalte [name]: Zwei Artikel dürfen nicht denselben Namen haben. Ohne ausdrücklichen Namen würde Hibernate einen unleserlichen erzeugen ([UK3f8k...]), der in Fehlermeldungen erscheinen würde. Parameter von Annotationen, die Arrays sind, werden in Kotlin in eckigen Klammern geschrieben ([[UniqueConstraint(...)]], [["name"]]); eine Annotation, die als Argument einer anderen Annotation verwendet wird, wird ohne [@] geschrieben;
  • Zeilen 22–23: ein Pflichtname von höchstens 30 Zeichen;
  • Zeilen 25–26: ein Preis im Format [decimal(10,2)];
  • Zeilen 28–29: die beiden Lagerbestände vom Typ [Int]: Spalten [NOT NULL];
  • Zeilen 32–36: der Bezeichner. Der Modifizierer der Eigenschaft ist als [protected] deklariert: Die Anwendung kann den Bezeichner lesen, aber nicht ändern, da er von Hibernate verwaltet wird (die Java-Klasse hat aus demselben Grund keine Methode [setId]). Er könnte nicht [private] sein: Die Eigenschaft ist öffentlich ([all-open]), und Kotlin verbietet einen privaten Modifizierer bei einer öffentlichen Eigenschaft, die eine abgeleitete Klasse neu definieren könnte („[private setters for open properties are prohibited.]“);
  • Zeile 39: dieselbe Methode [toString] wie im ersten Beispiel.

Die Java-Version dieser Klasse umfasst fast neunzig Zeilen, darunter die beiden Konstruktoren und etwa zehn Zugriffsmethoden ([getX]/[setX]); in Kotlin erfüllen die Eigenschaften des primären Konstruktors und die beiden Plugins diesen Zweck.

Das Objekt [BaseArticles] enthält die Hibernate-Konfiguration für die Datenbank [hbarticles]:

package articles

import org.hibernate.SessionFactory
import org.hibernate.cfg.AvailableSettings
import org.hibernate.jpa.HibernatePersistenceConfiguration
import tools.SqlLog
import java.math.BigDecimal

// die Datenbank [hbarticles]: Hibernate-Konfiguration und Initialisierung der Datenbank
// ein [object]: eine einzige Instanz, ohne Konstruktor (die Utility-Klasse von Java)
object BaseArticles {

    // die Datenbank; MySQL erstellt sie, falls sie nicht existiert (createDatabaseIfNotExist)
    const val URL = "jdbc:mysql://localhost:3306/hbarticles?createDatabaseIfNotExist=true"
    const val USER = "root"
    const val PASSWORD = ""

    // die Hibernate-Konfiguration: Entitäten, Datenbank, Formatierung der geloggten SQL-Anweisungen
    fun configuration(): HibernatePersistenceConfiguration =
        HibernatePersistenceConfiguration("articles")
            .managedClass(Article::class.java)
            .jdbcUrl(URL)
            .jdbcCredentials(USER, PASSWORD)
            .property(AvailableSettings.FORMAT_SQL, true)

    // eine SessionFactory für die Datenbank [hbarticles], mit der vorherigen Konfiguration
    fun createSessionFactory(): SessionFactory = configuration().createEntityManagerFactory()

    // (Neu-)Erstellung der Tabelle [articles] mit ihren sechs Artikeln, ohne SQL-Log
    fun initialize(sessionFactory: SessionFactory) = SqlLog.withoutLog {
        // Löschen und anschließendes Erstellen der Tabellen der Entitäten
        sessionFactory.schemaManager.drop(false)
        sessionFactory.schemaManager.create(false)
        // die sechs Artikel, in einer Transaktion hinzugefügt
        sessionFactory.inTransaction { session ->
            session.persist(Article("bike", BigDecimal(500), 10, 5))
            session.persist(Article("pump", BigDecimal(10), 10, 2))
            session.persist(Article("bow", BigDecimal(600), 4, 1))
            session.persist(Article("arrows - set of 6", BigDecimal(100), 12, 20))
            session.persist(Article("diving suit", BigDecimal(300), 8, 2))
            session.persist(Article("diver's oxygen tanks", BigDecimal(120), 10, 5))
        }
    }
}
  • Zeile 11: ein [object] (Kapitel 4): ein Singleton, das bei der ersten Verwendung erzeugt wird. Das entspricht einer Java-Hilfsklasse (einer [final]-Klasse mit statischen Membern und einem privaten Konstruktor);
  • Zeilen 14–16: die URL der Datenbank und die des Benutzers, die öffentlich sind, damit andere Unterprojekte sie verwenden können;
  • Zeilen 19–24: die Hibernate-Konfiguration. Sie wird von einer öffentlichen Funktion zurückgegeben, wodurch ein Beispiel sie vervollständigen kann, bevor es die [SessionFactory] erstellt. Die Eigenschaft [FORMAT_SQL] ([hibernate.format_sql]) weist Hibernate an, das SQL zu formatieren, das es dann an das Log [org.hibernate.SQL] übergibt: Diese formatierte Ausgabe verdichtet dann die Klasse [SqlLog];
  • Zeile 27: die [SessionFactory] der Datenbank [hbarticles], eine Funktion, deren Rumpf ein Ausdruck ist;
  • Zeilen 30–41: eine Funktion, die die Tabelle [articles] mit ihren sechs Einträgen neu erstellt, ohne das SQL-Log: Wir wollen das SQL dieser Initialisierung nicht in den Ergebnissen der Beispiele sehen. Der an [withoutLog] übergebene Block ist ein nach den Klammern geschriebenes Lambda, wobei die Klammern hier weggelassen werden (Kapitel 7);
  • Zeile 35: [sessionFactory.inTransaction { session -> ... }] öffnet eine Sitzung, startet eine Transaktion, führt das Lambda aus, indem es ihm die Sitzung übergibt, bestätigt die Transaktion (oder rollt sie zurück, wenn das Lambda eine Ausnahme auslöst) und schließt die Sitzung. Das ist die kürzeste Art, eine Arbeitseinheit zu schreiben; wir werden sie oft verwenden, zusammen mit ihren Varianten [inSession] (eine Sitzung ohne Transaktion), [fromTransaction], und [fromSession] (die das Ergebnis des Lambdas zurückgeben). Der Parameter dieser Java-Methoden ist eine funktionale Schnittstelle ([Consumer<Session>], [Function<Session, R>]): Kotlin akzeptiert dort direkt ein Lambda (SAM-Konvertierung, Kapitel 7);
  • Zeilen 36–41: [BigDecimal(500)] ruft den Konstruktor von [BigDecimal] auf, der eine Ganzzahl entgegennimmt; er liefert denselben Wert wie die Java-Methode [BigDecimal.valueOf(500)].

Das Unterprojekt [articles] hängt vom Unterprojekt [tools], von Hibernate und vom JDBC-Treiber ab:

// Bibliothek: die Entität [Article] und die Factory der SessionFactory der Datenbank [hbarticles]
plugins {
    kotlin("jvm")
    // der parameterlose Konstruktor der Entitäten (Plugin "no-arg", für JPA konfiguriert)
    kotlin("plugin.jpa")
    // Entitäten und Eigenschaften werden open (nicht final) gemacht: Hibernate kann Proxys davon ableiten
    kotlin("plugin.allopen")
    // das Bibliotheks-Plugin: es fügt die Konfiguration [api] hinzu
    `java-library`
}

repositories {
    mavenCentral()
}

dependencies {
    // das kompakte SQL-Log (und Logback)
    api(project(":tools"))
    // Hibernate: [api], weil die Benutzer der Bibliothek SessionFactory, Session... verwenden
    api("org.hibernate.orm:hibernate-core:7.4.5.Final")
    // der MySQL-JDBC-Treiber: nur zur Laufzeit nützlich
    runtimeOnly("com.mysql:mysql-connector-j:9.7.0")
}

// die so annotierten Klassen werden vom Plugin [allopen] geöffnet
allOpen {
    annotation("jakarta.persistence.Entity")
    annotation("jakarta.persistence.MappedSuperclass")
    annotation("jakarta.persistence.Embeddable")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}
  • Zeilen 5–9: Die Bibliothek definiert eine Entität; sie wendet beide Entitäts-Plugins und das Bibliotheks-Plugin an;
  • Zeile 18: die Abhängigkeit von einem anderen Unterprojekt des Builds, angegeben über seinen Pfad ([":tools"]);
  • Zeile 20: Hibernate, deklariert mit [api]: Unterprojekte, die die Bibliothek verwenden, manipulieren direkt deren Typen ([SessionFactory], [Session] ...);
  • Zeile 22: der JDBC-Treiber, nur zur Laufzeit erforderlich;
  • Zeilen 26–29: die Konfiguration des Plugins [all-open].

Die Beispiel-Unterprojekte benötigen dann nur noch eine Abhängigkeit: das Unterprojekt [articles]. Gradle fügt dessen Abhängigkeiten hinzu (man spricht von transitiven Abhängigkeiten): die Abhängigkeiten [api] für Kompilierung und Ausführung und die Abhängigkeit [runtimeOnly] für die Ausführung. Hier ist die Build-Datei des Unterprojekts [crud]:

// die grundlegenden Operationen: persist, find, merge, remove; die Zustände einer Entität
plugins {
    kotlin("jvm")
    // kein Plugin [jpa] oder [allopen]: das Unterprojekt definiert keine Entität
    // (die Klasse Article wird im Unterprojekt [articles] kompiliert)
    application
}

repositories {
    mavenCentral()
}

dependencies {
    // die Entität [Article] und die Datenbank [hbarticles] (Hibernate, MySQL und das SQL-Log eingeschlossen)
    implementation(project(":articles"))
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // das von [gradlew -q :crud:run] ausgeführte Programm, gestartet im Ordner 11-hibernate
    mainClass = "crud.MainKt"
}

// unter Windows wird die Bildschirmausgabe des von Gradle gestarteten Programms (run, bootRun ...) in UTF-8 kodiert,
// sonst werden Zeichen mit Akzenten in der IntelliJ-IDEA-Konsole oder im Terminal falsch dargestellt
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • Zeile 4: Das Unterprojekt definiert keine Entitäten: Es braucht die Plugins [jpa] und [allopen] nicht, die beim Kompilieren annotierter Klassen verwendet werden, hier der Klassen aus dem Unterprojekt [articles];
  • Zeile 15: die einzige Abhängigkeit;
  • Zeilen 31–34: Die von Gradle gestarteten Programme schreiben ihre Ausgabe in UTF-8, damit Zeichen mit Akzenten unter Windows korrekt angezeigt werden (Kapitel 2).

11.4.3. Weitere Möglichkeiten, Hibernate zu konfigurieren

Wir konfigurieren Hibernate programmatisch mit [HibernatePersistenceConfiguration]. Es gibt weitere Möglichkeiten, die man in Anwendungen und in der Dokumentation findet:

  • eine Datei [META-INF/persistence.xml], der traditionelle Ansatz von Jakarta Persistence: Sie beschreibt eine oder mehrere Persistenzeinheiten (Entitätsklassen, Verbindungseigenschaften, Optionen), und die Factory wird mit [Persistence.createEntityManagerFactory("articles")] erstellt;
  • eine Datei [hibernate.properties] (oder [hibernate.cfg.xml]), spezifisch für Hibernate, die von der Klasse [org.hibernate.cfg.Configuration] gelesen wird: [Configuration().addAnnotatedClass(Article::class.java).buildSessionFactory()]. Dies ist der Ansatz älterer Hibernate-Versionen;
  • In einer Spring-Boot-Anwendung die Eigenschaften [spring.datasource.*] und [spring.jpa.*] in der Datei [application.properties]: Spring Boot erstellt die Factory selbst.

Die Eigenschaften sind überall dieselben ([hibernate.format_sql], [jakarta.persistence.jdbc.url] ...): Es ändert sich nur die Art, wie sie angegeben werden.

11.5. Grundlegende Operationen: hinzufügen, lesen, ändern, löschen

11.5.1. Das [crud]-Programm

Das Unterprojekt [crud] demonstriert die vier grundlegenden Operationen (CRUD: Create, Read, Update, Delete) sowie die Verfolgung der Entitäten durch die Sitzung. Um diese Verfolgung sichtbar zu machen, verwendet es einige interne Hibernate-Methoden (dessen „SPI“, Service Provider Interface), die für Hibernate-Erweiterungen und nicht für Anwendungen gedacht sind: Sie sind in den Hilfsfunktionen am Ende der Datei zusammengefasst, die als Erweiterungsfunktionen von [Session] geschrieben sind (Kapitel 4). Die Transaktionen werden mit der Methode [inTransaction] der Sitzung geschrieben, einer Funktion höherer Ordnung: [session.inTransaction { ... }] startet eine Transaktion, führt den Block aus und bestätigt anschließend die Transaktion oder rollt sie zurück, wenn der Block eine Ausnahme auslöst. Der Code kann [commit] oder [rollback] im Fehlerfall nicht mehr vergessen.

package crud

import articles.Article
import articles.BaseArticles
import org.hibernate.Session
import org.hibernate.engine.spi.PersistenceContext
import org.hibernate.engine.spi.SessionImplementor
import java.math.BigDecimal

fun main() {
    BaseArticles.createSessionFactory().use { sessionFactory ->
        // die Tabelle [articles] wird mit ihren sechs Artikeln neu erstellt
        BaseArticles.initialize(sessionFactory)
        sessionFactory.openSession().use { session ->
            // 1 - Suche anhand des Primärschlüssels
            println("--- find(1)")
            val bike = session.find(Article::class.java, 1) ?: error("no article no. 1")
            println(bike)
            println("--- find(1) a second time")
            val bike2 = session.find(Article::class.java, 1)
            println("same object: ${bike === bike2}")

            // 2 - Hinzufügen eines Artikels, in einer Transaktion
            println("--- persist")
            val x = Article("x", BigDecimal(100), 10, 1)
            session.inTransaction {
                println("before persist: state=${session.state(x)}, id=${x.id}")
                session.persist(x)
                println("after persist: state=${session.state(x)}, id=${x.id}")
            }

            // 3 - Änderung: es genügt, das Objekt zu ändern
            println("--- modification of the price")
            session.inTransaction {
                x.price *= BigDecimal("1.1")
                println("session modified: ${session.isDirty}, " +
                    "original price=${session.originalValue(x, "price")}, current price=${x.price}")
                println("--- commit")
            }
            println("after commit: session modified: ${session.isDirty}")

            // 4 - Löschen
            println("--- remove")
            session.inTransaction {
                session.remove(x)
                println("before commit: state=${session.state(x)}")
            }
            println("after commit: state=${session.state(x)}")

            // 5 - ein losgelöstes Objekt (detached), geändert und dann mit der Session zusammengeführt
            println("--- detach and merge")
            val bow = session.find(Article::class.java, 3) ?: error("no article no. 3")
            session.detach(bow)
            println("after detach: state=${session.state(bow)}")
            bow.price = BigDecimal(550)
            session.inTransaction {
                val managedBow = session.merge(bow)
                println("merge: same object=${bow === managedBow}, " +
                    "state of the returned object=${session.state(managedBow)}")
            }

            // 6 - die von der Session verfolgten Entitäten
            println("--- the tracked entities")
            bike.currentStock--
            session.displayTrackedEntities()
        }
    }
}

// der Persistenzkontext der Session (interne Hibernate-API): eine Erweiterungseigenschaft
private val Session.trackingContext: PersistenceContext
    get() = unwrap(SessionImplementor::class.java).persistenceContext

// der Zustand eines Artikels in Bezug auf die Session (interne Hibernate-API)
private fun Session.state(article: Article): String = when {
    // ein von der Session verfolgtes Objekt: MANAGED, DELETED...
    trackingContext.isEntryFor(article) -> trackingContext.getEntry(article).status.name
    // ein der Session unbekanntes Objekt: nie gespeichert (ohne Bezeichner) oder losgelöst
    article.id == null -> "TRANSIENT"
    else -> "DETACHED"
}

// der Wert einer Eigenschaft, wie er aus der Datenbank gelesen wurde (interne Hibernate-API)
private fun Session.originalValue(entity: Any, property: String): Any? =
    trackingContext.getEntry(entity).getLoadedValue(property)

// die Entitäten des Persistenzkontexts der Session (interne Hibernate-API)
private fun Session.displayTrackedEntities() {
    for ((entity, entry) in trackingContext.reentrantSafeEntityEntries()) {
        val persister = entry.persister
        println("${persister.entityName} #${entry.id} ${entry.status}")
        // aktuelle Werte der Eigenschaften, verglichen mit den aus der Datenbank gelesenen Werten
        val current = persister.getValues(entity)
        val originals = entry.loadedState
        persister.propertyNames.forEachIndexed { i, name ->
            val modification = if (current[i] == originals[i]) ""
                else " (modified, original value: ${originals[i]})"
            println("    $name : ${current[i]}$modification")
        }
    }
    println("session modified: $isDirty")
}

Ergebnisse:

> gradlew -q :crud:run
--- find(1)
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 1
[1, bike, 500.00, 10, 5]
--- find(1) a second time
same object: true
--- persist
    SQL> -- start of transaction
before persist: state=TRANSIENT, id=null
    SQL> insert into articles (currentStock, minimumStock, name, price)
    SQL> values (?, ?, ?, ?)
    SQL> -- parameter 1 = 10
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = x
    SQL> -- parameter 4 = 100
after persist: state=MANAGED, id=7
    SQL> -- transaction committed (COMMIT)
--- modification of the price
    SQL> -- start of transaction
session modified: true, original price=100, current price=110.0
--- commit
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 10
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = x
    SQL> -- parameter 4 = 110.0
    SQL> -- parameter 5 = 7
    SQL> -- transaction committed (COMMIT)
after commit: session modified: false
--- remove
    SQL> -- start of transaction
before commit: state=DELETED
    SQL> delete from articles
    SQL> where id=?
    SQL> -- parameter 1 = 7
    SQL> -- transaction committed (COMMIT)
after commit: state=DETACHED
--- detach and merge
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 3
after detach: state=DETACHED
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 3
merge: same object=false, state of the returned object=MANAGED
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 4
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = bow
    SQL> -- parameter 4 = 550
    SQL> -- parameter 5 = 3
    SQL> -- transaction committed (COMMIT)
--- the tracked entities
articles.Article #1 MANAGED
    currentStock : 9 (modified, original value: 10)
    minimumStock : 5
    name : bike
    price : 500.00
articles.Article #3 MANAGED
    currentStock : 4
    minimumStock : 1
    name : bow
    price : 550
session modified: true

Kommentare:

  • Zeile 17: [session.find(Article::class.java, 1)] sucht den Datensatz mit dem Primärschlüssel 1. Es gibt [null] zurück, wenn der Schlüssel nicht existiert; der Operator [?:] löst dann eine Ausnahme aus ([error], Kapitel 3), und [bike] hat den Typ [Article], der nicht nullbar ist. Das generierte SQL (Zeilen 3–6 der Ergebnisse) ist ein parametrisiertes [SELECT], dessen Parameter auf 1 gesetzt ist: Das kompakte Log zeigt nun die Parameterwerte an;
  • Zeile 20: Der zweite Aufruf von [find(Article::class.java, 1)] sendet keinen SQL-Befehl und gibt dasselbe Objekt zurück (Zeile 9). Der Operator [===] vergleicht Referenzen (der Java-Operator []), während [] die Methode [equals] aufrufen würde (Kapitel 3). Die Sitzung speichert die Entitäten, die sie gelesen oder gespeichert hat, in ihrem Persistenzkontext, auch First-Level-Cache genannt: Bevor [find] die Datenbank abfragt, prüft es, ob die gesuchte Entität dort bereits vorhanden ist. Eine Sitzung enthält nie zwei Objekte für dieselbe Zeile der Datenbank;
  • Zeilen 25–29: Hinzufügen eines Artikels. Vor [persist] ist das Objekt [TRANSIENT] („transient“): Die Sitzung kennt es nicht, und sein Bezeichner ist [null] (Zeile 12). [persist] übernimmt es in die Sitzung, die sofort den Befehl [INSERT] ausführt (Zeilen 13–18), um den generierten Schlüssel zu erhalten, und ihn in das Feld [id] einträgt (Hibernate schreibt direkt in das Feld: Der Modifizierer protected der Eigenschaft verhindert das nicht). Der Artikel ist dann [MANAGED] („verwaltet“ oder „persistent“), und sein Bezeichner lautet 7 (Zeile 19). Die Transaktion wird zu Beginn des Blocks [inTransaction] geöffnet und an dessen Ende bestätigt (Zeilen 11 und 20 der Ergebnisse). Der Parameter des Blocks ([Transaction]) wird nicht verwendet: Er wird nicht benannt;
  • Zeile 35: Um eine Zeile in der Datenbank zu ändern, genügt es, das Objekt zu ändern. Eine Methode [update] ist nicht erforderlich: Die Sitzung hat eine Kopie der gelesenen oder gespeicherten Werte aufbewahrt (den ursprünglichen Zustand) und vergleicht die aktuellen Werte damit. Dies nennt man „Dirty Checking“. Der Operator [*=] wird hier von Kotlin in [x.price = x.price * BigDecimal("1.1")] übersetzt: Der Eigenschaft wird ein neues [BigDecimal]-Objekt (das unveränderlich ist) zugewiesen;
  • Zeilen 36–37: Die Eigenschaft [isDirty] (die Java-Methode [isDirty()]) gibt an, ob die Sitzung Änderungen enthält, die noch nicht in die Datenbank übernommen wurden: Das ist der Fall (Zeile 23). Die Funktion [originalValue] (Zeilen 84–85) liest den ursprünglichen Wert des Preises, 100, aus dem Persistenzkontext, während der aktuelle Wert 110.0 beträgt;
  • Zeile 38: das Ende des Blocks. Das anschließende [commit] synchronisiert die Sitzung mit der Datenbank („Flush“): Der Befehl [UPDATE] wird ausgeführt (Zeilen 25–32), und danach wird die Transaktion bestätigt. Anschließend hat die Sitzung keine ausstehenden Änderungen mehr (Zeile 34);
  • Beachten Sie, dass der Befehl [UPDATE] alle Spalten der Tabelle schreibt, nicht nur die geänderte. Das ist das Standardverhalten von Hibernate: Ein einziger, ein für alle Mal vorbereiteter SQL-Befehl dient für alle Änderungen an Artikeln. Die auf der Entität angebrachte Annotation [@DynamicUpdate] weist Hibernate dagegen an, jedes Mal eine auf die geänderten Spalten beschränkte Abfrage zu erzeugen;
  • Zeilen 45–48: das Löschen. [remove] ändert den Status des Artikels in [DELETED] (Zeile 37); [commit] sendet den Befehl [DELETE] (Zeilen 38–40). Das Objekt wird dann von der Sitzung nicht mehr erkannt: Es wird [DETACHED] („losgelöst“, Zeile 42);
  • Zeilen 52–55: Der Bogen wird gelesen (Zeilen 44–47) und dann durch [detach] von der Sitzung gelöst: Die Sitzung vergisst ihn (Zeile 48). Jede Änderung seines Preises wird dann ignoriert. Ein losgelöstes Objekt kommt in einer Anwendung häufig vor: Es ist ein Objekt, das von einer inzwischen geschlossenen Sitzung gelesen wurde – zum Beispiel bei einer vorherigen HTTP-Anfrage – und anschließend vom Benutzer geändert wird;
  • Zeile 57: [session.merge(bow)] führt das losgelöste Objekt mit der Sitzung zusammen. Die Sitzung liest den Artikel aus der Datenbank (Zeilen 50–53), kopiert den Zustand des losgelösten Objekts in die von ihr verwaltete Entität und gibt Letztere zurück: Es ist nicht dasselbe Objekt (Zeile 54). Das an [merge] übergebene Objekt bleibt losgelöst; das zurückgegebene Objekt ist das, das anschließend verwendet werden muss. [commit] speichert den neuen Preis (Zeilen 55–62);
  • Zeile 64: Der Lagerbestand des Fahrrads wird ohne Transaktion aktualisiert;
  • Zeilen 71–72: der Persistenzkontext der Sitzung, ermittelt über eine Erweiterungseigenschaft: In den folgenden Funktionen wird [trackingContext] wie eine Eigenschaft der Sitzung behandelt. [unwrap] ermöglicht den Zugriff auf die interne Schnittstelle [SessionImplementor] der Sitzung;
  • Zeilen 75–80: der Status eines Artikels, berechnet durch ein [when] ohne Argumente. Zunächst wird mit [isEntryFor] geprüft, ob die Sitzung dem Artikel zugeordnet ist: Die Methode [getEntry], die für ein unbekanntes Objekt [null] zurückgibt (worauf der Java-Code prüft), ist in Hibernate dennoch als [@NonNull] annotiert. Kotlin berücksichtigt diese Nullbarkeits-Annotationen der Java-Bibliotheken: Es geht davon aus, dass [getEntry] einen nicht nullbaren [EntityEntry] zurückgibt, und kennzeichnet eine Prüfung mit [?.] auf dessen Ergebnis als überflüssig („[unnecessary safe call on a non-null receiver of type 'EntityEntry'.]“) (eine Warnung und damit bei unseren Kompilierungsoptionen ein Fehler). Das ist ein seltener, aber lehrreicher Fall: Die Typen einer Java-Bibliothek sind stets genau das, was ihre Annotationen festlegen;
  • Zeilen 88–101: Anzeige des Persistenzkontexts. Für jede verfolgte Entität ([EntityEntry]) werden ihr Name, ihr Bezeichner und ihr Zustand angezeigt, gefolgt vom aktuellen Wert jeder Eigenschaft und ihrem ursprünglichen Wert, falls dieser abweicht. Das Objekt [EntityPersister] ist dasjenige in Hibernate, das die Zuordnung zwischen einer Entität und ihrer Tabelle kennt: Es liefert die Namen der Eigenschaften und ihre Werte. Die Schleife [for ((entity, entry) in ...)] zerlegt jedes Element des Arrays, ein [Map.Entry] (Kapitel 5); [forEachIndexed] durchläuft die Namen der Eigenschaften zusammen mit ihren Indizes. Der Operator [==] zwischen zwei Werten – die [null] sein können – ersetzt das [Objects.equals] von Java. In einer Erweiterungsfunktion bezieht sich [isDirty] auf die Eigenschaft des Receivers, der Sitzung;
  • Zeilen 65–75 der Ergebnisse: Die Sitzung verfolgt das Fahrrad, dessen Bestand von 10 auf 9 gesunken ist, und den Bogen. Die Änderung am Fahrrad wird nicht gespeichert: Die Sitzung wird ohne Synchronisierung geschlossen. Es gibt kein [commit], und eine Sitzung synchronisiert sich beim Schließen nicht automatisch.

11.5.2. Die Zustände einer Entität

Eine Entität befindet sich in Bezug auf eine Sitzung in einem der folgenden Zustände (Jakarta Persistence bezeichnet sie als „new“, „managed“, „detached“ und „removed“):

Zustand
Bedeutung
transient ([TRANSIENT])
Das Objekt wurde durch einen Konstruktoraufruf erzeugt und nie registriert: Es hat keinen Bezeichner, und keine Sitzung kennt es
Verwaltet ([MANAGED])
Das Objekt wurde von der Sitzung gelesen oder gespeichert, die es verfolgt: Änderungen daran werden bei der nächsten Synchronisierung in die Datenbank übernommen
Gelöscht ([DELETED])
Das Objekt wurde zum Löschen markiert ([remove]): Die nächste Synchronisierung sendet den Befehl [DELETE]
losgelöst ([DETACHED])
Das Objekt entspricht einer Zeile der Datenbank, aber die Sitzung, die es gelesen hat, ist geschlossen oder hat es vergessen ([detach], [clear]): Seine Änderungen werden ignoriert, es sei denn, es wird mit einer Sitzung zusammengeführt ([merge])

Das Synchronisieren („Flushen“) der Sitzung sendet die SQL-Befehle an das DBMS, die die Änderungen an den verwalteten Entitäten übertragen. Dies geschieht:

  • während der [commit]-Phase der Transaktion;
  • vor der Ausführung einer Abfrage, deren Ergebnis von noch nicht übernommenen Änderungen abhängen könnte (Modus [FlushMode.AUTO], der Standardmodus): Die Abfrage sieht somit die Daten der Sitzung;
  • bei einem expliziten Aufruf von [session.flush()]. Die Befehle werden dann ausgeführt, aber erst beim [commit] der Transaktion endgültig gespeichert.

Hier ein Überblick über den Ablauf mit Hibernate: Wir öffnen eine Sitzung und eine Transaktion, lesen Entitäten, ändern sie wie gewöhnliche Objekte, fügen sie hinzu ([persist]) und löschen sie ([remove]), und bestätigen dann die Transaktion, die alle erforderlichen Befehle in einem einzigen Batch an die Datenbank sendet. Die Sitzung fungiert als „Unit of Work“. Sie ist ein leichtgewichtiges Objekt, das für eine kurze Lebensdauer gedacht ist: eine Arbeitseinheit, etwa eine HTTP-Anfrage in einer Webanwendung. Man verwendet nicht dieselbe Sitzung während der gesamten Lebensdauer einer Anwendung – sie würde die verfolgten Entitäten in ihrem Persistenzkontext ansammeln.

In Kotlin wird dieser Zyklus natürlich mit den Funktionen höherer Ordnung von Hibernate umgesetzt: [sessionFactory.inTransaction { session -> ... }] für eine vollständige Arbeitseinheit (Sitzung und Transaktion), [sessionFactory.fromTransaction { session -> ... }] wenn sie ein Ergebnis zurückgibt, und [session.inTransaction { ... }] für eine Transaktion innerhalb einer bereits geöffneten Sitzung. Kurz gesagt, sie sind die Entsprechungen der Funktion [use] für Transaktionen.

11.6. Die HQL-Abfragen

11.6.1. HQL und JPQL

Um Entitäten anders als über ihren Primärschlüssel abzurufen, werden Abfragen in einer SQL-ähnlichen Sprache geschrieben, die sich jedoch auf Entitäten und Attribute statt auf Tabellen und Spalten bezieht: HQL (Hibernate Query Language). Jakarta Persistence definiert eine ähnliche Sprache, JPQL (Jakarta Persistence Query Language), deren Obermenge HQL ist: Eine JPQL-Abfrage ist eine gültige HQL-Abfrage. Hibernate übersetzt die Abfrage in SQL im Dialekt des DBMS, und das DBMS führt sie aus.

Einige Unterschiede zu SQL:

  • Wir verwenden den Namen der Entität ([Article]), nicht den der Tabelle ([articles]), und die Namen der Attribute ([currentStock]), nicht die der Spalten. Bei Entitäts- und Attributnamen wird zwischen Groß- und Kleinschreibung unterschieden, genau wie in Kotlin. Bei unseren Kotlin-Entitäten ist der Name eines Attributs derselbe wie der der Eigenschaft (Hibernate greift auf das Feld zu, das sie speichert, und dieses Feld trägt den Namen der Eigenschaft);
  • Die Klausel [select] ist in HQL optional: [from Article] gibt Entitäten [Article] zurück. JPQL verlangt die Schreibweise [select a from Article a];
  • Beziehungen zwischen Entitäten werden mit einem Punkt durchlaufen ([p.category.name]), wobei Hibernate die Joins selbst schreibt, wie wir sehen werden.

Eine Abfrage wird von der Methode [createSelectionQuery] der Session erzeugt, die den HQL-Text und den Ergebnistyp erhält ([Article::class.java], die Java-Klasse der Entität) und ein Objekt [SelectionQuery<T>] zurückgibt. Anschließend können Sie ihren Parametern Werte zuweisen und sie ausführen mit [getResultList] (eine Liste), [getSingleResult] (ein einzelnes Ergebnis; eine Exception, wenn es keines oder mehrere gibt), [getSingleResultOrNull] ([null] , wenn es keines gibt) oder [getResultStream] (ein Stream). Wie bei allen Java-Klassen erlaubt Kotlin, diese parameterlosen Methoden [getXxx] als Eigenschaften zu schreiben: [query.resultList], [query.singleResult], [query.singleResultOrNull]. Die Methode [createQuery] von Jakarta Persistence existiert ebenfalls; sie wird sowohl für lesende Abfragen als auch für Aktualisierungen verwendet.

11.6.2. Das Programm [hql]

Das Unterprojekt [hql] enthält mehrere Abfragebeispiele. Es hat nur eine Abhängigkeit: die Bibliothek [articles] (die Hibernate, den MySQL-Treiber und das kompakte SQL-Log bereitstellt); es definiert keine Entitäten und benötigt daher weder das Plugin [jpa] noch das Plugin [allopen]:

// HQL- / JPQL-Queries
plugins {
    kotlin("jvm")
    // kein Plugin [jpa] oder [allopen]: hier keine Entität (Article wird in [articles] kompiliert)
    application
}

repositories {
    mavenCentral()
}

dependencies {
    // die Entität [Article] und die Datenbank [hbarticles] (Hibernate, MySQL und das SQL-Log eingeschlossen)
    implementation(project(":articles"))
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // das von [gradlew -q :hql:run] ausgeführte Programm
    mainClass = "hql.MainKt"
}

// unter Windows wird die Bildschirmausgabe des von Gradle gestarteten Programms (run, bootRun ...) in UTF-8 kodiert,
// sonst werden Zeichen mit Akzenten in der IntelliJ-IDEA-Konsole oder im Terminal falsch dargestellt
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}

Das Programm:

package hql

import articles.Article
import articles.BaseArticles
import org.hibernate.query.SemanticException
import java.math.BigDecimal

// HQL- / JPQL-Queries auf der Tabelle [articles]

// eine Projektion: der Name eines Artikels und der Wert seines Bestands (eine Data-Klasse, keine Entität)
data class StockValue(val name: String, val value: BigDecimal)

// eine in Kotlin geschriebene Geschäftsregel (eine Erweiterungsfunktion):
// ein Artikel ist vergriffen, wenn sein Bestand unter dem Mindestbestand liegt
fun Article.isOutOfStock() = currentStock < minimumStock

fun main() {
    BaseArticles.createSessionFactory().use { sessionFactory ->
        // die Tabelle [articles] wird mit ihren sechs Artikeln neu erstellt
        BaseArticles.initialize(sessionFactory)
        sessionFactory.openSession().use { session ->
            // 1 - Filtern und Sortieren
            println("--- the articles to restock, in alphabetical order")
            val hql = "from Article where currentStock < minimumStock order by name"
            val toOrder = session.createSelectionQuery(hql, Article::class.java).resultList
            toOrder.forEach(::println)

            // 2 - Projektion: nur die nützlichen Spalten werden angefordert
            println("--- value of the stock of each article")
            val values = session
                .createSelectionQuery(
                    """
                    select name, price * currentStock from Article
                    order by price * currentStock desc""", StockValue::class.java
                )
                .resultList
            for ((name, value) in values) {
                println("%s : %.2f euros".format(name, value))
            }

            // 3 - ein einzelnes Ergebnis; der Wert [minPrice] wird als benannter Parameter übergeben
            println("--- the first article over 200 euros")
            val minPrice = BigDecimal(200)
            val article: Article? = session
                .createSelectionQuery(
                    """
                    select a from Article a
                    where a.price > :minPrice order by a.price""", Article::class.java
                )
                .setParameter("minPrice", minPrice)
                .setMaxResults(1)
                .singleResultOrNull
            println(article ?: "none")

            // 4 - Aggregate: die Berechnung erfolgt durch das DBMS
            println("--- aggregates")
            val nbArticles = session
                .createSelectionQuery("select count(*) from Article", Long::class.java)
                .singleResult
            val stockValue = session
                .createSelectionQuery("select sum(price * currentStock) from Article", BigDecimal::class.java)
                .singleResult
            println("%d articles, value of the stock: %.2f euros".format(nbArticles, stockValue))

            // 5 - like und in; eine Kotlin-Liste als Wert eines Parameters
            println("--- like and in")
            val names = listOf("bow", "pump", "racket")
            val results = session
                .createSelectionQuery(
                    """
                    select name from Article
                    where name like 'b%' or name in :names""", String::class.java
                )
                .setParameter("names", names)
                .resultList
            println(results.joinToString(", "))

            // 6 - Paginierung: die dritte Seite mit zwei Artikeln, nach aufsteigendem Preis
            println("--- pagination")
            val pageSize = 2
            val pageNumber = 3
            val page = session.createSelectionQuery("from Article order by price", Article::class.java)
                .setFirstResult((pageNumber - 1) * pageSize)
                .setMaxResults(pageSize)
                .resultList
            val text = page.joinToString(", ") { "%s (%.2f euros)".format(it.name, it.price) }
            println("page $pageNumber : $text")

            // 7 - eine fehlerhafte Query wird abgelehnt, sobald sie erstellt wird, vor jeder Ausführung
            println("--- incorrect query")
            try {
                session.createSelectionQuery("from Article where stock < minimumStock", Article::class.java)
            } catch (e: SemanticException) {
                println("${e.javaClass.simpleName} : ${e.message}")
            }

            // 8 - eine in Kotlin geschriebene Regel kann nicht in SQL übersetzt werden: Filtern im Speicher
            println("--- in-memory filtering")
            session.createSelectionQuery("from Article", Article::class.java).resultStream.use { stream ->
                stream.filter { it.isOutOfStock() }.forEach(::println)
            }
        }
    }
}

Ergebnisse:

> gradlew -q :hql:run
--- the articles to restock, in alphabetical order
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.currentStock<a1_0.minimumStock
    SQL> order by a1_0.name
[4, arrows - set of 6, 100.00, 12, 20]
--- value of the stock of each article
    SQL> select a1_0.name, (a1_0.price*a1_0.currentStock)
    SQL> from articles a1_0
    SQL> order by (a1_0.price*a1_0.currentStock) desc
bike : 5000.00 euros
bow : 2400.00 euros
diving suit : 2400.00 euros
arrows - set of 6 : 1200.00 euros
diver's oxygen tanks : 1200.00 euros
pump : 100.00 euros
--- the first article over 200 euros
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.price>?
    SQL> order by a1_0.price
    SQL> limit ?
    SQL> -- parameter 1 = 200
    SQL> -- parameter 2 = 1
[5, diving suit, 300.00, 8, 2]
--- aggregates
    SQL> select count(*)
    SQL> from articles a1_0
    SQL> select sum((a1_0.price*a1_0.currentStock))
    SQL> from articles a1_0
6 articles, value of the stock: 12300.00 euros
--- like and in
    SQL> select a1_0.name
    SQL> from articles a1_0
    SQL> where a1_0.name like 'b%' escape '' or a1_0.name in (?, ?, ?)
    SQL> -- parameter 1 = bow
    SQL> -- parameter 2 = pump
    SQL> -- parameter 3 = racket
bike, bow, pump
--- pagination
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> order by a1_0.price
    SQL> limit ?, ?
    SQL> -- parameter 1 = 4
    SQL> -- parameter 2 = 2
page 3 : bike (500.00 euros), bow (600.00 euros)
--- incorrect query
SemanticException : Could not interpret path expression 'stock'
--- in-memory filtering
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
[4, arrows - set of 6, 100.00, 12, 20]

Kommentare:

  • Zeilen 24–26: Die Klausel [where] vergleicht zwei Attribute der Entität; die Klausel [order by] sortiert nach Name: Sie werden im SQL-Befehl zu den Klauseln [WHERE] und [ORDER BY]. Die Abfrage wird ausgeführt von [resultList] (der Methode [getResultList]), die eine [List<Article>] zurückgibt; [forEach(::println)] gibt jedes Element mit seiner Methode [toString] aus;
  • Zeilen 30–38: eine Projektion. Die Abfrage liefert keine Entitäten, sondern zwei Werte pro Element: den Namen und den Lagerwert. Das erzeugte SQL liest nur die notwendigen Spalten und führt die Berechnung selbst durch. Der Ergebnistyp ist die Datenklasse [StockValue] aus Zeile 11: Hibernate erzeugt pro Zeile ein Objekt und übergibt die Werte der Klausel [select] der Reihe nach an deren Konstruktor (der Java-Kurs verwendete ein Record). Diese Objekte sind keine Entitäten: Die Session verfolgt sie nicht. Eine Datenklasse eignet sich hervorragend für diese Rolle, und wir nutzen ihre Destrukturierung: [for ((name, value) in values)] (Zeile 37);
  • Zeilen 32–34: Die Abfrage ist als Raw String (["""..."""], Kapitel 5) geschrieben, was lesbarer ist als ein langer String in einer einzigen Zeile. Anders als Java-Textblöcke behält ein Raw String die Einrückung seiner Zeilen und den anfänglichen Zeilenumbruch bei; das spielt hier keine Rolle, da Leerzeichen und Zeilenumbrüche in HQL unerheblich sind: Ein Aufruf von [trimIndent] ist nicht nötig;
  • Zeilen 44–53: eine Abfrage, die wie in JPQL mit einem Alias ([a]) geschrieben ist. [:minPrice] ist ein benannter Parameter, dessen Wert mit [setParameter] angegeben wird. Er wird zu einem Parameter des SQL-Befehls (das [?] der Klausel [WHERE], dessen Wert das Log anzeigt): Sie müssen sich also keine Gedanken über SQL-Injections machen, da der Wert getrennt vom Befehlstext übergeben wird. Dies ist die Regel, die Kapitel 10 auf vorbereitete Anweisungen angewendet hat. [setMaxResults(1)] begrenzt das Ergebnis auf eine einzige Zeile: die Klausel [LIMIT] von MySQL. [singleResultOrNull] liefert einen [Article?]: Der Nullable-Typ besagt eindeutig, dass es kein Ergebnis geben kann, und der Elvis-Operator [?:] gibt in diesem Fall [none] aus;
  • Auf eine Kotlin-spezifische Stolperfalle sollte man unbedingt hinweisen. Ihre String-Templates legen es sehr nahe, ["... where a.price > $minPrice"] zu schreiben. Das Programm würde funktionieren, aber der Wert würde dann in den Abfragetext kopiert: Genau diese Verkettung öffnet Injections Tür und Tor (Kapitel 10), und Hibernate müsste für jeden Wert eine neue Abfrage parsen. Wir verwenden niemals das Zeichen [$] , um einen Wert in einer HQL-Abfrage zu setzen: Werte werden über benannte Parameter übergeben. Auch ein im Abfragetext geschriebener Literalwert (wie ['b%'] in Zeile 72) wird in den Text des SQL-Befehls kopiert, wie das Log zeigt: Das ist für eine Programmkonstante akzeptabel, aber niemals für einen Wert aus einer externen Quelle;
  • Zeilen 57–63: Die Aggregate [count] und [sum] werden vom DBMS berechnet: Übertragen wird nur das Ergebnis, nicht die Zeilen. [Long::class.java] bezeichnet die Klasse des primitiven Typs [long] in Java (der Kotlin-Typ [Long] wird zu [long] kompiliert), während der Java-Kurs [Long.class] verwendete, die Wrapper-Klasse [java.lang.Long]; Hibernate akzeptiert beide (die Wrapper-Klasse würde als [Long::class.javaObjectType] geschrieben). HQL kennt außerdem [avg], [min], [max] sowie die Klauseln [group by] und [having];
  • Zeilen 67–76: der Operator [like] von SQL und der Operator [in], dessen Operand ein Parameter ist, der eine Kotlin-Liste akzeptiert (eine Kotlin-[List] ist eine [java.util.List] für Hibernate): Hibernate erweitert ihn zu so vielen SQL-Parametern, wie die Liste Elemente enthält. HQL unterstützt zahlreiche Funktionen für Zeichenketten ([upper], [length], [substring] ...), Datumsangaben und Zahlen, die es in den Dialekt des DBMS übersetzt;
  • Zeilen 82–85: Paginierung, um eine lange Liste seitenweise anzuzeigen. [setFirstResult] überspringt die Einträge der vorherigen Seiten, während [setMaxResults] die der gewünschten Seite behält: die Klausel [LIMIT ?, ?] von MySQL, deren zwei Parameter 4 und 2 sind. Paginierung ist nur bei einer sortierten Liste sinnvoll ([order by]). Die Zeilen 86–87 erstellen die Seitenanzeige mit [joinToString] und dessen Transformationsfunktion (Kapitel 5);
  • Zeilen 91–94: eine Abfrage, die ein nicht vorhandenes Attribut [stock] verwendet. Der Fehler wird bereits beim Erzeugen der Abfrage erkannt, vor jeder Ausführung, weil Hibernate den HQL-Text parst und mit dem Modell abgleicht: Es wirft eine [SemanticException] (die Meldungen von Hibernate sind auf Englisch). Ein Syntaxfehler würde eine [SyntaxException] auslösen. Beachten Sie, dass der von [createSelectionQuery] zurückgegebene Wert ignoriert wird: In Kotlin muss das Ergebnis einer Funktion nicht verwendet werden;
  • Zeilen 15 und 99–100: Eine Abfrage kann keine Kotlin-Funktion verwenden, etwa die Erweiterungsfunktion [isOutOfStock]: Hibernate kennt ihren Code nicht, und selbst wenn es ihn kennen würde, wüsste es nicht unbedingt, wie man ihn als SQL schreibt. Sie können alle Entitäten lesen und im Speicher filtern: [resultStream] (die Methode [getResultStream]) liefert einen Java-[Stream<Article>], der eine JDBC-Ressource geöffnet hält und nach der Verwendung geschlossen werden muss: Die Funktion [use] übernimmt dies, da ein [Stream] ein [AutoCloseable] ist. Das Ergebnis ist korrekt, aber die gesamte Tabelle wurde übertragen (der letzte SQL-Befehl hat keine Klausel [WHERE]): Bei einer großen Tabelle sollte man das vermeiden. Besser ist es, die Bedingung in die Abfrage zu schreiben, wie in Zeile 24. Die Erweiterungsfunktion zeigt außerdem, wie „kotlinesk“ man eine Geschäftsregel für eine Entität schreiben kann, ohne ihre Klasse zu ändern (Kapitel 4).

11.6.3. Benannte Abfragen und Validierung zur Kompilierzeit

Eine in einem String geschriebene Abfrage wird erst zur Laufzeit geparst. Es gibt zwei Möglichkeiten, Fehler früher zu erkennen:

  • Benannte Abfragen: Die Annotation [@NamedQuery(name = "Article.outOfStock", query = "from Article where currentStock < minimumStock")], die auf die Entität angewendet wird, deklariert eine Abfrage, die Hibernate beim Start parst, wenn es die [SessionFactory] erzeugt. Sie wird dann über ihren Namen ausgeführt: [session.createNamedSelectionQuery("Article.outOfStock", Article::class.java)]. Sie wird in Kotlin genauso geschrieben wie in Java; die Annotation ist wiederholbar: Sie wird so oft angewendet, wie Abfragen zu deklarieren sind;
  • der Annotationsprozessor von Hibernate („Hibernate Processor“, Bibliothek [org.hibernate.orm:hibernate-processor]). In Java wird er während der Kompilierung von [javac] ausgeführt: Er prüft die Abfragen in den Annotationen und erzeugt für jede Entität eine „Metamodell“-Klasse ([Article_] für [Article]), die wir bei der Criteria-API wiedersehen werden. Dieser Mechanismus gilt nicht ausschließlich für Kotlin: Wir kommen weiter unten bei der Besprechung des statischen Metamodells darauf zurück.

11.7. Die Criteria-API

11.7.1. Mit Code erstellte Abfragen

Eine HQL-Abfrage ist ein String, der durch Verkettung (oder in Kotlin mithilfe von Templates) aufgebaut werden kann: Dieses Vorgehen ist unzuverlässig und schwer lesbar, sobald die Abfrage von vielen optionalen Kriterien abhängt (zum Beispiel einem Suchformular). Jakarta Persistence bietet eine andere Möglichkeit, Abfragen zu schreiben: die Criteria-API, bei der die Abfrage ein Baum von Objekten ist, der durch Methodenaufrufe aufgebaut wird. Hibernate übersetzt diesen Baum in SQL, genau wie eine HQL-Abfrage (es übersetzt HQL ebenfalls in einen solchen Baum). Das Unterprojekt [criteria] (seine Datei [build.gradle.kts] entspricht der des Unterprojekts [hql], abgesehen vom Programmnamen) enthält mehrere Abfragen des vorherigen Programms:

package criteria

import articles.Article
import articles.BaseArticles
import jakarta.persistence.criteria.Path
import jakarta.persistence.criteria.Predicate
import org.hibernate.Session
import java.math.BigDecimal
import kotlin.reflect.KProperty1

// mit der Criteria API erstellte Queries

// eine Projektion: der Name eines Artikels und der Wert seines Bestands
data class StockValue(val name: String, val value: BigDecimal)

// ein Attribut, bezeichnet durch eine Eigenschaftsreferenz (Article::price) und nicht durch einen String ("price"):
// der Name wird vom Compiler geprüft, und der Typ des zurückgegebenen Pfads ist der der Eigenschaft
fun <X, T> Path<X>.get(property: KProperty1<X, T>): Path<T> = get(property.name)

fun main() {
    BaseArticles.createSessionFactory().use { sessionFactory ->
        // die Tabelle [articles] wird mit ihren sechs Artikeln neu erstellt
        BaseArticles.initialize(sessionFactory)
        sessionFactory.openSession().use { session ->
            // die Factory der Query-Elemente
            val cb = session.criteriaBuilder

            // 1 - Filtern und Sortieren; die Attribute werden durch Strings bezeichnet
            println("--- the articles to restock, in alphabetical order")
            val query = cb.createQuery(Article::class.java)
            val a = query.from(Article::class.java)
            query.select(a)
                .where(cb.lt(a.get<Int>("currentStock"), a.get<Int>("minimumStock")))
                .orderBy(cb.asc(a.get<String>("name")))
            session.createSelectionQuery(query).resultList.forEach(::println)

            // 2 - Projektion auf eine Data-Klasse; die Attribute werden durch Referenzen bezeichnet
            println("--- value of the stock of each article")
            val projection = cb.createQuery(StockValue::class.java)
            val p = projection.from(Article::class.java)
            val value = cb.prod(p.get(Article::price), p.get(Article::currentStock))
                .`as`(BigDecimal::class.java)
            projection.select(cb.construct(StockValue::class.java, p.get(Article::name), value))
                .orderBy(cb.desc(value))
            for ((name, v) in session.createSelectionQuery(projection).resultList) {
                println("%s : %.2f euros".format(name, v))
            }

            // 3 - eine nach den gelieferten Kriterien erstellte Query
            println("--- search: maximum price 150 euros")
            search(session, maxPrice = BigDecimal(150)).forEach(::println)
            println("--- search: maximum price 150 euros and name starting with [d]")
            search(session, maxPrice = BigDecimal(150), nameStart = "d").forEach(::println)

            // 4 - Aggregate
            println("--- aggregates")
            val count = cb.createQuery(Long::class.java)
            count.select(cb.count(count.from(Article::class.java)))
            val nbArticles = session.createSelectionQuery(count).singleResult
            val sum = cb.createQuery(BigDecimal::class.java)
            val s = sum.from(Article::class.java)
            val articleValue = cb.prod(s.get(Article::price), s.get(Article::currentStock))
                .`as`(BigDecimal::class.java)
            sum.select(cb.sum(articleValue))
            val stockValue = session.createSelectionQuery(sum).singleResult
            println("%d articles, value of the stock: %.2f euros".format(nbArticles, stockValue))
        }
    }
}

// die Artikel, deren Preis [maxPrice] nicht übersteigt und deren Name mit [nameStart] beginnt,
// wobei jedes Kriterium nur verwendet wird, wenn es nicht null ist
fun search(session: Session, maxPrice: BigDecimal? = null, nameStart: String? = null): List<Article> {
    val cb = session.criteriaBuilder
    val query = cb.createQuery(Article::class.java)
    val a = query.from(Article::class.java)
    // die Bedingungen, eine nach der anderen hinzugefügt
    val conditions = buildList<Predicate> {
        maxPrice?.let { add(cb.le(a.get(Article::price), it)) }
        nameStart?.let { add(cb.like(a.get(Article::name), "$it%")) }
    }
    query.select(a).where(conditions).orderBy(cb.asc(a.get(Article::price)))
    return session.createSelectionQuery(query).resultList
}

Ergebnisse:

> gradlew -q :criteria:run
--- the articles to restock, in alphabetical order
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.currentStock<a1_0.minimumStock
    SQL> order by a1_0.name
[4, arrows - set of 6, 100.00, 12, 20]
--- value of the stock of each article
    SQL> select a1_0.name, (a1_0.price*a1_0.currentStock)
    SQL> from articles a1_0
    SQL> order by (a1_0.price*a1_0.currentStock) desc
bike : 5000.00 euros
bow : 2400.00 euros
diving suit : 2400.00 euros
arrows - set of 6 : 1200.00 euros
diver's oxygen tanks : 1200.00 euros
pump : 100.00 euros
--- search: maximum price 150 euros
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.price<=?
    SQL> order by a1_0.price
    SQL> -- parameter 1 = 150
[2, pump, 10.00, 10, 2]
[4, arrows - set of 6, 100.00, 12, 20]
[6, diver's oxygen tanks, 120.00, 10, 5]
--- search: maximum price 150 euros and name starting with [d]
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.price<=? and a1_0.name like ? escape ''
    SQL> order by a1_0.price
    SQL> -- parameter 1 = 150
    SQL> -- parameter 2 = d%
[6, diver's oxygen tanks, 120.00, 10, 5]
--- aggregates
    SQL> select count(a1_0.id)
    SQL> from articles a1_0
    SQL> select sum((a1_0.price*a1_0.currentStock))
    SQL> from articles a1_0
6 articles, value of the stock: 12300.00 euros

Kommentare:

  • Zeile 26: Die Session liefert einen [HibernateCriteriaBuilder] ([criteriaBuilder], die Methode [getCriteriaBuilder]), die von Hibernate erweiterte Version des [CriteriaBuilder] von Jakarta Persistence: Er ist die Fabrik für alle Elemente einer Abfrage (Bedingungen, Ausdrücke, Sortierungen);
  • Zeilen 30–34: die Abfrage des ersten Beispiels, in HQL. [createQuery(Article::class.java)] erzeugt eine Abfrage, die Artikel liefert; [from(Article::class.java)] deklariert die abgefragte Entität und liefert deren Wurzel ([Root<Article>]), die dem Alias [a] in [from Article a] entspricht; [a.get<Int>("currentStock")] bezeichnet ein Attribut. Die Bedingung wird mit [cb.lt(x, y)] („less than“, [x < y]) aufgebaut und die Sortierung mit [cb.asc(...)]. Das explizite Typargument [<Int>] (in Java: [a.<Integer>get(...)]) legt den Typ des Attributs fest, der sich aus dem String ["currentStock"] nicht bestimmen lässt. Der Compiler kann nicht überprüfen, ob er stimmt: Er verlässt sich auf unser Wort;
  • Zeile 35: Die Abfrage wird von der Session ausgeführt, wie eine HQL-Abfrage. Das erzeugte SQL ist dasselbe wie das der HQL-Abfrage;
  • Zeile 18: eine Erweiterungsfunktion der Jakarta-Persistence-Schnittstelle [Path], die ein Attribut über eine Property-Referenz ([Article::price], vom Typ [KProperty1<Article, BigDecimal>], Kapitel 7) statt über einen String anspricht. Sie reicht einfach den Namen der Property ([property.name], hier ["price"]) an die ursprüngliche Methode [get] weiter, bietet aber zwei Garantien: Der Compiler prüft, dass die Property existiert, und der Typ des zurückgegebenen Pfades ([Path<BigDecimal>]) wird ohne explizites Typargument aus dem der Property abgeleitet. Das setzt voraus, dass der JPA-Attributname dem Namen der Kotlin-Property entspricht, was bei unseren Entitäten der Fall ist;
  • Zeilen 39–46: eine Projektion auf die Datenklasse [StockValue] unter Verwendung der Erweiterungsfunktion: [p.get(Article::price)]. [cb.prod(x, y)] ist das Produkt zweier Ausdrücke; [as(BigDecimal::class.java)] legt den Ergebnistyp fest ([as] ist ein Kotlin-Schlüsselwort: Um die Java-Methode mit diesem Namen aufzurufen, wird er in Backticks gesetzt); [cb.construct(StockValue::class.java, ...)] gibt an, dass jede Ergebniszeile an den Konstruktor der Datenklasse übergeben werden muss;
  • Zeilen 73–83: Hier zeigt die Criteria-API ihren größten Nutzen. Die Funktion [search] erstellt eine Abfrage anhand der übergebenen Kriterien. Ihre Kriterien sind nullable Parameter mit Standardwert ([maxPrice: BigDecimal? = null]), was die Aufrufe mit benannten Argumenten in den Zeilen 51 und 53 ermöglicht (in Java musste [null] explizit übergeben werden). Die Liste der Bedingungen wird von [buildList] aufgebaut: Jede Bedingung wird nur hinzugefügt, wenn das entsprechende Kriterium nicht [null] ist ([maxPrice?.let { ... \}]), und die Klausel [where] erhält die gesamte Liste ([where(conditions)], eine Überladung, die mit Jakarta Persistence 3.2 eingeführt wurde), wobei die Bedingungen mit [and] verknüpft werden. Der erste Aufruf erzeugt eine Abfrage mit einer Bedingung; der zweite eine Abfrage mit zwei Bedingungen. Beachten Sie, dass Hibernate bei der Criteria-API die Werte ([150], [d%]) als Parameter im SQL-Befehl übergibt: Das Template ["$it%"] in Zeile 80 erzeugt den Wert für den Parameter (das Muster für [like]), nicht den Abfragetext;
  • Zeilen 57–64: die Aggregate [count] und [sum].

11.7.2. Das statische Metamodell

Die Schwäche der Abfragen im ersten Beispiel besteht darin, dass Attribute über Strings bezeichnet werden ([a.get<Int>("currentStock")]): Ein Tippfehler fällt erst zur Laufzeit auf, und der Compiler kennt den Typ des Attributs nicht. Um dem abzuhelfen, bietet Jakarta Persistence ein statisches Metamodell: Für jede Entität [Article] gibt es eine Klasse [Article_] , die pro Attribut ein Feld mit dessen Namen und Typ enthält. In Java schreibt man dann ***[cb.lt(a.get(Article\_.currentStock), a.get(Article\_.minimumStock))]***, was der Compiler vollständig validiert. Diese Klassen werden nicht von Hand geschrieben: Sie werden bei der Kompilierung vom Annotationsprozessor von Hibernate erzeugt. Dies ist der empfohlene Ansatz in einem Java-Projekt, das die Criteria-API verwendet.

In Kotlin ist es nicht ganz so einfach. Der Annotationsprozessor von Hibernate ist ein Java-Annotationsprozessor: Er wird von [javac] auf Java-Quellcode ausgeführt, aber unsere Entitäten werden vom Kotlin-Compiler kompiliert. Das Kotlin-Werkzeug für diese Art der Codegenerierung ist KSP (Kotlin Symbol Processing), doch Hibernate stellt keinen KSP-Prozessor bereit. Bleibt kapt („Kotlin annotation processing tool“), das Java-Prozessoren auf aus Kotlin-Code erzeugten „Stubs“ ausführt; kapt befindet sich bei JetBrains jedoch im Wartungsmodus (dort wird KSP empfohlen), verlangsamt die Kompilierung, und die Kombination aus kapt und Hibernate Processor ist keine von Hibernate dokumentierte Konfiguration. Wir verwenden es daher nicht. Die Property-Referenzen von Kotlin bieten einen Großteil des Nutzens ohne zusätzliche Werkzeuge: Mit der Erweiterungsfunktion des Programms wird ein Tippfehler zur Kompilierzeit erkannt. Hier sehen Sie, was der Compiler für [a.get(Article::stock)] meldet, kompiliert in einer Testdatei:

1
2
3
Typo.kt:9:50: error: unresolved reference 'stock'.
fun condition(a: Path<Article>) = a.get(Article::stock)
                                                 ^^^^^

(Der Compiler zeigt vorher auch die Liste der infrage kommenden Methoden [get] an, von denen keine passt.) Die Prüfung ist jedoch nicht umfassend: Eine Kotlin-Property, die kein persistentes Attribut ist (zum Beispiel eine berechnete Property), würde vom Compiler akzeptiert, aber von Hibernate zur Laufzeit abgelehnt.

Für eine feste Abfrage ist HQL lesbarer als die Criteria-API; für eine Abfrage, die je nach Umständen aufgebaut wird, ist die Criteria-API sicherer. Beides lässt sich kombinieren: Hibernate erlaubt es, aus einem HQL-String ([cb.createQuery(hql, Article::class.java)]) eine Criteria-Abfrage zu erzeugen und sie anschließend per Code zu ergänzen.

11.8. Beziehungen

11.8.1. Das Shop-Modell

Die Tabellen einer Datenbank sind miteinander verknüpft. Hibernate stellt diese Verknüpfungen als Assoziationen dar: Properties, die auf eine andere Entität oder eine Sammlung von Entitäten verweisen. Das Unterprojekt [relations] verwendet eine Datenbank [hbshop], die einen kleinen Laden mit sechs Entitäten beschreibt. Da es Entitäten definiert, wendet seine Datei [build.gradle.kts] die Plugins [jpa] und [allopen] an, genau wie die der Bibliothek [articles]; es hängt direkt von der Bibliothek [tools] (dem SQL-Log), von Hibernate und vom MySQL-Treiber ab:

// Beziehungen zwischen Entitäten: die Datenbank [hbshop]
plugins {
    kotlin("jvm")
    // der parameterlose Konstruktor der Entitäten (Plugin "no-arg", für JPA konfiguriert)
    kotlin("plugin.jpa")
    // Entitäten und Eigenschaften werden open (nicht final) gemacht: Hibernate kann Proxys davon ableiten
    kotlin("plugin.allopen")
    application
}

repositories {
    mavenCentral()
}

dependencies {
    // das kompakte SQL-Log (und Logback)
    implementation(project(":tools"))
    // Hibernate und der MySQL-JDBC-Treiber
    implementation("org.hibernate.orm:hibernate-core:7.4.5.Final")
    runtimeOnly("com.mysql:mysql-connector-j:9.7.0")
}

// die so annotierten Klassen werden vom Plugin [allopen] geöffnet
allOpen {
    annotation("jakarta.persistence.Entity")
    annotation("jakarta.persistence.MappedSuperclass")
    annotation("jakarta.persistence.Embeddable")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // das von [gradlew -q :relations:run] ausgeführte Programm
    mainClass = "relations.MainKt"
}

// unter Windows wird die Bildschirmausgabe des von Gradle gestarteten Programms (run, bootRun ...) in UTF-8 kodiert,
// sonst werden Zeichen mit Akzenten in der IntelliJ-IDEA-Konsole oder im Terminal falsch dargestellt
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}

Eine Kategorie fasst Produkte zusammen:

package relations

import jakarta.persistence.CascadeType
import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.OneToMany
import jakarta.persistence.Table

// eine Kategorie fasst mehrere Produkte zusammen (One-to-many-Beziehung)
@Entity
@Table(name = "categories")
class Category(
    @Column(nullable = false, length = 30)
    var name: String,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    // die Produkte der Kategorie: die inverse Seite der Beziehung, beschrieben durch Product.category
    @OneToMany(mappedBy = "category", cascade = [CascadeType.PERSIST])
    val products: MutableList<Product> = mutableListOf()

    // Hinzufügen eines Produkts: die beiden Seiten der Beziehung werden aktualisiert
    fun add(product: Product) {
        products += product
        product.category = this
    }
}

Ein Produkt gehört zu einer Kategorie und hat Tags:

package relations

import jakarta.persistence.CascadeType
import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.FetchType
import jakarta.persistence.ForeignKey
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.JoinColumn
import jakarta.persistence.JoinTable
import jakarta.persistence.ManyToMany
import jakarta.persistence.ManyToOne
import jakarta.persistence.Table
import java.math.BigDecimal

// ein Produkt gehört zu einer Kategorie und trägt mehrere Tags
@Entity
@Table(name = "products")
class Product(
    @Column(nullable = false, length = 30)
    var name: String,
    @Column(nullable = false, precision = 10, scale = 2)
    var price: BigDecimal,
    vararg tags: Tag,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    // Many-to-one-Beziehung: der Fremdschlüssel [category_id] der Tabelle [products]
    // [lateinit]: die Kategorie wird nach der Konstruktion durch Category.add gesetzt
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "category_id", foreignKey = ForeignKey(name = "fk_products_category"))
    lateinit var category: Category
        internal set

    // Many-to-many-Beziehung, in einer Zuordnungstabelle gespeichert
    @ManyToMany(cascade = [CascadeType.PERSIST])
    @JoinTable(
        name = "products_tags",
        joinColumns = [JoinColumn(name = "product_id")],
        inverseJoinColumns = [JoinColumn(name = "tag_id")],
        foreignKey = ForeignKey(name = "fk_products_tags_product"),
        inverseForeignKey = ForeignKey(name = "fk_products_tags_tag"),
    )
    val tags: MutableSet<Tag> = mutableSetOf()

    init {
        // nur die besitzende Seite der Beziehung wird gefüllt: sie ist diejenige, die Hibernate speichert
        this.tags += tags
    }
}

Ein Tag wird mehreren Produkten zugewiesen:

package relations

import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.ManyToMany
import jakarta.persistence.Table

// ein Tag (promo, new...) wird von mehreren Produkten getragen
@Entity
@Table(name = "tags")
class Tag(
    @Column(nullable = false, length = 20)
    var label: String,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    // die inverse Seite der durch Product.tags beschriebenen Beziehung
    @ManyToMany(mappedBy = "tags")
    val products: MutableSet<Product> = mutableSetOf()
}

Ein Kunde gibt Bestellungen auf:

package relations

import jakarta.persistence.CascadeType
import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.OneToMany
import jakarta.persistence.Table

// ein Kunde gibt Bestellungen auf
@Entity
@Table(name = "clients")
class Client(
    @Column(nullable = false, length = 30)
    var name: String,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    @OneToMany(mappedBy = "client", cascade = [CascadeType.PERSIST])
    val orders: MutableList<CustomerOrder> = mutableListOf()

    // Hinzufügen einer Bestellung: die beiden Seiten der Beziehung werden aktualisiert
    fun add(order: CustomerOrder) {
        orders += order
        order.client = this
    }
}

Eine Bestellung gehört zu einem Kunden und enthält Positionen:

package relations

import jakarta.persistence.CascadeType
import jakarta.persistence.Entity
import jakarta.persistence.FetchType
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.JoinColumn
import jakarta.persistence.ManyToOne
import jakarta.persistence.OneToMany
import jakarta.persistence.Table
import java.time.LocalDate

// eine Bestellung eines Kunden, bestehend aus Positionen
@Entity
@Table(name = "orders")
class CustomerOrder(
    var date: LocalDate,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "client_id")
    lateinit var client: Client
        internal set

    @OneToMany(mappedBy = "order", cascade = [CascadeType.PERSIST])
    val lines: MutableList<OrderLine> = mutableListOf()

    // Hinzufügen einer Position: die beiden Seiten der Beziehung werden aktualisiert
    fun add(line: OrderLine) {
        lines += line
        line.order = this
    }
}

Eine Bestellposition hat eine ID, eine Menge und zwei Many-to-one-Assoziationen – eine zu ihrer Bestellung und eine zu ihrem Produkt:

package relations

import jakarta.persistence.Entity
import jakarta.persistence.FetchType
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.JoinColumn
import jakarta.persistence.ManyToOne
import jakarta.persistence.Table

// eine Bestellposition: eine Menge eines Produkts
@Entity
@Table(name = "order_lines")
class OrderLine(
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "product_id")
    var product: Product,
    var quantity: Int,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "order_id")
    lateinit var order: CustomerOrder
        internal set
}

Sie enthält drei Arten von Assoziationen:

  • eine Many-to-one-Beziehung ([@ManyToOne]): Ein Produkt gehört zu einer Kategorie (die Property [category] von [Product]). In der Datenbank wird dies durch einen Fremdschlüssel dargestellt, die Spalte [category_id] in der Tabelle [products], wobei [@JoinColumn] den Namen und den Namen der Constraint festlegt ([fk_products_category]). [optional = false] macht die Beziehung zwingend: Die Spalte wird [NOT NULL] sein. Beachten Sie die Syntax für verschachtelte Annotationen in Kotlin: Eine Annotation, die als Argument an eine andere übergeben wird, wird ohne [@] geschrieben ([foreignKey = ForeignKey(name = ...)]), und ein Array von Annotationen wird in eckigen Klammern geschrieben ([joinColumns = [JoinColumn(name = "product_id")]]), ebenso wie das Array [cascade = [CascadeType.PERSIST]];
  • die umgekehrte One-to-many-Beziehung ([@OneToMany]): Eine Kategorie enthält mehrere Produkte (die Property [products] von [Category]). Sie erzeugt nichts in der Datenbank: [mappedBy = "category"] gibt an, dass sie durch die Property [category] der Entität [Product] beschrieben wird. [Product.category] ist die besitzende Seite der Beziehung, und [Category.products] ihre inverse Seite: Hibernate speichert den Wert der besitzenden Seite. Beide Seiten müssen jedoch im Speicher konsistent gehalten werden: Das ist die Aufgabe der Funktion [add] von [Category], die das Produkt zur Liste hinzufügt ([products += product], der Operator [+=] für eine veränderliche Collection, Kapitel 5) und dessen Kategorie setzt;
  • eine Many-to-many-Beziehung ([@ManyToMany]): Ein Produkt hat mehrere Tags, und ein Tag ist mehreren Produkten zugeordnet. Sie wird in einer Zuordnungstabelle gespeichert, [products_tags], für die [@JoinTable] den Namen, die Namen der beiden Spalten und die Namen der beiden Fremdschlüssel festlegt (die Property [tags] von [Product]). Die Gegenseite ist [Tag.products] ([mappedBy = "tags"]). Bei einer Many-to-many-Beziehung wird ein Set ([MutableSet]) einer Liste ([MutableList]) vorgezogen: Bei einer Liste löscht Hibernate bei jeder Änderung der Collection alle Zeilen der Zuordnungstabelle und fügt sie neu ein;
  • [fetch = FetchType.LAZY] fordert das Lazy Loading der Kategorie eines Produkts an: Sie wird erst gelesen, wenn sie verwendet wird. Dies ist das Standardverhalten für Collections ([@OneToMany], [@ManyToMany]), nicht aber für Beziehungen zu einer einzelnen Entität ([@ManyToOne]), die der Standard standardmäßig sofort lädt ([EAGER]): [fetch = FetchType.LAZY] wird ihnen systematisch hinzugefügt, wie es die Hibernate-Dokumentation empfiehlt;
  • [cascade = [CascadeType.PERSIST]] propagiert die Operation [persist]: Das Persistieren einer Kategorie persistiert ihre Produkte, und das Persistieren eines Produkts persistiert seine Tags. Die anderen Werte ([MERGE], [REMOVE], [ALL] ...) propagieren die übrigen Operationen.

Der Wechsel zu Kotlin erfordert einige Anmerkungen:

  • Collections werden mit den veränderlichen Schnittstellen von Kotlin deklariert, [MutableList] und [MutableSet], die mit [mutableListOf()] und [mutableSetOf()] initialisiert werden. Diese Wahl ist zwingend: Hibernate ersetzt die Collection einer von ihm gelesenen Entität durch seine eigene Collection (ein [PersistentBag] oder ein [PersistentSet]), die eine veränderliche [java.util.List] bzw. [java.util.Set] ist und bei Bedarf geladen werden kann. Eine schreibgeschützte [List] von Kotlin wäre für den Compiler akzeptabel, würde aber ein Objekt, das Hibernate und die Funktion [add] verändern, nicht zutreffend darstellen. Die Properties sind [val]: Wir verändern den Inhalt der Collection, niemals die Referenz;
  • eine Beziehung zu einer einzelnen Entität, die zwingend ist, wird als [lateinit var category: Category] deklariert (in [Product]; dasselbe gilt für [CustomerOrder.client] und [OrderLine.order]). Der Typ ist nicht nullable, weil ein registriertes Produkt immer eine Kategorie hat; im Moment seiner Erzeugung hat es aber noch keine: [Category.add] setzt sie. [lateinit] drückt genau das aus: Die Property wird später initialisiert, und ihr Lesen davor würde eine [UninitializedPropertyAccessException] auslösen, die aussagekräftiger ist als eine [NullPointerException]. Der Java-Kurs hatte sich bis dahin auf [null] gestützt. Wir hätten auch [var category: Category? = null] schreiben können, um den Preis, jedes Mal [?.] oder [!!] verwenden zu müssen;
  • der Modifizierer [internal set] unter diesen Properties beschränkt die Änderung der Kategorie eines Produkts (des Kunden einer Bestellung, der Position einer Bestellung) auf das Modul – das heißt auf das Gradle-Unterprojekt [relations]: Nur die Funktion [add] verwendet ihn. In Java war die Methode [setCategory] nur innerhalb des Pakets sichtbar; Kotlin kennt keine „Paket“-Sichtbarkeit, und [internal] ist das nächstliegende Äquivalent;
  • Die Tags eines Produkts werden über einen Parameter [vararg] an seinen Konstruktor übergeben, der keine Property ist (es gibt kein [val] oder [var]): Er wird nur im Block [init] verwendet, der sie zum Set hinzufügt. In diesem Block bezeichnet [tags] den Parameter und [this.tags] die Property; der Block [init] steht nach der Deklaration der Property, weil Initialisierungen in der Reihenfolge ausgeführt werden, in der sie im Text stehen. Der Operator [+=] fügt einer veränderlichen Collection alle Elemente eines Arrays hinzu;
  • der parameterlose Konstruktor, den das Plugin [jpa] hinzufügt (derjenige, den Hibernate zum Erzeugen der gelesenen Entitäten verwendet), führt die Initialisierungen der Properties nicht aus: Die Collection [tags] eines von Hibernate gelesenen Produkts wird daher nicht von [mutableSetOf()] erzeugt. Das ist kein Problem, denn Hibernate selbst füllt alle Assoziationen der von ihm gelesenen Entitäten mit seinen Lazy-Loading-Collections;
  • Entitäten bleiben gewöhnliche Klassen, keine Datenklassen. Beziehungen liefern dafür einen weiteren Grund: Die für eine Datenklasse erzeugten Funktionen [toString], [equals] und [hashCode] verwenden alle die Properties ihres Primärkonstruktors; würden sie Assoziationen einbeziehen, würden sie über die Lazy-Collections iterieren (und damit Abfragen oder außerhalb der Session eine [LazyInitializationException] auslösen), und zwei Entitäten, die aufeinander verweisen, würden sich endlos gegenseitig aufrufen ([StackOverflowError]);
  • Schließlich ist das Plugin [allopen] hier unverzichtbar: Für eine Lazy-Beziehung zu einer einzelnen Entität setzt Hibernate einen Proxy – ein zur Laufzeit erzeugtes Objekt einer Unterklasse der Entität – in die Property, was voraussetzt, dass die Klasse und ihre Accessoren nicht final sind. Wir sehen diesen Proxy im Programm in Aktion.

Das Objekt [Shop] konfiguriert Hibernate für die Datenbank [hbshop] und erzeugt dort einen Anfangsdatenbestand:

package relations

import org.hibernate.SessionFactory
import org.hibernate.cfg.AvailableSettings
import org.hibernate.jpa.HibernatePersistenceConfiguration
import tools.SqlLog
import java.math.BigDecimal
import java.time.LocalDate

// die Datenbank [hbshop]: Hibernate-Konfiguration und erster Datensatz
object Shop {

    // eine SessionFactory für die Datenbank [hbshop] und ihre sechs Entitäten
    fun createSessionFactory(): SessionFactory =
        HibernatePersistenceConfiguration("shop")
            .managedClasses(
                Category::class.java, Product::class.java, Tag::class.java,
                Client::class.java, CustomerOrder::class.java, OrderLine::class.java,
            )
            .jdbcUrl("jdbc:mysql://localhost:3306/hbshop?createDatabaseIfNotExist=true")
            .jdbcCredentials("root", "")
            .property(AvailableSettings.FORMAT_SQL, true)
            .createEntityManagerFactory()

    // (Neu-)Erstellung der Tabellen und eines ersten Datensatzes, ohne SQL-Log
    fun initialize(sessionFactory: SessionFactory) = SqlLog.withoutLog {
        sessionFactory.schemaManager.drop(false)
        sessionFactory.schemaManager.create(false)
        sessionFactory.inTransaction { session ->
            // zwei Tags
            val promo = Tag("promo")
            val novelty = Tag("new")
            // drei Kategorien und ihre Produkte: ein Objektgraph
            val cycles = Category("cycles")
            cycles.add(Product("bike", BigDecimal(500), promo))
            val pump = Product("pump", BigDecimal(10))
            cycles.add(pump)
            val archery = Category("archery")
            val bow = Product("bow", BigDecimal(600), novelty)
            archery.add(bow)
            archery.add(Product("arrows - set of 6", BigDecimal(100), promo, novelty))
            val diving = Category("diving")
            // die Persistierung wird an die Produkte und die Tags weitergegeben (Cascade)
            session.persist(cycles)
            session.persist(archery)
            session.persist(diving)
            // ein Kunde und seine Bestellung mit zwei Positionen
            val order = CustomerOrder(LocalDate.of(2026, 9, 28))
            order.add(OrderLine(pump, 2))
            order.add(OrderLine(bow, 1))
            val martin = Client("Martin")
            martin.add(order)
            session.persist(martin)
        }
    }
}
  • Zeile 11: Wie [BaseArticles] ersetzt ein [object] die Java-Utility-Klasse;
  • Zeilen 16–18: die sechs Entitäten, deklariert durch [managedClasses];
  • Zeile 26: Die Funktion ist ein Ausdruck: das Ergebnis von [SqlLog.withoutLog], dem die ohne (SQL-)Log auszuführende Verarbeitung übergeben wird;
  • Zeilen 31–42: ein Objektgraph: drei Kategorien, ihre Produkte und die Tags der Produkte;
  • Zeilen 44–46: Es genügt, die Kategorien zu persistieren: Dank der Kaskadierung durchläuft Hibernate die Assoziationen und persistiert alle erreichten Entitäten in der richtigen Reihenfolge (die Kategorien vor den Produkten, die auf sie verweisen), wobei es die Fremdschlüssel und die Zuordnungstabelle füllt;
  • Zeilen 48–53: ein Kunde, seine Bestellung und deren zwei Positionen, in einer einzigen Operation persistiert.

Die von Hibernate erzeugten Tabellen sind die folgenden:

> mysql -uroot hbshop -e "SHOW TABLES; SHOW CREATE TABLE products\G SHOW CREATE TABLE products_tags\G"
Tables_in_hbshop
categories
clients
order_lines
orders
products
products_tags
tags
*************************** 1. row ***************************
       Table: products
Create Table: CREATE TABLE `products` (
  `id` int NOT NULL AUTO_INCREMENT,
  `name` varchar(30) NOT NULL,
  `price` decimal(10,2) NOT NULL,
  `category_id` int NOT NULL,
  PRIMARY KEY (`id`),
  KEY `fk_products_category` (`category_id`),
  CONSTRAINT `fk_products_category` FOREIGN KEY (`category_id`) REFERENCES `categories` (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=5 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
*************************** 1. row ***************************
       Table: products_tags
Create Table: CREATE TABLE `products_tags` (
  `product_id` int NOT NULL,
  `tag_id` int NOT NULL,
  PRIMARY KEY (`product_id`,`tag_id`),
  KEY `fk_products_tags_tag` (`tag_id`),
  CONSTRAINT `fk_products_tags_product` FOREIGN KEY (`product_id`) REFERENCES `products` (`id`),
  CONSTRAINT `fk_products_tags_tag` FOREIGN KEY (`tag_id`) REFERENCES `tags` (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
  • Die Liste der Tabellen: eine Tabelle pro Entität sowie die Zuordnungstabelle [products_tags];
  • die Tabelle [products]: Ihr Fremdschlüssel [category_id] verweist auf die Tabelle [categories]. Er ist [NOT NULL] ([optional = false]). MySQL erstellt einen Index auf jedem Fremdschlüssel (Zeile [KEY]). Anders als andere ORMs verlangt Hibernate keine kaskadierende Löschung in der Datenbank ([ON DELETE CASCADE]): Diese lässt sich mit der Annotation [@OnDelete(action = OnDeleteAction.CASCADE)] erreichen;
  • Die Zuordnungstabelle hat zwei Spalten – Fremdschlüssel auf die beiden verknüpften Tabellen –, die zusammen ihren Primärschlüssel bilden.

Das Schema ist genau dasselbe wie im Java-Kurs: Die in Kotlin geschriebenen Annotationen sind identisch.

11.8.2. Das Programm

package relations

import org.hibernate.LazyInitializationException
import org.hibernate.Session
import java.math.BigDecimal
import java.time.LocalDate

// Beziehungen zwischen Entitäten: Lazy Loading, Join Fetch, Entity Graph, Joins

// die Ergebnisse der Projektions-Queries
data class ProductCategory(val product: String, val category: String)

data class OrderAmount(val id: Int, val client: String, val amount: BigDecimal)

data class CategoryStatistics(val category: String, val count: Long, val averagePrice: Double)

fun main() {
    Shop.createSessionFactory().use { sessionFactory ->
        // 1 - Erstellung der Tabellen und eines ersten Datensatzes, ohne Log
        Shop.initialize(sessionFactory)

        // 2 - ein Kunde, seine Bestellung und deren Positionen, in einem Zug hinzugefügt
        println("--- addition of a client, an order and its two lines")
        sessionFactory.inTransaction { session ->
            val bike = session.product("bike")
            val arrows = session.product("arrows - set of 6")
            val order = CustomerOrder(LocalDate.of(2026, 10, 1))
            order.add(OrderLine(bike, 1))
            order.add(OrderLine(arrows, 3))
            val client = Client("Dupont")
            client.add(order)
            session.persist(client)
            println("client no. ${client.id}, order no. ${order.id}")
        }

        // 3 - Lazy Loading: die Beziehungen werden bei Bedarf gelesen
        println("--- lazy loading")
        sessionFactory.inSession { session ->
            val orders = session
                .createSelectionQuery("from CustomerOrder order by id", CustomerOrder::class.java)
                .resultList
            for (order in orders) {
                // der Kunde und die Positionen werden erst hier bei der ersten Verwendung gelesen
                println("order no. ${order.id} : client=${order.client.name}, " +
                        "${order.lines.size} line(s)")
            }
            // die Eigenschaft [client] enthält einen Proxy: ein Objekt einer Unterklasse von Client
            println("class of the client: ${orders[0].client.javaClass.name}")
        }

        // 4 - eine nicht geladene Beziehung ist nach dem Schließen der Session nicht mehr zugänglich
        println("--- after the session is closed")
        val detachedOrder = sessionFactory.fromSession { it.find(CustomerOrder::class.java, 1) }
        try {
            println("${detachedOrder.lines.size} line(s)")
        } catch (e: LazyInitializationException) {
            println("${e.javaClass.simpleName} : ${e.message}")
        }

        // 5 - Join Fetch: die Bestellungen, ihr Kunde, ihre Positionen und ihre Produkte in einer Query
        println("--- join fetch")
        sessionFactory.inSession { session ->
            val orders = session.createSelectionQuery(
                """
                from CustomerOrder c
                join fetch c.client
                join fetch c.lines l
                join fetch l.product
                order by c.id""", CustomerOrder::class.java
            ).resultList
            for (order in orders) {
                println("order no. ${order.id} of ${order.date} for ${order.client.name}")
                for (line in order.lines) {
                    val product = line.product
                    println("  %d x %s at %.2f euros".format(line.quantity, product.name, product.price))
                }
            }
        }

        // 6 - ein Entity Graph: was mit der Entität geladen werden muss, außerhalb der Query beschrieben
        println("--- entity graph")
        val category = sessionFactory.fromSession { session ->
            val graph = session.createEntityGraph(Category::class.java)
            graph.addAttributeNodes(Category::products.name)
            session.find(graph, 2)
        }
        // die Session ist geschlossen, aber die Produkte wurden geladen
        println("${category.name} : ${category.products.joinToString(", ") { it.name }}")

        // 7 - die Many-to-many-Beziehung in einer Query
        println("--- the products on promotion")
        sessionFactory.inSession { session ->
            session.createSelectionQuery(
                """
                select p.name, p.category.name from Product p join p.tags e
                where e.label = :label order by p.name""", ProductCategory::class.java
            )
                .setParameter("label", "promo")
                .resultList
                .forEach { (product, category) -> println("$product ($category)") }
        }

        // 8 - eine Berechnung über die Beziehungen hinweg, vom DBMS durchgeführt
        println("--- amount of the orders")
        sessionFactory.inSession { session ->
            session.createSelectionQuery(
                """
                select c.id, c.client.name, sum(l.quantity * l.product.price)
                from CustomerOrder c join c.lines l
                group by c.id, c.client.name order by c.id""", OrderAmount::class.java
            )
                .resultList
                .forEach { (id, client, amount) ->
                    println("order no. %d (%s) : %.2f euros".format(id, client, amount))
                }
        }

        // 9 - eine Gruppierung: Anzahl der Produkte und Durchschnittspreis pro Kategorie
        println("--- products per category")
        sessionFactory.inSession { session ->
            session.createSelectionQuery(
                """
                select p.category.name, count(*), avg(p.price) from Product p
                group by p.category.name order by p.category.name""", CategoryStatistics::class.java
            )
                .resultList
                .forEach { (category, count, averagePrice) ->
                    println("%s : %d product(s), average price %.2f euros".format(category, count, averagePrice))
                }
        }
    }
}

// das Produkt mit dem angegebenen Namen: eine Erweiterungsfunktion der Session
fun Session.product(name: String): Product =
    createSelectionQuery("from Product where name = :name", Product::class.java)
        .setParameter("name", name)
        .singleResult

Ergebnisse:

> gradlew -q :relations:run
--- addition of a client, an order and its two lines
    SQL> -- start of transaction
    SQL> select p1_0.id, p1_0.category_id, p1_0.name, p1_0.price
    SQL> from products p1_0
    SQL> where p1_0.name=?
    SQL> -- parameter 1 = bike
    SQL> select p1_0.id, p1_0.category_id, p1_0.name, p1_0.price
    SQL> from products p1_0
    SQL> where p1_0.name=?
    SQL> -- parameter 1 = arrows - set of 6
    SQL> insert into clients (name)
    SQL> values (?)
    SQL> -- parameter 1 = Dupont
    SQL> insert into orders (client_id, date)
    SQL> values (?, ?)
    SQL> -- parameter 1 = 2
    SQL> -- parameter 2 = 2026-10-01
    SQL> insert into order_lines (order_id, product_id, quantity)
    SQL> values (?, ?, ?)
    SQL> -- parameter 1 = 2
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = 1
    SQL> insert into order_lines (order_id, product_id, quantity)
    SQL> values (?, ?, ?)
    SQL> -- parameter 1 = 2
    SQL> -- parameter 2 = 4
    SQL> -- parameter 3 = 3
client no. 2, order no. 2
    SQL> -- transaction committed (COMMIT)
--- lazy loading
    SQL> select co1_0.id, co1_0.client_id, co1_0.date
    SQL> from orders co1_0
    SQL> order by co1_0.id
    SQL> select c1_0.id, c1_0.name
    SQL> from clients c1_0
    SQL> where c1_0.id=?
    SQL> -- parameter 1 = 1
    SQL> select l1_0.order_id, l1_0.id, l1_0.product_id, l1_0.quantity
    SQL> from order_lines l1_0
    SQL> where l1_0.order_id=?
    SQL> -- parameter 1 = 1
order no. 1 : client=Martin, 2 line(s)
    SQL> select c1_0.id, c1_0.name
    SQL> from clients c1_0
    SQL> where c1_0.id=?
    SQL> -- parameter 1 = 2
    SQL> select l1_0.order_id, l1_0.id, l1_0.product_id, l1_0.quantity
    SQL> from order_lines l1_0
    SQL> where l1_0.order_id=?
    SQL> -- parameter 1 = 2
order no. 2 : client=Dupont, 2 line(s)
class of the client: relations.Client$HibernateProxy
--- after the session is closed
    SQL> select co1_0.id, co1_0.client_id, co1_0.date
    SQL> from orders co1_0
    SQL> where co1_0.id=?
    SQL> -- parameter 1 = 1
LazyInitializationException : Cannot lazily initialize collection of role 'relations.CustomerOrder.lines' with key '1' (no session)
--- join fetch
    SQL> select
    SQL>     co1_0.id,
    SQL>     co1_0.client_id,
    SQL>     c1_0.id,
    SQL>     c1_0.name,
    SQL>     co1_0.date,
    SQL>     l1_0.order_id,
    SQL>     l1_0.id,
    SQL>     l1_0.product_id,
    SQL>     p1_0.id,
    SQL>     p1_0.category_id,
    SQL>     p1_0.name,
    SQL>     p1_0.price,
    SQL>     l1_0.quantity
    SQL> from orders co1_0
    SQL> join clients c1_0 on c1_0.id=co1_0.client_id
    SQL> join order_lines l1_0 on co1_0.id=l1_0.order_id
    SQL> join products p1_0 on p1_0.id=l1_0.product_id
    SQL> order by co1_0.id
order no. 1 of 2026-09-28 for Martin
  2 x pump at 10.00 euros
  1 x bow at 600.00 euros
order no. 2 of 2026-10-01 for Dupont
  1 x bike at 500.00 euros
  3 x arrows - set of 6 at 100.00 euros
--- entity graph
    SQL> select c1_0.id, c1_0.name, p1_0.category_id, p1_0.id, p1_0.name, p1_0.price
    SQL> from categories c1_0
    SQL> left join products p1_0 on c1_0.id=p1_0.category_id
    SQL> where c1_0.id=?
    SQL> -- parameter 1 = 2
archery : bow, arrows - set of 6
--- the products on promotion
    SQL> select p1_0.name, c1_0.name
    SQL> from products p1_0
    SQL> join products_tags t1_0 on p1_0.id=t1_0.product_id
    SQL> join tags t1_1 on t1_1.id=t1_0.tag_id
    SQL> join categories c1_0 on c1_0.id=p1_0.category_id
    SQL> where t1_1.label=?
    SQL> order by p1_0.name
    SQL> -- parameter 1 = promo
arrows - set of 6 (archery)
bike (cycles)
--- amount of the orders
    SQL> select co1_0.id, c1_0.name, sum((l1_0.quantity*p1_0.price))
    SQL> from orders co1_0
    SQL> join order_lines l1_0 on co1_0.id=l1_0.order_id
    SQL> join products p1_0 on p1_0.id=l1_0.product_id
    SQL> join clients c1_0 on c1_0.id=co1_0.client_id
    SQL> group by co1_0.id, c1_0.name
    SQL> order by co1_0.id
order no. 1 (Martin) : 620.00 euros
order no. 2 (Dupont) : 800.00 euros
--- products per category
    SQL> select c1_0.name, count(*), avg(p1_0.price)
    SQL> from products p1_0
    SQL> join categories c1_0 on c1_0.id=p1_0.category_id
    SQL> group by c1_0.name
    SQL> order by c1_0.name
archery : 2 product(s), average price 350.00 euros
cycles : 2 product(s), average price 255.00 euros

Kommentare:

  • Zeilen 11–15: Die Datenklassen, die die Ergebnisse der Projektionen aufnehmen. Ihre Typen entsprechen denen, die das DBMS liefert: [Long] für [count], [Double] für [avg];
  • Zeilen 135–138: das Produkt mit dem angegebenen Namen, gelesen von einer Erweiterungsfunktion der Hibernate-Schnittstelle [Session]: In ihr wird [createSelectionQuery] auf der Session selbst aufgerufen ([this], implizit). Sie wird wie eine Methode der Session aufgerufen: [session.product("bike")] (Zeile 25), wo der Java-Code zuvor eine statische Methode [product(session, "bike")] definierte;
  • Zeilen 24–33: Ein Kunde, seine Bestellung und deren zwei Positionen werden mit einem einzigen Aufruf von [persist] persistiert. Das SQL zeigt die Reihenfolge der Einfügungen: zuerst der Kunde, dann die Bestellung – deren Fremdschlüssel [client_id] den erzeugten Schlüssel des Kunden (2) erhält – und schließlich die Positionen, deren Fremdschlüssel [order_id] den Schlüssel der Bestellung erhält. [inTransaction] erhält ein Kotlin-Lambda, wo Hibernate ein funktionales Java-Interface erwartet ([Consumer<Session>]): Das ist die SAM-Konvertierung aus Kapitel 7;
  • Zeilen 39–45: Lazy Loading. Die Abfrage liest nur die Bestellungen: Der Kunde und die Positionen jeder Bestellung werden erst gelesen, wenn das Programm sie verwendet, über zusätzliche Abfragen (zwei für die erste Bestellung, zwei für die zweite). Für den Kunden hat Hibernate einen Proxy in die Property [client] gesetzt – ein von Hibernate (mit Byte Buddy) erzeugtes Objekt einer Unterklasse von [Client] –, das nur den Bezeichner enthält und den Kunden beim ersten Aufruf eines Accessors liest ([order.client.name], d. h. [getName()]). Zeile 48 zeigt dies: Die Klasse des Objekts ist [relations.Client$HibernateProxy]. Deshalb darf eine Entität keine finale Klasse sein und ihre Accessoren keine finalen Methoden: In Kotlin, wo Klassen und Member standardmäßig final sind, macht das Plugin [allopen] sie nicht final. Bei den Positionen ist die Liste eine Hibernate-Collection, die bei der ersten Verwendung geladen wird ([size]);
  • Zeilen 53–57: Die Bestellung wird von einer Session gelesen, die sofort geschlossen wird ([fromSession], das das Ergebnis des Lambdas zurückgibt). Diese Positionen wurden nicht geladen, und nach dem Schließen der Session können sie nicht mehr geladen werden: Der Zugriff auf die Collection löst eine [LazyInitializationException] aus, eine der häufigsten Exceptions in Anwendungen, die Hibernate verwenden. Nichts im Typ [MutableList<OrderLine>] der Property weist den Kotlin-Compiler auf dieses Risiko hin: Die Typsicherheit endet dort, wo das Laden bei Bedarf beginnt. Sie müssen laden, was Sie benötigen, solange die Session geöffnet ist;
  • Zeilen 63–69: Vorabladen über eine Abfrage. [join fetch] weist Hibernate an, zusammen mit den Bestellungen ihre Kunden, ihre Positionen und das Produkt jeder Position zu laden: eine einzige Abfrage mit Joins. Die Ausgabe zeigt beide Bestellungen und ihre Positionen. Der Join mit den Positionen erzeugt pro Bestellposition eine SQL-Zeile; Hibernate leitet pro ID eine einzige Bestellung ab: Die gelieferte Liste enthält tatsächlich zwei Bestellungen. Der Abfragetext, der sich über mehrere Zeilen erstreckt, ist ein Raw String;
  • Zeilen 82–88: ein „Entity Graph“ (Jakarta Persistence) beschreibt unabhängig von jeder Abfrage, welche Assoziationen mit einer Entität geladen werden sollen: hier die Produkte der Kategorie, bezeichnet durch die Property-Referenz [Category::products.name] statt durch den String ["products"]. [session.find(graph, 2)] (Jakarta Persistence 3.2) liest die Kategorie 2 zusammen mit ihren Produkten in einer einzigen Abfrage (ein äußerer Join, [left join]). Nach dem Schließen der Session bleiben die Produkte zugänglich. Um eine Assoziation später zu laden, solange die Session geöffnet ist, verwenden Sie [Hibernate.initialize(category.products)]. Beachten Sie den Aufruf von [addAttributeNodes] (Plural) statt [addAttributeNode]: Letztere, generische Methode liefert einen *[AttributeNode<Y>]*, und Kotlin kann den Typ *[Y]* nicht ableiten, wenn das Ergebnis nicht verwendet wird („cannot infer type for type parameter 'Y'“);
  • Zeilen 95–100: Assoziationen werden in Abfragen verwendet: [join p.tags e] durchläuft die Many-to-many-Beziehung (zwei Joins, mit der Zuordnungstabelle und der Label-Tabelle), und [p.category.name] wird in einen impliziten Join mit der Kategorientabelle übersetzt. Der Text des Labels wird über einen benannten Parameter übergeben (der Java-Kurs schrieb ihn als Literal in die Abfrage); jedes Ergebnis wird in die Parameter des Lambdas entpackt: [{ (product, category) -> ... \}];
  • Zeilen 108–114: eine Berechnung über zwei Beziehungen – der Betrag jeder Bestellung –, vollständig vom DBMS ausgeführt: Joins, [sum] und [group by];
  • Zeilen 123–128: eine Gruppierung. [group by p.category.name] gruppiert die Produkte nach Kategoriename; für jede Gruppe werden die Anzahl der Produkte ([count], vom Typ [Long]) und der Durchschnittspreis ([avg], vom Typ [Double]) vom DBMS berechnet. Die Kategorie [diving], die kein Produkt hat, erscheint nicht: Der Join mit der Kategorientabelle ist ein Inner Join ([join]).

11.8.3. Das N+1-Abfrageproblem

Das Lazy Loading im Beispiel veranschaulicht ein Problem, das jeden Nutzer eines ORMs betrifft und als „N+1-Abfragen“-Problem bekannt ist: eine Abfrage, um die N Bestellungen zu lesen, dann eine Abfrage pro Bestellung, um ihren Kunden zu lesen (und eine weitere für ihre Positionen). Bei tausend Bestellungen führt das zu tausendundeinem Roundtrip zum Server, wo ein einziger genügt hätte. Das Problem ist umso heimtückischer, als es im Code unsichtbar ist: [order.client.name] sieht nicht nach einer Abfrage aus, und die Property-Syntax von Kotlin verbirgt es noch besser als der Java-Aufruf [getClient().getName()]. Die Lösungen sind die im Beispiel gezeigten: [join fetch], ein Entity Graph oder, besser noch, eine Projektion auf eine Datenklasse, die nur die notwendigen Daten abruft. Hibernate bietet außerdem das Batch-Laden an ([@BatchSize(size = 20)] , angewendet auf eine Collection oder auf die Klasse der referenzierten Entität, hier [Client]), das zum Beispiel die Kunden von zwanzig Bestellungen in einer einzigen Abfrage abruft. Das SQL-Log hilft, das Problem zu erkennen: Dieselbe Abfrage wird zahlreiche Male wiederholt.

11.9. Änderungen am Datenbankschema

11.9.1. Das Problem

Bisher wurden die Tabellen von Hibernate erstellt, nachdem sie gelöscht worden waren. Bei einer produktiven Anwendung ist das unmöglich: Ihre Datenbank enthält Daten, die erhalten bleiben müssen, wenn sich das Modell weiterentwickelt (eine neue Spalte, eine neue Tabelle). Die Datenbank muss sicher und reproduzierbar von einer Schemaversion zur nächsten migriert werden können, sowohl auf dem Rechner des Entwicklers als auch auf dem Produktionsserver. Man spricht von Schema-Migration.

Hibernate unterstützt keine Schemamigrationen: Es kann ein Schema erstellen, validieren und in begrenztem Umfang aktualisieren. Die übliche Praxis, wie sie in der JVM-Welt (sowohl in Java als auch in Kotlin) beschrieben wird, besteht darin, Migrationen an versionierte SQL-Skripte zu delegieren, die von einem dedizierten Werkzeug angewendet werden – meist Flyway oder Liquibase – und Hibernate prüfen zu lassen, ob das resultierende Schema zu den Entitäten passt.

11.9.2. Schemaverwaltung durch Hibernate

Die Eigenschaft [hibernate.hbm2ddl.auto] (oder die Methode [schemaToolingAction] in der Konfiguration, die vom folgenden Programm verwendet wird) legt fest, was Hibernate beim Erzeugen der [SessionFactory] mit dem Schema tun soll:

Wert
Konstante [Action]
Wirkung
[none]
[NONE]
keine (Standardwert)
[create-only]
[CREATE_ONLY]
Erstellen der Tabellen
[create]
[CREATE]
Löschen und anschließendes Erstellen der Tabellen
[create-drop]
[CREATE_DROP]
wie [create], plus Löschen der Tabellen beim Schließen der [SessionFactory]: für Tests
[drop]
[DROP]
Löschen der Tabellen
[validate]
[VALIDATE]
Prüfen, ob die Tabellen und Spalten der Entitäten mit kompatiblen Typen existieren; andernfalls wird eine Exception ausgelöst
[update]
[UPDATE]
Fehlende Tabellen und Spalten anlegen

Jakarta Persistence definiert eine verwandte Eigenschaft, [jakarta.persistence.schema-generation.database.action], mit den Werten [none], [create], [drop-and-create], und [drop]. Dieselben Aktionen stehen auch programmatisch zur Verfügung, wie wir es mit dem [SchemaManager] der [SessionFactory] getan haben ([create], [drop], [validate], [truncate]).

Die Option [update] ist verlockend: Hibernate vergleicht die Entitäten mit dem Datenbankschema und ergänzt, was fehlt. Sie hat jedoch Einschränkungen, die sie für eine produktive Anwendung ungeeignet machen:

  • Sie fügt nur hinzu: Sie löscht nie eine überflüssig gewordene Spalte oder Tabelle, ändert weder Typ noch Länge einer bestehenden Spalte und kann nichts umbenennen (das Umbenennen einer Property erzeugt eine neue leere Spalte, während die alte mit ihren Daten bestehen bleibt);
  • Sie kann keine Daten transformieren (eine neue Pflichtspalte füllen, eine Spalte in zwei aufteilen);
  • Was sie tut, hängt vom Zustand der vorgefundenen Datenbank ab: Es ist unmöglich, im Voraus zu wissen, welche Befehle in welcher Reihenfolge ausgeführt werden, und es wird nichts davon protokolliert.

Wir behalten daher [create], [create-drop] und [update] der Entwicklung und dem Testen vor und verwenden in der Produktion [validate] (oder [none]), wobei das Schema über Skripte verwaltet wird.

11.9.3. Versionierte SQL-Skripte

Das Prinzip skriptbasierter Migrationen ist einfach:

  • Jede Schemaänderung wird durch ein SQL-Skript beschrieben, das fortlaufend nummeriert ist: [V1__create_clients.sql], [V2__add_phone.sql] ... Sobald ein Skript auf eine Datenbank angewendet wurde, wird es nie wieder geändert: Jede Korrektur erfolgt in einem neuen Skript;
  • Die Datenbank enthält eine Verlaufstabelle, die die auf sie angewendeten Versionen auflistet;
  • Beim Start der Anwendung (oder während der Bereitstellung) vergleicht ein Werkzeug die verfügbaren Skripte mit dem Verlauf und wendet der Reihe nach diejenigen an, die noch nicht angewendet wurden.

Die Skripte sind Teil des Quellcodes der Anwendung: Sie werden zusammen mit dem übrigen Code gespeichert und verwaltet (zum Beispiel in einem Git-Repository). Um zu verstehen, wie das funktioniert, implementiert das Unterprojekt [clients] einen kleinen Runner für versionierte Skripte nach dem Vorbild von Flyway; anschließend stellen wir Flyway selbst vor.

11.9.4. Das [clients]-Unterprojekt

Das Unterprojekt [clients] verwendet die Datenbank [hbclients]. Es hat zwei Programme: [clients.MainKt], das standardmäßig läuft, und [clients.GenerateScriptKt], das bei Bedarf über die Eigenschaft [main] angegeben wird, wie in den vorherigen Kapiteln. Seine Datei [build.gradle.kts] ist dieselbe wie die des Unterprojekts [relations], mit einer Ausnahme:

1
2
3
4
5
application {
    // das von [gradlew -q :clients:run] ausgeführte Programm: standardmäßig clients.MainKt,
    // oder das durch die Eigenschaft [main] angegebene: gradlew -q :clients:run -Pmain=clients.GenerateScriptKt
    mainClass = providers.gradleProperty("main").orElse("clients.MainKt")
}

Die Entität ist ein Kunde:

package clients

import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.Table

// ein Kunde
@Entity
@Table(name = "clients")
class Client(
    @Column(nullable = false, length = 50)
    var name: String,
    @Column(nullable = false, length = 100)
    var email: String,
    // Version 2: das Telefon, optional (Typ String? und eine Spalte, die NULL akzeptiert)
    @Column(length = 20)
    var phone: String? = null,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    override fun toString() = "[$id, $name, $email, ${phone ?: "no phone"}]"
}

In der ersten Version der Anwendung hat der Kunde keine Telefonnummer: Die Zeilen 18–20 existieren noch nicht. Wir fügen sie in der zweiten Version hinzu. Die Telefonnummer ist optional, was Kotlin mit dem Nullable-Typ [String?] und dem Standardwert [null] ausdrückt (so können wir einen Kunden ohne Telefonnummer anlegen: [Client("Durand", "durand@example.com")]). Hibernate kennt die Kotlin-Typen jedoch nicht: Es ist das Fehlen von ***[nullable = false] in *[@Column] , das die Spalte optional macht (umgekehrt erzeugt ein nicht nullbarer Kotlin-[String] nur dann eine Spalte [NOT NULL], wenn dies ausdrücklich verlangt wird, wie bei [name] und [email]). Die Funktion [toString] (Zeile 27) verwendet den Elvis-Operator, um das Fehlen einer Telefonnummer anzuzeigen.

Die Skripte befinden sich im Ordner [src/main/resources/db/migration] des Unterprojekts, den Gradle in den Classpath kopiert (in den Ordner [build/resources/main]). Es sind die Skripte aus dem Java-Kurs: Ein SQL-Skript hängt nicht von der Programmiersprache der Anwendung ab. Das erste erstellt die Tabelle:

1
2
3
4
5
6
7
-- Version 1: die Kundentabelle
create table clients (
    id integer not null auto_increment,
    name varchar(50) not null,
    email varchar(100) not null,
    primary key (id)
) engine=InnoDB;

Das zweite fügt die Spalte für die Telefonnummer hinzu:

1
2
3
-- Version 2: das (optionale) Telefon der Kunden
alter table clients
    add column phone varchar(20);

Die Klasse [Migrations] wendet die Skripte mit JDBC (Kapitel 10) unabhängig von Hibernate an:

package clients

import java.nio.file.Path
import java.sql.Connection
import java.sql.DriverManager
import java.sql.SQLException
import kotlin.io.path.listDirectoryEntries
import kotlin.io.path.name
import kotlin.io.path.readLines

// ein kleiner Runner für versionierte SQL-Skripte nach dem Vorbild von Flyway: die Skripte
// [db/migration/V<version>__<description>.sql] werden nur einmal angewendet, in der Reihenfolge der Versionen,
// und die Tabelle [migration_history] der Datenbank verzeichnet die bereits angewendeten
class Migrations(
    private val url: String,
    private val user: String,
    private val password: String,
) {
    // ein Migrationsskript
    data class Script(val version: Int, val description: String, val path: Path) {
        override fun toString() = "V$version ($description)"
    }

    private companion object {
        // der Name eines Skripts: V1__create_clients.sql
        val NAME = Regex("""V(\d+)__(\w+)\.sql""")

        // die Verlaufstabelle
        const val CREATE_HISTORY = """
            create table if not exists migration_history (
                version integer not null primary key,
                description varchar(100) not null,
                applied_on datetime not null default current_timestamp
            ) engine=InnoDB"""
    }

    // eine Verbindung zur Datenbank
    private fun connection(): Connection = DriverManager.getConnection(url, user, password)

    // die Skripte des Ordners [db/migration] im Classpath, in Versionsreihenfolge
    fun scripts(): List<Script> {
        val folder = Migrations::class.java.getResource("/db/migration") ?: return emptyList()
        return Path.of(folder.toURI()).listDirectoryEntries()
            .mapNotNull { file ->
                // die Dateien, deren Name nicht der Konvention folgt, werden ignoriert (null)
                NAME.matchEntire(file.name)?.destructured?.let { (version, description) ->
                    Script(version.toInt(), description.replace('_', ' '), file)
                }
            }
            .sortedBy { it.version }
    }

    // die bereits auf die Datenbank angewendeten Versionen (die Verlaufstabelle wird bei Bedarf erstellt)
    fun appliedVersions(): Set<Int> = connection().use { cnx ->
        cnx.createStatement().use { statement ->
            statement.execute(CREATE_HISTORY)
            statement.executeQuery("select version from migration_history").use { rows ->
                sortedSetOf<Int>().apply {
                    while (rows.next()) add(rows.getInt(1))
                }
            }
        }
    }

    // die noch anzuwendenden Skripte
    fun pending(): List<Script> {
        val applied = appliedVersions()
        return scripts().filter { it.version !in applied }
    }

    // Anwendung der ausstehenden Skripte bis einschließlich Version [target]; die angewendeten Skripte werden zurückgegeben
    fun migrate(target: Int = Int.MAX_VALUE): List<Script> =
        pending().takeWhile { it.version <= target }.onEach { applyScript(it) }

    // Anwendung eines Skripts und Eintragen seiner Version in den Verlauf, in einer Transaktion
    private fun applyScript(script: Script) {
        // die Anweisungen des Skripts, durch Semikolons getrennt, ohne die Kommentarzeilen
        val statements = script.path.readLines()
            .filterNot { it.trim().startsWith("--") }
            .joinToString("\n")
            .split(";")
            .filter { it.isNotBlank() }
        connection().use { cnx ->
            cnx.autoCommit = false
            try {
                cnx.createStatement().use { statement -> statements.forEach { statement.execute(it) } }
                cnx.prepareStatement("insert into migration_history(version, description) values (?, ?)")
                    .use { history ->
                        history.setInt(1, script.version)
                        history.setString(2, script.description)
                        history.executeUpdate()
                    }
                cnx.commit()
            } catch (e: SQLException) {
                // Achtung: bei MySQL kann eine Anweisung zur Schemaänderung nicht zurückgesetzt werden
                cnx.rollback()
                throw e
            }
        }
    }
}
  • Zeilen 14–17: Die Datenbank wird durch die privaten Properties des Primärkonstruktors beschrieben;
  • Zeilen 20–21: Ein Skript wird durch eine verschachtelte Datenklasse beschrieben, [Migrations.Script]: seine Version, seine Beschreibung und sein Pfad; ihre Methode [toString] wird für die Anzeige überschrieben;
  • Zeilen 24–34: die Klassenkonstanten in einem privaten Companion Object. Zeile 26: Der Name eines Skripts folgt der Flyway-Konvention: [V] – die Versionsnummer, zwei Unterstriche und eine Beschreibung. Der reguläre Ausdruck ist als Raw String geschrieben, in dem der Backslash nicht verdoppelt werden muss (["""V(\d+)__(\w+)\.sql"""]; in Java: ["V(\\d+)__(\\w+)\\.sql"]). Die Verlaufstabelle (eine Zeile pro angewendeter Version, mit ihrer Beschreibung und dem Datum der Anwendung) wird durch einen als Raw String geschriebenen Befehl erstellt, eine Konstante [const val];
  • Zeilen 41–50: die Liste der Skripte. [getResource("/db/migration")] liefert die URL des Verzeichnisses im Classpath oder [null] , falls es nicht existiert: Der Elvis-Operator gibt dann sofort eine leere Liste zurück ([?: return emptyList()]). Das Verzeichnis wird von der Erweiterungsfunktion [listDirectoryEntries] von [kotlin.io.path] aufgelistet (Kapitel 5). Jede Datei wird von [matchEntire] gegen den regulären Ausdruck geprüft, das [null] zurückgibt, wenn der Name nicht passt: [mapNotNull] filtert diese Dateien heraus, und die Gruppen des Ausdrucks werden per Destrukturierung abgerufen ([destructured], Kapitel 5). Dieser Code setzt voraus, dass das Verzeichnis ein echtes Verzeichnis ist (was der Fall ist, wenn das Programm von Gradle aus dem Verzeichnis [build/resources/main] gestartet wird); Flyway kann Skripte auch aus einem [.jar]-Archiv lesen. Die Skripte werden nach Versionsnummer sortiert ([sortedBy]): Eine alphabetische Sortierung würde [V10] vor [V2] einordnen;
  • Zeilen 54–59: Die bereits angewendeten Versionen, abgerufen aus der Verlaufstabelle, die bei Bedarf erstellt wird ([create table if not exists]). Die drei JDBC-Ressourcen (Verbindung, Statement, Ergebnisse) werden von drei verschachtelten [use]-Ressourcen geschlossen. Die Funktion gibt eine sortierte Menge zurück ([sortedSetOf], ein Java-[TreeSet]), die von [apply] befüllt wird;
  • Zeilen 66–68: die noch anzuwendenden Skripte: Der Operator [!in] prüft, ob eine Version in der Menge fehlt;
  • Zeilen 72–73: Anwenden der ausstehenden Skripte bis zu einer bestimmten Version (standardmäßig alle: [target: Int = Int.MAX_VALUE]). [takeWhile] behält die Skripte, solange ihre Version das Ziel nicht überschreitet; [onEach] wendet jedes von ihnen an und gibt die Liste selbst zurück: Die Funktion passt in einen einzigen Ausdruck, wohingegen Java eine Schleife mit [break] geschrieben hätte;
  • Zeilen 76–97: Anwenden eines Skripts: seine Befehle (Kommentarzeilen werden von [filterNot] entfernt, der Text an Semikolons aufgeteilt), anschließend das Eintragen seiner Version in die Verlaufstabelle, innerhalb einer Transaktion ([cnx.autoCommit = false], die Kotlin-Property, die [setAutoCommit] entspricht). Eine Einschränkung, die im Kommentar in Zeile 95 vermerkt ist: Unter MySQL führt ein Befehl zur Schemaänderung ([CREATE TABLE], [ALTER TABLE]) implizit ein Commit der laufenden Transaktion aus und kann nicht zurückgerollt werden. Tritt mitten in einem Skript ein Fehler auf, kann die Datenbank in einem Zwischenzustand verbleiben. Deshalb empfiehlt es sich, kurze Skripte zu verwenden, die jeweils nur eine Operation ausführen.

Beachten Sie, dass keine Funktion der Klasse die Exceptions deklariert, die sie auslösen kann: Die Java-Version musste [throws SQLException, IOException, URISyntaxException] bei den meisten ihrer Methoden angeben, ebenso bei der Methode [main], die sie aufruft. Kotlin kennt keine geprüften Exceptions (Kapitel 3): Eine [SQLException] wird einfach bis zu demjenigen weitergereicht, der sie behandeln möchte.

Das Hauptprogramm wendet die Migrationen an und lässt dann Hibernate das Schema validieren:

package clients

import jakarta.persistence.PersistenceException
import org.hibernate.cfg.AvailableSettings
import org.hibernate.jpa.HibernatePersistenceConfiguration
import org.hibernate.tool.schema.Action

// die Datenbank clients; MySQL erstellt sie, falls sie nicht existiert
const val URL = "jdbc:mysql://localhost:3306/hbclients?createDatabaseIfNotExist=true"

fun main(args: Array<String>) {
    // die angestrebte Version: standardmäßig die letzte oder die als Argument übergebene
    val target = args.firstOrNull()?.toInt() ?: Int.MAX_VALUE

    // der Zustand der Migrationen
    val migrations = Migrations(URL, "root", "")
    println("applied versions: ${migrations.appliedVersions()}")
    println("pending migrations: ${migrations.pending()}")

    // Anwendung der ausstehenden Migrationen
    for (script in migrations.migrate(target)) {
        println("migration applied: $script")
    }

    // Hibernate prüft, ob das Datenbankschema zu den Entitäten passt (validate)
    try {
        HibernatePersistenceConfiguration("clients")
            .managedClass(Client::class.java)
            .jdbcUrl(URL)
            .jdbcCredentials("root", "")
            .property(AvailableSettings.FORMAT_SQL, true)
            .schemaToolingAction(Action.VALIDATE)
            .createEntityManagerFactory()
            .use { sessionFactory ->
                println("the database schema matches the entities")
                // die neue Spalte ist verwendbar
                sessionFactory.inTransaction { session ->
                    session.persist(Client("Dupont", "dupont@example.com", "01 23 45 67 89"))
                }
                sessionFactory.inSession { session ->
                    session.createSelectionQuery("from Client", Client::class.java)
                        .resultList
                        .forEach(::println)
                }
            }
    } catch (e: PersistenceException) {
        // der Validierungsfehler ist die Ursache der Exception
        val cause = e.cause ?: e
        println("${cause.javaClass.simpleName} : ${cause.message}")
    }
}
  • Zeile 9: die URL der Datenbank, eine Konstante auf oberster Ebene im Paket [clients], die auch das zweite Programm verwenden wird;
  • Zeile 13: Sie können als Argument die Version angeben, bis zu der die Migrationen angewendet werden sollen; standardmäßig werden alle angewendet. [args.firstOrNull()?.toInt() ?: Int.MAX_VALUE] kombiniert den Safe-Call-Operator und den Elvis-Operator;
  • Zeilen 16–22: der Status der Migrationen, gefolgt von ihrer Anwendung;
  • Zeilen 27–34: Die [SessionFactory] wird mit der Aktion [VALIDATE] erzeugt: Hibernate prüft, ob das Datenbankschema zur Entität [Client] passt. Ist das nicht der Fall, schlägt die Erzeugung der [SessionFactory] mit einer [PersistenceException] fehl, deren Ursache der Validierungsfehler ist (Zeilen 46–49). [e.cause ?: e] fängt die Ursache ab, oder die Exception selbst, wenn sie keine hat;
  • Zeilen 37–43: Die neue Spalte wird verwendet.

11.9.5. Skripte mit Hibernate erzeugen

Die SQL-Skripte werden von Hand geschrieben. Hibernate kann jedoch beim Schreiben helfen: Es kann – ohne es auszuführen – das Skript zum Erstellen des Schemas erzeugen oder, indem es die Entitäten mit einer bestehenden Datenbank vergleicht, das Skript zu deren Aktualisierung. Genau das tut das Programm [GenerateScript.kt]:

package clients

import org.hibernate.cfg.AvailableSettings
import org.hibernate.jpa.HibernatePersistenceConfiguration
import java.io.StringWriter

// Erzeugung des SQL-Skripts, das das Datenbankschema erstellt (create) oder aktualisiert (update), durch Hibernate
fun main(args: Array<String>) {
    // die Aktion: create (standardmäßig) oder update
    val action = args.firstOrNull() ?: "create"
    val script = StringWriter()
    // eine SessionFactory, die das Skript schreibt, ohne es auszuführen; sie wird nur dafür erstellt:
    // sie wird sofort geschlossen
    HibernatePersistenceConfiguration("clients")
        .managedClass(Client::class.java)
        .jdbcUrl(URL)
        .jdbcCredentials("root", "")
        .property(AvailableSettings.JAKARTA_HBM2DDL_SCRIPTS_ACTION, action)
        .property(AvailableSettings.JAKARTA_HBM2DDL_SCRIPTS_CREATE_TARGET, script)
        .property(AvailableSettings.HBM2DDL_DELIMITER, ";")
        .property(AvailableSettings.FORMAT_SQL, true)
        .createEntityManagerFactory()
        .close()
    // das Skript, ohne die Einrückung von 4 Leerzeichen seiner Zeilen
    script.toString().trim().lines()
        .map { it.removePrefix("    ").trimEnd() }
        .forEach(::println)
}
  • Zeile 10: die Aktion, die als Argument übergeben wird: [create] oder [update];
  • Zeilen 14–23: Die [SessionFactory] wird allein zum Erzeugen des Skripts angelegt: Sie wird unmittelbar nach der Erzeugung geschlossen, ohne überhaupt in einer Variablen gespeichert zu werden (der Java-Kurs deklarierte sie in einer [try]-Anweisung mit Ressourcen und verwendete die anonyme Java-Variable [_] ab Java 22);
  • Zeilen 18–21: die Eigenschaften zur Skripterzeugung, die wir bereits im Unterprojekt [model] kennengelernt haben. Diesmal verbindet sich Hibernate mit der Datenbank: Für die Aktion [update] muss es deren Schema kennen;
  • Zeilen 25–27: das Skript, dessen Zeilen von der 4-Leerzeichen-Einrückung befreit werden durch [removePrefix], das das Präfix nur entfernt, wenn es vorhanden ist.

Beachten Sie, dass die beiden Programme des Unterprojekts jeweils eine Funktion [main] auf oberster Ebene haben im selben Paket: Das ist für die Funktion [main] erlaubt, da jede in ihre eigene Dateiklasse kompiliert wird ([clients.MainKt], [clients.GenerateScriptKt]).

Das Erstellungsskript, das aus der aktuellen Version der Entität erzeugt wird, dient dazu, eine neue Datenbank auf einmal anzulegen (zum Beispiel für Tests):

1
2
3
4
5
6
7
8
> gradlew -q :clients:run -Pmain=clients.GenerateScriptKt
create table clients (
    id integer not null auto_increment,
    phone varchar(20),
    name varchar(50) not null,
    email varchar(100) not null,
    primary key (id)
) engine=InnoDB;

Mit der ersten Version der Entität (ohne Telefonnummer) hätte es in derselben Spaltenreihenfolge das Skript [V1__create_clients.sql] ergeben.

11.9.6. Die Migrationen anwenden

Nehmen wir an, die Datenbank existiert noch nicht. Wir wenden nur die erste Migration an und übergeben die Version 1 als Argument (Option [--args] der Task [run]):

1
2
3
4
5
> gradlew -q :clients:run --args="1"
applied versions: []
pending migrations: [V1 (create clients), V2 (add phone)]
migration applied: V1 (create clients)
SchemaManagementException : Schema validation: missing column [phone] in table [clients]
  • Keine Version ist angewendet; zwei Skripte stehen aus (die Kotlin-Liste wird genauso angezeigt wie die Java-Liste, in eckigen Klammern). Die Verlaufstabelle wurde von der Funktion [appliedVersions] erstellt und die Datenbank [hbclients] von MySQL ([createDatabaseIfNotExist=true]);
  • Das Skript [V1] wird angewendet;
  • Hibernate stellt fest, dass die Spalte [phone] der Entität in der Tabelle nicht existiert: Das ist normal, da die Datenbank den Stand von Version 1 hat und die Entität den von Version 2. Mit der Entität in Version 1 wäre die Validierung erfolgreich gewesen.

Die Anwendung entwickelt sich weiter: Wir fügen der Entität die Telefonnummer hinzu. Um das Skript für Version 2 zu schreiben, lassen wir Hibernate die Entität mit der Datenbank vergleichen, die sich noch auf Version 1 befindet:

1
2
3
> gradlew -q :clients:run -Pmain=clients.GenerateScriptKt --args="update"
alter table clients
   add column phone varchar(20);

Das ist, abgesehen von der Formatierung, dasselbe wie das Skript [V2__add_phone.sql]. Wir wenden nun alle ausstehenden Migrationen an:

> gradlew -q :clients:run
applied versions: [1]
pending migrations: [V2 (add phone)]
migration applied: V2 (add phone)
the database schema matches the entities
    SQL> -- start of transaction
    SQL> insert into clients (email, name, phone)
    SQL> values (?, ?, ?)
    SQL> -- parameter 1 = dupont@example.com
    SQL> -- parameter 2 = Dupont
    SQL> -- parameter 3 = 01 23 45 67 89
    SQL> -- transaction committed (COMMIT)
    SQL> select c1_0.id, c1_0.email, c1_0.name, c1_0.phone
    SQL> from clients c1_0
[1, Dupont, dupont@example.com, 01 23 45 67 89]
  • Version 1 ist angewendet, Version 2 steht aus und wird angewendet;
  • Die Validierung ist erfolgreich;
  • Die neue Spalte ist einsatzbereit: Der Kunde wird mit seiner Telefonnummer gespeichert und anschließend abgerufen.

Die Verlaufstabelle enthält nun beide Versionen:

1
2
3
4
5
6
7
> mysql -uroot -t hbclients -e "SELECT * FROM migration_history"
+---------+----------------+---------------------+
| version | description    | applied_on          |
+---------+----------------+---------------------+
|       1 | create clients | 2026-10-04 10:55:57 |
|       2 | add phone      | 2026-10-04 10:56:18 |
+---------+----------------+---------------------+

Ein erneuter Programmlauf wendet nichts an: Beide Versionen stehen im Verlauf (er fügt allerdings einen zweiten Kunden namens Dupont hinzu, den wir nicht anzeigen):

1
2
3
4
> gradlew -q :clients:run
applied versions: [1, 2]
pending migrations: []
the database schema matches the entities

11.9.7. Flyway

Flyway ist das am weitesten verbreitete Migrationswerkzeug der JVM-Welt (Spring Boot führt es beim Start einer Anwendung automatisch aus, wenn es im Classpath vorhanden ist). Es arbeitet exakt nach demselben Prinzip wie unser Executor, ist aber umfassender: [V<version>__<description>.sql]-Skripte werden standardmäßig im Ordner [db/migration] des Classpath gesucht, die Verlaufstabelle [flyway_schema_history] wird verwendet, und ausstehende Skripte werden in der Reihenfolge der Versionen angewendet. Es ergänzt insbesondere eine Prüfsumme für jedes Skript, wodurch Änderungen an einem bereits angewendeten Skript erkannt werden; „wiederholbare“ Skripte ([R__description.sql], die bei jeder Änderung erneut angewendet werden, zum Beispiel für Views); in der Sprache der Anwendung geschriebene Migrationen (Java- oder Kotlin-Klassen); eine Sperre, die verhindert, dass zwei Instanzen der Anwendung die Datenbank gleichzeitig migrieren, sowie ein Gradle-Plugin (Tasks [flywayMigrate], [flywayInfo]).

Um es im Unterprojekt [clients] zu verwenden, fügen Sie einfach die Abhängigkeiten [org.flywaydb:flyway-core] und [org.flywaydb:flyway-mysql] (in ihren neuesten Versionen) zur Datei [build.gradle.kts] hinzu, behalten beide Skripte unverändert bei – da sie bereits seiner Konvention folgen – und ersetzen die Verwendung der Klasse [Migrations] durch eine einzige Zeile: [Flyway.configure().dataSource(URL, "root", "").load().migrate()].

Liquibase, das andere häufig verwendete Werkzeug, beschreibt Schemaänderungen in XML-, YAML- oder SQL-Dateien (den „Changelogs“) und kann das für das jeweilige DBMS spezifische SQL erzeugen. In beiden Fällen wird Hibernate mit [validate] oder [none] konfiguriert und ändert das Schema nicht mehr.

11.10. Hibernate und Virtual Threads

Eine Datenbankabfrage ist eine E/A-Operation: Während der Server die Anfrage verarbeitet, tut der wartende Thread nichts. Die Kapitel 8 und 9 haben zwei Möglichkeiten vorgestellt, bei diesen Wartezeiten keine Threads zu verschwenden: die Virtual Threads des JDK und die Kotlin-Coroutines. Die API von Hibernate ist, wie das von ihr verwendete JDBC, blockierend: [getResultList] (in Kotlin die Property [resultList]) gibt die Kontrolle erst zurück, wenn die Zeilen gelesen wurden. Mit Virtual Threads ist das kein Nachteil mehr: Ein auf E/A blockierter Virtual Thread gibt den System-Thread frei, der ihn ausführte, und man kann Tausende davon erzeugen. Man schreibt also gewöhnlichen blockierenden Code, der von Virtual Threads ausgeführt wird. Bei Coroutines vertrauen wir diesen blockierenden Code ebenfalls einem für E/A ausgelegten Dispatcher an, [Dispatchers.IO] (Kapitel 9), und zwar mit [withContext]: Die auf das Ergebnis wartende Coroutine wird suspendiert, ohne ihren Thread zu blockieren.

In beiden Fällen muss eine Regel beachtet werden: Eine Session ist nicht threadsicher. Sie wird niemals von mehreren Threads oder mehreren Coroutines gemeinsam genutzt: Jeder Thread, jede Task und jede Coroutine öffnet ihre eigene Session mit der [SessionFactory], die ihrerseits gemeinsam genutzt wird. Bei Coroutines erfordert diese Regel besondere Aufmerksamkeit: Eine Coroutine kann nach einer Suspendierung auf einem anderen Thread weiterlaufen als dem, auf dem sie gestartet wurde; eine vor einem suspendierenden Aufruf geöffnete und danach verwendete Session würde daher den Thread wechseln. Am einfachsten öffnet und schließt man die Session innerhalb des Blocks [withContext], der keine Suspendierungspunkte enthält. Hibernate erkennt die gleichzeitige Verwendung derselben Session nicht immer; die daraus resultierenden Fehler sind unvorhersehbar.

Das Unterprojekt [async] setzt diese Regel um. Zusätzlich zur Bibliothek [articles] hängt es von kotlinx-coroutines ab:

// Hibernate, virtuelle Threads und Coroutinen
plugins {
    kotlin("jvm")
    // kein Plugin [jpa] oder [allopen]: das Modul definiert keine Entität (Article wird in [articles] kompiliert)
    application
}

repositories {
    mavenCentral()
}

dependencies {
    // die Entität [Article] und die Datenbank [hbarticles] (Hibernate, MySQL und das SQL-Log eingeschlossen)
    implementation(project(":articles"))
    // Coroutinen (Kapitel 9)
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // das von [gradlew -q :async:run] ausgeführte Programm
    mainClass = "async.MainKt"
}

// unter Windows wird die Bildschirmausgabe des von Gradle gestarteten Programms (run, bootRun ...) in UTF-8 kodiert,
// sonst werden Zeichen mit Akzenten in der IntelliJ-IDEA-Konsole oder im Terminal falsch dargestellt
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • Zeile 14: die Entität [Article] und die Datenbank [hbarticles], wie in den vorherigen Beispielen;
  • Zeile 16: die Coroutines-Bibliothek (Kapitel 9);
  • Zeilen 32–35: Die von Gradle gestarteten Programme schreiben ihre Ausgabe in UTF-8, damit Zeichen mit Akzenten unter Windows korrekt angezeigt werden (Kapitel 2).

Das Programm:

package async

import articles.Article
import articles.BaseArticles
import jakarta.persistence.QueryTimeoutException
import java.math.BigDecimal
import java.util.concurrent.CompletableFuture
import java.util.concurrent.Executors
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.async
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withContext
import org.hibernate.SessionFactory

// Hibernate (eine blockierende API) mit virtuellen Threads, dann mit Coroutinen
fun main() {
    BaseArticles.createSessionFactory().use { sessionFactory ->
        // die Tabelle [articles] wird mit ihren sechs Artikeln neu erstellt
        BaseArticles.initialize(sessionFactory)

        // 1 - zwei Queries, gleichzeitig von zwei virtuellen Threads ausgeführt, jede mit ihrer Session
        println("--- two queries in parallel")
        Executors.newVirtualThreadPerTaskExecutor().use { executor ->
            val lowPrices = executor.submit<List<Article>> {
                sessionFactory.fromSession { s ->
                    s.createSelectionQuery("from Article where price < 200 order by price", Article::class.java)
                        .resultList
                }
            }
            val hql = "select count(*) from Article where currentStock < minimumStock"
            val outOfStock = executor.submit<Long> {
                sessionFactory.fromSession { s ->
                    s.createSelectionQuery(hql, Long::class.java).singleResult
                }
            }
            // get() wartet auf das Ende jedes Tasks
            lowPrices.get().forEach { println(it) }
            println("${outOfStock.get()} article(s) out of stock")
        }

        // 2 - eine von einem virtuellen Thread ausgeführte Transaktion, gefolgt von einer Verarbeitung ihres Ergebnisses
        println("--- CompletableFuture")
        Executors.newVirtualThreadPerTaskExecutor().use { executor ->
            val processing = CompletableFuture
                .supplyAsync({
                    sessionFactory.fromTransaction { session ->
                        session.createSelectionQuery("from Article where name = 'bow'", Article::class.java)
                            .singleResult
                            .apply { price = BigDecimal.valueOf(550) }
                    }
                }, executor)
                .thenAccept { bow -> println("new price of the bow: ${bow.price}") }
            processing.join()
        }

        // 3 - Coroutinen: jede führt eine suspendierende Funktion aus, die ihre eigene Session öffnet
        println("--- coroutines")
        runBlocking {
            // zwei Kind-Coroutinen von runBlocking, gleichzeitig ausgeführt
            val cheap = async {
                countArticles(sessionFactory, "select count(*) from Article where price < 200")
            }
            val expensive = async {
                countArticles(sessionFactory, "select count(*) from Article where price >= 200")
            }
            // await() setzt die Haupt-Coroutine bis zum Ergebnis jeder Kind-Coroutine aus
            println("${cheap.await()} article(s) under 200 euros")
            println("${expensive.await()} article(s) at 200 euros or more")
        }

        // 4 - ein Stream: die Entitäten werden während des Lesens verarbeitet
        println("--- getResultStream")
        sessionFactory.inSession { session ->
            session.createSelectionQuery("from Article where price >= 300", Article::class.java)
                .resultStream
                .use { articles -> articles.forEach { println("read: ${it.name}") } }
        }

        // 5 - eine zu lange Query wird nach dem festgelegten Timeout (in Sekunden) unterbrochen
        println("--- timeout exceeded")
        try {
            sessionFactory.inSession { session ->
                session.createNativeQuery("select sleep(5)", Int::class.java)
                    .setTimeout(1)
                    .singleResult
            }
        } catch (e: QueryTimeoutException) {
            println("${e::class.simpleName} : ${e.message}")
        }
    }
}

// eine Zähl-Query, in einer für die Coroutine spezifischen Session ausgeführt; die blockierende Arbeit wird
// an den [IO]-Dispatcher übergeben: die aufrufende Coroutine wird ausgesetzt, ihr Thread wird nicht blockiert
suspend fun countArticles(sessionFactory: SessionFactory, hql: String): Long =
    withContext(Dispatchers.IO) {
        sessionFactory.fromSession { session ->
            session.createSelectionQuery(hql, Long::class.java).singleResult
        }
    }

Ergebnisse:

> gradlew -q :async:run
--- two queries in parallel
    SQL> select count(*)
    SQL> from articles a1_0
    SQL> where a1_0.currentStock<a1_0.minimumStock
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.price<200
    SQL> order by a1_0.price
[2, pump, 10.00, 10, 2]
[4, arrows - set of 6, 100.00, 12, 20]
[6, diver's oxygen tanks, 120.00, 10, 5]
1 article(s) out of stock
--- CompletableFuture
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name='bow'
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 4
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = bow
    SQL> -- parameter 4 = 550
    SQL> -- parameter 5 = 3
    SQL> -- transaction committed (COMMIT)
new price of the bow: 550
--- coroutines
    SQL> select count(*)
    SQL> from articles a1_0
    SQL> where a1_0.price<200
    SQL> select count(*)
    SQL> from articles a1_0
    SQL> where a1_0.price>=200
3 article(s) under 200 euros
3 article(s) at 200 euros or more
--- getResultStream
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.price>=300
read: bike
read: bow
read: diving suit
--- timeout exceeded
    SQL> select sleep(5)
    SQL> -- failure: Statement cancelled due to timeout or client request
QueryTimeoutException : JDBC exception executing SQL [Statement cancelled due to timeout or client request] [select sleep(5)]

Kommentare:

  • Zeile 23: ein Executor, der pro Task einen Virtual Thread erzeugt (Kapitel 8). Ein [ExecutorService] ist [AutoCloseable]: Die Funktion [use] schließt ihn am Ende des Blocks, und sein Schließen wartet, bis alle Tasks beendet sind;
  • Zeilen 24–33: Zwei Tasks, die an den Executor übergeben werden. Jede öffnet ihre eigene Session ([fromSession]) und führt eine Abfrage aus; beide Abfragen laufen gleichzeitig auf zwei Verbindungen des Pools. Ihre Reihenfolge im Log (Zeilen 3–9 der Ergebnisse) kann daher von Ausführung zu Ausführung variieren. Der Ergebnistyp wird in [submit] angegeben ([submit<List<Article>>]): Andernfalls könnte das Lambda als [Runnable] – das nichts zurückgibt – statt als [Callable] interpretiert werden;
  • Zeile 33: der Ergebnistyp der Count-Abfrage. [Long::class.java] bezeichnet hier den primitiven Java-Typ [long]; Hibernate akzeptiert ihn und liefert den Wert als [java.lang.Long], den Kotlin als [Long] behandelt;
  • Zeilen 36–38: [get()] wartet auf den Abschluss jeder Task und liefert ihr Ergebnis (Zeilen 10–13);
  • Zeilen 44–53: ein [CompletableFuture] (Kapitel 9), dessen erster Schritt – eine vollständige Transaktion – von einem Virtual Thread ausgeführt wird ([supplyAsync(..., executor)]) und dessen zweiter Schritt sein Ergebnis anzeigt. Die Funktion [apply] ändert den gelesenen Datensatz und gibt ihn zurück: Das ist der Wert des Lambdas und damit das Ergebnis der Transaktion. Der von der Transaktion zurückgegebene Datensatz ist detached (seine Session ist geschlossen): Wir können seine Properties lesen, aber keine Assoziationen laden;
  • Zeilen 58–68: dieselbe Idee mit Coroutines. [runBlocking] erzeugt eine Haupt-Coroutine; [async] startet zwei untergeordnete Coroutines, die die Suspend-Funktion [countArticles] aufrufen. Beide Anfragen laufen gleichzeitig (Zeilen 30–35), und [await] suspendiert die Haupt-Coroutine, bis jede von ihnen zurückkehrt (Zeilen 36–37);
  • Zeilen 95–96: Die Suspend-Funktion delegiert die blockierende Arbeit an den Dispatcher [Dispatchers.IO], dessen Threads darauf ausgelegt sind, auf E/A-Operationen zu warten. Die Session wird von [fromSession] innerhalb des Blocks [withContext] geöffnet und geschlossen: Sie wird nur von einer einzigen Coroutine und auf einem einzigen Thread verwendet. So sollte man vorgehen, wenn man Hibernate aus suspendierendem Code aufruft. Man könnte auch einen auf Virtual Threads aufgebauten Dispatcher verwenden ([Executors.newVirtualThreadPerTaskExecutor().asCoroutineDispatcher()], Kapitel 9);
  • Zeilen 73–76: Die Property [resultStream] (die Methode [getResultStream]) liefert einen Java-Stream: Die Entitäten werden während des Lesens verarbeitet, ohne eine Liste zu bilden (Zeilen 42–44). Ein Stream ist [AutoCloseable]: [use] schließt ihn, wodurch der JDBC-Cursor freigegeben wird. Er ließe sich auch in eine Kotlin-Sequenz umwandeln ([asSequence()], Kapitel 5). Das ist nützlich, um eine große Zahl von Zeilen zu verarbeiten. Beachten Sie bei MySQL, dass der Treiber standardmäßig alle Zeilen des Ergebnisses liest, bevor er die erste zurückgibt; für ein wirklich fortlaufendes Lesen müssen Sie ihn anweisen, einen Cursor zu verwenden (Parameter [useCursorFetch=true] der URL und per [setFetchSize] festgelegte Batchgröße);
  • Zeilen 83–87: Eine maximale Ausführungszeit in Sekunden, festgelegt mit [setTimeout]. Die Abfrage (eine native SQL-Abfrage, auf die wir später eingehen) dauert fünf Sekunden; nach einer Sekunde unterbricht der JDBC-Treiber sie, und Hibernate löst eine [QueryTimeoutException] aus (Zeilen 46–48).

Die Dauer der letzten Anfrage verdient eine Anmerkung. In Kapitel 9 haben wir Coroutines ([job.cancel()], [withTimeout]) und Tasks ([Future.cancel]) abgebrochen. Diese Abbrüche hätten hier keine Wirkung auf die Anfrage: Das Abbrechen einer Coroutine ist kooperativ, und eine im JDBC-Treiber blockierte Coroutine prüft nicht, ob sie abgebrochen wurde; auch das Unterbrechen eines im Treiber blockierten Threads unterbricht die gerade auf dem Server laufende Anfrage nicht. Ein [withTimeout(1000) { countArticles(...) }] würde zwar eine [TimeoutCancellationException] auslösen ... aber erst, wenn die Anfrage abgeschlossen ist, nach fünf Sekunden: Der Block [withContext] von [countArticles] gibt die Kontrolle erst zurück, wenn er seine blockierende Operation beendet hat. Um die Dauer einer Anfrage zu begrenzen, müssen Sie sich daher über [setTimeout] an den JDBC-Treiber wenden.

Für Anwendungen, die eine wirklich nicht blockierende API benötigen, gibt es Hibernate Reactive, eine Variante von Hibernate, die statt JDBC auf reaktive Treiber (die von Vert.x) setzt und deren Methoden [CompletionStage] oder Objekte der Bibliothek Mutiny zurückgeben; Ein [CompletionStage] wird in einer Coroutine mit der Erweiterungsfunktion [await] von kotlinx-coroutines erwartet. Virtual Threads und der Dispatcher [Dispatchers.IO] beseitigen diese Komplexität in den meisten Fällen: Dieser Ansatz wird in diesem Kurs verfolgt.

11.11. Transaktionen und Nebenläufigkeit

11.11.1. Transaktionen

Kapitel 10 hat Transaktionen eingeführt: eine Menge von Operationen, die entweder alle gelingen oder alle fehlschlagen. Mit Hibernate gilt:

  • Jede schreibende Operation wird innerhalb einer Transaktion ausgeführt, die von [session.beginTransaction()] geöffnet und von [commit] oder [rollback] geschlossen wird. Die Methoden [inTransaction] und [fromTransaction] der [SessionFactory] übernehmen dies für uns: Sie führen ein Commit der Transaktion aus, wenn das Lambda normal endet, und ein Rollback, wenn es eine Exception auslöst, die dann erneut ausgelöst wird;
  • Alle während der Transaktion gesendeten Befehle (sofortige Befehle über [INSERT], explizite Synchronisierungen über [flush] und die Synchronisierung über [commit]) werden entweder gemeinsam bestätigt oder gemeinsam zurückgerollt;
  • Ein Fehler des DBMS wird als Hibernate-Exception weitergereicht, die von [JDBCException] abgeleitet ist und die [SQLException] des Treibers kapselt: [ConstraintViolationException] bei einer Verletzung einer Constraint (Primärschlüssel, Eindeutigkeit, Fremdschlüssel, [NOT NULL]), [SQLGrammarException] bei einem Fehler in der SQL-Anweisung und so weiter. Dies sind ungeprüfte Exceptions, sowohl in Java als auch in Kotlin (das, zur Erinnerung, keine geprüften Exceptions kennt: Kapitel 3); wir fangen nur diejenigen ab, die wir zu behandeln wissen.

Das Unterprojekt [transactions] veranschaulicht die beiden Arten, eine Transaktion zu handhaben:

package transactions

import articles.Article
import articles.BaseArticles
import java.math.BigDecimal
import org.hibernate.SessionFactory
import org.hibernate.exception.ConstraintViolationException

// die beiden Arten, eine Transaktion zu verwalten: inTransaction und eine vom Code verwaltete Transaktion
fun main() {
    BaseArticles.createSessionFactory().use { sessionFactory ->
        // die Tabelle [articles] wird mit ihren sechs Artikeln neu erstellt
        BaseArticles.initialize(sessionFactory)

        // 1 - inTransaction: Commit, wenn alles gelingt, Rollback bei einer Exception
        println("--- two additions, the second of which violates the uniqueness of the name")
        try {
            sessionFactory.inTransaction { session ->
                session.persist(Article("racket", BigDecimal.valueOf(80), 5, 2))
                session.persist(Article("bike", BigDecimal.valueOf(450), 3, 1))
            }
        } catch (e: ConstraintViolationException) {
            println("${e::class.simpleName} : constraint [${e.constraintName}] violated")
        }
        display(sessionFactory, "racket")

        // 2 - eine vom Code verwaltete Transaktion: mehrere Schreibvorgänge, gemeinsam bestätigt oder zurückgesetzt
        println("--- transaction rolled back")
        sessionFactory.openSession().use { session ->
            val transaction = session.beginTransaction()
            try {
                // Verkauf von zwei Fahrrädern: das UPDATE wird durch flush gesendet
                val bike = session
                    .createSelectionQuery("from Article where name = 'bike'", Article::class.java)
                    .singleResult
                bike.currentStock -= 2
                session.flush()
                // Hinzufügen eines Artikels, dessen Name bereits existiert: Fehler
                session.persist(Article("pump", BigDecimal.valueOf(12), 5, 1))
                // Commit des Ganzen (hier nicht erreicht)
                transaction.commit()
            } catch (e: ConstraintViolationException) {
                println("${e::class.simpleName} : ${e.sqlException.message}")
                // Rollback aller Operationen der Transaktion
                transaction.rollback()
            }
        }
        // der Verkauf der Fahrräder wurde zurückgesetzt
        display(sessionFactory, "bike")
    }
}

// Anzeige eines aus der Datenbank gelesenen Artikels, mit einer neuen Session
fun display(sessionFactory: SessionFactory, name: String) {
    val article = sessionFactory.fromSession { session ->
        session.createSelectionQuery("from Article where name = :name", Article::class.java)
            .setParameter("name", name)
            .singleResultOrNull
    }
    println("article [$name] in the database: ${article ?: "missing"}")
}

Ergebnisse:

> gradlew -q :transactions:run
--- two additions, the second of which violates the uniqueness of the name
    SQL> -- start of transaction
    SQL> insert into articles (currentStock, minimumStock, name, price)
    SQL> values (?, ?, ?, ?)
    SQL> -- parameter 1 = 5
    SQL> -- parameter 2 = 2
    SQL> -- parameter 3 = racket
    SQL> -- parameter 4 = 80
    SQL> insert into articles (currentStock, minimumStock, name, price)
    SQL> values (?, ?, ?, ?)
    SQL> -- parameter 1 = 3
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = bike
    SQL> -- parameter 4 = 450
    SQL> -- failure: Duplicate entry 'bike' for key 'articles.uk_articles_name'
    SQL> -- transaction rolled back (ROLLBACK)
ConstraintViolationException : constraint [articles.uk_articles_name] violated
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = racket
article [racket] in the database: missing
--- transaction rolled back
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name='bike'
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 8
    SQL> -- parameter 2 = 5
    SQL> -- parameter 3 = bike
    SQL> -- parameter 4 = 500.00
    SQL> -- parameter 5 = 1
    SQL> insert into articles (currentStock, minimumStock, name, price)
    SQL> values (?, ?, ?, ?)
    SQL> -- parameter 1 = 5
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = pump
    SQL> -- parameter 4 = 12
    SQL> -- failure: Duplicate entry 'pump' for key 'articles.uk_articles_name'
ConstraintViolationException : Duplicate entry 'pump' for key 'articles.uk_articles_name'
    SQL> -- transaction rolled back (ROLLBACK)
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = bike
article [bike] in the database: [1, bike, 500.00, 10, 5]

Kommentare:

  • Zeilen 18–20: Zwei Artikel werden in einer von [inTransaction] verwalteten Transaktion hinzugefügt; der zweite Artikel hat denselben Namen wie ein bereits vorhandener. Beide [INSERT]-Befehle werden sofort ausgeführt (Zeilen 4–15); der zweite verletzt die Eindeutigkeitsbedingung der Spalte [name]: MySQL lehnt ihn ab (Zeile 16), [persist] löst eine [ConstraintViolationException] aus, [inTransaction] rollt die Transaktion zurück (Zeile 17) und löst die Exception erneut aus;
  • Zeilen 22–23: Die Exception wird abgefangen; die Property [constraintName] (die Methode [getConstraintName]) liefert den Namen der verletzten Constraint (Zeile 18). Das zeigt den Wert einer benannten Constraint;
  • Zeile 25: Der Tennisschläger, der erfolgreich eingefügt worden war, befindet sich nicht in der Datenbank (Zeile 23): Das Zurückrollen der Transaktion hat ihn gelöscht;
  • Zeilen 29–45: Eine vom Code verwaltete Transaktion in einer Session, die von [openSession] geöffnet und von [use] geschlossen wird ([Session] ist [AutoCloseable]). Zwei Fahrräder werden verkauft ([bike.currentStock -= 2]: Der Operator [-=] wird auf eine Property [var] genauso angewendet wie auf eine Variable), und die Änderung wird mit einem expliziten [flush] an das DBMS gesendet (Zeilen 29–36); anschließend wird ein Artikel hinzugefügt, dessen Name bereits existiert: Das Einfügen schlägt fehl (Zeile 43);
  • Zeile 41: Das Commit wird nie erreicht;
  • Zeilen 42–45: Im [catch] wird die Transaktion zurückgerollt (Zeile 45 der Ergebnisse). Die Property [sqlException] liefert die ursprüngliche Exception des JDBC-Treibers, und ihre Meldung stammt von MySQL (Zeile 44);
  • Zeile 49: Der Verkauf der Fahrräder wurde, obwohl er per [flush] an das DBMS gesendet worden war, rückgängig gemacht: Der Lagerbestand der Fahrräder beträgt weiterhin 10 (Zeile 50);
  • Zeilen 54–60: eine Funktion, die einen Datensatz mit einer neuen Session erneut liest, um den tatsächlichen Zustand der Datenbank statt der Entitäten der aktuellen Arbeitssession zu sehen. Die Property [singleResultOrNull] liefert [null], wenn die Abfrage nichts findet; der Elvis-Operator ([?:]) zeigt dann „missing“ an.

Nach einer Exception sollte eine Session nicht mehr verwendet werden: Ihr Persistenzkontext kann Entitäten in einem Zustand enthalten, der nicht mit der Datenbank übereinstimmt. Wir rollen die Transaktion zurück, schließen die Session und beginnen bei Bedarf mit einer neuen Session von vorn. Das tut [inTransaction], und das tut auch unser Code beim Verlassen des Blocks [use], der die Session schließt.

Die Isolationsstufe der Transaktion ist die der JDBC-Verbindung: [REPEATABLE_READ], der Standardwert von MySQL, wie das erste Beispiel zeigt. Sie können dies für die gesamte [SessionFactory] mit der Methode [jdbcTransactionIsolation] in der Konfiguration ändern.

11.11.2. Optimistische Nebenläufigkeit

Zwei Benutzer lesen denselben Artikel, dessen Lagerbestand 10 beträgt. Der erste Benutzer verkauft einen Artikel und setzt den Bestand auf 9. Der zweite Benutzer, der den Bestand vor dieser Aktualisierung gelesen hat, verkauft drei Artikel und setzt den Bestand auf 7: Der Verkauf des ersten Benutzers geht verloren. Das ist das Problem der verlorenen Aktualisierungen.

Eine Lösung bestünde darin, die Zeile für die gesamte Dauer der Operation jedes Benutzers zu sperren („pessimistische“ Nebenläufigkeit): Das blockiert andere Benutzer, manchmal für lange Zeit. Bei Hibernate wird im Allgemeinen die optimistische Nebenläufigkeit bevorzugt: Nichts wird gesperrt, aber beim Speichern wird geprüft, dass die Zeile seit dem Lesen nicht verändert wurde. Der übliche Weg dafür ist, der Entität eine Versionsnummer hinzuzufügen – eine mit [@Version] annotierte Property. Hibernate erhöht diese Nummer bei jeder Änderung der Zeile und ergänzt über die Befehle [UPDATE] und [DELETE] die Bedingung „die Version hat noch den gelesenen Wert“ in der Klausel [WHERE]. Ändert die Transaktion keine Zeile, hat ein anderer Benutzer bereits auf die Daten zugegriffen: Hibernate löst eine [OptimisticLockException] aus.

Das Unterprojekt [concurrency] verwendet seine eigene Datenbank [hbconcurrency] und seine eigene Entität [Article], auf das Wesentliche reduziert:

// ein Artikel, dessen Änderungen durch eine Versionsnummer kontrolliert werden
@Entity
@Table(name = "articles")
class Article(
    @Column(nullable = false, length = 30)
    var name: String,
    var currentStock: Int,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    // die Versionsnummer: bei jeder Änderung der Zeile von Hibernate inkrementiert
    @Version
    var version: Int = 0
        protected set
}
  • Zeilen 15–17: die Versionsnummer, vom Typ [Int] (Sie können auch [Long] oder ein Datum vom Typ [Instant] verwenden). Die Anwendung ändert sie nie selbst: Ihr Modifizierer ist geschützt ([protected set]), genau wie der des Bezeichners; Hibernate, das direkt auf das Feld zugreift, ist davon nicht betroffen. Der Anfangswert [0] ist der eines von der Anwendung erzeugten Artikels; bei einem aus der Datenbank gelesenen Artikel führt der parameterlose Konstruktor, den das Plugin [jpa] hinzufügt, diese Initialisierung nicht aus (wie wir gesehen haben), aber Hibernate weist der Property sofort den gelesenen Wert zu.

Da die Entität im Unterprojekt selbst definiert ist, wendet seine Build-Datei die Plugins [jpa] und [allopen] an und hängt direkt von Hibernate und der Bibliothek [tools] ab:

// optimistische Nebenläufigkeit: eine Entität mit Versionsnummer, in ihrer eigenen Datenbank [hbconcurrency]
plugins {
    kotlin("jvm")
    // das Modul definiert seine eigene Entität: die Plugins [jpa] und [allopen]
    kotlin("plugin.jpa")
    kotlin("plugin.allopen")
    application
}

repositories {
    mavenCentral()
}

dependencies {
    // das kompakte SQL-Log (und Logback)
    implementation(project(":tools"))
    // Hibernate und der MySQL-JDBC-Treiber
    implementation("org.hibernate.orm:hibernate-core:7.4.5.Final")
    runtimeOnly("com.mysql:mysql-connector-j:9.7.0")
}

// die so annotierten Klassen werden vom Plugin [allopen] geöffnet
allOpen {
    annotation("jakarta.persistence.Entity")
    annotation("jakarta.persistence.MappedSuperclass")
    annotation("jakarta.persistence.Embeddable")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // das von [gradlew -q :concurrency:run] ausgeführte Programm
    mainClass = "concurrency.MainKt"
}

// unter Windows wird die Bildschirmausgabe des von Gradle gestarteten Programms (run, bootRun ...) in UTF-8 kodiert,
// sonst werden Zeichen mit Akzenten in der IntelliJ-IDEA-Konsole oder im Terminal falsch dargestellt
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • Zeilen 5–6: die beiden Entitäts-Plugins, konfiguriert durch den Block [allOpen] (Zeilen 23–26);
  • Zeilen 16–19: das kompakte SQL-Log, Hibernate und der JDBC-Treiber für MySQL;
  • Zeilen 42–45: Die von Gradle gestarteten Programme schreiben ihre Ausgabe in UTF-8, damit Zeichen mit Akzenten unter Windows korrekt angezeigt werden (Kapitel 2).

Das Programm simuliert die beiden Benutzer mit zwei Sessions:

package concurrency

import jakarta.persistence.OptimisticLockException
import org.hibernate.cfg.AvailableSettings
import org.hibernate.jpa.HibernatePersistenceConfiguration
import tools.SqlLog

// optimistische Nebenläufigkeit: zwei Benutzer ändern denselben Artikel
fun main() {
    HibernatePersistenceConfiguration("concurrency")
        .managedClass(Article::class.java)
        .jdbcUrl("jdbc:mysql://localhost:3306/hbconcurrency?createDatabaseIfNotExist=true")
        .jdbcCredentials("root", "")
        .property(AvailableSettings.FORMAT_SQL, true)
        .createEntityManagerFactory()
        .use { sessionFactory ->
            // die Tabelle [articles] wird mit einem einzigen Artikel neu erstellt, ohne Log
            SqlLog.withoutLog {
                sessionFactory.schemaManager.drop(false)
                sessionFactory.schemaManager.create(false)
                sessionFactory.inTransaction { session -> session.persist(Article("bike", 10)) }
            }

            // zwei Benutzer, zwei Sessions: jeder liest denselben Artikel
            sessionFactory.openSession().use { session1 ->
                sessionFactory.openSession().use { session2 ->
                    println("--- the two users read the bike")
                    val bike1 = session1.find(Article::class.java, 1)
                    val bike2 = session2.find(Article::class.java, 1)

                    // Benutzer 1 verkauft 1 Fahrrad
                    println("--- user 1 sells 1 bike")
                    val transaction1 = session1.beginTransaction()
                    bike1.currentStock -= 1
                    transaction1.commit()
                    println("stock saved by user 1: ${bike1.state()}")

                    // Benutzer 2 verkauft 3 Fahrräder auf Basis veralteter Daten (Bestand = 10, Version 0)
                    println("--- user 2 sells 3 bikes")
                    val transaction2 = session2.beginTransaction()
                    bike2.currentStock -= 3
                    try {
                        session2.flush()
                        transaction2.commit()
                    } catch (e: OptimisticLockException) {
                        println("${e::class.simpleName} : ${e.message}")
                        transaction2.rollback()
                    }
                }
            }

            // Lösung: Benutzer 2 liest den Artikel mit einer neuen Session erneut und beginnt von vorn
            println("--- user 2 reads the bike again and starts over")
            sessionFactory.inTransaction { session ->
                val bike = session.find(Article::class.java, 1)
                println("stock read again: ${bike.state()}")
                bike.currentStock -= 3
                session.flush()
                println("stock saved by user 2: ${bike.state()}")
            }
        }
}

// der Zustand eines Artikels, zur Anzeige: eine Erweiterungsfunktion
fun Article.state() = "$currentStock (version $version)"

Ergebnisse:

> gradlew -q :concurrency:run
--- the two users read the bike
    SQL> select a1_0.id, a1_0.currentStock, a1_0.name, a1_0.version
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 1
    SQL> select a1_0.id, a1_0.currentStock, a1_0.name, a1_0.version
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 1
--- user 1 sells 1 bike
    SQL> -- start of transaction
    SQL> update articles
    SQL> set currentStock=?, name=?, version=?
    SQL> where id=? and version=?
    SQL> -- parameter 1 = 9
    SQL> -- parameter 2 = bike
    SQL> -- parameter 3 = 1
    SQL> -- parameter 4 = 1
    SQL> -- parameter 5 = 0
    SQL> -- transaction committed (COMMIT)
stock saved by user 1: 9 (version 1)
--- user 2 sells 3 bikes
    SQL> -- start of transaction
    SQL> update articles
    SQL> set currentStock=?, name=?, version=?
    SQL> where id=? and version=?
    SQL> -- parameter 1 = 7
    SQL> -- parameter 2 = bike
    SQL> -- parameter 3 = 1
    SQL> -- parameter 4 = 1
    SQL> -- parameter 5 = 0
OptimisticLockException : Unexpected row count (expected row count 1 but was 0) [update articles set currentStock=?,name=?,version=? where id=? and version=?] for entity [concurrency.Article with id '1']
    SQL> -- transaction rolled back (ROLLBACK)
--- user 2 reads the bike again and starts over
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.name, a1_0.version
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 1
stock read again: 9 (version 1)
    SQL> update articles
    SQL> set currentStock=?, name=?, version=?
    SQL> where id=? and version=?
    SQL> -- parameter 1 = 6
    SQL> -- parameter 2 = bike
    SQL> -- parameter 3 = 2
    SQL> -- parameter 4 = 1
    SQL> -- parameter 5 = 1
stock saved by user 2: 6 (version 2)
    SQL> -- transaction committed (COMMIT)

Kommentare:

  • Zeilen 10–15: die Hibernate-Konfiguration für die Datenbank [hbconcurrency] und ihre einzige Entität;
  • Zeilen 18–21: Die Tabelle wird mit einem einzigen Artikel neu angelegt, dem Fahrrad, in Version 0. Die Funktion [withoutLog] aus der Bibliothek [tools] erhält die auszuführende Aktion in Form eines Lambdas, das ohne Klammern geschrieben wird, da es ihr einziger Parameter ist (Kapitel 7);
  • Zeilen 28–29: Jeder Benutzer liest das Fahrrad in seiner eigenen Session; die beiden Sessions werden von zwei verschachtelten [use] -Funktionen geöffnet und in umgekehrter Reihenfolge ihrer Öffnung wieder geschlossen. Die Spalte [version] wird zusammen mit den übrigen gelesen (Zeilen 3–10);
  • Zeilen 33–35: Der [UPDATE]-Befehl des ersten Benutzers (Zeilen 13–20) schreibt die neue Version (1) und enthält die Bedingung [version=?] mit der gelesenen Version (0). Die Zeile wird geändert; die Eigenschaft [version] der Entität wird auf 1 gesetzt (Zeile 22);
  • Zeilen 41–44: Die Anfrage des zweiten Benutzers enthält dieselbe Bedingung, mit der von ihm gelesenen Version 0, während die Version der Zeile in der Datenbank inzwischen 1 ist. Es wird keine Zeile geändert, und Hibernate wirft eine [OptimisticLockException] (Zeile 33). Wir synchronisieren die Session ausdrücklich ([flush]) vor dem [commit] , um diese Exception unverändert auszulösen; würde sie während des [commit] ausgelöst, wäre sie in eine [RollbackException] eingebettet;
  • Zeilen 54–59: Die Lösung hängt von der Anwendung ab: abbrechen, den Benutzer benachrichtigen oder, wie hier, den Artikel mit einer neuen Session erneut lesen (die Session, die die Exception erhalten hat, darf nicht mehr verwendet werden) und die Operation wiederholen. Der aufgefüllte Lagerbestand beträgt 9 in Version 1 (Zeile 41), und der Verkauf der drei Fahrräder ergibt einen Lagerbestand von 6 in Version 2 (Zeile 50);
  • Zeile 65: eine Erweiterungsfunktion (Kapitel 4), die den Zustand eines Artikels für die Anzeige formatiert. Sie wird innerhalb des Programms definiert, ohne die Entität zu ändern.

Zwei Varianten:

  • Ohne Versionsspalte kann Hibernate die alten Werte der Spalten selbst prüfen: Mit den Annotationen [@OptimisticLocking(type = OptimisticLockType.DIRTY)] und [@DynamicUpdate] an der Entität enthält die [WHERE]-Klausel des [UPDATE] den gelesenen Wert jeder geänderten Spalte ([where id=? and currentStock=?]). Das ist nützlich für eine bestehende Datenbank, die nicht geändert werden kann;
  • Pessimistische Nebenläufigkeitskontrolle bleibt möglich, wenn Konflikte häufig sind: [session.find(Article::class.java, 1, LockModeType.PESSIMISTIC_WRITE)] liest die Zeile mit einem [select ... for update]-Befehl, der sie bis zum Ende der Transaktion sperrt.

11.12. Das native SQL

Hibernate erzeugt das SQL aus HQL oder der Criteria API, aber es ist weiterhin möglich, das SQL einer Abfrage selbst zu schreiben, um eine für das DBMS spezifische Funktion zu nutzen oder eine komplexe Abfrage zu optimieren: Man spricht dann von einer nativen Abfrage. Das Teilprojekt [rawsql] listet die verfügbaren Methoden auf:

package rawsql

import articles.Article
import articles.BaseArticles
import java.math.BigDecimal
import java.sql.Connection

// native SQL-Queries: von Hand geschrieben, unverändert an das DBMS übergeben
fun main() {
    BaseArticles.createSessionFactory().use { sessionFactory ->
        // die Tabelle [articles] wird mit ihren sechs Artikeln neu erstellt
        BaseArticles.initialize(sessionFactory)
        sessionFactory.openSession().use { session ->
            // 1 - eine von Hand geschriebene SQL-Query, die Entitäten zurückgibt
            println("--- createNativeQuery: entities")
            val minPrice = BigDecimal.valueOf(200)
            val expensive = session
                .createNativeQuery(
                    """
                    select * from articles
                    where price > :minPrice order by name""".trimIndent(), Article::class.java
                )
                .setParameter("minPrice", minPrice)
                .resultList
            expensive.forEach { println(it) }

            // 2 - ein als Parameter übergebener Wert: keine SQL-Injection möglich
            println("--- SQL injection attempt with a parameter")
            val name = "x' or '1'='1"
            var nb = session
                .createNativeQuery("select count(*) from articles where name = :name", Long::class.java)
                .setParameter("name", name)
                .singleResult
            println("$nb article(s) found")
            // dieselbe Query, mit einem String-Template erstellt: niemals so machen
            println("--- the same attempt with a string template")
            val sql = "select count(*) from articles where name = '$name'"
            nb = session.createNativeQuery(sql, Long::class.java).singleResult
            println("$nb article(s) found")

            // 3 - Ergebnisse, die keine Entitäten sind
            println("--- createNativeQuery: values")
            val names = session
                .createNativeQuery(
                    "select name from articles where currentStock < minimumStock", String::class.java
                )
                .resultList
            println("out of stock: ${names.joinToString(", ")}")
            val value = session
                .createNativeQuery("select sum(price * currentStock) from articles", BigDecimal::class.java)
                .singleResult
            println("value of the stock: %.2f euros".format(value))

            // 4 - eine update-Anweisung
            println("--- createNativeMutationQuery")
            val nbRows = session.fromTransaction { _ ->
                session
                    .createNativeMutationQuery(
                        """
                        update articles set price = price * :coefficient
                        where name = :name""".trimIndent()
                    )
                    .setParameter("coefficient", BigDecimal("0.9"))
                    .setParameter("name", "bow")
                    .executeUpdate()
            }
            println("$nbRows row(s) modified")

            // 5 - die JDBC-Verbindung der Session, für gewöhnlichen JDBC-Code
            println("--- doWork: the JDBC connection")
            session.doWork { connection: Connection ->
                val query = "select name, price from articles where name = 'bow'"
                connection.createStatement().use { statement ->
                    statement.executeQuery(query).use { rows ->
                        while (rows.next()) {
                            val price = rows.getBigDecimal("price")
                            println("${rows.getString("name")} : %.2f euros".format(price))
                        }
                    }
                }
            }
        }
    }
}

Ergebnisse:

> gradlew -q :rawsql:run
--- createNativeQuery: entities
    SQL> select *
    SQL> from articles
    SQL> where price > ?
    SQL> order by name
    SQL> -- parameter 1 = 200
[1, bike, 500.00, 10, 5]
[3, bow, 600.00, 4, 1]
[5, diving suit, 300.00, 8, 2]
--- SQL injection attempt with a parameter
    SQL> select count(*)
    SQL> from articles
    SQL> where name = ?
    SQL> -- parameter 1 = x' or '1'='1
0 article(s) found
--- the same attempt with a string template
    SQL> select count(*)
    SQL> from articles
    SQL> where name = 'x' or '1'='1'
6 article(s) found
--- createNativeQuery: values
    SQL> select name
    SQL> from articles
    SQL> where currentStock < minimumStock
out of stock: arrows - set of 6
    SQL> select sum(price * currentStock)
    SQL> from articles
value of the stock: 12300.00 euros
--- createNativeMutationQuery
    SQL> -- start of transaction
    SQL> update articles
    SQL> set price = price * ?
    SQL> where name = ?
    SQL> -- parameter 1 = 0.9
    SQL> -- parameter 2 = bow
    SQL> -- transaction committed (COMMIT)
1 row(s) modified
--- doWork: the JDBC connection
bow : 540.00 euros

Kommentare:

  • Zeilen 17–24: [createNativeQuery] führt eine Abfrage (SQL) aus, die Zeilen aus der Tabelle einer Entität zurückgibt, und der zweite Parameter ([Article::class.java]) weist Hibernate an, sie als von der Session verwaltete Entitäten zu materialisieren. Die Spaltennamen im Ergebnis müssen mit denen des Modells übereinstimmen: [select *] ist hier passend. Die Abfrage ist als Rohstring geschrieben (["""]), aus dem [trimIndent] die gemeinsame Einrückung entfernt (Kapitel 5). Sie wird unverändert an das DBMS übergeben (Zeilen 3–6), nur dass der Parameter mit dem Namen [:minPrice] zu einem JDBC-Parameter wird ([?]);
  • Zeilen 29–34: ein SQL-Injection-Versuch. Der Wert von [name] wird als Parameter übergeben: Er wird unverändert mit der Spalte [name] verglichen, und kein Artikel passt (Zeile 16);
  • Zeilen 37–38: dieselbe Abfrage, erstellt mit einem String-Template (['$name']). Templates sind in Kotlin so bequem, dass man versucht ist, sie zum Erstellen einer Abfrage zu verwenden: Das ist ein schwerer Fehler. Der Wert von [name] wird zu SQL-Code, die Bedingung ist immer wahr (Zeile 20), und die Abfrage liefert sechs Artikel (Zeile 21): Das ist eine erfolgreiche SQL-Injection. Wie in Kapitel 10 darf eine native Abfrage nur konstanten Text enthalten, wobei Werte als Parameter übergeben werden;
  • Zeilen 43–52: Abfragen, die einzelne Werte zurückgeben ([String], [BigDecimal]): Der zweite Parameter von [createNativeQuery] ist dann der Typ des Werts. Bei mehreren Spalten können Sie eine Datenklasse angeben (deren Konstruktor die Spalten der Reihe nach erhält) oder [Array<Any>::class.java] verwenden;
  • Zeilen 56–65: [createNativeMutationQuery] bereitet eine Änderungsanweisung vor, die von [executeUpdate] ausgeführt wird und die Anzahl der geänderten Zeilen zurückgibt. Sie läuft innerhalb einer Transaktion: Die Methode [fromTransaction] der Session öffnet sie, führt den Commit durch und gibt das Ergebnis des Lambdas zurück. Das Lambda erhält die Transaktion als Parameter; da es sie nicht verwendet, heißt dieser Parameter [_];
  • Zeilen 71–77: [doWork] gewährt Zugriff auf die JDBC-Verbindung der Session ([java.sql.Connection]) für Standard-JDBC-Code (Kapitel 10): Aufruf einer gespeicherten Prozedur, Nutzung einer Treiberfunktion ... Es enthält die Funktion [use], die das Statement ([Statement]) und das [ResultSet] schließt. Der Preis des Bogens wurde tatsächlich um 10 % gesenkt (Zeile 40).

Eine Anmerkung zu Zeile 71: Der Typ des Lambda-Parameters ([connection: Connection]) wird hier ausdrücklich angegeben, was in Kotlin nicht der üblichen Praxis entspricht. Ohne diese Angabe lehnt der Compiler das Programm ab:

error: type annotation class 'org.checkerframework.checker.nullness.qual.UnknownKeyFor' of the inferred type is inaccessible. Check the module classpath for missing or conflicting dependencies.

Die Hibernate-Schnittstelle [Work], die das Lambda implementiert, trägt an ihrem Parametertyp Typannotationen der Bibliothek Checker Framework; diese Annotationen werden von den Hibernate-Entwicklern verwendet, um die Verwendung von [null] in ihrem Code zu überprüfen. Diese Bibliothek gehört nicht zu den Abhängigkeiten von Hibernate; daher sind ihre Annotationen dem Compiler unbekannt, der es ablehnt, einen Typ abzuleiten, der sie trägt. Indem wir den Typ des Parameters selbst angeben, umgehen wir die Typinferenz – und den Fehler. Diese Art von Problem tritt manchmal bei der Verwendung einer Java-Bibliothek aus Kotlin auf: Der Java-Code selbst ignoriert diese Annotationen.

Eine native Abfrage ist nicht von einem DBMS auf ein anderes übertragbar, und Hibernate kann sie vor der Ausführung nicht validieren: Sie ist den Fällen vorbehalten, in denen HQL nicht ausreicht. HQL deckt tatsächlich einen großen Teil von SQL ab (Joins aller Art, Unterabfragen, Fensterfunktionen, [union] ...) und erlaubt es, eine Funktion des DBMS aufzurufen, die es nicht kennt.

11.13. Massenänderungen, Nur-Lese-Modus und Batches

Die Änderungsverfolgung hat ihren Preis: Um den Preis von 100 Artikeln zu erhöhen, müssen Sie alle 100 Artikel lesen, einzeln ändern, und die Synchronisierung der Session sendet 100 [UPDATE]-Befehle. Hibernate bietet mehrere Möglichkeiten, große Mengen von Zeilen effizient zu verarbeiten. Das Teilprojekt [bulkupdate] stellt sie vor:

package bulkupdate

import articles.Article
import articles.BaseArticles
import java.math.BigDecimal

// Massenverarbeitung: HQL-update/delete-Anweisungen, Read-only, zustandslose Session und Batches
fun main() {
    BaseArticles.createSessionFactory().use { sessionFactory ->
        // die Tabelle [articles] wird mit ihren sechs Artikeln neu erstellt
        BaseArticles.initialize(sessionFactory)
        sessionFactory.openSession().use { session ->
            var transaction = session.beginTransaction()

            // 1 - HQL-update: eine einzige UPDATE-Anweisung, keine Entität in den Speicher geladen
            println("--- restocking the articles that are out of stock")
            var nbRows = session
                .createMutationQuery(
                    """
                    update Article set currentStock = minimumStock * 2
                    where currentStock < minimumStock""".trimIndent()
                )
                .executeUpdate()
            println("$nbRows article(s) modified")

            println("--- 10 % increase of the prices below 150 euros")
            nbRows = session
                .createMutationQuery("update Article set price = price * 1.1 where price < 150")
                .executeUpdate()
            println("$nbRows article(s) modified")

            // 2 - HQL-delete: eine einzige DELETE-Anweisung
            println("--- deletion of the articles over 550 euros")
            nbRows = session
                .createMutationQuery("delete from Article where price > 550")
                .executeUpdate()
            println("$nbRows article(s) deleted")
            transaction.commit()

            // 3 - Read-only: die gelesenen Entitäten werden nicht verfolgt
            println("--- read-only")
            transaction = session.beginTransaction()
            val articles = session
                .createSelectionQuery("from Article order by id", Article::class.java)
                .setReadOnly(true)
                .resultList
            articles.forEach { println(it) }
            // die Änderung einer schreibgeschützten Entität wird ignoriert
            articles.first().price = BigDecimal.ZERO
            println("session modified: ${session.isDirty}")
            transaction.commit()

            // 4 - eine HQL-update-Anweisung ändert die von der Session bereits geladenen Entitäten nicht
            println("--- HQL update and loaded entities")
            transaction = session.beginTransaction()
            val pump = session.find(Article::class.java, 2)
            session.createMutationQuery("update Article set price = 9.5 where id = :id")
                .setParameter("id", pump.id)
                .executeUpdate()
            println("price in memory: ${pump.price}")
            session.refresh(pump)
            println("price after refresh: ${pump.price}")
            transaction.commit()
        }

        // 5 - eine zustandslose Session (StatelessSession) und in Batches gesendete Anweisungen
        println("--- StatelessSession and batches of 3 statements")
        sessionFactory.inStatelessTransaction { session ->
            session.jdbcBatchSize = 3
            val articles = session
                .createSelectionQuery("from Article order by id", Article::class.java)
                .resultList
            for (article in articles) {
                article.currentStock += 1
                // jede Änderung wird explizit angefordert: die Entitäten werden nicht verfolgt
                session.update(article)
            }
        }
    }
}

Ergebnisse (das sich wiederholende Ende wurde gekürzt):

> gradlew -q :bulkupdate:run
    SQL> -- start of transaction
--- restocking the articles that are out of stock
    SQL> update articles a1_0
    SQL> set currentStock=(a1_0.minimumStock*2)
    SQL> where a1_0.currentStock<a1_0.minimumStock
1 article(s) modified
--- 10 % increase of the prices below 150 euros
    SQL> update articles a1_0
    SQL> set price=(a1_0.price*1.1)
    SQL> where a1_0.price<150
3 article(s) modified
--- deletion of the articles over 550 euros
    SQL> delete a1_0
    SQL> from articles a1_0
    SQL> where a1_0.price>550
1 article(s) deleted
    SQL> -- transaction committed (COMMIT)
--- read-only
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> order by a1_0.id
[1, bike, 500.00, 10, 5]
[2, pump, 11.00, 10, 2]
[4, arrows - set of 6, 110.00, 40, 20]
[5, diving suit, 300.00, 8, 2]
[6, diver's oxygen tanks, 132.00, 10, 5]
session modified: false
    SQL> -- transaction committed (COMMIT)
--- HQL update and loaded entities
    SQL> -- start of transaction
    SQL> update articles a1_0
    SQL> set price=9.5
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 2
price in memory: 11.00
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 2
price after refresh: 9.50
    SQL> -- transaction committed (COMMIT)
--- StatelessSession and batches of 3 statements
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> order by a1_0.id
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 11
    SQL> -- parameter 2 = 5
    SQL> -- parameter 3 = bike
    SQL> -- parameter 4 = 500.00
    SQL> -- parameter 5 = 1
...
    SQL> -- execution of a batch of 3 statement(s)
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
...
    SQL> -- execution of a batch of 2 statement(s)
    SQL> -- transaction committed (COMMIT)

Kommentare:

  • Zeilen 17–23: Ein als HQL geschriebener [update]-Befehl, vorbereitet von [createMutationQuery], und ausgeführt von [executeUpdate]. Er wird zu einer einzigen SQL-Anweisung [UPDATE] (Zeilen 4–6), die das DBMS auf allen betroffenen Zeilen ausführt, ohne dass eine Entität in den Speicher geladen wird. Der neue Wert kann von der Zeile selbst abhängen ([minimumStock * 2]). Ein solcher Befehl wird innerhalb einer Transaktion ausgeführt (Zeilen 2 und 18);
  • Zeilen 27–29: eine Erhöhung der niedrigen Preise um 10 %. Die Konstanten der HQL-Abfrage ([1.1], [150]) werden direkt in den Text des SQL-Befehls geschrieben (Zeilen 10–11);
  • Zeilen 34–36: Eine [delete] -HQL-Anweisung entfernt den Bogen, den einzigen Artikel mit einem Preis über 550 Euro (Zeilen 14–16);
  • Zeilen 43–50: eine Nur-Lese-Operation ([setReadOnly(true)]). Die gelesenen Entitäten werden von der Session verwaltet, aber die Session behält ihren ursprünglichen Zustand nicht und überwacht sie nicht: Das ist schneller und speicherschonender für Daten, die gelesen, aber nicht geändert werden (Anzeige, Berechnungen). Der Preis dafür ist, dass jede Änderung an einer solchen Entität ignoriert wird (Zeile 49): Die Session hat nichts zu synchronisieren ([session.isDirty] ist gleich [false], Zeile 29), und [commit] sendet keine Befehle. Sie können auch eine ganze Session auf Nur-Lesen setzen ([session.isDefaultReadOnly = true]);
  • Zeilen 56–62: eine Falle. Ein Befehl wie [update] in HQL wirkt direkt auf die Datenbank: Er ändert keine Entitäten, die die Session bereits geladen hat. Die von der Session verwaltete Pumpe behält ihren alten Preis (Zeile 37), bis sie mit [session.refresh(pump)] erneut gelesen wird (Zeilen 38–42);
  • Zeilen 68–76: Eine zustandslose Session ([StatelessSession]), hier mit einer Transaktion über [inStatelessTransaction] geöffnet. Sie hat keinen Persistenzkontext: kein First-Level-Cache, keine Änderungsverfolgung, kein Lazy Loading und keine Kaskaden. Jede Operation wird ausdrücklich angefordert ([insert], [update], [delete], [get]) und unverändert ausgeführt. Das ist das Werkzeug für Massenverarbeitung: den Import einer großen Datei, die Neuberechnung aller Zeilen einer Tabelle;
  • Zeile 69: Die SQL-Befehle werden in Batches (siehe Kapitel 10) zu je drei an das DBMS gesendet: Der JDBC-Treiber überträgt drei Befehle in einem einzigen Austausch mit dem Server. In Kotlin wird das Paar [getJdbcBatchSize]/[setJdbcBatchSize] als Eigenschaft verwendet. Das Log zeigt die ersten drei [UPDATE]-Einträge, gefolgt von der Ausführung des Batches (Zeile 58), und endet mit dem letzten Batch aus zwei Befehlen (Zeile 63). Eine Anwendung legt die Batch-Größe für alle ihre Sessions mit der Eigenschaft [hibernate.jdbc.batch_size] fest (typischerweise zwischen 10 und 50). Beachten Sie, dass sich Einfügungen in eine Tabelle, deren Schlüssel durch [IDENTITY] erzeugt wird, nicht zu Batches zusammenfassen lassen.

Bei der Massenverarbeitung mit einer regulären Session müssen Sie verhindern, dass sich in ihrem Persistenzkontext Entitäten ansammeln: Synchronisieren Sie die Session regelmäßig und leeren Sie sie, zum Beispiel alle fünfzig Datensätze ([session.flush(); session.clear()]). In Kotlin teilt die Funktion [chunked] für Sequenzen und Collections (Kapitel 5) die Daten bequem in Blöcke dieser Größe auf.

11.14. Hibernate und Dependency Injection: Spring

11.14.1. Die [SessionFactory] im Container

Die vorherigen Beispiele haben ihre eigenen Sessions erstellt. In einer Anwendung mit Schichten (Kapitel 6) und in allen Spring-Anwendungen ist die [SessionFactory] ein Objekt im Dependency-Injection-Container, genau wie die Schichten, die sie verwenden. Dazu stellt das Spring Framework in seiner Bibliothek [spring-orm] Folgendes bereit:

  • die Klasse [LocalSessionFactoryBean], die die [SessionFactory] aus einer Datenquelle ([DataSource], Kapitel 10) und einer Liste von Entitäten erstellt;
  • die Klasse [HibernateTransactionManager], ein Transaktionsmanager, der für jede Transaktion eine Hibernate-Session öffnet, sie dem aktuellen Thread zuordnet und am Ende der Transaktion schließt;
  • die Annotation [@Transactional] (Bibliothek [spring-tx]): Auf eine Methode angewendet, oder auf eine Klasse für alle ihre öffentlichen Methoden, weist sie Spring an, die Methode innerhalb einer Transaktion auszuführen, die bestätigt wird, wenn die Methode normal endet, und zurückgerollt wird, wenn sie eine nicht abgefangene Exception wirft. Man spricht von deklarativen Transaktionen. Ein Hinweis zu Kotlin: Standardmäßig rollt Spring die Transaktion bei einer von Java so definierten geprüften Exception nicht zurück (zum Beispiel einer [IOException]). Kotlin unterscheidet diese Exceptions nicht von anderen, Spring aber schon: Bei einer Kotlin-Funktion, die innerhalb einer transaktionalen Methode eine [IOException] wirft, wird die Transaktion bestätigt! Wir schreiben daher [@Transactional(rollbackFor = [Exception::class])] , damit die Transaktion in jedem Fall zurückgerollt wird.

Innerhalb einer transaktionalen Methode liefert ***[sessionFactory.currentSession]*** (die Methode *[getCurrentSession] ) die Session der aktuellen Transaktion. Eine [dao]-Schicht kann dann ein Singleton sein, das die [SessionFactory] (Thread-sicher) erhält und in jeder Methode bei ihr die aktuelle Session anfordert: Die Regel „eine Session pro Arbeitseinheit, nie zwischen Threads geteilt“ wird mühelos eingehalten. Vorsicht bei Coroutinen: Die aktuelle Session ist dem Thread zugeordnet, und eine Suspend-Funktion, die mitten in einer Transaktion den Thread wechselt, würde ihre Session verlieren. Deshalb behalten wir die blockierenden transaktionalen Methoden bei und rufen sie aus einer Coroutine innerhalb eines [withContext(Dispatchers.IO)]-Blocks auf, wie im Beispiel [async]* gezeigt.

11.14.2. Das [injection]-Teilprojekt

Das Teilprojekt [injection] hängt zusätzlich zur Bibliothek [articles] von Spring und HikariCP ab:

// Hibernate und Dependency Injection: Spring ORM und deklarative Transaktionen
plugins {
    kotlin("jvm")
    // macht die von Spring annotierten Klassen open (@Configuration, @Transactional...)
    kotlin("plugin.spring")
    application
}

repositories {
    mavenCentral()
}

dependencies {
    // die Entität [Article] und die Datenbank [hbarticles] (Hibernate, MySQL und das SQL-Log eingeschlossen)
    implementation(project(":articles"))
    // Spring: Container, deklarative Transaktionen, Hibernate-Integration
    implementation("org.springframework:spring-context:7.0.9")
    implementation("org.springframework:spring-orm:7.0.9")
    // der Verbindungspool HikariCP
    implementation("com.zaxxer:HikariCP:7.0.2")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // das von [gradlew -q :injection:run] ausgeführte Programm
    mainClass = "injection.MainKt"
}

// unter Windows wird die Bildschirmausgabe des von Gradle gestarteten Programms (run, bootRun ...) in UTF-8 kodiert,
// sonst werden Zeichen mit Akzenten in der IntelliJ-IDEA-Konsole oder im Terminal falsch dargestellt
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • Zeile 5: Das für Spring konfigurierte Plugin [all-open] (Kapitel 6). Es macht die mit [@Configuration] sowie mit [@Transactional] und einigen weiteren ([@Component], [@Service], [@Async] ...) annotierten Klassen sowie deren Methoden offen. Wir werden sehen, warum das unerlässlich ist;
  • Zeile 15: die Entität [Article] und die Datenbank [hbarticles] (einschließlich Hibernate, MySQL und des SQL-Logs);
  • Zeilen 17–18: der Spring-Container und die Hibernate-Integration; [spring-orm] enthält [spring-tx], die Transaktionsbibliothek;
  • Zeile 19: der HikariCP-Verbindungspool (Kapitel 10);
  • Zeilen 36–39: Von Gradle gestartete Programme schreiben ihre Ausgabe in UTF-8, damit Zeichen mit Akzenten unter Windows korrekt angezeigt werden (Kapitel 2).

Die Spring-Konfiguration ist in Kotlin geschrieben, mit den Annotationen [@Configuration] und [@Bean] aus Kapitel 6:

package injection

import articles.Article
import articles.BaseArticles
import com.zaxxer.hikari.HikariDataSource
import java.util.Properties
import javax.sql.DataSource
import org.hibernate.SessionFactory
import org.hibernate.cfg.AvailableSettings
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.orm.jpa.hibernate.HibernateTransactionManager
import org.springframework.orm.jpa.hibernate.LocalSessionFactoryBean
import org.springframework.transaction.annotation.EnableTransactionManagement

// die Spring-Konfiguration: Verbindungspool, SessionFactory, Transaktionsmanager, [dao]-Schicht
@Configuration
@EnableTransactionManagement
class Config {

    // der Verbindungspool HikariCP (Kapitel 10)
    @Bean(destroyMethod = "close")
    fun dataSource() = HikariDataSource().apply {
        jdbcUrl = BaseArticles.URL
        username = BaseArticles.USER
        password = BaseArticles.PASSWORD
    }

    // die SessionFactory, von Spring mit dem Verbindungspool erstellt
    @Bean
    fun sessionFactory(dataSource: DataSource) = LocalSessionFactoryBean().apply {
        setDataSource(dataSource)
        setAnnotatedClasses(Article::class.java)
        hibernateProperties = Properties().apply { put(AvailableSettings.FORMAT_SQL, "true") }
    }

    // der Transaktionsmanager: eine Hibernate-Session pro Transaktion
    @Bean
    fun transactionManager(sessionFactory: SessionFactory) = HibernateTransactionManager(sessionFactory)

    // die [dao]-Schicht: ein Singleton, das die SessionFactory erhält
    @Bean
    fun articlesDao(sessionFactory: SessionFactory) = ArticlesDao(sessionFactory)
}
  • Zeile 18: aktiviert die Annotation [@Transactional]: Spring ersetzt jedes Objekt, das eine Methode mit dieser Annotation besitzt, durch einen Proxy, der die Transaktion um den Aufruf herum öffnet und bestätigt;
  • Zeilen 22–26: der HikariCP-Verbindungspool aus Kapitel 10, konfiguriert in einem [apply]-Block: Die Setter [setJdbcUrl], [setUsername] und [setPassword] werden als Eigenschaften verwendet. Das Attribut [destroyMethod] gibt die Methode an, die beim Herunterfahren des Containers aufgerufen wird. Der abgeleitete Rückgabetyp der Funktion ist [HikariDataSource]: Unter diesem Typ registriert Spring die Bean;
  • Zeilen 31–34: [SessionFactory]. Eine *[LocalSessionFactoryBean] ist eine Factory für *[SessionFactory]*: Spring registriert das von ihr erzeugte Objekt im Container, und man erhält eine *[SessionFactory] , wenn man diese Bean anfordert. Sie erhält den Verbindungspool (der den eingebauten Pool von Hibernate ersetzt), die Entitäten und die Hibernate-Eigenschaften. Wir schreiben [setDataSource(dataSource)] statt [dataSource = dataSource], was den Parameter sich selbst zuweisen würde (und abgelehnt würde, da ein Parameter schreibgeschützt ist);
  • Zeile 39: der Transaktionsmanager;
  • Zeile 43: die [dao]-Schicht, die die [SessionFactory] erhält.

Die [dao]-Schicht:

package injection

import articles.Article
import org.hibernate.Session
import org.hibernate.SessionFactory
import org.springframework.transaction.annotation.Transactional

// die [dao]-Schicht: jede öffentliche Methode läuft in einer von Spring geöffneten Transaktion
@Transactional
class ArticlesDao(
    // die SessionFactory, von allen Threads gemeinsam genutzt
    private val sessionFactory: SessionFactory
) {

    // liefern zwei Anforderungen der aktuellen Session in derselben Transaktion dieselbe Session?
    fun sameSession() = sessionFactory.currentSession === sessionFactory.currentSession

    // die Session der Transaktion
    fun session(): Session = sessionFactory.currentSession

    // die aufzufüllenden Artikel; eine Read-only-Transaktion
    @Transactional(readOnly = true)
    fun articlesOutOfStock(): List<String> {
        val hql = "select name from Article where currentStock < minimumStock"
        return sessionFactory.currentSession.createSelectionQuery(hql, String::class.java).resultList
    }

    // der Artikel mit dem angegebenen Namen
    @Transactional(readOnly = true)
    fun article(name: String): Article =
        sessionFactory.currentSession
            .createSelectionQuery("from Article where name = :name", Article::class.java)
            .setParameter("name", name)
            .singleResult

    // der Verkauf einer Menge eines Artikels: eine Exception setzt die Transaktion zurück
    fun sell(name: String, quantity: Int) {
        val article = article(name)
        article.currentStock -= quantity
        // check wirft eine IllegalStateException, wenn die Bedingung falsch ist
        check(article.currentStock >= 0) { "insufficient stock for the article [$name]" }
    }
}
  • Zeile 9: Alle öffentlichen Methoden der Klasse sind transaktional;
  • Zeile 12: die [SessionFactory], die vom primären Konstruktor entgegengenommen wird;
  • Zeile 16: Liefern innerhalb derselben Transaktion zwei Anforderungen der aktuellen Session dieselbe Session? Der Operator [===] vergleicht die Referenzen (Kapitel 3);
  • Zeile 19: die Session der Transaktion, an den Aufrufer zurückgegeben (für das folgende Experiment: In einer echten Anwendung geschieht das nicht);
  • Zeilen 22–25: eine Nur-Lese-Transaktion ([readOnly = true]): Spring setzt die Session auf Nur-Lesen und synchronisiert sie nicht;
  • Zeilen 37–41: der Verkauf einer Menge eines Artikels. Wird der Lagerbestand negativ, wirft die Kotlin-Funktion [check] (Kapitel 3) eine [IllegalStateException], eine nicht behandelte Exception: Spring rollt die Transaktion zurück. Der Aufruf der Methode [article] (Zeile 38) ist ein interner Aufruf innerhalb des Objekts, der nicht über den Proxy läuft: Er wird innerhalb der Transaktion von [sell] ausgeführt.

Der von Spring für die Klasse [ArticlesDao] erzeugte Proxy ist eine Unterklasse von ihr, die zur Laufzeit von der Bibliothek CGLIB generiert wird und jede öffentliche Methode neu definiert, um sie in eine Transaktion einzubetten. Ohne das Plugin [plugin.spring] wäre die Kotlin-Klasse final, und Spring könnte nicht von ihr ableiten. Wenn Sie das Teilprojekt ohne dieses Plugin kompilieren (indem Sie die Klasse [Config] und ihre [open]-Funktionen manuell deklarieren, um den ersten Fehler zu umgehen, dem wir schon in Kapitel 6 begegnet sind), weigert sich der Container zu starten:

1
2
3
Exception in thread "main" org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'articlesDao' defined in injection.Config: Could not generate CGLIB subclass of class injection.ArticlesDao: Common causes of this problem include using a final class or a non-visible class
Caused by: org.springframework.aop.framework.AopConfigException: Could not generate CGLIB subclass of class injection.ArticlesDao: Common causes of this problem include using a final class or a non-visible class
Caused by: java.lang.IllegalArgumentException: Cannot subclass final class injection.ArticlesDao

Eine tückischere Falle erwartet jeden, der die Klasse manuell öffnet ([open class ArticlesDao]), ohne ihre Methoden zu öffnen: Der Proxy wird dann erstellt, kann aber die Methoden, die final bleiben, nicht überschreiben. Der direkte Aufruf dieser Methoden führt den Code der Klasse [ArticlesDao] auf dem Proxy-Objekt aus, dessen Felder nicht initialisiert wurden (Spring erzeugt es, ohne den Konstruktor der Klasse aufzurufen). Das Ergebnis, das man beim Kompilieren des Teilprojekts auf diese Weise erhält, ist verwirrend:

--- sessions and transactions
Exception in thread "main" java.lang.NullPointerException: Cannot invoke "org.hibernate.SessionFactory.getCurrentSession()" because "this.sessionFactory" is null

Die Eigenschaft [sessionFactory], die einen nicht nullbaren Typ hat, ist auf [null] gesetzt! Das Plugin verhindert diese beiden Fehler: Mit ihm sind die Klasse und alle ihre Methoden offen.

Das Hauptprogramm:

package injection

import articles.BaseArticles
import org.hibernate.HibernateException
import org.hibernate.SessionFactory
import org.springframework.beans.factory.getBean
import org.springframework.context.annotation.AnnotationConfigApplicationContext

// Hibernate im Spring-Container: aktuelle Session und deklarative Transaktionen
fun main() {
    // der Spring-Container, konfiguriert durch die Klasse [Config]
    AnnotationConfigApplicationContext(Config::class.java).use { context ->
        // die Tabelle [articles] wird mit ihren sechs Artikeln neu erstellt
        val sessionFactory = context.getBean<SessionFactory>()
        BaseArticles.initialize(sessionFactory)
        val dao = context.getBean<ArticlesDao>()

        // 1 - während einer Transaktion ist die aktuelle Session immer dieselbe
        println("--- sessions and transactions")
        println("one transaction: same session = ${dao.sameSession()}")
        // 2 - zwei Transaktionen: zwei Sessions, am Ende ihrer Transaktion geschlossen
        val session1 = dao.session()
        val session2 = dao.session()
        println("two transactions: same session = ${session1 === session2}, " +
                "first session open = ${session1.isOpen}")
        // 3 - außerhalb einer Transaktion gibt es keine aktuelle Session
        try {
            sessionFactory.currentSession
        } catch (e: HibernateException) {
            println("${e::class.simpleName} : ${e.message}")
        }

        // 4 - transaktionale Methoden der [dao]-Schicht
        println("--- articles out of stock")
        println("out of stock: ${dao.articlesOutOfStock()}")
        println("--- sale of 2 bikes")
        dao.sell("bike", 2)
        println("--- sale of 50 pumps")
        try {
            dao.sell("pump", 50)
        } catch (e: IllegalStateException) {
            println("${e::class.simpleName} : ${e.message}")
        }
        println("--- state of the database")
        println(dao.article("bike"))
        println(dao.article("pump"))
    }
}

Ergebnisse:

> gradlew -q :injection:run
--- sessions and transactions
    SQL> -- start of transaction
    SQL> -- transaction committed (COMMIT)
one transaction: same session = true
    SQL> -- start of transaction
    SQL> -- transaction committed (COMMIT)
    SQL> -- start of transaction
    SQL> -- transaction committed (COMMIT)
two transactions: same session = false, first session open = false
HibernateException : Could not obtain transaction-synchronized Session for current thread
--- articles out of stock
    SQL> -- start of transaction
    SQL> select a1_0.name
    SQL> from articles a1_0
    SQL> where a1_0.currentStock<a1_0.minimumStock
    SQL> -- transaction committed (COMMIT)
out of stock: [arrows - set of 6]
--- sale of 2 bikes
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = bike
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 8
    SQL> -- parameter 2 = 5
    SQL> -- parameter 3 = bike
    SQL> -- parameter 4 = 500.00
    SQL> -- parameter 5 = 1
    SQL> -- transaction committed (COMMIT)
--- sale of 50 pumps
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = pump
    SQL> -- transaction rolled back (ROLLBACK)
IllegalStateException : insufficient stock for the article [pump]
--- state of the database
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = bike
    SQL> -- transaction committed (COMMIT)
[1, bike, 500.00, 8, 5]
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = pump
    SQL> -- transaction committed (COMMIT)
[2, pump, 10.00, 10, 2]

Kommentare:

  • Zeile 12: der Spring-Container, konfiguriert durch die Klasse [Config]. Er wird am Ende des [use]-Blocks geschlossen, der die [SessionFactory] und den Verbindungspool schließt;
  • Zeile 14: die von Spring erstellte [SessionFactory] , die über die Erweiterungsfunktion [getBean<T>()] von Spring bezogen wird (Kapitel 6); mit ihr wird die Artikeltabelle neu angelegt;
  • Zeile 20: eine Transaktion (Zeilen 3–4): Innerhalb derselben Transaktion bleibt die aktuelle Session dieselbe (Zeile 5);
  • Zeilen 22–25: zwei Aufrufe, zwei Transaktionen (Zeilen 6–9), zwei verschiedene Sessions; die erste ist geschlossen, da ihre Transaktion abgeschlossen ist (Zeile 10). Die Eigenschaft [isOpen] ist die Methode [isOpen()] der Session;
  • Zeilen 28–29: Außerhalb einer Transaktion gibt es keine aktuelle Session: [getCurrentSession] löst eine [HibernateException] aus (Zeile 11). Das ist der klassische Fehler einer Methode, bei der die Annotation [@Transactional] vergessen wurde;
  • Zeile 35: eine Nur-Lese-Transaktion (Zeilen 13–17);
  • Zeile 37: der Verkauf von zwei Fahrrädern. Die Transaktion wird bestätigt, und die Synchronisierung der Session sendet das [UPDATE] (Zeilen 20–33);
  • Zeilen 40–41: Der Verkauf von fünfzig Pumpen löst eine Exception aus: Spring rollt die Transaktion zurück (Zeile 40), und das [UPDATE] wird nie gesendet, da die Session nicht synchronisiert wurde;
  • Zeilen 45–46: Zustand der Datenbank: Der Lagerbestand der Fahrräder hat sich auf 8 geändert, während der Lagerbestand der Pumpen bei 10 bleibt (Zeilen 49 und 56).

In einer Spring-Boot-Anwendung geschieht das alles automatisch: Spring Boot erstellt den Verbindungspool, die Factory (in ihrer Jakarta-Persistence-Form eine [EntityManagerFactory]) und den Transaktionsmanager aus der Datei [application.properties]. Spring Data JPA wird häufig auf Hibernate aufgesetzt; es erzeugt die [dao]-Schicht aus einer einfachen Schnittstelle: [interface ArticleRepository : JpaRepository<Article, Int>] stellt [findAll], [findById], [save], [delete] ... bereit, und eine deklarierte Methode [fun findByPriceLessThan(price: BigDecimal): List<Article>] wird automatisch in eine Abfrage übersetzt. Spring Data ergänzt einige Erweiterungsfunktionen für Kotlin, etwa [findByIdOrNull], die einen [Article?] statt eines [Optional<Article>] zurückgibt.

11.15. Beispielanwendung - Version 7

11.15.1. Die Architektur

Version 6 der Anwendung zur Steuerberechnung (Kapitel 10) las die Steuerstufen mit JDBC aus einer MySQL-Datenbank. Version 7 tut dasselbe mit Hibernate. Wie bei Version 6 ändert sich nur die [dao]-Schicht: Die Schichten [business] und [ui] aus Version 5 (Kapitel 6) werden dank der zusammengesetzten Architektur unverändert wiederverwendet.

Image

Version 7 besteht aus zwei Teilprojekten der Struktur aus Kapitel 11, die im Ordner [TaxV7] abgelegt sind:

11-hibernate/
  settings.gradle.kts                   the subprojects and the included build (chapter 6)
  TaxV7/
    tax-dao-hibernate/                  library: the Hibernate [dao] layer
      build.gradle.kts
      src/main/kotlin/tax/dao/
        Bracket.kt                      the entity
        HibernateTax.kt                 the implementation of ITaxDao
        CreateDatabase.kt               the creation of the [hbtaxes] database
      src/main/resources/
        logback.xml
    tax-ui-hibernate/                   executable: integration of the layers
      build.gradle.kts
      src/main/kotlin/tax/ui/
        MainHibernate.kt
      tax-hibernate.properties
      tax-hibernate-error.properties

Der Ordner [TaxV7] hat keine Build-Datei: Wie der Ordner [TaxV5] in Kapitel 6 ist er einfach eine Sammlung von Teilprojekten. Die Module von Version 5 ([tax-dao], [tax-business], [tax-ui], in Version 5.0) stellt der Build aus Kapitel 6 bereit, eingebunden über die Zeile [includeBuild("../06-architectures")] in der Datei [settings.gradle.kts]: Gradle ersetzt jede Abhängigkeit [examples.tax:tax-xxx:5.0] durch das entsprechende Teilprojekt dieses Builds, das es bei Bedarf kompiliert. Es muss vorab nichts installiert werden, anders als bei Maven, wo Sie zuvor im Ordner von Version 5 [mvn install] eingeben mussten.

11.15.2. Die [dao]-Schicht

Das Teilprojekt [tax-dao-hibernate] hängt von der [dao]-Schicht aus Version 5 ab, die die Entitäten der Anwendung ([TaxBracket], [TaxException]) und die Schnittstelle [ITaxDao] enthält:

// TaxV7: das Unterprojekt tax-dao-hibernate, eine Bibliothek (die mit Hibernate geschriebene [dao]-Schicht)
plugins {
    kotlin("jvm")
    // die Entität [Bracket]: die Plugins [jpa] und [allopen]
    kotlin("plugin.jpa")
    kotlin("plugin.allopen")
    // das Bibliotheks-Plugin: es fügt die Konfiguration [api] hinzu
    `java-library`
    // [gradlew -q :TaxV7:tax-dao-hibernate:run] erstellt die Datenbank [hbtaxes]
    application
}

// die Koordinaten der Bibliothek: examples.tax:tax-dao-hibernate:7.0
group = "examples.tax"
version = "7.0"

repositories {
    mavenCentral()
}

dependencies {
    // die [dao]-Schicht von Version 5 (Kapitel 6): Entitäten, Interface ITaxDao, HardwiredTax
    api("examples.tax:tax-dao:5.0")
    // Hibernate, der MySQL-JDBC-Treiber und Logback
    implementation("org.hibernate.orm:hibernate-core:7.4.5.Final")
    runtimeOnly("com.mysql:mysql-connector-j:9.7.0")
    runtimeOnly("ch.qos.logback:logback-classic:1.5.38")
}

// die so annotierten Klassen werden vom Plugin [allopen] geöffnet
allOpen {
    annotation("jakarta.persistence.Entity")
    annotation("jakarta.persistence.MappedSuperclass")
    annotation("jakarta.persistence.Embeddable")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // die Erstellung der Datenbank [hbtaxes]
    mainClass = "tax.dao.CreateDatabaseKt"
}

// unter Windows wird die Bildschirmausgabe des von Gradle gestarteten Programms (run, bootRun ...) in UTF-8 kodiert,
// sonst werden Zeichen mit Akzenten in der IntelliJ-IDEA-Konsole oder im Terminal falsch dargestellt
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • Zeilen 5–6: Entitäts-Plugins: Das Teilprojekt definiert die Entität [Bracket];
  • Zeile 8: Das Teilprojekt ist eine Bibliothek, die einige ihrer Abhängigkeiten über die Konfiguration [api] nach außen bereitstellt;
  • Zeile 10: das Plugin [application], das zum Erstellen der Datenbank verwendet wird (Zeile 47);
  • Zeile 23: die [dao]-Schicht von Version 5. Das ist eine Abhängigkeit vom Typ [api]: Die Klasse [HibernateTax] implementiert die Schnittstelle [ITaxDao] aus dieser Bibliothek, die ihre Benutzer daher ebenfalls sehen müssen;
  • Zeilen 25–27: Hibernate, der JDBC-Treiber für MySQL und Logback. Hibernate ist eine Abhängigkeit vom Typ [implementation]: Es wird intern von der Bibliothek verwendet, erscheint aber nicht in ihrer öffentlichen Schnittstelle;
  • Zeilen 31–34: die Standardkonfiguration für das Plugin [allopen];
  • Zeilen 50–53: Von Gradle gestartete Programme schreiben ihre Ausgabe in UTF-8, damit Zeichen mit Akzenten unter Windows korrekt angezeigt werden (Kapitel 2).

Die Datenklasse [TaxBracket] aus Version 5 kann keine Hibernate-Entität sein: Sie ist eine Datenklasse (wir haben gesehen, warum das für eine Entität keine gute Idee ist), sie ist unveränderlich, und sie hat keinen Bezeichner. Wir ändern sie nicht, weil sie Teil des Vertrags zwischen den Schichten ist, den alle Versionen gemeinsam nutzen. Wir erstellen eine Entität, die für die [dao]-Schicht spezifisch ist und deren Aufgabe es ist, eine Zeile der Tabelle darzustellen:

// eine Steuerstufe, wie sie in der Datenbank gespeichert ist: eine Hibernate-Entität
@Entity
@Table(name = "brackets")
class Bracket(
    @Column(name = "limits", nullable = false, precision = 10, scale = 2)
    private var limit: BigDecimal,

    @Column(name = "coeffr", nullable = false, precision = 6, scale = 4)
    private var coeffR: BigDecimal,

    @Column(name = "coeffn", nullable = false, precision = 10, scale = 2)
    private var coeffN: BigDecimal,
) {
    // der Primärschlüssel, der in der Klasse TaxBracket nicht existiert
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private var id: Int? = null
}
  • Zeile 3: die Tabelle [brackets];
  • Zeilen 6–12: die drei Spalten, deklariert im primären Konstruktor, mit passenden [decimal]-Typen: Die Grenze und der Koeffizient [coeffN] sind Beträge mit zwei Nachkommastellen, und [coeffR] ist ein Satz mit vier Nachkommastellen. Die Spaltennamen sind kleingeschrieben. Die Eigenschaften sind privat: Die Entität dient nur zum Befüllen der Tabelle ([CreateDatabase]) und zum Schreiben von Abfragen; der Rest der Anwendung sieht sie nie. Hibernate, das direkt auf die Felder zugreift, verlangt nicht, dass sie öffentlich sind;
  • Zeilen 15–17: der Primärschlüssel, der auch zum Sortieren der Stufen dient.

Die Klasse [HibernateTax] implementiert die Schnittstelle [ITaxDao]:

package tax.dao

import tax.entities.TaxException
import tax.entities.TaxBracket
import jakarta.persistence.PersistenceException
import org.hibernate.jpa.HibernatePersistenceConfiguration

// eine [dao]-Schicht, die die Steuerstufen mit Hibernate aus einer Datenbank liest
class HibernateTax(url: String, user: String, password: String) : ITaxDao {

    companion object {
        // für diese Implementierung spezifische Fehlercodes
        const val ACCESS_ERROR = 1
        const val EMPTY_TABLE = 2
    }

    // Steuerstufen, einmalig bei der Konstruktion gelesen
    override val taxBrackets: List<TaxBracket> = try {
        // eine kurzlebige SessionFactory, gerade lange genug, um die Tabelle zu lesen
        HibernatePersistenceConfiguration("tax")
            .managedClass(Bracket::class.java)
            .jdbcUrl(url)
            .jdbcCredentials(user, password)
            .createEntityManagerFactory()
            .use { sessionFactory ->
                // die Zeilen der Tabelle werden auf die Klasse TaxBracket der Anwendung projiziert
                val hql = "select b.limit, b.coeffR, b.coeffN from Bracket b order by b.id"
                sessionFactory.fromSession { session ->
                    session.createSelectionQuery(hql, TaxBracket::class.java).resultList
                }
            }
    } catch (e: PersistenceException) {
        // Hibernate- oder DBMS-Fehler: er wird in eine TaxException verpackt
        throw TaxException("Error while reading the tax brackets from the database",
            e, ACCESS_ERROR)
    }

    init {
        // die [business]-Schicht benötigt mindestens eine Stufe
        if (taxBrackets.isEmpty()) {
            throw TaxException("The tax brackets table is empty", code = EMPTY_TABLE)
        }
    }
}
  • Zeilen 11–14: die Fehlercodes dieser Implementierung, wie bei [FileTax] und [JsonTax];
  • Zeile 9: Die [dao]-Schicht erhält die URL der Datenbank sowie den Benutzer und sein Passwort. Das sind einfache Konstruktorparameter ([val] wird nicht geschrieben: Sie werden nicht zu Eigenschaften, da sie nur für die Konstruktion verwendet werden). Sie liest die Stufen einmalig bei der Konstruktion: Sie wird ein Singleton sein;
  • Zeile 18: die Eigenschaft [taxBrackets] der Schnittstelle [ITaxDao], initialisiert durch einen [try] -Ausdruck (Kapitel 3): Ihr Wert ist der des [try]-Blocks; tritt ein Fehler auf, wirft [catch] eine Exception;
  • Zeilen 20–25: Eine kurzlebige [SessionFactory] – gerade lange genug, um die Tabelle zu lesen – die sofort von [use] geschlossen wird. Da die Schicht nur ein einziges Mal auf die Datenbank zugreift, muss sie sie nicht aufbewahren; eine [dao]-Schicht, die bei jedem Aufruf auf die Datenbank zugreift, würde stattdessen eine einmalig erstellte [SessionFactory] erhalten, wie im vorherigen Beispiel;
  • Zeilen 27–29: Lesen der Tabelle in der Reihenfolge des Primärschlüssels. Die Abfrage ist eine Projektion auf die Datenklasse [TaxBracket]: Hibernate fordert vom DBMS nur die drei relevanten Spalten an und erzeugt direkt die Anwendungsobjekte, indem es den Konstruktor von *[TaxBracket] mit den drei Werten aufruft, ohne den Umweg über *[Bracket] -Entitäten. Der von [fromSession] und dann von [use] zurückgegebene Wert ist die gelesene Liste: Das ist der Wert der Eigenschaft;
  • Zeilen 32–35: Ein Fehler von Hibernate oder des DBMS (Datenbank nicht erreichbar, Tabelle fehlt usw.) äußert sich als [PersistenceException] (die Basisklasse der Jakarta-Persistence-Exceptions, von der die Exceptions von Hibernate abgeleitet sind). Wie bei den anderen Implementierungen wird sie in eine *[TaxException] eingebettet. Die Exception kann schon bei der Erstellung der *[SessionFactory]* auftreten (Zeile 24), die sich mit dem Server verbindet: Sie liegt ebenfalls innerhalb des ***[try]** -Blocks;
  • Zeilen 38–41: Eine leere Tabelle ist ebenfalls ein Fehler: Die [business]-Schicht verlangt mindestens eine Zeile. Der [init]-Block wird nach der Initialisierung der Eigenschaft ausgeführt, die in der Klasse vor ihm steht. Der Fehlercode wird über ein benanntes Argument übergeben ([code = EMPTY_TABLE]), da die Exception keine Ursache hat (Kapitel 6).

11.15.3. Die Datenbank

Die Datenbank [hbtaxes] wird vom Programm [CreateDatabase.kt] erstellt. Um die Tarifstufen nicht neu schreiben zu müssen, verwendet es die der Klasse [HardwiredTax] aus Version 5 wieder:

package tax.dao

import org.hibernate.jpa.HibernatePersistenceConfiguration
import org.hibernate.tool.schema.Action

// Erstellung der Datenbank [hbtaxes]: die Tabelle [brackets], gefüllt mit den Stufen von HardwiredTax
fun main() {
    HibernatePersistenceConfiguration("tax")
        .managedClass(Bracket::class.java)
        .jdbcUrl("jdbc:mysql://localhost:3306/hbtaxes?createDatabaseIfNotExist=true")
        .jdbcCredentials("root", "")
        // Anzeige der SQL-Anweisungen, ohne Formatierung
        .showSql(true, false, false)
        // die Tabelle wird beim Erstellen der SessionFactory gelöscht und neu erstellt
        .schemaToolingAction(Action.CREATE)
        .createEntityManagerFactory()
        .use { sessionFactory ->
            // die Stufen des Steuertarifs, die von Version 5, vom DBMS ab 1 nummeriert
            sessionFactory.inTransaction { session ->
                for ((limit, coeffR, coeffN) in HardwiredTax().taxBrackets) {
                    session.persist(Bracket(limit, coeffR, coeffN))
                }
            }
        }
}
  • Zeile 10: die Datenbank [hbtaxes], die MySQL anlegt, falls sie nicht existiert;
  • Zeile 13: zeigt die SQL-Anweisungen ohne Formatierung an;
  • Zeile 15: Die Tabelle wird gelöscht und dann neu angelegt, wenn die [SessionFactory] erstellt wird;
  • Zeilen 19–21: eine [Bracket]-Entität pro Stufe der Klasse [HardwiredTax], die in einer Transaktion persistiert wird. Die [for]-Schleife zerlegt jede [TaxBracket] in ihre drei Bestandteile ([(limit, coeffR, coeffN)]) mithilfe der Funktionen [component1], [component2] und [component3], die für eine Datenklasse generiert werden (Kapitel 4).

Das Teilprojekt enthält außerdem eine Datei namens [logback.xml], die von [CreateDatabase.kt] und von der Anwendung verwendet wird und nur die folgenden Fehler durchlässt:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Logback-Konfiguration: nur Hibernate-Fehler werden angezeigt -->
<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%-5level %logger{0} - %msg%n</pattern>
        </encoder>
    </appender>
    <!-- die Fehler des DBMS werden der Anwendung durch Exceptions übergeben: sie werden nicht geloggt -->
    <logger name="org.hibernate.orm.jdbc.error" level="OFF"/>
    <root level="ERROR">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>
  • Zeile 10: Fehler des DBMS, die Hibernate protokolliert, bevor es eine Exception wirft, werden nicht angezeigt: Die Anwendung meldet sie selbst;
  • Zeile 11: Die übrigen Logs erfassen nur Fehler.

Ausführung:

> gradlew -q :TaxV7:tax-dao-hibernate:run
Hibernate: drop table if exists brackets
Hibernate: create table brackets (coeffn decimal(10,2) not null, coeffr decimal(6,4) not null, id integer not null auto_increment, limits decimal(10,2) not null, primary key (id)) engine=InnoDB
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)

Wir überprüfen den Inhalt der Tabelle:

> mysql -uroot -t hbtaxes -e "SELECT id, limits, coeffr, coeffn FROM brackets"
+----+----------+--------+---------+
| id | limits   | coeffr | coeffn  |
+----+----------+--------+---------+
|  1 |  4962.00 | 0.0000 |    0.00 |
|  2 |  8382.00 | 0.0680 |  291.09 |
|  3 | 14753.00 | 0.1910 | 1322.92 |
|  4 | 23888.00 | 0.2830 | 2668.39 |
|  5 | 38868.00 | 0.3740 | 4846.98 |
|  6 | 47932.00 | 0.4260 | 6883.66 |
|  7 |     0.00 | 0.4810 | 9505.54 |
+----+----------+--------+---------+

Wir sehen die Tarifstufen, wobei die letzte eine Grenze von null hat (sie wird von der [business]-Schicht nicht verwendet, die die letzte Stufe wählt, wenn keine andere zutrifft).

So erstellen Sie die Datenbank auf Ihrem eigenen System:

  • Starten Sie MySQL (in Laragon; siehe Anhang; Benutzer [root] ohne Passwort);
  • Wechseln Sie in den Ordner [11-hibernate] und geben Sie den Befehl [gradlew -q :TaxV7:tax-dao-hibernate:run] ein (oder führen Sie [CreateDatabase.kt] in IntelliJ IDEA aus, mit dem grünen Dreieck vor der Funktion [main]). Gradle kompiliert gleichzeitig die Module von Version 5 im benachbarten Ordner [06-architectures].

Die Datenbank [hbtaxes] wird dann angelegt, ihre Tabelle [brackets] ist befüllt. Schlägt der Befehl fehl, prüfen Sie, ob MySQL läuft und ob die URL in [CreateDatabase.kt] Ihrem Server entspricht (Port 3306, Benutzername [root], leeres Passwort). Alternativ können Sie die Tabelle und ihre Zeilen auch mit einem SQL-Skript erstellen, wie in Kapitel 10 beschrieben.

11.15.4. Integration der Schichten

Das Teilprojekt [tax-ui-hibernate] vereint die folgenden Schichten:

// TaxV7: das Unterprojekt tax-ui-hibernate, die Integration der Schichten
plugins {
    kotlin("jvm")
    application
}

group = "examples.tax"
version = "7.0"

repositories {
    mavenCentral()
}

dependencies {
    // die [business]- und [ui]-Schichten von Version 5, unverändert (Composite Build)
    implementation("examples.tax:tax-business:5.0")
    implementation("examples.tax:tax-ui:5.0")
    // die neue [dao]-Schicht, die Hibernate, den JDBC-Treiber und Logback mitbringt
    implementation(project(":TaxV7:tax-dao-hibernate"))
    // der Dependency-Injection-Container von Spring
    implementation("org.springframework:spring-context:7.0.9")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // das Hauptprogramm: gradlew -q :TaxV7:tax-ui-hibernate:run [--args="file.properties"]
    mainClass = "tax.ui.MainHibernateKt"
}

tasks.named<JavaExec>("run") {
    // das Programm liest die Tastatur
    standardInput = System.`in`
}

// unter Windows wird die Bildschirmausgabe des von Gradle gestarteten Programms (run, bootRun ...) in UTF-8 kodiert,
// sonst werden Zeichen mit Akzenten in der IntelliJ-IDEA-Konsole oder im Terminal falsch dargestellt
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • Zeilen 16–17: die Schichten [business] und [ui] aus Version 5. Das Teilprojekt [tax-ui] enthält das Hauptprogramm von Version 5; es wird hier als Bibliothek verwendet, genauer gesagt für sein Objekt [Dialog];
  • Zeile 19: die neue [dao]-Schicht, die Hibernate, den JDBC-Treiber und Logback einbindet;
  • Zeile 21: der Spring-Container;
  • Zeile 34: die Hauptklasse;
  • Zeilen 37–39: Das Programm liest von der Tastatur (Kapitel 6);
  • Zeilen 42–45: Von Gradle gestartete Programme schreiben ihre Ausgabe in UTF-8, damit Zeichen mit Akzenten unter Windows korrekt angezeigt werden (Kapitel 2).

Die Konfigurationsdatei [tax-hibernate.properties] im Ordner des Teilprojekts legt die Datenbank fest:

1
2
3
4
# Konfiguration der [Tax]-Anwendung, Version 7: die Datenbank der Steuerstufen
jdbc.url=jdbc:mysql://localhost:3306/hbtaxes
jdbc.user=root
jdbc.password=

Die Datei [tax-hibernate-error.properties] verweist auf eine Datenbank namens [hbtaxesmissing], die nicht existiert:

1
2
3
4
# eine nicht existierende Datenbank
jdbc.url=jdbc:mysql://localhost:3306/hbtaxesmissing
jdbc.user=root
jdbc.password=

Das Hauptprogramm ist das aus Version 5, in dem sich nur die Zusammensetzung der [dao]-Schicht ändert:

package tax.ui

import tax.dao.HibernateTax
import tax.dao.ITaxDao
import tax.entities.TaxException
import tax.business.ITaxBusiness
import tax.business.TaxBusiness
import java.util.Properties
import kotlin.io.path.Path
import kotlin.io.path.bufferedReader
import kotlin.system.exitProcess
import org.springframework.beans.factory.getBean
import org.springframework.context.support.GenericApplicationContext
import org.springframework.context.support.registerBean

// Version 7: die [dao]-Schicht liest die Steuerstufen mit Hibernate aus einer Datenbank
fun main(args: Array<String>) {
    // die Konfigurationsdatei: standardmäßig tax-hibernate.properties oder die als Argument übergebene
    val configFile = args.firstOrNull() ?: "tax-hibernate.properties"

    // Integration der Schichten
    val business: ITaxBusiness = try {
        // Lesen der Konfiguration im aktuellen Ordner
        val config = Properties()
        Path(configFile).bufferedReader().use { config.load(it) }
        val url = config.getProperty("jdbc.url")
            ?: throw TaxException("Database URL [jdbc.url] missing from the file $configFile")
        val user = config.getProperty("jdbc.user", "root")
        val password = config.getProperty("jdbc.password", "")

        // der Spring-Container: die Schichten werden darin registriert
        val context = GenericApplicationContext()
        // die [dao]-Schicht: HibernateTax, mit der Datenbank der Konfiguration
        context.registerBean<ITaxDao> { HibernateTax(url, user, password) }
        // die [business]-Schicht von Version 5: der Container übergibt ihr die [dao]-Schicht
        context.registerBean<TaxBusiness>()

        // Start des Containers: er erstellt die [dao]-Schicht, dann die [business]-Schicht
        context.refresh()
        context.getBean<ITaxBusiness>()
    } catch (e: Exception) {
        // Anzeige des Fehlers und Ende des Programms
        Dialog.displayError(e)
        exitProcess(1)
    }

    // der Dialog mit dem Benutzer, der von Version 5
    Dialog.run(business)
}
  • Die Datei heißt nicht [Main.kt]: Sie würde in eine Klasse namens [tax.ui.MainKt] kompiliert, die im Modul [tax-ui] von Version 5, von dem wir abhängen, bereits existiert. Die Datei [MainHibernate.kt] erzeugt eine Klasse namens [tax.ui.MainHibernateKt];
  • Zeilen 26–29: die erforderliche URL der Datenbank, der Benutzername und das Passwort, gelesen aus der Konfiguration. [getProperty] gibt für einen fehlenden Schlüssel [null] zurück: Der Elvis-Operator ([?:]) wertet dann zu [TaxException] aus ([throw] ist in Kotlin ein Ausdruck);
  • Zeile 34: Die [dao]-Schicht ist eine [HibernateTax], erzeugt von einem Lambda, das ihr die Parameter der Datenbank übergibt;
  • Zeile 36: die [business]-Schicht aus Version 5: Der Container übergibt die [dao]-Schicht an ihren Konstruktor;
  • Zeile 48: der Dialog aus Version 5.

11.15.5. Ausführungen

Die Eingaben des Benutzers, die zum Erzeugen dieser Ergebnisse an das Programm umgeleitet wurden, wurden hinter die Fragen gesetzt:

1
2
3
4
5
6
7
8
> gradlew -q :TaxV7:tax-ui-hibernate:run
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Tax=4282 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 3 60000
Tax=2959 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: n 0 60000
Tax=11519 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop:

Die Kontrollwerte der vorherigen Versionen bleiben erhalten: 4.282 Euro für ein Ehepaar mit zwei Kindern und einem gemeinsamen Einkommen von 60.000 Euro, 2.959 Euro mit drei Kindern und 11.519 Euro für eine alleinstehende Person ohne Kinder.

Mit der Konfigurationsdatei [tax-hibernate-error.properties], die auf eine nicht vorhandene Datenbank verweist:

> gradlew -q :TaxV7:tax-ui-hibernate:run --args="tax-hibernate-error.properties"
Exception chain:
----------------------------------------
org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'tax.dao.ITaxDao': Instantiation of supplied bean failed
----------------------------------------
tax.entities.TaxException: Error while reading the tax brackets from the database
----------------------------------------
org.hibernate.service.spi.ServiceException: Unable to create requested service [org.hibernate.engine.jdbc.env.spi.JdbcEnvironment] due to: Error calling Driver.connect() [Unknown database 'hbtaxesmissing']
----------------------------------------
org.hibernate.exception.SQLGrammarException: Error calling Driver.connect() [Unknown database 'hbtaxesmissing']
----------------------------------------
java.sql.SQLSyntaxErrorException: Unknown database 'hbtaxesmissing'
----------------------------------------
  • Zeile 12: die ursprüngliche Exception, geworfen vom JDBC-Treiber;
  • Zeilen 8 und 10: die Hibernate-Exceptions, die sie einbetten: Der Fehler trat bei der Erstellung der [SessionFactory] auf, als Hibernate sich mit dem Server verband, um dessen Version zu ermitteln;
  • Zeile 6: Die [dao]-Schicht hat den Fehler in eine [TaxException] eingebettet;
  • Zeile 4: Der Spring-Container, der die [dao]-Schicht erstellte, hat die Exception seinerseits in eine [BeanCreationException] eingebettet, die vom Hauptprogramm angezeigt wurde.

Das DBMS zu wechseln bedeutet, die URL der Datenbank und die Abhängigkeit vom JDBC-Treiber zu ändern: Hibernate wählt den SQL-Dialekt automatisch anhand des vorgefundenen DBMS aus, und der in HQL geschriebene Code der Klasse [HibernateTax] bleibt unverändert. Nur die Erstellung der Datenbank – die von den Spaltentypen abhängt – muss wiederholt werden, was das Programm [CreateDatabase.kt] ohne weitere Änderungen außer an seiner eigenen URL erledigt.

11.16. Fazit: JDBC, JdbcClient, jOOQ – Exposed oder Hibernate?

Wir haben nun zwei Möglichkeiten, auf eine Datenbank zuzugreifen: JDBC (Kapitel 10) und Hibernate (dieses Kapitel). Es gibt weitere, dazwischenliegende Ansätze, die weit verbreitet sind:

  • JdbcClient aus dem Spring Framework (Bibliothek [spring-jdbc]) ergänzt JDBC um eine flexible API, die eine handgeschriebene SQL-Abfrage ausführt und die Ergebniszeilen automatisch in Objekte umwandelt: [jdbcClient.sql("select * from articles where price > :price").param("price", 200).query(Article::class.java).list()]. Sie schreiben das SQL; Spring kümmert sich um die Parameter und kopiert die Spalten in die Objekte (auch in Datenklassen, deren Konstruktoren die Spalten erhalten). Das ist ein „Micro-ORM“;
  • jOOQ generiert aus dem Datenbankschema Klassen, mit denen Sie in Java oder Kotlin ein SQL schreiben können, das vom Compiler überprüft wird: [dsl.selectFrom(ARTICLES).where(ARTICLES.PRICE.gt(price)).fetch()]. Sie behalten die volle Kontrolle über das SQL, mit der Sicherheit der Typprüfung;
  • Exposed von JetBrains ist die in Kotlin und für Kotlin geschriebene Bibliothek für den Datenbankzugriff. Tabellen werden dort mit Kotlin-Objekten beschrieben ([object Articles : Table("articles")] mit Spalten wie [val price = decimal("price", 10, 2)]), ohne Codegenerierung, und Abfragen werden in einer eigenen Sprache („DSL“) geschrieben, die SQL ähnelt und vom Compiler überprüft wird: [Articles.selectAll().where { Articles.price greater minPrice }]. Exposed bietet außerdem eine zweite API, eine leichtgewichtige ORM-Variante (Entitätsklassen, die mit Tabellen verknüpft sind), und stützt sich auf JDBC oder optional auf nicht blockierende Treiber (R2DBC), die aus Coroutinen heraus verwendet werden können. Es nutzt alles, was wir zu Kotlin behandelt haben: Erweiterungsfunktionen, Lambdas mit Receiver, Infix-Funktionen ([greater]) und nullbare Typen für optionale Spalten.
 
Stärken
Schwächen
JDBC
Volle Kontrolle über das SQL; Performance; keine Abhängigkeiten
viel sich wiederholender Code (Parameter, Lesen der Spalten), in Kotlin gestrafft durch [use] und Erweiterungsfunktionen; SQL in Strings, vom Compiler nicht überprüft
JdbcClient
Handgeschriebenes SQL ohne Copy-and-paste-Code; Performance ähnlich wie bei JDBC
Keine Änderungsverfolgung und keine Generierung von [INSERT]/[UPDATE]; SQL nicht überprüft
jOOQ
Vom Compiler überprüftes SQL; alle Funktionen des DBMS
Codegenerierung bei jeder Schemaänderung; keine Änderungsverfolgung; für bestimmte kommerzielle DBMS-Versionen ist eine kostenpflichtige Lizenz erforderlich
Exposed
Für Kotlin entworfen; vom Compiler überprüfte Abfragen, ohne Codegenerierung; leichtgewichtig
Kotlin-spezifisch; weniger verbreitet als Hibernate und weniger Dokumentation; das Schema wird manuell im Code beschrieben
Hibernate
Objektorientiertes Modell; Änderungsverfolgung; Beziehungen; HQL und Criteria API; Standard Jakarta Persistence; unabhängig vom DBMS
eine zusätzliche Schicht, die man verstehen muss (Sessions, Zustände, Lazy Loading); generierter SQL-Code, der überwacht werden muss; weniger geeignet für komplexe Massenverarbeitung; einige Anpassungen für Kotlin (Plugins [jpa] und [allopen] , keine Datenklassen für Entitäten)

Die folgenden Richtlinien lassen sich vorschlagen:

  • Hibernate (oft über Spring Data JPA) eignet sich für die meisten Geschäftsanwendungen: ein Modell miteinander verbundener Entitäten, Operationen zum Lesen und Aktualisieren von Entitäten und ein Schema, das sich mit der Anwendung weiterentwickelt. Es ist die Standardwahl für Spring-Boot-Anwendungen, sowohl in Kotlin als auch in Java;
  • JDBC, JdbcClient, jOOQ oder Exposed eignen sich, wenn Sie das ausgeführte SQL genau steuern möchten: komplexe statistische Abfragen, gespeicherte Prozeduren, die Verarbeitung sehr großer Datenmengen oder eine bestehende Datenbank mit einem Schema, das schlecht zu einem objektorientierten Modell passt. Exposed ist eine naheliegende Wahl für eine vollständig in Kotlin geschriebene Anwendung, insbesondere außerhalb von Spring (zum Beispiel mit dem Web-Framework Ktor von JetBrains);
  • Diese Ansätze lassen sich kombinieren: Eine Anwendung kann Hibernate für den Großteil ihrer Operationen und handgeschriebenen SQL-Code – in Form nativer Abfragen – mit [JdbcClient] oder JDBC ([doWork]) für einige kritische Abfragen verwenden.

In jedem Fall nimmt ORM Ihnen nicht die Notwendigkeit ab, SQL und die Funktionsweise des DBMS zu verstehen: Das Log der ausgeführten SQL-Befehle, das wir in diesem Kapitel durchgehend angezeigt haben, ist das wichtigste Werkzeug, um zu überprüfen, was Hibernate tatsächlich tut.

Zum Weiterlernen ist die Dokumentation von Hibernate umfassend, und ihr Einführungsleitfaden ist der beste Einstieg: Hibernate ORM - documentation. Die Spezifikation Jakarta Persistence wird von der Eclipse Foundation veröffentlicht: Jakarta Persistence. Der Leitfaden von Spring zur Verwendung von JPA in Kotlin fasst die in diesem Kapitel behandelten Konzepte zusammen (Plugins, Entitäten, Nullbarkeit): Building web applications with Spring Boot and Kotlin. Exposed wird auf seiner GitHub-Seite vorgestellt, die auf die Dokumentation verweist: JetBrains Exposed.