DDI – Dynamic Dependency Injection

Getting Started

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

1. Add the dependency

DDI is published to Maven Central. Add the artifact to your build:

<dependency>
 <groupId>com.svenruppert</groupId>
 <artifactId>ddi</artifactId>
 <version>06.01.01</version>
</dependency>

Gradle (Kotlin DSL):

implementation("com.svenruppert:ddi:06.01.01")

DDI targets JDK 21+. The 1.0.x line targets JDK 8 if you need it.

2. Bootstrap the container

DDI scans the classpath for implementations, producers and resolvers. Tell it which package(s) to scan — typically your application’s root:

import com.svenruppert.ddi.DI;

public class Main {
 public static void main(String[] args) {
 DI.activatePackages("com.example");
 var app = DI.activateDI(App.class);
 app.run();
 }
}

That’s the whole bootstrap. No XML, no annotation processor, no container configuration. Repeated calls to activatePackages add more packages to the scan.

Resolution Rules

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

When DDI encounters an @Inject-annotated field, it walks a deterministic decision tree to pick one class or producer to instantiate. This page is the exact rule set, lifted from the project README and grouped by the kind of target you injected.

The rules use four building blocks:

Concept	What it is
Impl	A class implementing the injected interface.
Producer	A method or class annotated `@Produces`, returning the interface or an impl.
ClassResolver	A `ClassResolver<T>` annotated `@ResponsibleFor(T.class)` — runs on every lookup and returns the class to use.
ProducerResolver	A resolver that picks between multiple producers for the same impl.

When you inject an interface

@Inject Service service;

Setup	Resolution
0 Impl	Exception — nothing to inject.
0 Impl, 1 Producer for the interface	The producer is used.
1 Impl, 0 Producer	The single impl is used.
1 Impl, 1 Producer for the impl	The producer for the impl is used.
1 Impl, n Producers for the impl	Exception — ambiguous.
1 Impl, 1 Producer for the interface	The producer for the interface is used.
1 Impl, n Producers for the interface	Exception — ambiguous.
1 Impl, 1 Producer for the interface + 1 Producer for the impl	Exception — ambiguous.
n Impls, no resolver	Exception — ambiguous.
n Impls, 1 responsible ClassResolver	The class returned by the resolver is used.
n Impls, 1 Producer for the interface	The producer for the interface is used.
n Impls, 1–n Producers for an impl	Exception — ambiguous.
n Impls, 1 ClassResolver + 1 Producer for the interface	The producer for the interface is used.
n Impls, 1 ClassResolver + 1–n Producers for impls	The class returned by the resolver is used, or its matching producer if one exists.
n Impls, n responsible ClassResolvers	Exception — conflicting responsibility.
1 Impl, n Producers for impl, 1 ProducerResolver	The producer selected by the ProducerResolver is used.
n Impls, 1 ClassResolver, 0–n Producers per impl, 1 ProducerResolver per impl	The producer selected by the ProducerResolver is used, for the impl selected by the ClassResolver.

When you inject an implementation directly

@Inject FriendlyGreeter greeter;

Setup	Resolution
Impl, no producer	The impl is used.
Impl, 1 producer	The producer is used.

Reading the table

The two principles behind every row:

ClassResolver

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

Work in progress. This page is the canonical reference for the ClassResolver API. Full content lands with the SaaS-policy tutorial series (see the roadmap).

The contract

package com.svenruppert.ddi.implresolver;

public interface ClassResolver<T> {
 Class<? extends T> resolve(Class<T> interf);
}

Annotate the resolver with @ResponsibleFor(Service.class) so DDI knows which interface it claims. One ClassResolver per interface — competing claims are a hard error.

Minimum viable example

@ResponsibleFor(Service.class)
public class ServicePolicy implements ClassResolver<Service> {
 public Class<? extends Service> resolve(Class<Service> i) {
 return SecurityContext.current().plan() == Plan.ENTERPRISE
 ? PremiumService.class
 : BasicService.class;
 }
}

DDI calls resolve(...) every time the field is injected. That’s the defining property of the library — and the reason classic DI containers can’t do this cleanly.

Producers

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

Work in progress. This page is the canonical reference for Producer<T> and @Produces. Full content lands alongside the producer-vs-resolver tutorial (see the roadmap).

When you need a producer

Direct class instantiation works for the common case: DDI calls the no-arg constructor, injects fields, runs @PostConstruct, done. You need a producer when:

The instance requires constructor arguments DDI can’t supply.
The factory call has side effects you want explicit (opening a connection, reading config).
The decision which subtype to instantiate is data-driven and you don’t want a ClassResolver for it.

The shape

package com.svenruppert.ddi.producer;

public interface Producer<T> {
 T create();
}

Annotate the producer with @Produces to advertise it to the container:

Scopes

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

Work in progress. This page is the canonical reference for the scope API. Full content lands alongside the Writing a custom scope tutorial (see the roadmap).

The built-in scope

Out of the box DDI ships a single scope:

JVMSingletonInjectionScope — one instance per class, for the lifetime of the JVM. The simplest possible model, and a good default for stateless services.

DI.registerClassForScope(MyService.class, "jvm-singleton");

Writing your own scope

The scope interface (InjectionScope) lets you implement other lifetimes — per-request, per-tenant, per-session, per-virtual-thread. The mechanism is intentionally small. Documentation and a worked example are on the roadmap.

Compatibility

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

JDK matrix

DDI version line	JDK baseline	Status
06.x (current)	JDK 21 LTS	Active development
05.x	JDK 21 LTS	Maintenance only
04.x	JDK 8 source / JDK 11+ build	End-of-life
1.0.x	JDK 8	Frozen — for legacy projects

Newer JDKs (22, 23, …) are tested but not officially declared “supported” until they have reached at least one quarterly maintenance release.

Runtime environments

DDI is plain Java — there is no servlet, no container, no agent. It works wherever the JDK works:

DDI 06.01.01 — standalone documentation site

Mon, 18 May 2026 00:00:00 +0000

DDI has lived for over a decade inside the umbrella dependencies repository. That worked while the library was an internal helper. It stopped working once the dynamic-resolution story — the reason DDI exists — got buried under the parent project’s release notes for everything else.

So: this site.

What’s new in 06.01.01

This is primarily a documentation release. The library API did not change in a breaking way; the source still lives in [svenruppert/dependencies]({{ .Site.Params.github }}) as the ddi module.