Jakarta CDI Explained With Scopes Producers and Events
Learn Jakarta CDI: bean discovery, scopes, injection, qualifiers, producers, observers and events, interceptors and how CDI compares with Spring.

Contexts and Dependency Injection, CDI, is the dependency injection model of Jakarta EE and the one that Quarkus, Weld and OpenWebBeans implement. It does what Spring's container does, with different vocabulary and a few ideas that Spring lacks, such as typed events and decorators. This post covers the pieces you use daily: beans and scopes, qualifiers, producers, events, interceptors, and the split between CDI Lite and CDI Full that arrived with Jakarta EE 10. It ends with a comparison with Spring for readers who know that container. It uses CDI 4.1, as in Jakarta EE 11, on JDK 21 or later.
A bean and its scope
A bean is an object the container creates, injects and manages. What turns a class into a bean is a bean-defining annotation, which in practice is a scope:
@ApplicationScoped
public class InvoiceService {
@Inject PaymentGateway gateway;
@Inject Event<InvoiceIssued> issued;
public Invoice issue(Order order) {
Invoice invoice = Invoice.from(order);
gateway.charge(invoice);
issued.fire(new InvoiceIssued(invoice));
return invoice;
}
}@Inject asks the container for a bean of the type PaymentGateway. The scope says how long an instance lives and who shares it.
| Scope | Lifetime |
|---|---|
@ApplicationScoped | One instance for the application |
@SessionScoped | One per HTTP session (the bean must be serializable) |
@RequestScoped | One per request |
@ConversationScoped | Between a begin and an end that you control (Full only) |
@Dependent | The default; a new instance for each injection point, living as long as its owner |
The detail that most often confuses newcomers is that the normal scopes (all except @Dependent) are proxied. What is injected is a client proxy that finds the real instance in the current context on each call. That is how a @RequestScoped bean can be injected into an @ApplicationScoped one: the application bean holds a proxy, and each call reaches the instance for the current request. It also means the bean class must be proxyable: non-final, with a non-private no-argument constructor, and public methods called through the proxy. A final class with a normal scope fails at deployment with an unproxyable bean error.
Discovery decides which classes are beans. In CDI 4 the default mode is annotated: only classes with a bean-defining annotation (a scope, or a stereotype) are beans. Classes without one are ignored, so a plain public class Helper is not injectable until you annotate it. The older all mode is configurable with beans.xml. In Quarkus, discovery is done at build time by ArC and works the same way, covered in Quarkus CDI.
Qualifiers
When two beans have the same type, the container cannot choose, and the deployment fails with an ambiguous resolution error, the same problem that appears as NoUniqueBeanDefinitionException in Spring, see that fix. A qualifier is an annotation that tags a bean and an injection point:
@Qualifier
@Retention(RUNTIME)
@Target({TYPE, FIELD, METHOD, PARAMETER})
public @interface Sandbox { }
@ApplicationScoped @Sandbox
class FakeGateway implements PaymentGateway { /* ... */ }
@ApplicationScoped
class StripeGateway implements PaymentGateway { /* ... */ }
@Inject @Sandbox PaymentGateway gateway; // gets FakeGateway
@Inject PaymentGateway real; // gets StripeGateway (the @Default qualifier)A bean without a qualifier has the built-in @Default; @Named("name") is a string qualifier for use from expressions in Faces pages. A custom annotation is type-safe, so a typo is a compile error, which is the reason CDI prefers it to string names. @Alternative with @Priority replaces a bean for a whole application, which is the mechanism for swapping an implementation in tests.
Producers
Not every object can be a bean by annotation: a class from a library, an object that needs configuration to build, a value read from the environment. A producer method creates it:
@ApplicationScoped
class Clients {
@Produces @ApplicationScoped
HttpClient httpClient() {
return HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(2)).build();
}
@Produces @Dependent
Logger logger(InjectionPoint point) {
return LoggerFactory.getLogger(point.getMember().getDeclaringClass());
}
void close(@Disposes HttpClient client) { client.close(); }
}The return type and qualifiers define the bean. A producer can take an InjectionPoint to learn where it is injected, which suits loggers. A @Disposes method runs when the instance's scope ends, for cleanup. A producer's scope follows the same rules, and producing a final class in a normal scope has the proxy limitation above.
Events
Events decouple the code that announces something from the code that reacts. The example above fires InvoiceIssued; observers elsewhere subscribe by parameter type:
@ApplicationScoped
class MailNotifier {
void on(@Observes InvoiceIssued event) {
mailer.send(event.invoice().customerEmail(), "Your invoice");
}
void afterCommit(@Observes(during = TransactionPhase.AFTER_SUCCESS) InvoiceIssued event) {
audit.record(event);
}
}Firing is type-safe: the observer's parameter type, plus optional qualifiers, selects which events it receives. By default observers run synchronously, in the firing thread, and an exception in one propagates to the caller; fireAsync and @ObservesAsync run them on another thread. TransactionPhase ties an observer to the outcome of the current transaction, so a mail is sent only if the commit succeeded. Compare this with Spring's ApplicationEventPublisher and @EventListener: the shape is the same, and the CDI one is checked by types and qualifiers.
Interceptors
An interceptor adds behaviour around a method call, driven by an annotation you define, the CDI counterpart of an aspect:
@InterceptorBinding @Retention(RUNTIME) @Target({TYPE, METHOD})
public @interface Timed { }
@Timed @Interceptor @Priority(Interceptor.Priority.APPLICATION)
class TimingInterceptor {
@AroundInvoke
Object time(InvocationContext ctx) throws Exception {
long start = System.nanoTime();
try { return ctx.proceed(); }
finally { log.debug("{} took {} ns", ctx.getMethod().getName(), System.nanoTime() - start); }
}
}Annotate a bean or method with @Timed and the interceptor applies. Interceptors are called through the container's proxies, so a call from within the same class is not intercepted, the same limit as in Spring's proxy model. Decorators, a related feature (CDI Full), wrap a bean of a given type and see the typed method calls.
CDI Lite and Full
CDI 4 splits the specification. CDI Lite is the subset that can be processed at build time: beans, scopes, qualifiers, producers, events and interceptors, with build-compatible extensions. Quarkus implements Lite. CDI Full adds the portable extension SPI, decorators, conversation scope and more, and it is what WildFly, Payara and Open Liberty provide. Code that sticks to Lite runs in both. If you use portable extensions or decorators, you are on Full.
Compared with Spring
The two containers cover the same ground. @ApplicationScoped corresponds to a singleton, @Inject to @Autowired, @Produces to @Bean, @Observes to @EventListener, and a qualifier annotation to @Qualifier. The differences are in style: CDI resolves by type and qualifier and fails at deployment on ambiguity or a missing bean; its scopes are proxied by default, which makes narrower-scope injection safe; events and interceptors are in the specification, not in the framework's extras. Spring offers more configuration and integration. The shared idea is explained from the ground up in what dependency injection really is.
Where this does not apply
CDI is a container for application objects, not an application framework; persistence, REST and security are other specifications that happen to use it. In a Spring Boot application you use Spring's container, not CDI. The specification is at jakarta.ee/specifications/cdi, and the reference implementation's documentation at weld.cdi-spec.org.


