JPersist is a suite of modern, high-performance, and Gradle Configuration Cache-compliant plugins that completely automates the tedious boilerplate configuration of enterprise Jakarta Persistence API (JPA) environments. It provides zero-configuration support for Hibernate and EclipseLink multi-module builds.
Standard Gradle loops require verbose XML overrides, break incremental compilation states during bytecode manipulation, and crash with complex classpath tasks decoration proxy loops. JPersist fixes this permanently.
| Standard Gradle Setup | The JPersist Masterclass Advantage |
|---|---|
❌ Manual <class> tagging required |
✅ ASM-Powered Bytecode Scanning auto-detects entities |
| ❌ Hardcoded schema structures | ✅ Strategy-Driven Polymorphism supports JPA 2.0 to 3.2 dynamically |
| ❌ Rigid monolithic output paths | ✅ Declarative Attributes route individual JAR locations via the DSL |
| ❌ Broken workspace sync mappings | ✅ Automated IDE Indexing hooks into Buildship and IntelliJ out-of-the-box |
Running complex continuous integration checks, multi-spec regression testing matrices, and maintaining full compatibility with rapid Gradle releases requires continuous investment.
If JPersist is saving your engineering team debugging overhead hours, consider backing us!
👉 Become a GitHub Sponsor to support JPersist's independence
Apply the aggregate ecosystem plugin matching your infrastructure stack. Version suggestions from your corporate Version Catalogs or platform BOMs are dynamically propagated into all standard Java compilation scopes.
Groovy DSL
plugins {
id 'io.github.jpersist.hibernate-persistence' // Enables descriptor generation, modelgen, & enhancement
}
dependencies {
// Centralize versioning via a BOM platform configuration
jpa platform('org.hibernate.orm:hibernate-platform:6.6.56.Final')
}Kotlin DSL
plugins {
id("io.github.jpersist.hibernate-persistence")
}
dependencies {
"jpa"(platform("org.hibernate.orm:hibernate-platform:6.6.56.Final"))
}Groovy DSL
plugins {
id 'io.github.jpersist.eclipse-persistence' // Enables descriptor generation, modelgen, & static weaving
}
dependencies {
jpa platform('org.eclipse.persistence:org.eclipse.persistence.parent:4.0.9')
}Registers a processPersistenceDescriptor task for each Java source set. It parses existing user templates, resolves conflicts, and writes a pristine, 4-space indented, pretty-printed output into your build resources.
- Implicit Version Sync: Automatically extracts version attributes from physical source XMLs at configuration time to handle schema modifications dynamically.
- Declarative Dependency Routing: Pass custom namespaced attributes to control exactly what path prefix is written inside
<jar-file>element rows for custom archive environments:
dependencies {
jarFile(project(':common-entities')) {
attributes {
attribute(persist.jakarta.gradle.plugin.JakartaPersistencePlugin.JAR_LOCATION_ATTRIBUTE, 'lib/')
}
}
}Triggers raw bytecode modification tasks post-compilation, modifying entities safely in-place within the compilation pipeline boundaries.
- Proxy-Free Safety: Execution loops are fully encapsulated within an isolated static helper layer, making it completely immune to Gradle proxy object
MissingMethodExceptionbugs. - No Runtime Agents: Natively supports performance optimizations like lazy loading hooks and advanced inline dirty tracking without requiring an active runtime
-javaagentargument.
Registers a validatePersistenceSchema task for each Java source set that boots an isolated JVM worker process to verify JPA entity mappings against the database schema at build time — catching mapping drift before it reaches production.
- Worker Process Isolation: Leverages Gradle's
WorkerExecutorwith classloader isolation, keeping the JPA provider, entity classes, and JDBC driver completely separated from the Gradle daemon classpath. - Configurable Database Connection: Override the default in-memory H2 validation target via the
validationDSL block:
persistence {
main {
validation {
url = 'jdbc:h2:mem:my_validation_db;DB_CLOSE_DELAY=-1'
driver = 'org.h2.Driver'
user = 'sa'
password = ''
}
}
}Registers a generateJPAGraalVMMetadata task for each Java source set that produces a reflect-config.json file containing all ASM-discovered JPA entity classes — enabling ahead-of-time (AOT) reflection registration for GraalVM native image compilation with zero manual configuration.
- Automatic Entity Discovery: Reuses the plugin's existing ASM bytecode scanning pipeline to locate every
@Entity,@MappedSuperclass, and@Embeddableclass in the source set. - Native-Ready Builds: Emitted JSON declares
allDeclaredConstructors,allDeclaredFields, andallDeclaredMethodsfor each class, ensuring full JPA provider compatibility under native compilation.
A dedicated ValidationExtension interface is embedded inside each source set's PersistenceExtension, providing optional JDBC connection properties (url, driver, user, password) for schema validation. When omitted, sensible H2 defaults are applied automatically.
- Seamless DSL Integration: Accessible via the standard Gradle nested-closure notation through the
validation { }block, consistent with the existingpersistenceUnits { }andtransformer { }DSL patterns.
jakarta-persistence-gradle-plugin— Generates or mergespersistence.xmldescriptors using a declarative DSL.eclipse-persistence-gradle-plugin— Houses all EclipseLink-related tooling and processing enhancements.hibernate-persistence-gradle-plugin— Houses all Hibernate-related static generation and enhancement utilities.
📖 API Reference: Browse the full Groovydoc at jpersist.github.io/persistence/api/latest 📘 User Guide: Read the documentation at jpersist.github.io/persistence/guide/latest 🚀 Runnable Specs: Complete code templates are available in the
examples/directory.
- Gradle: 7.4+ or 8.x+ / 9.x+
- Java: JDK 17 or higher (Required by modern Jakarta specifications)
Distributed under the Apache License 2.0. See the LICENSE file for more information.