jakartaee / jakartaee/cdi

Should we specify anything for `Singleton`?

Open
#987 5 comments 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
240
Forks
83
PR merge metrics
No merged PRs in 30d

Description

For `@Eager` (#835) we specified

> Only `@ApplicationScoped` beans may be eagerly initialized.
> If a bean of any other normal scope or the `@Dependent` pseudo-scope is eagerly initialized, definition error occurs.
> If a bean of any other pseudo-scope is eagerly initialized, non-portable behavior results.

In the ["what's new" blog post](https://jakartaee.github.io/cdi/2026/06/05/whats-new-in-cdi50.html) we mentioned that `@Eager` is likely to be supported on `@Singleton` beans by implementations. Someone on my team asked the reasonable question of why we didn't _specify_ `@Eager` for `@Singleton` beans.

The slightly wider question is why do we not specify _anything_ about `Singleton`? The only mentions are:
- as an example of a pseudo-scoped bean
- that we provide `SingletonLiteral`

Though we don't say much directly about `Singleton`, we can infer:
- In Jakarta EE environments, it's required to be supported because [Jakarta Injection is required](https://jakarta.ee/specifications/platform/11/jakarta-platform-spec-11.0#a2161)
- I don't see anything in CDI that directly requires it, though other things in `jakarta.inject` like `Inject` and `Provider` are clearly required
- It's annotated `@Scope`, [so it's a pseudo-scope](https://jakarta.ee/specifications/cdi/4.1/jakarta-cdi-spec-4.1#normal_scope)
- [Its Javadoc](https://jakarta.ee/specifications/dependency-injection/2.0/apidocs/jakarta/inject/singleton) says "Identifies a type that the injector only instantiates once. Not inherited."
- There's no further information in the [Jakarta Injection specification document](https://jakarta.ee/specifications/dependency-injection/2.0/jakarta-injection-spec-2.0)

I think my questions are:
- should we specify that `@Eager` must work for `@Singleton` beans?
- is there anywhere else in the spec that it might be worth specifying anything about `@Singleton`?
- would it be helpful to provide an _informational_ note in the spec pointing out some of the gotchas about `@Singleton` and differences between it and `@ApplicationScoped`?
- it's a pseudo-scope
- it won't have a client proxy
- the CDI container will only instantiate one instance, and that instance will be used for all injection points
- `@Singleton` is not a bean discovery annotation, so `@Singleton` beans will not be discovered automatically

If that sort of informational content (i.e. not specifying anything, but merely pointing out consequences of other spec requirements) is not helpful in a specification document, perhaps it would make a good blog post?

Contributor guide

Open the contributing guide

Research direction

Review the CDI 4.1 references to `Singleton`, the linked Jakarta Injection specification and Javadoc, and the existing `@Eager` wording. Compare what is currently specified with the questions raised about `@Singleton`; done means reaching a decision on the scope of any specification or informational changes and identifying the relevant specification or blog location.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.