JExHibernate — Hibernate für Plugins, Spring Boot und alles dazwischen

Ich habe vor zwei Jahren angefangen, JExHibernate zu schreiben, weil mich der Zustand von Persistenz-Code in Minecraft-Plugins zu sehr nervte. Was als kleiner Wrapper begann, ist heute eine echte Bibliothek, die ich auch in produktiven Spring-Boot-Diensten einsetze. Repository: github.com/JExcellence/JEHibernate (das Artefakt heißt aus historischen Gründen JEHibernate; mündlich nenne ich es JExHibernate, weil es zur JExcellence-Familie gehört).

Dieser Post erklärt, was die Bibliothek macht, warum sie existiert, und wie sie sich in den drei Welten verhält, in denen sie regelmäßig läuft: Bukkit/Paper/Folia, Spring Boot, und Standalone-Java.

Was JExHibernate ist

Ein dünner, opinionierter Wrapper um Hibernate ORM 7.x mit einer fluenten API, die laut Eigenmessung etwa 65 % des Boilerplate-Codes wegnimmt, den man in einem typischen JPA-Projekt schreibt — Repository-Klassen, Pagination, Query-Builder, Caching, Transaktionsbehandlung, async-Varianten von allem. Java 17+, mit automatischer Nutzung von Virtual Threads, sobald die Laufzeit Java 21 oder neuer ist.

Acht Datenbanken werden out-of-the-box unterstützt: H2, MySQL, MariaDB, PostgreSQL, Oracle, SQL Server, SQLite und HSQLDB. Connection-Pooling über Agroal, Second-Level-Cache über JCache — beide optional, beide mit sinnvollen Defaults.

Drei Welten, ein Wrapper

1. Spigot, Paper, Folia

Hier ist JExHibernate geboren. Das Plugin-Umfeld hat drei spezifische Eigenarten, die jede ungeschützte Hibernate-Integration zerlegen:

• Class loaders. Bukkit, Paper und Folia laden jedes Plugin mit einem eigenen ClassLoader. Hibernate erwartet alle Entity-Klassen unter einem kanonischen Loader. JExHibernate übernimmt das Thread-Context-Wechseln intern, damit das nicht jeder Plugin-Entwickler einzeln debuggen muss.
• Main-Thread-Hygiene. Jede Repository-Methode hat eine Async-Variante, die ein CompletableFuture zurückgibt. Das ist nicht bloß Convenience — auf einem Server, der zwanzig Mal pro Sekunde ticken muss, ist das die Grenze zwischen „läuft" und „zuckt unter Last".
• Folia-Bewusstsein. Folia (PaperMC's regionalisierter Threading-Branch) verändert die Main-Thread-Annahmen. Die Repository-Schicht ist regions-agnostisch; die Async-Calls funktionieren auf allen drei Servern identisch.

Das Setup im Plugin-onEnable:

public class MyPlugin extends JavaPlugin {
    private JEHibernate jeHibernate;

    @Override
    public void onEnable() {
        saveResource("database/hibernate.properties", false);

        jeHibernate = JEHibernate.builder()
            .configuration(config -> config.fromProperties(
                PropertyLoader.load(
                    getDataFolder(), "database", "hibernate.properties"
                )))
            .scanPackages("com.example.myplugin")
            .build();

        var playerRepo = jeHibernate.repositories().get(PlayerRepository.class);
        playerRepo.preloadAsync();
    }

    @Override
    public void onDisable() {
        jeHibernate.close();
    }
}

Server-Admins wechseln die Datenbank über die mitgelieferte hibernate.properties ohne Recompilation — database.type=H2 für eine eingebettete Entwicklungs-DB, database.type=MYSQL für die produktive Box. Sechs weitere Anbieter funktionieren genauso.

2. Spring Boot

Spring Data JPA ist hervorragend — wenn man im Spring-Universum bleibt. Sobald man aber Code zwischen Plugins und Spring-Diensten teilen möchte (was bei mir oft der Fall ist, weil ein Web-Dashboard und das zugehörige Plugin auf dieselben Entities greifen), fängt es an zu reiben.

JExHibernate funktioniert in Spring Boot als reguläres @Bean und integriert sich mit @PreDestroy sauber in den Spring-Lifecycle:

@Configuration
public class JEHibernateConfig {

    @Bean
    public JEHibernate jeHibernate() {
        return JEHibernate.builder()
            .configuration(config -> config
                .database(DatabaseType.POSTGRESQL)
                .url("jdbc:postgresql://localhost:5432/mydb")
                .credentials("user", "pass")
                .ddlAuto("validate")
                .connectionPool(5, 20))
            .scanPackages("com.example")
            .build();
    }

    @Bean
    public PlayerRepository playerRepository(JEHibernate jeh) {
        return jeh.repositories().get(PlayerRepository.class);
    }

    @PreDestroy
    public void shutdown(JEHibernate jeh) { jeh.close(); }
}

Was Spring Boot sich erspart: keine spring-boot-starter-data-jpa-Abhängigkeit, kein @EnableJpaRepositories-Geraffel, keine Property-Magie über drei verschiedene application.yml-Profile. Stattdessen ein einziger Bean, der überall identisch konfiguriert ist — Plugin oder Service.

3. Standalone-Java / CLI-Tools

Für CLI-Tools, Migrations-Skripte und ad-hoc-Datenfixes funktioniert es genauso. JEHibernate.fromProperties(...) in der main-Methode, fertig. Kein Container, kein Servlet-Stack, keine Annotations-Magie.

Die Features, die in der Praxis zählen

Repositories ohne Boilerplate

Eine vollständige Repository-Klasse ist drei Zeilen:

public class PlayerRepository extends AbstractCrudRepository<PlayerData, UUID> {
    public PlayerRepository(ExecutorService ex, EntityManagerFactory emf, Class<PlayerData> cls) {
        super(ex, emf, cls);
    }
}

Damit hast du findById, findAll, save, create, update, delete, refresh, exists, count, plus alle Async-Varianten, plus Batch-Operationen (saveAll, deleteAll), plus Pagination mit PageResult-Metadaten, Specifications und einen typsicheren Query Builder.

Query Builder — kein SQL, kein JPQL

var richActive = repo.query()
    .and("active", true)
    .greaterThan("balance", 10_000)
    .like("username", "%alice%")
    .in("rank", List.of("VIP", "ADMIN"))
    .orderByDesc("balance")
    .fetch("inventory")        // INNER JOIN FETCH
    .fetchLeft("guild")        // LEFT JOIN FETCH (nullable)
    .getPage(0, 20);

richActive.totalElements();    // 14_823
richActive.totalPages();       // 742
richActive.hasNext();          // true

Das ist der Punkt, an dem JExHibernate sich klar von einem rohen Hibernate-Setup absetzt: kein N+1 mehr aus Versehen, kein LazyInitializationException-Drama, kein manuelles Page-Counting in einer zweiten Query.

Cached Repositories

Für Lookups, die häufig vorkommen aber selten ändern (Profile, Rangliste, Berechtigungen), gibt es AbstractCachedRepository — eine Doppelschicht aus Caffeine-Caches mit ID- und Custom-Key-Lookup, Stale-while-Revalidate, TTL-Jitter gegen Stampede-Probleme, automatischer Invalidierung bei Mutationen.

public class PlayerRepository
    extends AbstractCachedRepository<PlayerData, UUID, String> {

    public PlayerRepository(ExecutorService ex, EntityManagerFactory emf, Class<PlayerData> cls) {
        super(ex, emf, cls,
            PlayerData::getUsername,         // Cache-Key
            CacheConfig.builder()
                .expiration(Duration.ofMinutes(30))
                .refreshAfterWrite(Duration.ofMinutes(25))
                .maxSize(5000)
                .jitterPercent(10)
                .build());
    }
}

Auf einem Server mit zehntausend Spielern macht das den Unterschied zwischen einem Lookup in 5 ms und einem in 200 ns.

Optimistic Lock Retry

Konkurrierende Updates auf derselben Entity sind Realität, sobald mehr als ein Thread mit den Daten arbeitet. Statt jeden Aufruf einzeln in Try-Catch zu wickeln:

OptimisticLockRetry.execute(() -> {
    var p = repo.findByIdOrThrow(uuid);
    p.setBalance(p.getBalance() + amount);
    return repo.save(p);
});

Standardmäßig drei Versuche mit Exponential Backoff. Optional auch für Datenbank-Deadlocks aktivierbar.

Slow Query Detection

Jede Query, die länger als 500 ms läuft, wird automatisch auf WARN-Level geloggt. Die Schwelle ist konfigurierbar. Eine der wenigen Funktionen, die ich im Tagesgeschäft jeden Tag nutze — auf einem produktiven Server ist das oft das Erste, was vor einer kommenden Performance-Wand warnt.

Was JExHibernate bewusst nicht macht

• Kein eigenes DI-Framework. Es gibt eine kleine @Inject-Implementierung für ad-hoc-Wiring, aber wer Spring oder Guice einsetzt, behält das.
• Keine REST-Schicht. Wer das braucht, kombiniert JExHibernate mit Javalin, Spark oder Spring — was ich für Web-Dashboards regelmäßig tue.
• Keine Multi-Server-Synchronisation. Eventbus oder Redis-Pub/Sub liegen außerhalb des Scope.

Wo es hingeht

Aktuelle Version (Mai 2026): 3.0.1 mit Hibernate 7.x und Jakarta Persistence 3.1+. 78 Tests, alle grün.

Auf der Roadmap:

• Bessere Test-Werkzeuge — eine @RepositoryTest-Annotation, die ein H2-In-Memory-DB plus Schema-Migrationen automatisch aufsetzt.
• Tiefere Folia-Integration. Die Repository-Schicht ist heute regions-agnostisch; das Lifecycle-Management wird sauberer Folia-spezifisch ausgewiesen.
• Mehr Datenbank-Dialekte falls Bedarf aufkommt — CockroachDB und YugabyteDB sind die nächsten Kandidaten.

Wer Plugins, Spring-Services oder Standalone-Tools mit echter Persistenz baut und nicht jedes Mal denselben Boilerplate schreiben will, schaut sich JExHibernate an. Pull Requests willkommen — der Code ist absichtlich übersichtlich gehalten und vollständig dokumentiert.

Repository: github.com/JExcellence/JEHibernate · Apache License 2.0 · 78 Tests · Java 17+, Hibernate 7.x.