Chronicle Runtime Compiler

Table of Contents

• 1. Quick-Start
• 2. Installation
• 3. Feature Highlights
• 4. Advanced Usage & Patterns
• 5. Operational Notes
• 6. Documentation & Requirements
• 7. FAQ / Troubleshooting
• 8. CI / Build & Test
• 9. Contributing & License

This library lets you feed plain Java source as a String, compile it in-memory and immediately load the resulting Class<?> - perfect for hot-swapping logic while the JVM is still running.

1. Quick-Start

<!-- Maven -->
<dependency>
    <groupId>net.openhft</groupId>
    <artifactId>compiler</artifactId>
    <version>Look up the most recent version on Maven Central.</version>
</dependency>

/* Gradle (Kotlin DSL) */
implementation("net.openhft:compiler:Look up the most recent version on Maven Central.")

Example: compile and run a Runnable at runtime

import net.openhft.compiler.CompilerUtils;

String className = "mypackage.MyDynamicClass";
String src = """
    package mypackage;
    public class MyDynamicClass implements Runnable {
        public void run() {
            System.out.println("Hello World");
        }
    }
""";

Class<?> clazz = CompilerUtils.CACHED_COMPILER.loadFromJava(className, src);
((Runnable) clazz.getDeclaredConstructor().newInstance()).run();

2. Installation

• Requires a full JDK (8, 11, 17 or 21 LTS), not a slim JRE.

• On Java 11 + supply these flags (copy-paste safe):

--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED
--add-opens=jdk.compiler/com.sun.tools.javac=ALL-UNNAMED

• Spring-Boot / fat-JAR users

  • unpack Chronicle jars: bootJar { requiresUnpack("*/chronicle-.jar") }

3. Feature Highlights

Feature	Benefit
In-memory compile & load	Hot-swap code without restarting JVM
CachedCompiler	Skips recompilation of unchanged source
Debug Mode	Writes .java / .class so IDE breakpoints work
Custom ClassLoader support	Isolate plugins or enable class unloading
Nested-class handling	Build helper hierarchy in a single call

4. Advanced Usage & Patterns

• Hot-swappable strategy interface for trading engines

  • Rule-engine: compile business rules implementing Rule

    • Supports validator hook to vet user code

  • Replace reflection: generate POJO accessors, 10 x faster

  • Off-heap accessors with Chronicle Bytes / Map

5. Operational Notes

• Compile on a background thread at start-up; then swap instances.

  • Re-use class names or child classloaders to control Metaspace.

    • Use CompilerUtils.DEBUGGING = true during dev; remember to prune artefacts.

  • SLF4J categories: net.openhft.compiler (INFO), compilation errors at ERROR.

  • Micrometer timers/counters: compiler.compiles, compiler.failures.

6. Documentation & Requirements

• Project requirements outline functional, non-functional, and compliance obligations.

• Release notes provide the tagged release history.

7. FAQ / Troubleshooting

• `ToolProvider.getSystemJavaCompiler() == null`

• You are running on a JRE; use a JDK.

• `ClassNotFoundException: com.sun.tools.javac.api.JavacTool`

• tools.jar is required on JDK ⇐ 8. Newer JDKs need the --add-exports and --add-opens flags.

• Classes never unload

• Generate with a unique ClassLoader per version so classes can unload; each loader uses Metaspace.

• Illegal-reflective-access warning

• Add the --add-opens & --add-exports flags shown above.

8. CI / Build & Test

• GitHub Actions workflow runs mvn verify, unit & race-condition tests.

  • Code-coverage report published to SonarCloud badge above.

9. Contributing & License

• Fork → feature branch → PR; run mvn spotless:apply before pushing.

  • All code under the Apache License 2.0 - see LICENSE.