Documentation
Reference documentation for ProxyBuilder — runtime proxies, static proxies, custom annotation processors, JPMS.
ProxyBuilder gives you two ways to put a proxy in front of an interface implementation in Java: at runtime through a builder API on top of JDK dynamic proxies, or at compile time through annotation processing that generates static proxy classes.
This documentation walks through both, plus the extension points for building your own processors.
Where to start
- New to the project? Start with Getting Started for the elevator pitch, dependency coordinates and a five-minute Quickstart.
- You want runtime proxies (wrap an existing instance, add hooks, security, metrics): jump to Runtime Proxies.
- You want generated proxies at build time (no reflection at runtime, GraalVM native-image ready): jump to Static Proxies.
- You want your own annotation processor (security wrappers, audit, multi- tenancy guards): see Custom Processors.
Runtime vs. compile time at a glance
| Aspect | Runtime (DynamicProxyBuilder) | Compile time (@Static*Proxy) |
|---|---|---|
| When | Object construction | javac round |
| Reflection at runtime? | Yes (JDK dynamic proxies) | No |
| GraalVM native image | Needs reflection config | Works out of the box |
| Composability | Builder chain, fluent | Combine annotations on the type |
| Best for | Cross-cutting concerns on existing code | Production-grade generated code |
Both strategies live in the same module and share the same supporting APIs (metrics, security rules, virtual proxy strategies). You can mix them in the same project.
In this section
- Getting Started
What ProxyBuilder is, when to reach for it, and how to add it to a Java project.
- Runtime Proxies
Wrap an interface implementation at runtime through a builder API. JDK dynamic proxies, no AOP framework.
- Static Proxies
Annotation-driven proxy classes generated during compilation. Zero reflection at runtime.
- Custom Processors
Write your own annotation processor on top of BasicStaticProxyAnnotationProcessor.
- JPMS module
ProxyBuilder is a JPMS module. The descriptor, the transitive dependencies and the jdeps validation command.
- Processor safety rules
Method and class shapes that the static proxy processors refuse to generate code for, and why.