ProxyBuilder — Proxies in Java, without the magic on ProxyBuilder

@StaticLoggingProxy

Mon, 01 Jan 0001 00:00:00 +0000

@StaticLoggingProxy generates a wrapper class that logs every method call through the project’s HasLogger infrastructure and delegates to the real implementation.

Usage

Annotate the interface:

import com.svenruppert.proxybuilder.proxy.generated.annotations.StaticLoggingProxy;

@StaticLoggingProxy
public interface Service {
 String work(String input);
}

After mvn compile, the processor generates ServiceStaticLoggingProxy in target/generated-sources/annotations/. Use it like this:

Service proxy = new ServiceStaticLoggingProxy()
 .withDelegator(new ServiceImpl());

proxy.work("hello"); // logs the call, then runs ServiceImpl.work("hello")

What it logs

For each method on the interface:

Basics

Mon, 01 Jan 0001 00:00:00 +0000

A custom processor extends BasicStaticProxyAnnotationProcessor<T> where T is the annotation you handle. You implement three things: which annotation you are responsible for, what extra class-level bits you want, and how each method body looks.

The smallest useful processor

public final class SecuredAnnotationProcessor
 extends BasicStaticProxyAnnotationProcessor<Secured> {

 @Override
 public Class<Secured> responsibleFor() {
 return Secured.class;
 }

 @Override
 protected void addClassLevelSpecs(TypeElement typeElement, RoundEnvironment roundEnv) {
 // Add fields, marker annotations, helper methods, or constructor details.
 }

 @Override
 protected CodeBlock defineMethodImplementation(ExecutableElement methodElement,
 String methodName2Delegate,
 TypeElement targetType) {
 return CodeBlock.builder()
 .addStatement(delegatorStatementWithReturn(methodElement, methodName2Delegate))
 .build();
 }
}

responsibleFor() tells the base class which annotation to discover. addClassLevelSpecs is your hook for adding state at class level — a field, a marker annotation, a helper. defineMethodImplementation runs once per method on the target interface and returns the generated body.

DynamicProxyBuilder

Mon, 01 Jan 0001 00:00:00 +0000

DynamicProxyBuilder is the entry point for the runtime side. It produces a JDK dynamic proxy that implements the target interface and routes every call through the configured hooks before reaching your implementation.

Construction

DynamicProxyBuilder<Service> builder =
 DynamicProxyBuilder.createBuilder(Service.class, new ServiceImpl());

The two arguments are the interface type and the concrete implementation instance. The builder is generic on the interface, so the result of .build() is typed as Service.

Pre and post actions

A pre-action runs before each method invocation. A post-action runs after.

@StaticMetricsProxy

Mon, 01 Jan 0001 00:00:00 +0000

@StaticMetricsProxy generates a wrapper class that records method timings through Dropwizard Metrics and delegates to the real implementation.

Usage

import com.svenruppert.proxybuilder.proxy.generated.annotations.StaticMetricsProxy;

@StaticMetricsProxy
public interface Service {
 String work(String input);
}

After compilation, use the generated class:

Service proxy = new ServiceStaticMetricsProxy()
 .withDelegator(new ServiceImpl());

Every call to a method on proxy is now timed.

Where the metrics live

Timings are recorded against RapidPMMetricsRegistry, the same registry used by the runtime .addMetrics() builder call. A JMX or console reporter attached to that registry sees both runtime-proxy and static-proxy metrics in the same place.

Method decorators

Mon, 01 Jan 0001 00:00:00 +0000

BasicStaticProxyAnnotationProcessor provides three composition slots for method-level annotations: beforeDelegation, aroundDelegation and afterDelegation. They let one processor handle several annotations on the same method without forking each combination by hand.

The three slots

@Override
protected List<CodeBlock> beforeDelegation(ExecutableElement methodElement,
 String methodName2Delegate,
 TypeElement targetType) {
 if (hasAnnotation(methodElement, RequiresRole.class.getCanonicalName())) {
 return List.of(CodeBlock.of("securityEnforcer.requireRole();\n"));
 }
 return List.of();
}

@Override
protected Optional<CodeBlock> aroundDelegation(ExecutableElement methodElement,
 String methodName2Delegate,
 TypeElement targetType) {
 return Optional.of(
 CodeBlock.of("$L;\n",
 delegatorStatementWithReturn(methodElement, methodName2Delegate)));
}

@Override
protected List<CodeBlock> afterDelegation(ExecutableElement methodElement,
 String methodName2Delegate,
 TypeElement targetType) {
 return List.of(CodeBlock.of("securityAudit.recordSuccess();\n"));
}

beforeDelegation returns blocks to emit before the delegate call. aroundDelegation returns the delegate call itself (with the return value if any). afterDelegation returns blocks to emit after the delegate call.

Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

This page shows the smallest possible ProxyBuilder usage end to end: add the dependency, define an interface, wrap an instance with pre and post hooks.

1. Add the dependency

In your pom.xml:

<dependency>
 <groupId>com.svenruppert</groupId>
 <artifactId>proxybuilder</artifactId>
 <version>00.10.00</version>
</dependency>

2. Define an interface and an implementation

public interface GreetingService {
 String greet(String name);
}

public class GreetingServiceImpl implements GreetingService {
 @Override
 public String greet(String name) {
 return "Hello, " + name;
 }
}

3. Wrap it with the builder

import com.svenruppert.proxybuilder.proxy.dymamic.DynamicProxyBuilder;

GreetingService proxy = DynamicProxyBuilder
 .createBuilder(GreetingService.class, new GreetingServiceImpl())
 .addIPreAction((original, method, args) ->
 System.out.println("before " + method.getName()))
 .addIPostAction((original, method, args) ->
 System.out.println("after " + method.getName()))
 .build();

System.out.println(proxy.greet("world"));

Run it. You will see:

Security rules

Mon, 01 Jan 0001 00:00:00 +0000

A security rule is a Supplier<Boolean> you hand to the builder. Before every method invocation the proxy evaluates the rule. If it returns false, the invocation is refused.

Basic usage

Service proxy = DynamicProxyBuilder
 .createBuilder(Service.class, new ServiceImpl())
 .addSecurityRule(() -> currentUserCanCallService())
 .build();

The rule is evaluated on every invocation. There is no caching. If your check is expensive, cache it yourself in the supplier.

Composing rules

You can register multiple security rules. They are evaluated in registration order; the first one that returns false short-circuits and blocks the call.

@StaticVirtualProxy

Mon, 01 Jan 0001 00:00:00 +0000

@StaticVirtualProxy generates a wrapper class backed by the virtual proxy strategy infrastructure. The wrapper holds a creation strategy; the real implementation is built on first use and cached.

Usage

import com.svenruppert.proxybuilder.proxy.generated.annotations.StaticVirtualProxy;

@StaticVirtualProxy
public interface Service {
 String work(String input);
}

After compilation, the generator produces ServiceStaticVirtualProxy. Configure it with a factory and the first call materialises the real instance:

Service proxy = new ServiceStaticVirtualProxy()
 .withStrategy(new SingleInstanceCreationStrategy<>(() -> new ServiceImpl()));

proxy.work("hello"); // first call — constructs ServiceImpl, then delegates
proxy.work("again"); // reuses the already-constructed ServiceImpl

What “virtual” buys you

Lazy construction. The expensive implementation is not built at proxy creation time; it is built when something actually calls a method.
Thread safety. The default strategy is single-instance and thread-safe. Multiple threads racing on the first call will see one construction and the same cached instance.
Pluggable lifecycle. Swap in a custom CreationStrategy for caching with eviction, per-thread instances, or test fixtures that build a fresh instance each round.

When to prefer this over the runtime version

You want the compile-time benefits — no reflection, GraalVM-friendly, inspectable generated source.
You want the proxy to live in a JPMS module and be referenced by other modules without runtime opens.

When the runtime version is fine

You build the proxy in one place, hand it to one consumer, and never need to inspect the generated source.

Installation

Mon, 01 Jan 0001 00:00:00 +0000

ProxyBuilder ships a single artefact that contains both the runtime API and the annotation processors. Add it once for runtime use; for annotation processing add it to the compiler plugin’s processor path.

Runtime dependency

<dependency>
 <groupId>com.svenruppert</groupId>
 <artifactId>proxybuilder</artifactId>
 <version>00.10.00</version>
</dependency>

This is enough if you only use DynamicProxyBuilder and friends from the runtime API.

Annotation processing

To have @StaticLoggingProxy, @StaticMetricsProxy, @StaticVirtualProxy, @StaticObjectAdapter or @DynamicObjectAdapterBuilder actually generate classes, register the artefact on the compiler plugin’s annotation processor path:

Metrics

Mon, 01 Jan 0001 00:00:00 +0000

The .addMetrics() builder call wires Dropwizard Metrics into the proxy. Every method invocation is timed and recorded against a Dropwizard Timer keyed by the method signature.

Basic usage

Service proxy = DynamicProxyBuilder
 .createBuilder(Service.class, new ServiceImpl())
 .addMetrics()
 .build();

That is the entire setup. From this point on, every call to the proxy is measured.

Where the metrics live

Timings are collected through RapidPMMetricsRegistry, a thin wrapper over a Dropwizard MetricRegistry. You can:

Processor options

Mon, 01 Jan 0001 00:00:00 +0000

BasicStaticProxyAnnotationProcessor declares three compiler arguments out of the box. You can read them from your own processor and you can declare new ones for processor-specific options.

Built-in options

-Aproxybuilder.verbose — reserved for verbose diagnostic notes.
-Aproxybuilder.suffix=<value> — overrides the generated class suffix globally. Takes precedence over the suffix returned by generatedClassSuffix(TypeElement).
-Aproxybuilder.failOnStaticMethods=true|false — defaults to true. Set to false to downgrade the “static method on a proxy target” finding to a warning so the build continues.

Wiring options into Maven

<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-compiler-plugin</artifactId>
 <configuration>
 <compilerArgs>
 <arg>-Aproxybuilder.suffix=Secured</arg>
 <arg>-Aproxybuilder.failOnStaticMethods=true</arg>
 </compilerArgs>
 </configuration>
</plugin>

Adding your own option

Your processor inherits the standard SupportedOptions/getSupportedOptions() contract from javax.annotation.processing.Processor. Override getSupportedOptions() to declare additional keys, then read them through processingEnv.getOptions():

@StaticObjectAdapter

Mon, 01 Jan 0001 00:00:00 +0000

@StaticObjectAdapter generates an adapter class for an interface. For each method on the interface, the processor also generates a functional interface; the adapter exposes a setter that lets you install a lambda for that method. Methods that have not been overridden delegate to the wrapped instance.

Usage

import com.svenruppert.proxybuilder.proxy.generated.annotations.StaticObjectAdapter;

@StaticObjectAdapter
public interface Service {
 String work(String input);
}

After compilation, you can:

ServiceStaticObjectAdapter adapter = new ServiceStaticObjectAdapter()
 .withService(new ServiceImpl())
 .withServiceMethodWorkString(input -> "adapted " + input);

adapter.work("hello"); // returns "adapted hello"

withService(...) installs the original instance. withServiceMethodWorkString(...) installs a lambda that replaces just the work(String) method. Other methods on Service continue to delegate to the original.

Virtual proxies

Mon, 01 Jan 0001 00:00:00 +0000

A virtual proxy stands in for an instance until something tries to use it. The first method call triggers the creation strategy, which builds the real implementation; subsequent calls go straight to the now-cached real instance.

When to use it

The real implementation is expensive to construct (loads a model, opens a connection, parses a file).
You want construction to happen lazily, in the calling thread, the first time the dependency is actually exercised.
You do not want to leak the laziness into the calling code — the caller receives the interface and uses it as if it were the real thing.

Builder usage

Service proxy = DynamicProxyBuilder
 .createVirtualProxy(Service.class, () -> new ExpensiveServiceImpl())
 .build();

The supplier is invoked at most once. The result is cached inside the proxy.

@DynamicObjectAdapterBuilder

Mon, 01 Jan 0001 00:00:00 +0000

@DynamicObjectAdapterBuilder generates a builder and an invocation handler pair. The builder collects an original instance and per-method overrides; the result is a proxy that prefers the override when one is registered and delegates to the original otherwise.

Usage

import com.svenruppert.proxybuilder.objectadapter.dynamic.DynamicObjectAdapterBuilder;

@DynamicObjectAdapterBuilder
public interface Service {
 String work(String input);
}

The processor generates ServiceAdapterBuilder. Use it like this:

Service adapter = ServiceAdapterBuilder.newBuilder()
 .setOriginal(new ServiceImpl())
 .withWork(input -> "adapted " + input)
 .build();

adapter.work("hello"); // returns "adapted hello"

Each interface method gets a withXxx(...) method on the builder. The parameter type is the matching functional interface.

Add a pre-action

Mon, 01 Jan 0001 00:00:00 +0000

Problem

You have an interface and an implementation, and you want a callback to run before every method call — for argument logging, for instrumentation, for debugging, for a “what is going on?” trace. You do not want to touch the implementation; the wrapping should be invisible to the calling code.

The runtime builder solves this with .addIPreAction(...).

Files involved

AddPreActionTest.java ↗

The interface and the implementation

The test declares both as inner types in the same file. The implementation returns its input concatenated with the string "impl".

Add metrics at runtime

Mon, 01 Jan 0001 00:00:00 +0000

Problem

You want timing data on every method call through a proxy — how often it runs, how long it takes, distribution percentiles — without touching the implementation and without standing up a separate instrumentation layer.

addMetrics() on the builder wires Dropwizard Metrics into the proxy. From then on, every invocation is timed, and the metrics show up in RapidPMMetricsRegistry.

Files involved

End-to-end metrics test

testusage/src/test/java/.../DynamicProxyBuilderTest.java#testAddMetrics View on GitHub ↗

@Test
public void testAddMetrics() throws Exception {

 final InnerDemoClass original = new InnerDemoClass();
 final InnerDemoInterface demoLogic = DynamicProxyBuilder
 .createBuilder(InnerDemoInterface.class, original)
 .addSecurityRule(() -> true)
 .addSecurityRule(() -> true)
 .addMetrics()
 .build();
 Assertions.assertNotNull(demoLogic);
 Assertions.assertEquals(demoLogic.doWork(), original.doWork());

 final MetricRegistry metrics = RapidPMMetricsRegistry.getInstance().getMetrics();
 final ConsoleReporter reporter = ConsoleReporter.forRegistry(metrics)
 .convertRatesTo(TimeUnit.NANOSECONDS)
 .convertDurationsTo(TimeUnit.MILLISECONDS)
 .build();
 reporter.start(1, TimeUnit.SECONDS);

 IntStream.range(0, 10_000_000).forEach(i -> {
 final String s = demoLogic.doWork();
 workingHole(s.toUpperCase());
 });
 logger().info("s1 = {}", s1);

 final SortedMap<String, Histogram> histograms = metrics.getHistograms();
 Assertions.assertNotNull(histograms);
 Assertions.assertFalse(histograms.isEmpty());
 Assertions.assertTrue(histograms.containsKey(InnerDemoInterface.class.getName() + ".doWork"));
}

From proxybuilder tag 00.10.00

Architecture review

Mon, 01 Jan 0001 00:00:00 +0000

A three to five day engagement that produces a written assessment of your current setup and a concrete migration plan. We look at the architecture as a whole, not just individual classes.

When this is the right format

You have a working but ageing AOP setup (Spring AOP, AspectJ, ByteBuddy agents, javassist-based wrappers) and want to know whether — and how — to move away from it.
You are planning a Java-version upgrade (especially to a JPMS-strict module graph) and want to de-risk the proxy and reflection touch-points first.
You want GraalVM native image and you are tired of reflection configuration files.
You are about to write your own annotation processor and want a second opinion on the design.

What we do

Day 1 — Discovery. Walk through the proxy/AOP touch-points with you. Read the relevant code, build configuration, runtime configuration. Identify the top three risks and the top three opportunities.

Custom processor engineering

Mon, 01 Jan 0001 00:00:00 +0000

A longer engagement that goes beyond advice. We design and implement a custom annotation processor for your codebase, hand it over with tests and documentation, and stay on call for revisions.

Typical engagements

Security wrapper. @Secured, @RequiresRole, @RequiresPermission on service interfaces, generating compile-time-checked enforcement that calls through to your existing security context.
Audit emitter. Annotations that mark methods producing audit-trail entries, with a processor that generates the wiring to your logging or SIEM pipeline. No runtime reflection on the audit path.
Multi-tenancy guards. Per-method tenant-scope checks, derived from interface annotations. Build-time failure when new methods miss the annotation.
Custom metrics & tracing. Method-level instrumentation that emits to OpenTelemetry, Micrometer, or your existing metrics infrastructure — without weaving an agent into the JVM.

How an engagement is shaped

Scoping (1–2 days, fixed price). Discovery call, requirements walk-through, decision on processor design. Output: a one-page brief that defines the annotation surface, the generated-code shape and the acceptance criteria.
Implementation (sprint-sized, fixed price or weekly retainer). The processor is built against your codebase. Tests run as part of your normal build. Code reviews go through your usual channels.
Hand-over. Documentation written in your team’s idiom — README, architecture decision record, contributor guide. Walk-through with the team that will own it going forward.
Optional retainer. Two to eight hours a week, ongoing, for follow-up questions, processor extensions, version bumps.

Deliverables

The processor source code, in your repository, under your licence.
A working test suite that exercises the processor against representative interfaces.
Documentation: how to use the annotation, how the generator works, how to extend it later.
Optional: a short internal talk to onboard the wider engineering team.

Logistics

Pricing: Scoping is fixed-price (€1,500–€3,000 depending on complexity). Implementation is fixed-price after scoping, or weekly retainer at €4,500/week for 4-day weeks.
Confidentiality: Source-level access under NDA. Code can be developed in a private branch you own; you control merge.
Lead time: Scoping typically starts within two weeks. Full engagements start two to six weeks after scoping concludes.

Datenschutzerklärung

Mon, 01 Jan 0001 00:00:00 +0000

Diese Seite verarbeitet so wenig personenbezogene Daten wie möglich. Dieses Dokument fasst zusammen, was im Detail erhoben, gespeichert und übermittelt wird.

1. Verantwortlicher

Verantwortlich für die Datenverarbeitung im Sinne der DSGVO ist:

Sven Ruppert Otto-Hahn-Str. 25 38116 Braunschweig Germany

E-Mail: sven.ruppert@gmail.com Telefon: +49 151 59100028

2. Hosting

Die Website wird auf einem Server in Deutschland (Hetzner, EU) betrieben. Beim Aufruf der Seiten werden vom Webserver standardmäßig folgende Daten verarbeitet:

IP-Adresse (gekürzt, wo möglich)
Datum und Uhrzeit des Zugriffs
Aufgerufene URL und HTTP-Statuscode
User-Agent (Browser- und Betriebssystem-Kennung)
Referrer (sofern vom Browser übermittelt)

Rechtsgrundlage: Art. 6 Abs. 1 lit. f DSGVO (berechtigtes Interesse an Betrieb, Stabilität und Sicherheit der Website). Server-Logs werden nach 14 Tagen automatisch gelöscht, sofern keine sicherheitsrelevanten Vorfälle dokumentiert werden.

Impressum

Mon, 01 Jan 0001 00:00:00 +0000

Diensteanbieter

Sven Ruppert Otto-Hahn-Str. 25 38116 Braunschweig Germany

Kontakt

E-Mail: sven.ruppert@gmail.com Telefon: +49 151 59100028

Umsatzsteuer-ID

Gemäß § 19 UStG wird keine Umsatzsteuer ausgewiesen.

Verantwortlich für den Inhalt nach § 18 Abs. 2 MStV

Sven Ruppert (Anschrift wie oben).

Streitschlichtung

Die Europäische Kommission stellt eine Plattform zur Online-Streitbeilegung (OS) bereit: https://ec.europa.eu/consumers/odr/. Unsere E-Mail-Adresse findest du oben im Impressum.

Wir sind nicht bereit oder verpflichtet, an Streitbeilegungsverfahren vor einer Verbraucherschlichtungsstelle teilzunehmen.

Haftung für Inhalte

Als Diensteanbieter sind wir gemäß § 7 Abs. 1 TMG für eigene Inhalte auf diesen Seiten nach den allgemeinen Gesetzen verantwortlich. Nach §§ 8 bis 10 TMG sind wir als Diensteanbieter jedoch nicht verpflichtet, übermittelte oder gespeicherte fremde Informationen zu überwachen oder nach Umständen zu forschen, die auf eine rechtswidrige Tätigkeit hinweisen.

Workshop

Mon, 01 Jan 0001 00:00:00 +0000

A focused workshop for a single engineering team. The format is half lecture, half pair-coding on a code base we agree on in advance — yours, a small sample, or the ProxyBuilder examples.

Who it is for

Java engineering teams that ship cross-cutting concerns (logging, metrics, security, audit, multi-tenancy) and want to understand the trade-offs between runtime reflection and compile-time generation.
Teams considering a move from a heavy AOP framework toward generated code for GraalVM, JPMS or startup-time reasons.
Teams that need a working mental model of javax.annotation.processing before they start writing their own processor.

Sample two-day agenda

Day 1 — Runtime side

Wrap an interface

Mon, 01 Jan 0001 00:00:00 +0000

Problem

You have an interface and a concrete implementation. You want a proxy you can hand to consumers of the interface, with no surprises in observed behaviour — the proxy must return the same results as the real instance.

This is the smallest possible runtime proxy, used as a sanity check and as the starting point for everything else.

Files involved

The interface and the implementation

testusage/src/test/java/.../InnerDemoInterface.java + InnerDemoClass.java View on GitHub ↗

public interface InnerDemoInterface {
 String doWork();
}

public class InnerDemoClass implements InnerDemoInterface, HasLogger {

 public InnerDemoClass() {
 logger().info("InnerDemoClass = init {}", System.nanoTime());
 }

 @Override
 public String doWork() {
 return "InnerDemoClass.doWork()";
 }
}

From proxybuilder tag 00.10.00

ProxyBuilder — Proxies in Java, without the magic on ProxyBuilder

@StaticLoggingProxy

Usage

What it logs

Basics

The smallest useful processor

DynamicProxyBuilder

Construction

Pre and post actions

@StaticMetricsProxy

Usage

Where the metrics live

Method decorators

The three slots

Quickstart

1. Add the dependency

2. Define an interface and an implementation

3. Wrap it with the builder

Security rules

Basic usage

Composing rules

@StaticVirtualProxy

Usage

What “virtual” buys you

When to prefer this over the runtime version

When the runtime version is fine

See also

Installation

Runtime dependency

Annotation processing

Metrics

Basic usage

Where the metrics live

Processor options

Built-in options

Wiring options into Maven

Adding your own option

@StaticObjectAdapter

Usage

Virtual proxies

When to use it

Builder usage

@DynamicObjectAdapterBuilder

Usage

Add a pre-action

Problem

Files involved

The interface and the implementation

Add metrics at runtime

Problem

Files involved

End-to-end metrics test

Architecture review

When this is the right format

What we do

Custom processor engineering

Typical engagements

How an engagement is shaped

Deliverables

Logistics

Datenschutzerklärung

1. Verantwortlicher

2. Hosting

Impressum

Diensteanbieter

Kontakt

Umsatzsteuer-ID

Verantwortlich für den Inhalt nach § 18 Abs. 2 MStV

Streitschlichtung

Haftung für Inhalte

Workshop

Who it is for

Sample two-day agenda

Wrap an interface

Problem

Files involved

The interface and the implementation