DEV Community: Yannick Ebongue

Gradle Under the Hood: Fighting Incremental Cache Misses in Bytecode Processing

Yannick Ebongue — Sun, 01 Nov 2026 11:47:50 +0000

If you have ever written a custom Gradle task to analyze or process compiled bytecode (like custom linters, schema validators, or metadata generators), you have probably encountered a hidden, silent performance killer: the aggressive compiler erasure.

In this first article of our Gradle Under the Hood series, we’ll explore how we re-engineered the incremental tracking of JPersist (a zero-boilerplate JPA build automation suite) to achieve bulletproof UP-TO-DATE execution states, even when the Java compiler tries to destroy your task's cache.

The Naive Approach to Bytecode Tasks

When building a task that processes compiled .class files, the most intuitive setup is to declare the compiler's output directory as your task's @InputDirectory:

abstract class MyBytecodeTask extends DefaultTask {
    @InputDirectory
    abstract DirectoryProperty getCompiledClassesDir()

    @TaskAction
    void execute(InputChanges inputChanges) {
        // Process altered files...
    }
}

You then wire it in your plugin by binding it to the JavaCompile task:

task.getCompiledClassesDir().set(compileJavaTask.flatMap { it.destinationDirectory })

Why this fails in the real world:
Gradle has a magnificent incremental build engine. However, JavaCompile is highly defensive. When a developer alters even a single line of Java source code, JavaCompile often wipes out its entire destination directory (build/classes/java/main) before rebuilding to guarantee no stale classes remain.

For your downstream bytecode task, this folder deletion is catastrophic. Even though you are using Gradle's InputChanges API, the engine sees that the root directory was destroyed and recreated. It panics, concludes that the historical file snapshot graph is non-linear, and forces inputChanges.incremental to evaluate to false. Your task is forced into a heavy, full-pass execution loop on every minor code tweak.

The Solution: Source-Driven Incremental Tracking

To make our query linters and schema validators truly incremental and immune to compiler erasures, we shifted our architectural paradigm: We stopped tracking the volatile compiler output folder and started tracking the stable source code repository layout instead.

Instead of listening to the .class directory, our tasks now listen to sourceSet.java.sourceDirectories as a flat @InputFiles collection wrapper:

abstract class ValidatePersistenceSchema extends DefaultTask {
    @Incremental
    @InputFiles
    @PathSensitive(PathSensitivity.RELATIVE)
    abstract ConfigurableFileCollection getSourceFiles()

    @InputDirectory // Kept as standard non-incremental input
    abstract DirectoryProperty getCompiledClassesDir()
}

Inside our plugin wiring loop, we feed it lazily while filtering out any intermediate or generated build directories:

task.getSourceFiles().from(project.provider {
    sourceSet.java.sourceDirectories.asFileTree.matching {
        exclude { element ->
            element.file.absolutePath.replace('\\', '/').contains(project.layout.buildDirectory.get().asFile.absolutePath.replace('\\', '/'))
        }
    }
})

Mapping Source Deltas to Bytecode Outputs

Because source directories are managed by the developer and are never aggressively wiped out by a compiler task, Gradle's file system snapshot engine maintains a perfect, unbroken lineage of mutations.

When a developer modifies an entity, InputChanges accurately catches exactly one modified .java file. Inside our @TaskAction, we intercept this .java path, compute its relative package structure, and translate it on-the-fly to find the corresponding compiled .class file inside the freshly compiled folder:

@TaskAction
void validate(InputChanges inputChanges) {
    List<String> affectedEntities = []

    if (inputChanges.incremental) {
        inputChanges.getFileChanges(getSourceFiles()).each { change ->
            if (change.file.name.endsWith('.java')) {
                String relativePath = change.normalizedPath
                // Translate com/example/model/User.java -> com.example.model.User
                String className = relativePath.substring(0, relativePath.lastIndexOf('.java')).replace('/', '.')

                if (change.changeType != ChangeType.REMOVED) {
                    affectedEntities.add(className)
                }
            }
        }

        // Fast-Exit Pass: If no active entities were touched, skip heavy DB bootstrapping!
        if (affectedEntities.isEmpty()) return
    } else {
        affectedEntities.addAll(fullDiscoveredEntityList)
    }

    // Submit isolated work wrapper with precisely filtered entity subsets...
}

The Engineering Win

By decoupling task delta tracking from the volatile compilation output graph, we achieved major engineering victories for the JPersist v1.8.0 release pipeline:

Immunity to Directory Purges: Even if JavaCompile erases and rewrites 5,000 class files, our tasks compare the stable source metadata signatures. If only 1 file changed, we only process 1 class binarized stream via ASM.
The Fast-Exit Optimization: If a developer edits a standard Service, Controller, or Utility class that doesn't hold JPA annotations, our tasks process the change stream in under 5 milliseconds and exit before ever spawning database connections or heavy classloaders.

Stay tuned for Part 2, where we’ll dive into ClassLoader Harvesting and how we forced isolated Gradle workers to run seamlessly on headless CI nodes without ever hitting network lookups or requiring mavenLocal() fallbacks!

What are your thoughts on handling aggressive compiler tasks in custom Gradle plugins? Let's discuss in the comments below!

🔗 Check out the JPersist open-source architecture: https://github.com/jpersist/persistence

Show Dev: JPersist v1.8.0 — Hardening Gradle Build Sandbox & ClassLoader Engineering for JPA

Yannick Ebongue — Sat, 31 Oct 2026 22:42:04 +0000

Hey everyone,

We just published version v1.8.0 of JPersist, an open-source ecosystem of highly optimized, Configuration Cache-compliant Gradle plugins designed to automate enterprise Jakarta Persistence (JPA) configurations.

In this release, we didn't just add features (like full Apache OpenJPA toolset orchestration) — we deep-dived into advanced Gradle task engineering to fix common continuous integration pain points.

The Problem: Aggressive Compiler Erasures & CI Pipeline Crashes

When writing custom incremental tasks that process bytecodes, pointing your task @InputDirectory to the compiler's output directory (build/classes/java/main) creates an incremental bottleneck. Why? Because whenever a single file changes, JavaCompile wipes out the whole folder, destroying Gradle's historical file snapshots and causing an incremental cache miss.

Furthermore, running isolated worker actions by injecting text coordinates (group:artifact:version) frequently crashes headless CI nodes if those artifacts aren't fully synchronized on Maven Central yet or if mavenLocal() access is disabled.

How JPersist v1.8.0 Solves This:

Source-Driven Incremental Auditing: Our verification tasks (validatePersistenceSchema and lintNamedQueries) now track flat file collection streams from sourceSet.java.sourceDirectories. Because source folders are never deleted by the build, our delta tracking remains 100% stable and fast.
ClassLoader Harvesting: Our plugins now dynamically query their own active ClassLoader at execution time to harvest the physical .jar file protection domains of our tools API. We pass these raw file handles directly to the isolated WorkerExecutor. Zero network calls, zero resolution exceptions.
Container-Friendly Scopes: We restricted dynamic injection to compileOnly and annotationProcessor. Your packaged WAR and EAR files remain clean, lightweight, and completely free of runtime classpath pollution.

If you are dealing with complex multi-module setups, multi-tenant databases, or looking to streamline your build performance, we'd love for you to check it out!

🔗 GitHub Organization: https://github.com/jpersist
🔗 Main Repository & Templates: https://github.com/jpersist/persistence

Show Dev: JPersist v1.7.0 — Zero-Boilerplate JPA Build Automation for Gradle

Yannick Ebongue — Sat, 24 Oct 2026 22:32:46 +0000

Hey everyone,

If you’ve ever managed enterprise Jakarta Persistence (JPA) setups in complex Gradle multi-module projects, you know the pain: managing verbose <class> tags in persistence.xml, fighting runtime exceptions caused by naming typos in @NamedQuery blocks, or dealing with dirty build states because a bytecode manipulation plugin broke incremental caching rules.

We built JPersist to solve these issues permanently at build time. It is an open-source suite of modern, high-performance, and Gradle Configuration Cache-compliant plugins that automate your entire persistence toolbelt using high-speed ASM bytecode scanning.

We just pushed v1.7.0 to production, which introduces some major capabilities:

🌟 Core Highlights of the Suite

Compile-Time Query Linting: Uses an isolated ANTLR4 parser loop to validate your @NamedQuery strings against your compiled bytecode. If you make a typo in an attribute name, the build fails before deployment.
Multi-Tenant Schema Validation: You can now configure multiple database connection profiles to validate your entity mappings across multiple live tenant partitions simultaneously during the check lifecycle.
Granular Incremental Tracking: Tasks track source modifications via flat file collection streams, protecting your delta compilation metrics from aggressive JavaCompile directory erasure.
GraalVM Native Image Readiness: Generates native reflection configurations (reflect-config.json) out of the box for all discovered entities.

⚡ Quick Comparison

Standard Gradle Setup	The JPersist Advantage
❌ Manual `<class>` tagging required	✅ ASM-powered bytecode scanning auto-detects entities
❌ Named query errors only at runtime	✅ Compile-time query linting catches JPQL/HQL syntax errors before deployment
❌ Broken workspace compiler sync	✅ Automated IDE indexing hooks into Buildship and IntelliJ out-of-the-box

We would love to get your feedback on the architecture! If you want to check out the source code, run the multi-module example templates, or read the full user documentation guides:

🔗 GitHub Repository: https://github.com/jpersist/persistence
🔗 User documentation: https://jpersist.github.io/persistence/plugins/guide/latest/

How We Engineered a Zero-Boilerplate Composite Build Architecture for Enterprise Gradle Plugins

Yannick Ebongue — Sun, 18 Oct 2026 15:14:49 +0000

The Monolithic Plugin Trap

When building enterprise Gradle plugins that handle deep bytecode tasks (like our JPA linter suite, JPersist), developers often fall into the classpath contamination trap. They bundle the core Java logic, framework dependencies (like Hibernate 5/6, EclipseLink, ANTLR4), and the Gradle API into a single monolithic project.

This creates massive friction for teams trying to scale:

IDE Slowdowns: The integrated development environment struggles to separate compiler scopes, leading to indexing fatigue.
Testing Nightmares: Gradle TestKit functional tests can leak runner classloaders and cause file-locking anomalies.
Barriers to Entry: Outside contributors get intimidated by a complex, tightly-coupled dependency tree.

To solve this permanently, we recently underwent a massive structural migration for our v1.6.0 release track, transforming JPersist into a fully decoupled Symmetric Composite Build.

The Blueprint: Dual Isolated `includeBuild` Structures

Instead of using standard nested subprojects that leak compilation classpaths, we split the repository into two entirely independent execution containers right at the root directory level:

jpersist/persistence
├── settings.gradle        <-- The Conductor (Combines everything)
├── libraries/             <-- Isolated Build (Pure Java SPI Engines)
│   ├── build.gradle
│   └── lint-persistence-api/
└── plugins/               <-- Isolated Build (Gradle Plugin Wrappers)
    ├── build.gradle
    └── jakarta-persistence-gradle-plugin/

In the root settings.gradle, we treat them as standalone environments using Gradle's includeBuild directive. This connects them as a unified ecosystem without letting their classpaths collide:

rootProject.name = 'jpersist'

// Include the decoupled core Java logic libraries
includeBuild('libraries')

// Include the isolated Gradle plugin definitions 
includeBuild('plugins')

Why This Composite Setup is a Developer Superpower

1. Absolute Compile-Time Classpath Separation

Our Java libraries inside libraries/ compile against native Hibernate 6 strings natively without knowing anything about Gradle or plugin lifecycles. Conversely, the plugin wrappers inside plugins/ pull those libraries down via standard coordinate notation strings:

dependencies {
    implementation 'io.github.jpersist.lint:lint-persistence-api:2.0.0'
}

During local testing, Gradle's composite build engine automatically intercepts these string coordinates and substitutes them with local project references seamlessly, eliminating manual local maven publishing steps completely.

2. Flawless Gradle TestKit Sandbox Testing

When running functional integration tests via TestKit, Gradle forks a separate JVM daemon. In standard layouts, this daemon can lock file paths or leak dependencies. With the composite build layout, plugins/ runs tests in an isolated sandbox, pulling pristine library binaries on-the-fly without colliding with the root build caching variables.

🌟 We're Open for Contributors! (Come Hack with Us)

With this pristine infrastructure locked down, we are officially opening JPersist to public contributions as we kick off the v1.7.0 - Performance & Multi-Tenancy tracks!

Thanks to the composite build separation, onboarding is incredibly easy. You just need JDK 17, and you can compile and verify the whole project immediately:

./gradlew -p plugins functionalTest

We have just logged our very first good first issue tickets on our public roadmap project board:

Ticket #68: [FEAT] Global modelgenProcessor Configuration.
Ticket #69: [FEAT] Isolated weavingClasspath Pipeline.

If you love advanced build systems engineering, bytecode scanning via ASM, or messing with ANTLR4 parsers, we would love to review your Pull Requests!

⭐ Explore the Roadmap & Grab an Issue: https://github.com/orgs/jpersist/projects

🎉 Update: JPersist v1.6.0 is Live & Open for Contributors!

Yannick Ebongue — Tue, 13 Oct 2026 22:40:22 +0000

We just shipped v1.6.0 to the Gradle Plugin Portal alongside our core query parsing engine libraries (v2.0.0) on Maven Central!

To celebrate, we have officially opened the repository to outside contributors and structured our very first automated issue templates. If you are looking to get your hands dirty with deep Gradle plugin architecture, Groovy task configurations, or ASM bytecode mechanics, we have just tagged two pristine good first issue tickets:

Global modelgenProcessor Configuration container (Easy - perfect for an overview of multi-module plugin hooks).
Isolated Task weavingClasspath Pipeline (Easy-Medium - great look into Gradle task property caching).

We provide a complete step-by-step local environment setup inside our CONTRIBUTING.md. Come help us make enterprise JPA pipelines faster and safer!

👉 Check out the issues here: https://github.com/jpersist/persistence

How We Solved Groovy's MissingMethodException inside Gradle Runtime Task Proxies

Yannick Ebongue — Wed, 07 Oct 2026 14:06:32 +0000

If you’ve ever authored a custom Gradle plugin that handles dynamic file structures using Groovy's MarkupBuilder or XmlParser, you have likely encountered a ghost in the machine: the dreaded MissingMethodException.

It usually happens when you are refining task settings or running complex incremental build tests. Suddenly, code that passed unit tests perfectly blows up in a real-world multi-module build execution pass.

Here is the deep engineering breakdown of how we encountered a hidden runtime proxy trap inside the Gradle Task Decoration Engine while building jPersist v1.4.1, and the design pattern we used to fix it permanently.

The Target Architecture: Dynamic XML Descriptor Management

In enterprise Jakarta Persistence (JPA) environments, managing persistence.xml files in large multi-module projects is a known headache. Our plugin, io.github.jpersist.jpa, solves this by automating entity class discovery via high-speed ASM bytecode scanning and generating or merging the final descriptors cleanly on the fly.

To keep configuration clean, we leveraged Groovy's idiomatic MarkupBuilder inside our custom task:

abstract class ProcessPersistenceDescriptor extends DefaultTask {
    // Gradle lazy property bindings...

    @TaskAction
    void process() {
        if (hasTemplate) {
            merge()
        } else {
            generate()
        }
    }

    private void generate() {
        StringWriter writer = new StringWriter()
        def xml = new groovy.xml.MarkupBuilder(writer)

        xml.persistence(version: "3.1") {
            // A closure manipulating elements dynamically
            "persistence-unit"(name: "app-unit") {
                provider("org.hibernate.jpa.HibernatePersistenceProvider")
            }
        }
    }
}

This looks elegant, passes isolated tests, and works seamlessly—until a downstream consumer tries to mutate plugin extensions or apply complex custom build profiles. Suddenly, the build crashes with a cryptic runtime trace:

Caused by: org.gradle.internal.metaobject.AbstractDynamicObject$CustomMessageMissingMethodException: 
Could not find method generate() for arguments [...] on task ':app:processPersistenceDescriptor' 
of type persist.jakarta.gradle.task.ProcessPersistenceDescriptor_Decorated.

Wait, generate() is a private method clearly defined right inside the task class. How can it be "missing"? And what on earth is ProcessPersistenceDescriptor_Decorated?

The Trap: Gradle's Decorated Runtime Proxy Object

To enforce lazy evaluation, property tracking, input validation, and incremental build snapshots caching, Gradle does not execute your raw task class directly.

Instead, on startup, Gradle’s internal object factory dynamically subclasses your task at runtime via bytecode generation, creating a wrapper proxy matching the pattern ${YourTaskClass}_Decorated.

  [ Your Task Class ]  <--- You wrote this
           ▲
           │ (Inherits & Overrides)
  [ YourTaskClass_Decorated ]  <--- Gradle executes this at runtime

This decorated proxy object intercepts all standard Groovy method dispatch mechanisms (invokeMethod, methodMissing, propertyMissing) to perform its internal dependency tracking and lifecycle magic.

Here is where the collision happens:
Groovy closures (like the code block inside xml.persistence { ... }) inherit the surrounding method instance as their default execution owner and delegate. When MarkupBuilder evaluates an abstract tag entry line like provider(...), Groovy's dynamic dispatcher starts sweeping up the delegation hierarchy to resolve the call.

Instead of hitting the MarkupBuilder configuration graph safely, Gradle's public decorated proxy wrapper interceptor flags the expression. Because the proxy exposes open-ended method definitions, it tricks Groovy into bypassing the builder context completely. It routes the evaluation right back into the task object instance, leading to an immediate parameters signature mismatch and a full task explosion.

Marking your methods private doesn't stop this, because the generated runtime proxy opens up visibility entry points to monitor task state transitions.

The Masterclass Solution: The Static Processor Isolation Strategy

To permanently insulate dynamic DSL blocks and XML parser closures from Gradle's runtime proxy manipulation, we must completely break the object instance chain.

If an execution closure doesn't carry a reference to a parent class object instance, Gradle's proxy wrapper has nothing to attach to. We achieved this by restructuring our plugin tasks around the Strategy Design Pattern and encapsulating the execution logic within a purely static evaluation utility.

Here is the bulletproof architecture shipped in jPersist v1.4.1:

@DisableCachingByDefault(because = "Process overwrite persistence.xml in place")
abstract class ProcessPersistenceDescriptor extends DefaultTask {
    // Task parameters handles strictly isolated to lazy Gradle Property wrappers
    @Input abstract Property<String> getXmlVersion()
    @OutputFile abstract RegularFileProperty getDestinationFile()

    @TaskAction
    void process() {
        // Unpack properties securely inside the safe @TaskAction boundary
        File destination = destinationFile.get().asFile
        String versionStr = xmlVersion.get()

        // 1. Resolve processing characteristics via a Strategy Factory Registry
        JpaVersionStrategyRegistry strategyConfig = JpaVersionStrategyRegistry.resolve(versionStr)

        // 2. PASS TO AN ISOLATED STATIC LAYER
        // This cuts off the parent instance reference, bypassing the proxy wrapper entirely!
        strategyConfig.delegate.process(destination, versionStr)
    }
}

And inside our decoupled, static execution strategy delegate layer:

static class JPA30DescriptorProcessorDelegate implements DescriptorProcessorDelegate {

    @Override
    void process(File target, String xmlVersion) {
        // All closures here evaluate inside a safe, predictable context
        StringWriter rawXmlWriter = new StringWriter()
        MarkupBuilder xml = new MarkupBuilder(rawXmlWriter)

        xml.persistence(version: xmlVersion) {
            // Groovy now resolves these paths directly via MarkupBuilder 
            // with ZERO risk of proxy interception!
            "persistence-unit"([name: "secure-unit"]) {
                provider("org.hibernate.jpa.HibernatePersistenceProvider")
            }
        }

        writeOutputFile(rawXmlWriter.toString(), target)
    }
}

The Engineering Takeaway

By unpacking raw task properties inside the @TaskAction boundary and passing them straight as primitives or decoupled objects into an independent static class block, we successfully cut off the parent instance reference.

When Groovy looks for method resolution paths inside the MarkupBuilder boundaries, it no longer crosses paths with ProcessPersistenceDescriptor_Decorated. The closures run inside a completely clean environment, allowing enterprise builds to run smoothly across any configuration cache change pass.

If you are building custom Gradle tooling that relies on nested builders, dynamic closures, or heavy XML transformations, save yourself days of debugging: Keep your tasks strictly focused on tracking input/output properties, and delegate the execution out to static processors.

🌐 Learn More & Support Independence

This architecture is part of jPersist, an open-source, configuration-cache-compliant Gradle plugin suite that automates descriptor management, static metamodel generation, and compile-time static weaving for Hibernate and EclipseLink ecosystems.

Check out the code, view runnable enterprise multi-module specs, or drop a star on GitHub:
👉 GitHub - jpersist/persistence

If this deep-dive saved you debugging hours on your custom build pipelines, consider checking out our GitHub Sponsors Tiers Profile to back the project's long-term independence!