Should we specify anything for `Singleton`?
- 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
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