Product technical reference

Detailed support, compatibility and architecture from the source baseline. Java 17+ is a target requirement, not certification of every JVM, OS or framework. Use the support reference for conditions and the evidence scope for measured environments. For your first reload use the installation guide; for concise change-specific outcomes use the reload matrix.

Why Reclazz?

Spring Boot DevTools restarts the application context after a code change. Reclazz is free, open-source, and can redefine classes in the existing JVM. In-place body edits retain existing object state; Spring bean recreation replaces objects and resets their mutable instance state. See state and reload scope.

Comparison

The Reclazz column is measured, on a running JVM, for the release it ships with; the field and enum rows in particular are the result of running each case rather than reasoning about it. The other two columns come from each project's own published documentation, so they say what those tools claim rather than what was tested here, and a blank where a tool is silent is not evidence of absence.

For the comparison that matters more: HotswapAgent covers a much wider set of frameworks than Reclazz and can add enum values, but needs a modified JVM (DCEVM) to do structural reload at all. Reclazz trades that breadth for working on the JDK you already have, and for going deeper on SAP Commerce than either.

Features

• Build packages: AutoCompile stages all modules before publishing output. IntelliJ build signals hold class changes until compilation succeeds. Failed attempts remain held for retry; newer builds invalidate pending acceptance. See the usage guide and BUILD protocol.

Spring Integration

• Spring Bean Refresh: Automatically destroys and recreates singleton beans after class reload
• MVC Re-scan: Re-registers @RequestMapping methods when controllers change structurally, including endpoints added after startup on a stock JDK and inside a Tomcat webapp class loader
• Cache dependencies: A reloaded helper invalidates the Spring cache regions computed through it, including outer caches that read cached inner results. Unrelated observed regions stay warm. Cache instances and classloaders remain distinct. Unknown or partial history retains conservative annotation fallback. See scope and concurrency limits.
• Scheduler Reload: Cancels and re-registers @Scheduled tasks, including supported methods added after startup on a stock JDK. See scope and example
• Event Listener Refresh: Refreshes only the edited beans, preserving unrelated listeners without duplication. Supports added methods within the documented scope, and an added @TransactionalEventListener fires at its transaction phase through Spring's own synchronization. Scope
• Added service operations: New transaction/cache methods on supported singleton services run through real Spring interceptors, including old CGLIB references and first operations on plain beans. Scope.
• AOP Proxy Refresh: Re-parses @Aspect pointcuts and updates supported existing singleton proxy chains in place
• Async Re-processing: Re-processes @Async beans
• Spring Data Refresh: Recreates warm singleton products of actual Spring Data repository types and repairs ordinary singleton holders. An ordinary Spring @Repository DAO stays on generic bean refresh. Scope.
• One line per save that says what it touched: Reloaded OrderService (12ms): bean orderService re-created, mappings re-scanned, caches evicted, and ; 1 thing now waits on a restart, ask PENDING when the save added something only a restart completes. The steps' own sentences are there under verbose
• A record and a way back: sessionLog=<path> appends every status line, timestamped, to a file; docs/usage.md says how to get back from a reload that went wrong and how breakpoints behave in reloaded code; the status socket is documented in docs/protocol.md for other IDEs and build tools
• Flight Recorder events: every reload is a reclazz.Reload JFR event (class, structural or not, duration, what changed) and every failure a reclazz.ReloadFailed one, so reloads sit on the JVM's own timeline next to GC and safepoints in JDK Mission Control; see docs/usage.md
• Spring Security rebuild: an edited @EnableWebSecurity configuration is applied to the running filter chain, so a rule that was permitAll starts answering 401 on the next request without a restart. Method security (@PreAuthorize, @Secured and friends) is a separate cache, resolved once per method and keyed by something redefinition does not change; it is cleared and refilled on every reload, so an edited expression on a service is enforced as written on the next request
• New bean classes: a brand-new @Service, @Component, @RestController or a custom meta-annotated stereotype file becomes a live bean on supported JDK 17+ paths, dependencies injected and mappings registered, with the bean name resolved the way component scanning would (including @AliasFor), instead of waiting for the next restart's component scan. Lazy components wait for first access; prototype components are created for each lookup. Class-level @Profile and @Conditional, including composed annotations, are checked against the current context before registration; a rejected component is neither registered nor initialized by the reload path. Web/custom scopes and scoped proxies require a restart. Scope.
• Annotation metadata: an edited @Transactional or @Cacheable takes effect, not just the method body it sits on
• New exception handlers (Spring 5.3.39 / 6.1.14 scope): add an @ExceptionHandler method to a supported running controller or controller advice; real HTTP tests cover status/body, local priority, advice selectors and repeated saves, including new endpoints. Scope and example.
• New binding and model methods: add @InitBinder and @ModelAttribute callbacks to supported running controllers or advice. Named binder scope, existing model values, advice ordering and later saves are covered by real Spring requests. Scope.
• New Kafka consumers: add a supported @KafkaListener to a running component, including topics and groups selected by Spring expressions on the bean. Real broker tests cover repeated edits, topic/group changes, removal, restoration and shutdown of replaced consumers. Scope. Evidence.
• New JMS consumers: add a supported @JmsListener to a running component. Synchronous replies support direct @SendTo and the caller's JMSReplyTo. Real broker tests cover reply conversion/correlation, queue edits, removal/restoration, consumer shutdown and local transaction rollback/redelivery. Scope. Evidence.
• New RabbitMQ consumers: add a supported @RabbitListener to a running component, including queues selected by Spring expressions from application beans. Real broker tests cover queue changes, removal/restoration and local transaction rollback/redelivery. Scope. Evidence.
• New @Bean factories: add an instance or static @Bean method to a running @Configuration class and its product is registered. Lite, default configuration and static factories take reference beans, typed collections and maps, arrays, Optional, Spring providers and @Value arguments. On a default configuration, instance factory calls resolve through the container, retaining singleton identity and supported explicit/prototype arguments from inter-bean calls, helpers and method references. Scope and lifecycle.
• New lifecycle methods: a @PostConstruct or @PreDestroy added to a supported singleton runs on the next instance, and each instance keeps the destroy callback it was initialised with. Scope and policy.
• Jackson input and output for added members: a getter, a void setter or an instance field added to a running DTO is discovered by Jackson with its saved annotations, so JSON is read and written through it on a stock JDK. Scope.
• Spring XML singleton recreation: a changed constructor argument, factory method or init/destroy method in a *-spring.xml recreates the singleton through Spring and repairs the beans still holding the old one; property edits keep applying in place. Scope.
• What the frameworks cached about your class: a reload is only half the job, because each framework answers from what it worked out about that class once, at startup. An @Autowired you add injects, a constraint you add is enforced, an @ExceptionHandler or @InitBinder you add runs, an edited pointcut is parsed again, and Jackson reads and writes the getter, setter or field you added instead of serialising the old shape

Core

• Reload between requests, opt-in: reloadBoundary=request waits for synchronous Spring MVC dispatches and supported Spring 5 javax or Spring 6 Jakarta MVC Callable/DeferredResult requests before a class reload batch starts. Async requests remain protected until native completion; a timed-out Callable worker remains counted until it actually exits. If a request outlasts the one-second drain deadline, new requests are admitted again and the edit stays queued for a natural idle boundary. This prevents a supported request from crossing a successful method-body reload. See scope and setup.

• Hot class reload: Redefines classes in the running JVM via Instrumentation API

• Save to live: measured end to end on macOS at the default settings, from writing the class file to the running application serving it, 612ms median. The JDK has no native file watching on macOS: it walks its registered directories and stats every file, and on SapMachine 21 here it notices a change about half a second later, whether one directory is registered or nine hundred. The files you are actually editing are checked directly instead, a handful of stat calls rather than a walk of the tree. The first change to any file still waits for the JDK, every one after it does not, and where the JDK watches natively (Linux, Windows) none of this is needed or used

• Structural changes: Add/remove methods and instance fields on supported JDK 17+ paths (companion-class engine). An added instance field is initialised on objects created after the reload, and on objects that already existed its initialiser runs on the field's first read: the initialiser's own instructions are lifted out of the constructor, so a live Spring singleton that gained cache = new ArrayList<>() reads a list. Isolated conditional instance initialisers are supported in single-constructor classes and use the object's state on first read. An initialiser that needs a constructor argument, or that is entangled with other fields, is named with the reason and the field reads the type default. An added static field gets its initial value too: a compile-time constant comes straight off the field, and an initialiser that forms a self-contained block, including a supported conditional expression, is lifted out of <clinit> and run on its own, so the rest of the static block is never re-executed. Where the two cannot be separated the field reads as null/0 and the log names it and the reason. An enum value added on the end goes live on JDK 17-25, and so does one removed from the end, which moves no ordinal (see the comparison table for the exact scope); inserting or reordering values is refused with the reason. A member the save removes stops being visible to reflection, so scans stop acting on it, while code that already holds it keeps running the implementation it had. A changed compile-time constant is named together with the sources that inlined it, found by looking for it in the watched modules; with autoCompile those sources are rebuilt and hot-swapped, so the new value takes effect. JBR/DCEVM additionally gives full reflective visibility of new members

• Property changes: a saved .properties change is first bound and validated on separate objects. An invalid value holds the whole candidate, including logger levels, and fixing it retries all pending keys. Unsupported binding checks hold the change; a failure during application is reported as partial and is not rolled back. Already-loaded Boot .properties, .yml and .yaml files also support nested values, lists and removed keys without overriding higher-priority sources. Removal reveals lower values or defaults; mutable property beans keep their identity. YAML/removal scope. See validation limits. After a clean check, a changed key goes into the running Environment and the @ConfigurationProperties beans whose prefix it touches are rebound, so a timeout or a feature flag takes effect without a restart. A bean bound through its constructor (a record, or @ConstructorBinding) is replaced rather than mutated: destroyed, rebuilt through the same constructor binding against the updated Environment, and the references holding it re-pointed. A @Value placeholder field is re-resolved and written in place, and a bean that takes a changed @Value through its constructor is rebuilt the same way the constructor-bound properties bean is. Scalar @Value fields can also compute arithmetic and conditional expressions from changed placeholders; unsupported expression operations hold the candidate without being evaluated. Supported scalar constructor and native @Bean factory arguments are checked before singleton recreation too. See computed fields

• Logging configuration: logging.level.<logger> in a properties file, or a saved logback.xml / log4j2.xml, is applied to the running logging context. Raising a logger to debug is one of the most common reasons to restart a server and one of the least necessary

• Auto-detection: Automatically detects Spring Boot, Maven, and Gradle project layouts

• Zero config: Just add -javaagent, no configuration files needed

• IntelliJ IDEA plugin: Auto-injects agent into run configurations, auto-detects JDK and JBR

Platform Support

• Spring Boot: Auto-detects target/classes (Maven) or build/classes/java/main (Gradle)
• SAP Commerce (Hybris): extension-aware; *-items.xml regeneration and reload, interceptor re-registration in the platform registry verified by a real model save on a live 2211 server, ImpEx auto-import with a macro-aware REMOVE guard, Spring XML property edits and singleton recreation
• Generic Java: Works with any Java application via watchDirs= configuration

Installation

From JetBrains Marketplace (Recommended)

plugins.jetbrains.com/plugin/33498-reclazz

Or from inside the IDE:

1. Go to Settings > Plugins > Marketplace
2. Search for "Reclazz"
3. Click Install and restart the IDE

The plugin bundles the agent JAR, so there is nothing else to download.

From GitHub

The agent on its own, which is all you need outside IntelliJ, is attached to every release:

curl -LO https://github.com/onurkat/reclazz/releases/latest/download/reclazz-agent-<version>.jar
java -javaagent:reclazz-agent-<version>.jar=platform=spring ...

Each release also carries a .sha256 beside it. The IntelliJ plugin is on the JetBrains Marketplace, and the signed zip is attached to the same release.

Or build both from source:

git clone https://github.com/onurkat/reclazz.git
cd reclazz

# The agent, to attach with -javaagent. This is the jar every example below uses.
./gradlew clean build          # -> agent/build/libs/agent-<version>.jar

# The IntelliJ plugin, if you want the IDE integration as well.
./gradlew buildPlugin          # -> build/distributions/reclazz-<version>.zip
# Install: Settings > Plugins > gear icon > Install Plugin from Disk

build/libs also holds agent-<version>-thin.jar, which is the module's own classes without the bytecode library shaded in. It is not the agent and cannot be attached as one.

What watching costs, on a platform where the JDK has to poll: the walk is linear in the number of files under the watched directories, not in the directories themselves. Measured against a real SAP Commerce extension tree, 953 directories holding 18,680 files, the JDK's own watcher thread used 9% of one core across four consecutive thirty-second windows with nobody editing anything, and the running server's watcher agreed. That is roughly 1% of a core per two thousand watched files, all day, and Tools > How Is Reclazz Doing? now reports the file count and that figure so it is not invisible. watchExtensions and excludePatterns are what shorten the walk. On Linux and Windows the kernel tells the JDK instead and none of this is paid at all.

While it is running, Tools > How Is Reclazz Doing? asks the agent what it has actually done: how long it has been up, what it has reloaded and what failed, what a save costs at the median and the 95th on your machine rather than on mine, how many directories it is watching and how many it could not, and how much is waiting on a restart. Tools > Why Didn't My Class Reload? and Tools > What Still Needs a Restart? answer the two narrower questions.

./gradlew :agent:check runs the unit suite and a coverage floor with it; :agent:jacocoTestReport writes the report to agent/build/reports/jacoco/test/html. The figure counts only what runs in the test process. Fourteen of the tests launch a child JVM with the real agent attached, which is the only honest way to check startup, behaviour under load, or a clean build, and none of that is instrumented.

Usage

Spring Boot

Add the agent to your JVM arguments:

# Maven
java -javaagent:/path/to/reclazz-agent.jar -jar target/myapp.jar

# Gradle
java -javaagent:/path/to/reclazz-agent.jar -jar build/libs/myapp.jar

# With explicit watch directories
java -javaagent:/path/to/reclazz-agent.jar=watchDirs=/path/to/target/classes -jar myapp.jar

Then build your project in another terminal:

mvn compile   # Maven
gradle classes  # Gradle

Reclazz watches the compiled .class output and hot-swaps changes automatically.

Structural changes (adding/removing methods and instance fields) work on supported JDK 17+ paths. On JBR/DCEVM, add -XX:+AllowEnhancedClassRedefinition for full reflective visibility of new members; on standard JVMs, reclazz uses a companion-class fallback (see Supported JDK Providers for the reflective-visibility caveat).

IntelliJ IDEA (Recommended)

When you run the application from IntelliJ, the plugin handles everything:

1. Install the plugin. Reclazz introduces itself once and asks whether to turn on: click Enable Reclazz. It starts switched off, because enabling it means putting an agent into the JVM that runs your code. (Missed the dialog, or opening a second project? Settings > Tools > Reclazz > Enable Reclazz.)
2. Run your application from IntelliJ (Run/Debug)
3. The agent is injected automatically with optimal JVM flags
4. Build your project. Changes are hot-swapped, status shown in the IDE

Without IntelliJ

The agent has no IDE dependency. It needs three things: the -javaagent flag on the JVM, a directory to watch, and any build that writes .class files into that directory.

java -javaagent:/path/to/reclazz-agent.jar=watchDirs=/path/to/build/classes/java/main -jar myapp.jar

Then let any compiler write class files on change:

gradle -t classes    # Gradle continuous build: recompiles on every save
mvn compile          # Maven: run it after each change; Maven has no built-in watch mode

VS Code's Java extension compiles on save, and Eclipse does the same with Build Automatically (its default), so both work out of the box: saving a file puts the fresh .class where Reclazz is watching. One thing to check in VS Code: Gradle projects imported there may have their class output under bin/ rather than build/classes, so point watchDirs at the directory your setup actually writes.

The IntelliJ plugin is a convenience on top of this, not a requirement: it adds auto-attach and a status UI.

Remote and containers

The agent does not care where the compiler runs. It only needs the changed .class files to appear in a directory it watches, on the filesystem of the JVM it lives in. Remote and containerized development is therefore a file-sync problem, not an agent feature.

For Docker, sync the host build output into the watched directory with Docker Compose Watch:

services:
  app:
    build: .
    # your entrypoint or JAVA_TOOL_OPTIONS adds:
    #   -javaagent:/opt/reclazz/reclazz-agent.jar=watchDirs=/app/classes
    develop:
      watch:
        - action: sync
          path: ./target/classes
          target: /app/classes

docker compose watch copies each changed class file into the container the moment the compiler writes it, and the agent inside picks it up.

For a VM, one rsync after each build does the same:

rsync -az target/classes/ user@devhost:/app/classes/

SAP Commerce Cloud (CCv2) is out of reach for this, and for every hot-reload tool: there is no SSH into the running container and the images are immutable, so a changed class file has no way to arrive. Hot reload on SAP Commerce is for locally hosted servers.

The trust boundary

A watched directory is a way to run code in the server's JVM, so it is worth stating plainly what that means. Anyone who can write a .class file into a watched directory has that class redefined into the running process; anyone who can write a .impex file into a watched ImpEx directory (opt-in) has it run against the live database. Reclazz does not, and cannot, verify where those files came from, any more than the JVM verifies its own classpath. So a watched directory should be trusted exactly as much as the server's classpath itself: keep it to your own build output on your own machine, which is what local development is. The agent opens one socket, bound to loopback, that answers two read-only status questions and triggers nothing; it makes no outbound network connection of any kind. Nothing about your code or your machine leaves the machine. What it will say, to anyone who can reach loopback on that host, is class names, the paths those classes were built to, and the list of things this session would need a restart for. On your own machine that is you; on a shared development server it is anyone with an account there, so treat it as readable by them.

Running under the agent also does not hand the application anything it did not have. The engine keeps each watched class's own lookup, which carries private access to that class, and its holder sits on the bootstrap classloader where every line of code in the process can reach it. Only the engine's own classes, named by identity before the application starts, are given it: application code asking is refused, which matters because code that can evaluate a submitted expression or reach a static method through a deserialized object cannot write a class file into a watched directory, and should not get there by another route. Reload-added field values are readable and writable through the same bootstrap classes, because the code the agent generates calls them, and they reach only the values Reclazz itself stores.

SAP Commerce (Hybris)

Edit hybris/config/local.properties:

tomcat.javaoptions=-javaagent:/path/to/reclazz-agent.jar

tomcat.javaoptions is the property the platform leaves empty for exactly this, and it is appended to the options the platform builds for itself. Do not write tomcat.generaloptions=... ${tomcat.generaloptions}: the platform defines that one, so referring to it from local.properties fails the build with Property tomcat.generaloptions was circularly defined.

Reclazz auto-detects the Hybris home directory from platform.home, HYBRIS_BIN_DIR, or the classpath. Start the server and run ant build. Reclazz hot-swaps the compiled classes automatically.

Set it as a property rather than by editing tomcat/conf/wrapper.conf directly: ant server regenerates that file from the properties, so a line added to it by hand is gone after the next rebuild, with no symptom except that saving a file stops doing anything. The IntelliJ plugin writes the same property for you, into a marked block it manages.

Hybris-specific features:

• items.xml and beans.xml regeneration: Saving a *-items.xml or *-beans.xml runs the platform's own code generation in the background and hot-reloads the regenerated model and DTO classes, instead of ant clean all and a restart. New attributes still need a database column, so Reclazz prints a reminder to run HAC > Platform > Update Running System; it will not run DDL against a live database.
• Spring XML reload: *-spring.xml property edits apply in place. Supported existing constructor/factory/lifecycle definitions are recreated, with writable direct holder references repaired. Scope.
• Interceptor reload: Captures mappings before Spring refresh and updates the actual SAP registry afterwards (Validate, Prepare, Load, Remove, InitDefaults). Missing or failed registration is reported instead of success. The SDK contract and the live model-save check are described in integration tests.
• ImpEx auto-import: Optionally imports changed .impex files on save (opt-in). It runs against your live database with no confirmation and nothing that undoes it, so files containing a REMOVE header are refused and named rather than executed. Set impexAllowRemove=true if you mean it.
• Property changes applied to the running server: the platform reads its property files once, at startup. Saving one now applies the keys whose value actually differs, through the same call the HAC console makes. Values that are consumed once at startup are named as still needing a restart rather than reported as applied.
• Log levels: SAP Commerce keeps them in properties rather than a log4j2.xml, as a log4j2.logger.<key>.name and .level pair. Changing a level applies it to the running Log4j2 context, so raising a logger to debug no longer costs a restart. Only the loggers the save touched are set, which leaves a level raised from the HAC console alone.
• Type and enum text: editing an <ext>-locales_<iso>.properties re-reads the platform's localization cache, so the new text is served on the next lookup. No system update and no database write.
• Backoffice labels: labels_<iso>.properties under an extension's *-backoffice-labels folder reach the label cache backoffice reads from, every copy of it. Reopen the view and the text is there.
• Extension-aware: Understands Hybris extension structure, classpath, and classloader hierarchy

On SAP Commerce, compared with JRebel

Compared against JRebel's own SAP Commerce manual, which covers reloading compiled classes and configuring rebel.xml. "Not in its Hybris manual" means exactly that, not that JRebel is broken: it reloads classes on Hybris and that is what it documents.

Attach to Running Server

If the server is already running without the -javaagent flag:

1. Go to Tools > Attach Reclazz to Running Server
2. Select the JVM from the list
3. The agent loads into the running JVM, no restart needed

Configuration

Agent Arguments

The canonical agent argument table defines every accepted option and default. The website configuration reference is generated from that table. See output formatting for the NO_COLOR environment variable; it is not an agent argument.

IntelliJ Plugin Settings

Go to Settings > Tools > Reclazz:

Verified On

Everything documented here is measured on a running system rather than inferred from the code. What that means concretely:

Older or newer versions are likely to work, and are not claimed to until they have been run.

Supported JDK Providers

Reclazz targets JDK 17+ with the standard java.lang.instrument API. Structural reload uses the documented companion path on stock JVMs. The vendor list below describes intended compatibility, not acceptance evidence for every listed vendor or version. The difference is reflective visibility, not whether the change takes effect.

There is a second number, and it is about the compiler rather than the runtime. Instrumentation reads and writes class files, and this build reads them up to Java 27. Runtime acceptance is bounded by the recorded JVM lanes; compiling to a newer class-file version is a separate limit, because the bytecode library learns a class file version after the JDK that introduced it ships. In that window the application runs and method body changes still reload, since the JVM reads those classes and that path does not go through the library, while adding or removing members is off. Reclazz says so once, in Java releases rather than header numbers, with the two ways out: compile with an older --release while you develop, or update Reclazz.

Enhanced redefinition (JBR/DCEVM) applies structural changes directly to the original Class object, so reflection and reflective caches (like Hybris ModelService) see new members immediately.

Companion-class mode (standard JVMs) puts new members on a hidden nestmate and routes calls through them via invokedynamic rewriting. Hot-compiled code that calls new members works transparently; reflection on the original class (Class.getMethod(...)) and caches built at boot time do not pick up the new members until server restart.

What Can Be Hot-Reloaded?

Architecture

             Build Tool (mvn/gradle/ant)
                       |
                       v
               classes/*.class files
                       |
+----------------------|---------------------------+
|  Application JVM     |                            |
|                      |                            |
|  +-------------------v--+                         |
|  |     FileWatcher      |  watches .class files   |
|  |   (NIO WatchService) |                         |
|  +----------+-----------+                         |
|             | bytecode                            |
|      +------v-------+                             |
|      | ClassReloader |                             |
|      | (Instrument-  |                             |
|      |  ation API)   |                             |
|      +------+--------+                             |
|             |                                     |
|   +---------+-----------+                          |
|   |         |           |                          |
|   v         v           v                          |
| Spring   Spring       Spring                      |
| Bean     MVC Re-      Cache                        |
| Refresh  scan         Eviction  + Scheduler,       |
|                                   AOP, Async,      |
|                                   Events, Data,    |
|                                   Security         |
|                                                   |
|   Application | Spring Context | Service Layer    |
+---------------------------------------------------+

What attaching the agent changes about your classes

Reclazz rewrites every watched class at load time, whether or not you ever reload anything. Most of that is invisible, and it is worth writing down which parts are not.

Nothing about reflection. A method keeps its annotations, its generic signature, its throws clause and its parameter names, so Spring still decides to proxy it and Jackson still sees List<Order> rather than a raw list. Every member Reclazz injects is marked synthetic, which is what keeps it out of the framework scans that skip synthetic members.

Stack traces gain a frame. A call into a watched method shows two frames: the dispatch under your own method name, and above it the moved body under an internal one.

at com.acme.OrderService.__reclazz$v0$place$9edc617f(OrderService.java:42)
at com.acme.OrderService.place(OrderService.java:42)

Both carry the real file and line, so the trace still says where the failure was and your IDE can still jump from the frame you recognise. The extra line is the cost of the dispatch the reload engine is built on. One thing does not recover: a log pattern that prints the calling method name (%M in Log4j2) reads it off the moved body, so it prints the internal name. The logger name, the line number and the class name are all unaffected.

serialVersionUID is pinned. Injecting members would change the number the JVM computes for a class that does not declare one. Reclazz computes the number your class would have had and writes it in. The core evidence records UID equality and a plain-class serialization round trip; it does not certify arbitrary serialized object graphs or mixed-cluster deployments.

Fields added by a reload are runtime-only. A field that appears in a reload lives beside the object rather than in it. The injected store is transient; its stored added-field values are not serialized. Clone writes use copy-on-write store isolation, with the usual shallow-copy semantics for referenced values. Deserialization starts without that store. The interaction with first-read initializers needs application-specific verification; do not assume every deserialized or pre-existing object reads the type default. See the component evidence and remaining limits.

A call into a watched class costs about 1.4 nanoseconds more. Measured with and without the agent on the same code: a method that only increments a field went from 0.3ns to 1.7ns per call, and one that concatenates two strings went from 19.4ns to 19.2ns, which is to say the cost disappears into anything that does work. It is the same whether the caller is watched, where its call site is rewritten, or not, where the call goes through the dispatch. After a structural reload, once the JIT has recompiled what the redefinition threw away, calls stay in the same few-nanosecond range.

Startup cost is below this machine's own variation. Six SAP Commerce boots with the agent ranged from 91 to 99 seconds; two warm boots without it were 97.4 and 97.9. Instrumenting every watched class at load time is real work, and on a platform that takes a minute and a half to start it is not something you can see from outside.

What the agent itself holds is bounded and does not grow with reloading. Measured on a live SAP Commerce server after a full integration run, with a heap histogram: 95,996 objects and 2.2 MB across all of Reclazz's own classes. It scales with how many classes were transformed rather than with how many times they were reloaded, which was measured the same way, twenty-nine reloads apart: every count identical. The largest part is the record of each transformed class's method and field signatures, which is what a structural reload diffs against. The last-known-good bytecode cache is capped at 8 MB deflated and evicts by least-recently-used, and the per-class reflection state lives in a ClassValue, so it dies with the class rather than pinning its classloader.

Each reload costs metaspace that is never returned. Around 8.5 KB, measured over 60 reloads. This is the JVM's cost rather than Reclazz's: redefining a class makes the JVM keep the previous version, so that threads still running the old code keep working, and a bare redefineClasses loop with no agent at all measured 10.6 KB per redefinition on the same JDK. Reclazz's own companion classes are collected, one for one with the reloads. It is only worth thinking about where metaspace is capped, which on SAP Commerce it is: a day of heavy editing is a few MB, and Reclazz warns when the pool passes 85% full so that a long session ends in a restart you chose rather than an OutOfMemoryError you did not.

synchronized survives. Both the dispatch and the moved body take the monitor, so mutual exclusion holds from startup, and a structural reload keeps it: the body copied into the companion is wrapped in the monitor the original took, the receiver for an instance method and the class for a static one, and released on the way out including the exceptional one. Measured with two threads through a method that holds for 300ms, before and after a structural reload: 609ms and 615ms, against 305ms when the wrapping was not there.

Project Structure

reclazz/
├── agent/                                    # Java agent (runs inside JVM)
│   └── src/main/java/com/onurkat/reclazz/
│       ├── agent/                            # Agent entry point, config, reloader
│       ├── platform/                         # Platform abstraction layer
│       │   ├── PlatformContext.java           # Interface for platform-specific ops
│       │   ├── PlatformDetector.java          # Auto-detects runtime platform
│       │   ├── SpringBootContext.java         # Spring Boot / generic Java context
│       │   ├── HybrisPlatformContext.java     # SAP Commerce context
│       │   ├── ApplicationContextHolder.java  # Spring context capture
│       │   └── SpringContextInterceptTransformer.java
│       ├── spring/                           # Generic Spring reloaders
│       │   ├── SpringReloadOrchestrator.java  # Coordinates all reloaders
│       │   ├── SpringBeanReloader.java        # Singleton destroy + recreate
│       │   ├── SpringMvcReloader.java         # @RequestMapping re-scan
│       │   ├── SpringCacheReloader.java       # Cache eviction
│       │   ├── SpringSchedulerReloader.java   # @Scheduled re-register
│       │   ├── SpringEventReloader.java       # @EventListener refresh
│       │   ├── SpringAopReloader.java         # AOP cache and living proxy refresh
│       │   ├── SpringAsyncReloader.java       # @Async re-processing
│       │   ├── SpringDataReloader.java        # Repository refresh
│       │   └── SpringSecurityReloader.java    # Security config notification
│       ├── compiler/                         # Incremental compilation
│       ├── hybris/                           # SAP Commerce specific
│       ├── watcher/                          # File watching (NIO WatchService)
│       ├── transform/                        # Bytecode transformation engine
│       ├── reload/                           # Structural reload engine
│       ├── bootstrap/                        # Bootstrap classloader classes
│       └── ui/                               # Console output
│
├── src/main/                                 # IntelliJ IDEA plugin (Kotlin)
├── docs/                                     # Documentation
├── branding/                                 # The mark, and where it is used
│
├── integration-test/                         # End-to-end suite (needs a live
│                                             #   SAP Commerce install; see its README)
└── reclazztest/                              # The extension that suite edits

integration-test/ and reclazztest/ are test scaffolding. They ship in no release, nothing in agent/ or src/ refers to them, and both need a licensed SAP Commerce installation to run. ./gradlew clean build is the whole gate for everyone else. See CONTRIBUTING.md for what each layer of the test suite actually checks.

Troubleshooting

"Do I still need to restart?"

Tools > What Still Needs a Restart? answers it. Reclazz keeps a note of everything this session did that a restart would change: a static field whose initialiser could not be separated from the rest of the static block, an enum change the JVM would not take, a superclass change, a Spring bean the XML reload could not apply, a property the platform refused. When the list is empty it says so, which is the answer that saves the restart.

"Why didn't my class reload?"

Ask the agent: Tools > Why Didn't My Class Reload?, or right-click in the editor. It reports what it found for that class, into the reload log: whether a compiled file exists under a watched directory and when it was last built, whether the JVM has loaded it, whether the agent prepared it, and what the last reload attempt did and which file it took the bytes from. Most of the time the answer is that no reload was ever attempted, and none of those reasons produce an error message on their own.

"No class output directories detected"

Reclazz couldn't find target/classes (Maven) or build/classes/java/main (Gradle) on the classpath. Use watchDirs= to specify the directory explicitly.

"Class redefinition not supported"

Your JVM doesn't support class redefinition. This shouldn't happen with modern JDKs.

Structural change fails on a class

Structural reload works on supported JDK 17+ paths for classes the agent transformed at load time. If the message says the class "was loaded before Reclazz attached", start the server with -javaagent (the IntelliJ plugin's Install action sets this up) instead of attaching later. Attach mode cannot retrofit the reload infrastructure into already-loaded classes on standard JVMs.

Spring bean not refreshed

Reclazz destroys and recreates the singleton, cascades the refresh to dependent beans, and re-points fields that still hold the old instance to the new one (stale-reference healing). If a component still sees stale behavior, check the Reclazz tool window for a reload error on that class.

Spring Boot DevTools compatibility

Reclazz can run alongside DevTools, but it's recommended to disable DevTools when using Reclazz. DevTools performs full context restarts which are slower and lose application state.

Docker / containerized environments

Mount the agent JAR into the container and add the -javaagent flag to JAVA_OPTS:

COPY reclazz-agent.jar /opt/reclazz/agent.jar
ENV JAVA_OPTS="-javaagent:/opt/reclazz/agent.jar=watchDirs=/app/target/classes"