Using Eclipse Hot Code Replace to Update Java Code at Runtime

What you can do with Hot Code Replace

Eclipse’s Hot Code Replace (HCR) feature lets you modify the body of a Java method while the application is paused at a breakpoint, save the change, and have the running JVM execute the updated bytecode without a full restart. This speeds up iterative debugging because you avoid rebuilding and relaunching the program for small logic tweaks.

How the mechanism works

When you start a Java launch in debug mode, Eclipse communicates with the JVM via the Java Debug Wire Protocol (JDWP). If the JVM supports class redefinition (most modern HotSpot JVMs do), Eclipse can send a redefinition request that replaces only the modified method’s bytecode. The debugger then resumes execution, and the new code runs immediately.

To enable HCR:

1. Open Window → Preferences → Java → Debug → Hot Code Replace.
2. Set the policy to Always or On breakpoint for your launch configuration (or keep the workspace default).
3. Ensure Build automatically is enabled (Project → Build Automatically) so Eclipse compiles your changes incrementally.

After hitting a breakpoint, edit the method body, save the file (Ctrl+S), and Eclipse will prompt to apply the changes. If successful, you see a "Hot Code Replace successful" message in the Debug view.

Worked example: editing a loop’s print statement

Create a minimal Java project to verify HCR:

public class LoopDemo {
    public static void main(String[] args) {
        for (int i = 0; i < 5; i++) {
            System.out.println("Iteration: " + i);
        }
    }
}

1. Set a breakpoint on the line containing System.out.println.
2. Launch the class in debug mode (Debug As → Java Application).
3. When the breakpoint hits, change the print statement to, for example, System.out.println("Value: " + i * 2); and save.
4. Eclipse will ask to apply the Hot Code Replace; accept.
5. Resume (F8) and observe the console output: it now shows the doubled values without restarting the program.

If you instead add a new field to LoopDemo (e.g., private static int extra;) and save, Eclipse will indicate that the change cannot be applied via HCR and will suggest a full restart, illustrating the feature’s limits.

Limits and common mistakes

What HCR cannot change

• Method signatures (adding/removing parameters, changing return type, or altering throws clauses).
• Fields (adding, removing, or changing their type or modifiers).
• Class hierarchy (adding/removing superclasses or interfaces).
• Annotations on types, methods, or fields.
• Static initializers.

These structural changes require a full rebuild and relaunch because the JVM cannot redefine them at runtime.

Typical pitfalls

• Failing to enable automatic builds. If Build automatically is off, Eclipse does not generate the updated class file, and the HCR request fails silently.
• Editing outside a method body. Adding a new method or field while paused will not be applied; you’ll see no change and may mistakenly think HCR is broken.
• JVM or agent restrictions. Some JVMs (e.g., older IBM J9) or profiling agents that disable class redefinition cause HCR to be ignored. Check the Error Log for warnings like "JVMTI error: Cannot redefine class".
• Bytecode weaving tools. Projects using AspectJ or similar weavers may have HCR apply only to the unwoven bytecode, leading to unexpected behavior after a change.
• Optimized code. HotSpot may have compiled a method to native code; after HCR the interpreter may still execute stale optimized code until a de‑optimization occurs, which can cause surprising results in tight loops.

Practical verification steps

1. Run the loop example above and confirm the output changes after an HCR‑eligible edit.
2. Look for the "Hot Code Replace successful" message in the Debug view.
3. Introduce an illegal change (e.g., add a field) and verify that Eclipse either prompts for a full restart or logs an HCR‑related warning.
4. If no message appears, open Window → Show View → Error Log and filter for "Hot Code Replace" to diagnose the issue.

By following the enablement steps, staying within method‑body edits, and checking the debugger feedback, you can reliably use Eclipse Hot Code Replace to shorten your debug‑edit cycle.