Over the first three articles of our Gradle Under the Hood series, we explored incremental source tracking, network-immune classloader harvesting, and compile-only dependency isolation.

Today, in the grand finale of this series, we tackle our biggest architectural challenge: How do you build a cohesive build automation suite that supports three completely different object-relational mapping (ORM) frameworks—Hibernate, EclipseLink, and Apache OpenJPA—without creating a monolithic, tightly-coupled mess of conflicting dependencies?

Let's dive into how we designed a Federated Plugin Architecture in JPersist to orchestrate specialized bytecode transformations while isolating complex provider-specific execution graphs.

The Ecosystem Fragmentation Trap

Compile-time bytecode modification is the holy grail of JPA performance. By weaving change-tracking or lazy-loading hooks directly into compiled .class binaries post-compilation, you eliminate the need for heavy runtime reflection proxies or fragile -javaagent startup flags.

However, each major persistence provider drives its enhancement engine through radically different internal APIs:

  • Hibernate relies on an intensive programmatic cycle (org.hibernate.bytecode.spi.Enhancer) requiring granular execution parameters.
  • EclipseLink uses an offline processor (StaticWeaveProcessor) that consumes raw file paths and streams metadata through explicit directory structures.
  • Apache OpenJPA uses a standalone CLI driver utility (PCEnhancer) driven by command-line arguments.

If you try to jam all three framework dependencies into a single, monolithic Gradle plugin, you create a dependency nightmare. Conflicting versions of bytecode manipulation libraries leak into the global Gradle build daemon classpath, causing silent build-time crashes and memory leaks.

The Solution: A Federated Plugin Architecture

To achieve clean separation of concerns, we designed a Federated Plugin Architecture. Instead of one monolithic plugin, JPersist provides a modular suite of specialized sibling plugins that users can apply independently depending on their stack:

  • io.github.jpersist.jpa (The Core Plugin)
  • io.github.jpersist.hibernate-persistence (The Hibernate Optimization Suite)
  • io.github.jpersist.openjpa-persistence (The Apache OpenJPA Suite)
  • io.github.jpersist.eclipse-persistence (The EclipseLink Static Weaving Plugin)

The core plugin acts as the orchestrator. It manages the central persistence {} DSL extension container, registers global configuration spaces like modelgenProcessor, and auto-discovers annotated entities via a high-speed, lightweight ASM scanner.

The sibling provider plugins then plug directly into this core infrastructure. They read configuration states from the central extension and register their own specialized, framework-native enhancement tasks.

Divergent Execution Strategies: Workers vs. Process Forks

Because the plugins are decoupled, we were free to engineer the exact execution strategy that best fits each framework's unique constraints, rather than forcing a one-size-fits-all model.

1. Hibernate: The ClassLoader-Isolated Worker SPI

Hibernate carries a dual-namespace problem: legacy projects still target the javax.persistence namespace (Hibernate 5), while modern ones target jakarta.persistence (Hibernate 6).

To manage this safely, the Hibernate plugin delegates bytecode transformation to a dedicated Service Provider Interface (SPI) module (persistence-tools-api) executing inside a hermetic Gradle Worker sandbox (classLoaderIsolation):

// Inside HibernateEnhancementPlugin.groovy (v1.8.1) def enhanceTaskProvider = project.tasks.register(enhanceTaskName, HibernateEnhancementTask) { task -> task.jpaVersion.set(activeVersionProvider) // Wire the project's native compile classpath directly to satisfy legacy engines task.enhanceClasspath.from(enhanceConfigProvider) task.enhanceClasspath.from(JakartaPersistencePlugin.resolvePersistenceToolsFiles(project, activeVersionProvider)) task.compileClasspath.from(sourceSet.compileClasspath) }

The underlying EnhancementWorker uses Java's native ServiceLoader API inside the sandbox to dynamically discover the correct environment adapter matching the module's target JPA version.

2. EclipseLink & OpenJPA: Lightweight Java Exec Forks

Unlike Hibernate, EclipseLink and OpenJPA drive their weaving routines via standalone main-class CLI processors (StaticWeave and PCEnhancer). Running them inside the main Gradle daemon classpath would contaminate the environment.

Instead of writing complex worker code, our specialized tasks extend Gradle's built-in DefaultTask and use an injected ExecOperations service to fork a completely isolated, short-lived JVM process:

// Inside OpenJPAEnhanceTask.groovy (v1.8.1) @TaskAction void enhance() { // Stage raw compiled classes into the isolated target output directory first project.copy { spec -> spec.from(sourceClassesDir).into(targetClassesDir) } // Fork OpenJPA's PCEnhancer in a detached JVM process boundary execOperations.javaexec { spec -> spec.mainClass.set('org.apache.openjpa.enhance.PCEnhancer') spec.classpath = project.files(enhancerClasspath, compileClasspath, resourcesDir) spec.args('-directory', targetClassesDir.get().asFile.absolutePath, ...) } }

This delivers optimal execution speeds. The heavy framework dependencies are loaded exclusively within a transient process fork, keeping the main Gradle daemon completely clean.

The Ultimate Engineering Victory

By adopting a federated plugin layout combined with tailored execution strategies, the JPersist Suite balances developer productivity with bulletproof build engineering:

  1. Absolute ClassLoader Safety: The Gradle daemon remains pristine. It never loads an internal class from Hibernate, EclipseLink, or OpenJPA into its root context, completely eliminating memory leaks and cross-plugin linkage errors.
  2. Tailored Performance: Heavy, namespace-shifting frameworks run inside classloader-isolated worker sandboxes, while CLI-driven frameworks execute via rapid process forks.
  3. Infinite Extensibility: Adding a new ORM provider or updating a framework version requires zero changes to the core plugin code. You simply release a new standalone sibling plugin that reads from the shared core extensions.

This wraps up our Gradle Under the Hood series! We built an automation platform that is blazing fast through source-driven incremental tracking, immune to network drops via ClassLoader harvesting, container-compliant through compile-only scopes, and beautifully modular through a federated plugin architecture.

How do you handle multi-framework automation or isolate conflicting dependency graphs inside your enterprise build engineering pipelines? Let's discuss in the comments below!

🔗 Explore the complete JPersist open-source architecture on GitHub: https://github.com/jpersist/persistence