Groovy @CompileStatic: Architecture Decisions for Static Compilation in Mixed Codebases

The Problem: Dynamic Dispatch Overhead in Performance-Critical Paths

Groovy's dynamic dispatch uses call-site caching that adds measurable overhead in tight loops, math-heavy pipelines, and framework extension points. Teams reach for @CompileStatic to get Java-like performance and compile-time type checking while keeping Groovy's syntax sugar. The feature is not a drop-in replacement—it changes semantics (for example, == maps to equals() rather than identity) and disables most runtime metaprogramming. The architectural decision is where to draw the static boundary so you gain throughput without breaking builders, DSLs, or metaprogramming that the codebase relies on.

Requirements Driving the Decision

• Performance: Eliminate call-site caching overhead in hot paths (data processing, numerical code, high-throughput message handling).
• Type safety: Catch contract drift at compile time across module boundaries.
• Java interoperability: Seamless calls from Java into Groovy and vice versa without reflective bridges.
• Syntax retention: Keep literals, operator overloading, default arguments, and closure syntax.

The default remains dynamic dispatch. @CompileStatic is opt-in per class or per method.

Smallest Suitable Design: Selective Annotation

Annotate only the hot-path classes or modules. A typical pattern:

@CompileStatic
class DataPipeline {
    // static compilation for throughput
    List<Result> process(Collection<RawEvent> events) { ... }
}

// Dynamic class left unannotated for DSL/metaprogramming
class ReportBuilder {
    def build(ReportSpec spec) { ... }
}

For selective opt-out inside a static class, use @CompileStatic(TypeCheckingMode.SKIP) on individual methods that need dynamic features (e.g., a method that calls methodMissing). Keep dynamic features—builders, DSLs, @Mixin, @Category, runtime @Delegate—in unannotated classes to avoid fighting the type checker.

Trust and Data Boundaries

@CompileStatic creates a static-typing boundary. Data crossing from dynamic to static code must conform to declared types; Groovy's coercion rules still apply at runtime but the compiler assumes correctness. This means:

• A dynamic caller can pass a Map where a User is expected if the map has matching properties—coercion happens at runtime.
• The static compiler does not insert defensive checks; a ClassCastException can still surface if the dynamic side violates the contract.

Use @TypeChecked on test boundaries to catch contract drift early without enabling full static compilation in tests.

Operational Checks and CI Guards

Verbose Compilation Logging

Enable in CI to verify only intended classes are compiled statically:

# Gradle
tasks.withType(GroovyCompile) {
    groovyOptions.forkOptions.jvmArgs << '-Dgroovy.compile.static.verbose=true'
}

# Maven

  org.codehaus.gmavenplus
  gmavenplus-plugin
  
    -Dgroovy.compile.static.verbose=true
  

Run groovyc -Dgroovy.compile.static.verbose=true on a sample module and confirm only intended classes show "Compiling statically" in the output.

Bytecode Size and Startup Monitoring

Static classes produce larger bytecode (bridge methods, type descriptors). Track JAR size delta and startup time in CI. A practical guard: fail the build if the count of @CompileStatic annotations exceeds a team‑agreed threshold:

# Bash check in CI
grep -r '@CompileStatic' src/main/groovy | wc -l
# Fail if > THRESHOLD

Liskov Substitution Verification

When a static class is subclassed dynamically, add @CompileDynamic on the subclass and verify behavior:

@CompileStatic
class BaseProcessor { String process(String input) { input.toUpperCase() } }

@CompileDynamic
class LoggingProcessor extends BaseProcessor {
    String process(String input) { log.info(input); super.process(input) }
}

Failure Modes and Mitigations

Failure Mode	Symptom	Mitigation
Accidental @CompileStatic on class using methodMissing/propertyMissing	MissingMethodException at runtime	Audit annotated classes for metaprogramming; use @CompileStatic(TypeCheckingMode.SKIP) on offending methods
Generic type erasure differences vs Java	Bridge-method conflicts, VerifyError	Enable -Xverify:all in test JVM; prefer concrete types over wildcards at boundaries
Closure delegate type inference fails	Compiler error: "Cannot infer delegate type"	Add explicit @DelegatesTo(TargetClass) on closure parameters
Joint compilation order issues	Java sees stale Groovy stubs	Ensure correct sourceSet ordering: Groovy stubs generated before Java compile (Gradle: compileGroovy before compileJava)

Concrete Verification Steps

1. Compile-time audit: Run groovyc -Dgroovy.compile.static.verbose=true on a module; verify output lists only intended classes.
2. Reflection test: Add a unit test that uses reflection to confirm critical hot-path methods are compiled as static (no CallSite array references in bytecode).
3. JMH benchmark: Compare @CompileStatic vs dynamic mode for a representative workload (throughput, allocation rate). Expect 2–10× improvement in numeric loops; marginal gains in I/O-bound code.
4. Bytecode verification: Run tests with -Xverify:all to catch bridge-method conflicts early.
5. Threshold guard: Enforce the grep count check in CI to prevent overuse.

Conditions That Change the Design

• Groovy 4+ (indie parser): Improved generic inference reduces bridge-method conflicts; re-evaluate @DelegatesTo requirements.
• GraalVM native-image: Favors fully static code; may push more modules to @CompileStatic or motivate migration of hot paths to Java/Kotlin.
• Java 17+ sealed interfaces/records: Reduces need for Groovy AST transforms; static Groovy interoperates cleanly with sealed hierarchies.
• Project shifts to pure Kotlin/Java for performance-critical paths: @CompileStatic becomes a transitional tool rather than a long-term strategy.

Limitations

• @CompileStatic disables most AST transformations that rely on runtime metaprogramming (@Mixin, @Category, runtime @Delegate).
• Mixing static and dynamic code in the same class via @CompileDynamic on methods can confuse IDE refactoring and produce noisy stack traces.
• Joint compilation with Maven/Gradle requires correct sourceSet ordering; otherwise Java sees stale Groovy stubs.
• Semantics change: == becomes equals(), is() remains identity. Document this at module boundaries.

Practical Checklist Before Enabling

• Identify hot-path classes via profiling (JFR, async-profiler).
• Confirm no methodMissing/propertyMissing or runtime metaprogramming in those classes.
• Add @DelegatesTo where closure delegates are used.
• Run verbose compilation and JMH benchmark.
• Add CI guards: verbose log check, annotation count threshold, -Xverify:all in test JVM.
• Document the static boundary for future maintainers.