Skip to content
Projects

JExcellence/JEHibernate has 52 GitHub stars and 8 forks. GitHot measured +1 stars in 24 hours and +1 in 7 days. Last checked 2026-11-15 12:27 UTC. Last push 2026-10-28.

How these counts are measured

52 stars8 Forks +1 in 24h

Measured star growth

in 24h
+1
in 7 days
+1
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

A Hibernate Repository to handle easier usage of the Hibernate / Jakarta Framework for Applications likes Paper / Bukkit / Spigot Minecraft Servers or Spring Applications

Data

README.md

Original

JEHibernate

Modern Hibernate/JPA utility library for Java 17+
Built for Minecraft plugins. Works everywhere.

Java 17+ Hibernate 7.x Maven Central License: MIT


JEHibernate wraps Hibernate ORM with a fluent, type-safe repository API designed around the Minecraft plugin lifecycle: async operations that never block the main thread, cached repositories for fast player lookups, and session-scoped lazy loading. It runs anywhere Hibernate does, so the same code works in a plugin, a Spring Boot service, or a standalone application.

Runs on: Spigot, Paper, Folia, Spring Boot, standalone Java applications. Requires: Java 17+ (virtual threads auto-enabled on 21+), Hibernate 7.x, Jakarta Persistence 3.1+.


Install

Replace 4.2.0 with the current version shown on the Maven Central badge above.

Gradle (Kotlin DSL)

dependencies {
    implementation("de.jexcellence.hibernate:jehibernate-core:4.2.0")

    // Pick your database driver
    runtimeOnly("com.h2database:h2:2.4.240")          // H2 (embedded, dev/testing)
    runtimeOnly("com.mysql:mysql-connector-j:9.3.0")  // MySQL
    runtimeOnly("org.postgresql:postgresql:42.7.7")   // PostgreSQL
}

Maven

<dependency>
    <groupId>de.jexcellence.hibernate</groupId>
    <artifactId>jehibernate-core</artifactId>
    <version>4.2.0</version>
</dependency>

Multi-module projects can import the BOM (jehibernate-bom) to align every module on one version.


Quick Start

1. Define an entity

@Entity
@Table(name = "players")
public class PlayerData extends UuidEntity {
    @Column(nullable = false)
    private String username;
    private long balance;

    protected PlayerData() {}

    public PlayerData(UUID uuid, String username) {
        setId(uuid);
        this.username = username;
    }

    public String getUsername() { return username; }
    public long getBalance()    { return balance; }
    public void setBalance(long balance) { this.balance = balance; }
}

2. Define a repository

public class PlayerRepository extends AbstractCrudRepository<PlayerData, UUID> {
    public PlayerRepository(ExecutorService executor, EntityManagerFactory emf) {
        super(executor, emf);   // entity type inferred from the generic superclass
    }
}

3. Save and load asynchronously

var je = JEHibernate.builder()
    .configuration(config -> config
        .database(DatabaseType.H2)
        .url("jdbc:h2:file:./plugins/MyPlugin/database/mydb")
        .credentials("sa", "")
        .ddlAuto("update"))
    .scanPackages("com.example.myplugin")
    .build();

var players = je.repositories().get(PlayerRepository.class);
var uuid = UUID.randomUUID();

// Save, then load — off the main thread, callbacks on completion
players.createAsync(new PlayerData(uuid, "alice"))
    .thenCompose(saved -> players.findByIdAsync(saved.getId()))
    .thenAccept(found -> found.ifPresent(p ->
        System.out.println("Loaded " + p.getUsername() + " (balance " + p.getBalance() + ")")));

je.close(); // on shutdown

Every repository method has a synchronous form (create, findById, save, …) and an async *Async variant returning CompletableFuture. On Java 21+ the async variants run on virtual threads; on Java 17 they use a cached thread pool.

For the full API — query builder, specifications, caching, transactions, dependency injection, and platform integration — see the API reference.


Modules

Pick the modules you need:

Module Use it for
jehibernate-core Required. The library — repositories, sessions, pooling, migration.
jehibernate-spring-boot Spring Boot auto-configuration that reuses your DataSource bean.
jehibernate-plugin Spigot/Paper PropertyLoader data-folder convenience.
jehibernate-testing Testcontainers + fixtures (test scope only).
jehibernate-bom Maven BOM that aligns the versions of all modules.

Configuration

Builder API

var jeHibernate = JEHibernate.builder()
    .configuration(config -> config
        .database(DatabaseType.POSTGRESQL)
        .url("jdbc:postgresql://localhost:5432/mydb")
        .credentials("user", "pass")
        .ddlAuto("validate")
        .batchSize(50)
        .showSql(true)
        .formatSql(true)
        .connectionPool(5, 20))
    .scanPackages("com.example")
    .build();

Properties File

Load from filesystem, classpath, or a Bukkit plugin data folder:

// Classpath or filesystem
var jeh = JEHibernate.fromProperties("hibernate.properties");

// Bukkit plugin data folder
var jeh = JEHibernate.fromProperties(getDataFolder(), "database", "hibernate.properties");

Place hibernate.properties in src/main/resources/database/:

# Database type. Supported: H2, MYSQL, MARIADB, POSTGRESQL, ORACLE, MSSQL_SERVER, SQLITE, HSQLDB
database.type=H2

# H2 (embedded, no external database needed)
h2.url=jdbc:h2:file:./plugins/MyPlugin/database/mydb;MODE=MySQL;AUTO_SERVER=TRUE
h2.username=sa
h2.password=

# MySQL (uncomment and set database.type=MYSQL)
# mysql.url=jdbc:mysql://localhost:3306/mydb?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC
# mysql.username=root
# mysql.password=change_me

# PostgreSQL (uncomment and set database.type=POSTGRESQL)
# postgresql.url=jdbc:postgresql://localhost:5432/mydb
# postgresql.username=postgres
# postgresql.password=change_me

# Hibernate settings
hibernate.hbm2ddl.auto=update
hibernate.show_sql=false
hibernate.format_sql=false

Server admins switch databases by changing database.type and uncommenting the relevant section — no recompilation needed. All hibernate.* properties pass through directly to Hibernate.

Property format: {prefix}.url, {prefix}.username, {prefix}.password. Optionally {prefix}.driver and {prefix}.dialect to override auto-detected defaults.

Supported Databases

Type Prefix Default Driver
H2 h2 org.h2.Driver
MySQL mysql com.mysql.cj.jdbc.Driver
MariaDB mariadb org.mariadb.jdbc.Driver
PostgreSQL postgresql org.postgresql.Driver
Oracle oracle oracle.jdbc.OracleDriver
SQL Server mssql com.microsoft.sqlserver.jdbc.SQLServerDriver
SQLite sqlite org.sqlite.JDBC
HSQLDB hsqldb org.hsqldb.jdbc.JDBCDriver

Connection Pooling

HikariCP is the default connection pool and is bundled with jehibernate-core — no extra dependency needed. Size it via the builder:

.connectionPool(5, 20)  // min 5, max 20 connections

For finer control (idle timeout, leak detection, max lifetime) pass a PoolConfig, and inspect the pool at runtime via jeHibernate.getPoolHealth().

Second-Level Cache

Add a JCache provider to enable Hibernate's second-level cache:

implementation("org.hibernate.orm:hibernate-jcache")
.enableSecondLevelCache()

Entity Base Classes

All base classes provide automatic createdAt / updatedAt timestamps, optimistic locking via @Version, and correct equals / hashCode (safe for HashSet / HashMap even before persistence).

Class ID Type Use Case
LongIdEntity Auto-increment Long Most entities (warps, homes, shops)
UuidEntity UUID (native per dialect: uuid / binary(16)) Players, distributed systems
StringIdEntity Custom String Natural keys (world names, permission nodes)
@Entity
public class Warp extends LongIdEntity {
    private String name;
    private String world;
    private double x, y, z;
    // ...
}

Spring Boot Starter

Add the starter — auto-configuration reuses your Spring DataSource and registers a JEHibernate bean. No @Bean boilerplate needed:

implementation("de.jexcellence.hibernate:jehibernate-spring-boot:4.2.0")
# application.yml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/app
    username: app
    password: secret
jehibernate:
  database: POSTGRESQL
  ddl-auto: validate
  scan-packages: [com.example.domain]
  migration-enabled: false   # let Spring Boot's own Flyway run migrations
@Service
class UserService {
    private final UserRepository users;
    UserService(JEHibernate jeHibernate) {          // auto-configured bean
        this.users = jeHibernate.repositories().get(UserRepository.class);
    }
}

The auto-configuration activates when a DataSource bean is present, reuses it (JEHibernate never closes Spring's pool), and is driven by jehibernate.* properties. To configure programmatically instead, define your own JEHibernate @Bean (auto-config backs off via @ConditionalOnMissingBean). Set jehibernate.enabled=false to disable it entirely. See the API reference for the programmatic path.


Schema Migration

Migrations own the schema (ddl-auto defaults to validate). Flyway runs before Hibernate boots.

Property Default Meaning
jehibernate.migration.enabled true Run migrations at bootstrap
jehibernate.migration.tool flyway flyway | liquibase | none
jehibernate.migration.location classpath:db/migration Flyway location / Liquibase changelog path
jehibernate.pool.maximumPoolSize 10 HikariCP max connections
jehibernate.pool.minimumIdle 2 HikariCP min idle connections

Add org.flywaydb:flyway-core to the classpath to enable Flyway; omit it and migration is a silent no-op. Put SQL files in src/main/resources/db/migration/V001__init.sql, V002__..., etc.

To keep the pre-4.0 hbm2ddl.auto=update behaviour instead of migrations:

.configuration(c -> c.database(...).url(...).ddlAuto("update"))
// or set jehibernate.migration.enabled=false

Multi-Tenancy (optional, off by default)

// DISCRIMINATOR: a @TenantId column on entities; strict leak-guard throws if no tenant is bound.
config.multiTenancy(MultiTenancyConfig.discriminator());

try (var ignored = TenantContext.open("acme")) {
    noteRepo.findAll();   // sees only acme's data
}

Strategies: DISCRIMINATOR (row-level), SCHEMA (schema-per-tenant, shared pool), DATABASE (database-per-tenant). Full details in docs/multi-tenancy-guide.md.


Documentation

  • API reference — repository operations, query builder, specifications, caching, transactions, dependency injection, Bukkit/Paper and Spring Boot integration, logging, troubleshooting, and architecture.
  • Lazy-loading guide — session scoping vs. read-only vs. EntityGraph vs. OSIV.
  • Audit guide — Hibernate Envers audit trail, with DSGVO retention/erasure notes.
  • Multi-tenancy guide — DISCRIMINATOR / SCHEMA / DATABASE strategies.
  • Testing guide — @JEHibernateTest, Testcontainers, fixtures.
  • Architecture decision records — the rationale behind the 4.0 design.
  • CHANGELOG — release history and migration notes.
  • CONTRIBUTING — build, test, and code-style guidance for contributors.

Upgrading to 4.0

4.0 is a multi-module release. The key changes:

  • Published coordinate: de.jexcellence.hibernate:JEHibernate → de.jexcellence.hibernate:jehibernate-core.
  • HikariCP replaced Agroal as the default connection pool (bundled; connectionPool(min, max) unchanged).
  • ddl-auto defaults to validate (was update) — migrations own the schema.
  • Flyway migrations run before Hibernate boots; Liquibase is opt-in.
  • Audit trail via Hibernate Envers (@Audited + enableAudit()) and multi-tenancy (DISCRIMINATOR/SCHEMA/DATABASE) added.
// before
implementation("de.jexcellence.hibernate:JEHibernate:3.0.4")
// after
implementation("de.jexcellence.hibernate:jehibernate-core:4.2.0")
implementation("org.flywaydb:flyway-core:11.1.1") // optional: enables migrations

See the CHANGELOG and docs/adr/ for the full migration notes.


License

MIT License

Copyright (c) 2025 JExcellence