Add @Strategy marker annotation for static-polymorphism strategies

[dougqh]

What Does This Do

Adds @Strategy, a marker annotation for static-polymorphism strategy types and parameters — the stateless, concrete-typed policy objects the JIT can devirtualize and inline so one shared algorithm specializes to straight-line code per caller.

Motivation

Marks where static-polymorphism approach to an API is being used.

The intention is to clearly signal when this style of API is being used.
The annotation will serve as documentation on how to get the most performance out of such an API.

And eventually, tooling will be able to check if the API is being used as intended.

Additional Notes

From Claude...

Marker-only — no enforcement yet. The discipline it names is held by hand for now; the contract lives in the javadoc.

Design notes

• @Target({TYPE, PARAMETER}) — on a type: "this is a strategy" (hold it static final, concrete-typed, so it inlines). On a parameter: "this is a strategy slot" (the arg should be a static final constant or a non-capturing lambda). The parameter target lets us tag a slot even when its type can't be (e.g. a java.util.function.Function we don't own).
• @Retention(SOURCE) — zero bytecode footprint, no runtime metadata (agent hygiene); a source-level checker reads it fine.
• @Documented — the contract is human-facing, so it belongs in the generated javadoc.
• @Inherited — documentary intent (a concrete subclass of a strategy base is a strategy); inert under SOURCE retention, kept as a signal.

Applications

None here, by design — the first uses land in the stacked FlatHashtable PR that builds on this one.

🤖 Generated with Claude Code

[datadog-datadog-prod-us1-2]

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 56.82% (-0.48%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 120469d | Docs | Datadog PR Page | Give us feedback!}

[dd-octo-sts]

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	13.96 s	13.94 s	[-0.6%; +0.8%] (no difference)
startup:insecure-bank:tracing:Agent	12.89 s	13.04 s	[-2.1%; -0.3%] (maybe better)
startup:petclinic:appsec:Agent	16.81 s	16.73 s	[-0.9%; +1.8%] (no difference)
startup:petclinic:iast:Agent	16.41 s	16.84 s	[-6.9%; +1.7%] (no difference)
startup:petclinic:profiling:Agent	16.54 s	16.37 s	[-3.5%; +5.6%] (no difference)
startup:petclinic:sca:Agent	16.81 s	16.63 s	[-0.2%; +2.3%] (no difference)
startup:petclinic:tracing:Agent	15.73 s	15.68 s	[-5.6%; +6.2%] (unstable)

Commit: 120469d4 · CI Pipeline · Benchmarking Platform UI

---

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

[datadog-datadog-prod-us1-2]

More details

Two marker annotations for static-polymorphism strategies: @strategy (for types/parameters) and @StrategyConsumer (for methods). Both use SOURCE retention, require no runtime behavior, and contain no enforcement. Compilation, metaannotations, and javadoc are correct; no uses yet (by design). Zero behavioral or bytecode impact — this is a documentation-first pattern telegraph.

Was this helpful? React 👍 or 👎

_{📊 Validated against 5 scenarios · Open Bits AI session}

_{🤖 Datadog Autotest · Commit da64961 · What is Autotest? · Any feedback? Reach out in #autotest}

[mcculls]

@Inherited has no affect on source-only annotations, so this could be dropped

(it also has no affect on parameter annotations - it's only really useful on class annotations: https://docs.oracle.com/javase/8/docs/api/java/lang/annotation/Inherited.html)

[dougqh]

Yes, I thought about that. Ultimately, I decided to keep it to show the intent -- that the concept transfers from parent to child -- including abstract child classes.

[mcculls]

Interested to see where this goes

[dougqh]

Interested to see where this goes

@mcculls If you are curious to see usage, you can look at #11980 where the first Strategy and StrategyConsumer are located.

I'm also going to try figure out a way to update the perf-review to check for this, but I'm not quite sure what that will look like yet.

[dd-octo-sts]

/merge

[gh-worker-devflow-routing-ef8351]

View all feedbacks in Devflow UI.

2026-07-20 19:27:03 UTC ℹ️ Start processing command /merge

---

2026-07-20 19:27:08 UTC ℹ️ MergeQueue: pull request added to the queue

The expected merge time in master is approximately 2h (p90).

---

2026-07-20 20:25:27 UTC ℹ️ MergeQueue: This merge request was merged