Load-Time Weaving (LTW)

LTW in Spring is a three-legged stool — remove any leg and it silently does nothing or fails at startup. ## 1. `@EnableLoadTimeWeaving` (Spring side) Put it on a `@Configuration` class (XML equivalent: `<context:load-time-weaver/>`). It: - Registers a **`LoadTimeWeaver`** bean (named `loadTimeWeaver`). The concrete type is usually **`InstrumentationLoadTimeWeaver`**, which wraps the JVM's `java.lang.instrument.Instrumentation`. - Wires the AspectJ weaving `ClassFileTransformer` into that weaver so matching classes get transformed as they load. It has an attribute **`aspectjWeaving`** with values `ENABLED`, `DISABLED`, and `AUTODETECT` (the default). `AUTODETECT` turns weaving on only if a `META-INF/aop.xml` is found on the classpath. You can also implement **`LoadTimeWeavingConfigurer`** to supply a custom `LoadTimeWeaver` (e.g. for a specific app server). ## 2. `META-INF/aop.xml` (AspectJ side) This is **not** a Spring file — it is AspectJ's own weaver configuration, discovered on the classpath. It has two key sections: ```xml <aspectj> <aspects> <aspect name="com.example.audit.AuditAspect"/> </aspects> <weaver options="-verbose -showWeaveInfo"> <include within="com.example..*"/> </weaver> </aspectj> ``` - `<aspects>` lists the aspect classes to apply (they must be on the classpath; annotation-style `@Aspect` classes are supported). - `<weaver>` controls scope and diagnostics. The **`<include within=...>`** filters are important: without them the weaver inspects *every* class the JVM loads, which slows startup badly. `options` like `-showWeaveInfo` / `-verbose` print what got woven — invaluable when "nothing is happening." You can have multiple `aop.xml` files (one per jar); AspectJ merges them. ## 3. The Java agent (JVM side) A `ClassFileTransformer` can only be installed if the JVM was started with an **agent** that grabs the `Instrumentation` handle. Two common choices: - **`-javaagent:spring-instrument-<version>.jar`** — Spring's minimal agent (`InstrumentationSavingAgent`). It just captures `Instrumentation` so Spring's `InstrumentationLoadTimeWeaver` can use it. Lightweight; used together with `@EnableLoadTimeWeaving`. - **`-javaagent:aspectjweaver-<version>.jar`** — the full AspectJ agent. It reads `aop.xml` and weaves directly, independent of Spring's plumbing. Some environments differ: - Certain **application servers / servlet containers** expose an instrumentable classloader, so Spring can weave **without** a `-javaagent` flag (this is why `AUTODETECT` exists). Plain `java -jar` (e.g. a Boot fat jar) does **not** — you must pass the agent. - The agent must be an actual file path on the launch command; it cannot be added purely from application code after the JVM has started. ## Putting it together / common failure modes - **No agent** → `InstrumentationLoadTimeWeaver` has no `Instrumentation` → weaving is skipped (or Spring throws that instrumentation is unavailable). This is the #1 "my aspect never runs" cause. - **aop.xml missing or in the wrong place** (must be `META-INF/aop.xml`) → nothing to weave. - **No `<include>`** → works but huge startup penalty as every class is scanned. - **Class already loaded before the weaver is ready** → a class loaded during early bootstrap won't be woven; ordering matters. Use `-verbose` to spot "already defined" warnings. ## When to use Only when you need weaving proxies can't provide (self-invocation, non-bean classes, `@Configurable` domain objects). Otherwise the agent + aop.xml overhead isn't worth it.