add @Eager

api/src/main/java/jakarta/enterprise/context/Eager.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2025, Contributors to the Eclipse Foundation
+ *
+ * This program and the accompanying materials are made available under the
+ * Apache Software License 2.0 which is available at:
+ * https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package jakarta.enterprise.context;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import jakarta.enterprise.util.AnnotationLiteral;
+
+/**
+ * Marks the annotated bean as eagerly initialized. May be applied to a bean class,
+ * producer method or field or {@linkplain jakarta.enterprise.inject.Stereotype stereotype}.
+ * <p>
+ * Only {@link ApplicationScoped @ApplicationScoped} beans may be eagerly initialized.
+ * <p>
+ * Contextual instance of an eagerly initialized bean is created no later than at the moment
+ * the container fires the {@link jakarta.enterprise.event.Startup Startup} event.
+ *
+ * @since 5.0
+ */
+@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD })
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface Eager {
+    /**
+     * Supports inline instantiation of the {@link Eager} annotation.
+     */
+    final class Literal extends AnnotationLiteral<Eager> implements Eager {
+        public static final Literal INSTANCE = new Literal();
+
+        private static final long serialVersionUID = 1L;
+
+        private Literal() {
+        }
+    }
+}

api/src/main/java/jakarta/enterprise/inject/Reserve.java

@@ -47,6 +47,8 @@
  * <p>
  * Unlike {@linkplain Alternative alternatives}, reserves cannot be selected for a bean archive in {@code beans.xml}.
  * </p>
+ *
+ * @since 5.0
  */
 @Target({ TYPE, METHOD, FIELD })
 @Retention(RUNTIME)
@@ -59,5 +61,8 @@ final class Literal extends AnnotationLiteral<Reserve> implements Reserve {
         public static final Literal INSTANCE = new Literal();
 
         private static final long serialVersionUID = 1L;
+
+        private Literal() {
+        }
     }
 }

api/src/main/java/jakarta/enterprise/inject/Stereotype.java

@@ -84,7 +84,8 @@
  * <li>all beans with the stereotype have defaulted bean names, or that</li>
  * <li>all beans with the stereotype are alternatives, or that</li>
  * <li>all beans with the stereotype have predefined {@code @Priority}, or that</li>
- * <li>all beans with the stereotype are reserves.</li>
+ * <li>all beans with the stereotype are reserves, or that</li>
+ * <li>all beans with the stereotype are eagerly initialized.</li>
  * </ul>
  *
  * <p>
@@ -149,6 +150,21 @@
  * </pre>
  *
  * <p>
+ * A stereotype may declare an {@link jakarta.enterprise.context.Eager &#064;Eager} annotation, which specifies
+ * that every bean with the stereotype is eagerly initialized.
+ * </p>
+ *
+ * <pre>
+ * &#064;ApplicationScoped
+ * &#064;Eager
+ * &#064;Stereotype
+ * &#064;Target(TYPE)
+ * &#064;Retention(RUNTIME)
+ * public @interface InitOnStartup {
+ * }
+ * </pre>
+ *
+ * <p>
  * A stereotype may declare other stereotypes. Stereotype declarations are transitive. A stereotype declared by a second
  * stereotype is inherited by all beans and other stereotypes that declare the second stereotype.
  * </p>

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/BeanInfo.java

@@ -126,6 +126,7 @@ public interface BeanInfo {
      * Returns whether this bean is a {@linkplain jakarta.enterprise.inject.Reserve reserve}.
      *
      * @return whether this bean is a {@linkplain jakarta.enterprise.inject.Reserve reserve}
+     * @since 5.0
      */
     boolean isReserve();
 
@@ -138,6 +139,14 @@ public interface BeanInfo {
      */
     Integer priority();
 
+    /**
+     * Returns whether this bean is {@linkplain jakarta.enterprise.context.Eager eagerly initialized}.
+     *
+     * @return whether this bean is {@linkplain jakarta.enterprise.context.Eager eagerly initialized}
+     * @since 5.0
+     */
+    boolean isEager();
+
     /**
      * Returns the bean name of this bean. A bean name is usually defined
      * using the {@link jakarta.inject.Named @Named} annotation.

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/StereotypeInfo.java

@@ -19,7 +19,8 @@
  * a set of {@linkplain #interceptorBindings() interceptor bindings},
  * default {@linkplain #priority() priority}, whether all beans with
  * the stereotype are {@linkplain #isAlternative() alternatives}
- * or {@linkplain #isReserve() reserves}, or have {@linkplain #isNamed() default names}.
+ * or {@linkplain #isReserve() reserves}, are {@linkplain #isEager() eagerly initialized},
+ * or have {@linkplain #isNamed() default names}.
  *
  * @since 4.0
  */
@@ -53,6 +54,7 @@ public interface StereotypeInfo {
      * This means that all beans with this stereotype are reserves.
      *
      * @return whether this stereotype is meta-annotated {@link jakarta.enterprise.inject.Reserve @Reserve}
+     * @since 5.0
      */
     boolean isReserve();
 
@@ -68,6 +70,15 @@ public interface StereotypeInfo {
      */
     Integer priority();
 
+    /**
+     * Returns whether this stereotype is meta-annotated {@link jakarta.enterprise.context.Eager @Eager}.
+     * This means that all beans with this stereotype are eagerly initialized.
+     *
+     * @return whether this stereotype is meta-annotated {@link jakarta.enterprise.context.Eager @Eager}
+     * @since 5.0
+     */
+    boolean isEager();
+
     /**
      * Returns whether this stereotype is meta-annotated {@link jakarta.inject.Named @Named}.
      * This means that all beans with this stereotype have default bean names.

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/SyntheticBeanBuilder.java

@@ -138,6 +138,7 @@ public interface SyntheticBeanBuilder<T> {
      * @return this {@code SyntheticBeanBuilder}
      * @throws IllegalStateException if this method is called multiple times
      *         or if the bean was previously marked as {@linkplain #alternative(boolean) alternative}.
+     * @since 5.0
      */
     SyntheticBeanBuilder<T> reserve(boolean isReserve);
 
@@ -155,6 +156,21 @@ public interface SyntheticBeanBuilder<T> {
      */
     SyntheticBeanBuilder<T> priority(int priority);
 
+    /**
+     * Marks this synthetic bean as a {@linkplain jakarta.enterprise.context.Eager eagerly initialized} if desired.
+     * <p>
+     * If not called, this synthetic bean will not be eagerly initialized.
+     * <p>
+     * If this synthetic bean does not have a scope that permits eager initialization,
+     * the synthetic bean registration will fail.
+     *
+     * @param isEager whether this synthetic bean should be eagerly initialized
+     * @return this {@code SyntheticBeanBuilder}
+     * @throws IllegalStateException if this method is called multiple times
+     * @since 5.0
+     */
+    SyntheticBeanBuilder<T> eager(boolean isEager);
+
     /**
      * Sets the bean name of this synthetic bean. If {@code beanName} is {@code null},
      * this synthetic bean will not have a name.

api/src/main/java/jakarta/enterprise/inject/spi/AfterTypeDiscovery.java

@@ -51,6 +51,7 @@ public interface AfterTypeDiscovery {
     /**
      * @return the list of enabled reserves for the application, sorted by priority in ascending order.
      * @throws IllegalStateException if called outside of the observer method invocation
+     * @since 5.0
      */
     public List<Class<?>> getReserves();
 

api/src/main/java/jakarta/enterprise/inject/spi/BeanAttributes.java

@@ -86,10 +86,23 @@ public interface BeanAttributes<T> {
      *
      * @return <code>true</code> if the bean is a {@linkplain Reserve reserve}, and <code>false</code>
      *         otherwise.
+     * @since 5.0
      */
     public default boolean isReserve() {
         // `default` to avoid breaking older `Bean` implementations
         return false;
     }
 
+    /**
+     * Determines if the bean is {@linkplain jakarta.enterprise.context.Eager eagerly initialized}.
+     *
+     * @return <code>true</code> if the bean is {@linkplain jakarta.enterprise.context.Eager eagerly initialized},
+     *         and <code>false</code> otherwise.
+     * @since 5.0
+     */
+    public default boolean isEager() {
+        // `default` to avoid breaking older `Bean` implementations
+        return false;
+    }
+
 }

api/src/main/java/jakarta/enterprise/inject/spi/BeanManager.java

@@ -319,7 +319,8 @@ public interface BeanManager extends BeanContainer {
      *
      * @param <T> the type
      * @param attributes a {@link BeanAttributes} which determines the bean types, qualifiers, scope, name and stereotypes of
-     *        the returned {@link Bean}, and the return value of {@link Bean#isAlternative()} and {@link Bean#isReserve()}
+     *        the returned {@link Bean}, and the return value of {@link Bean#isAlternative()}, {@link Bean#isReserve()},
+     *        and {@link Bean#isEager()}
      * @param beanClass a class, which determines the return value of {@link Bean#getBeanClass()}
      * @param injectionTargetFactory an {@link InjectionTargetFactory}, used to obtain an {@link InjectionTarget}
      * @return a container provided implementation of {@link Bean}
@@ -343,7 +344,8 @@ public <T> Bean<T> createBean(BeanAttributes<T> attributes, Class<T> beanClass,
      * @param <T> the type
      * @param <X> the type of the declaring bean
      * @param attributes a {@link BeanAttributes} which determines the bean types, qualifiers, scope, name and stereotypes of
-     *        the returned {@link Bean}, and the return value of {@link Bean#isAlternative()} and {@link Bean#isReserve()}
+     *        the returned {@link Bean}, and the return value of {@link Bean#isAlternative()}, {@link Bean#isReserve()},
+     *        and {@link Bean#isEager()}
      * @param beanClass a class, which determines the return value of <code>Bean.getClass()</code>
      * @param producerFactory a {@link ProducerFactory}, used to obtain a {@link Producer}
      * @return a container provided implementation of {@link Bean}

api/src/main/java/jakarta/enterprise/inject/spi/configurator/BeanAttributesConfigurator.java

@@ -190,7 +190,18 @@ public interface BeanAttributesConfigurator<T> {
      *
      * @param value value for reserve property
      * @return self
+     * @since 5.0
      */
     BeanAttributesConfigurator<T> reserve(boolean value);
 
+    /**
+     * Change the eagerly initialized status of the configured bean.
+     * By default, the configured bean is not eagerly initialized.
+     *
+     * @param value value for eagerly initialized property
+     * @return self
+     * @since 5.0
+     */
+    BeanAttributesConfigurator<T> eager(boolean value);
+
 }

api/src/main/java/jakarta/enterprise/inject/spi/configurator/BeanConfigurator.java

@@ -310,7 +310,7 @@ public interface BeanConfigurator<T> {
 
     /**
      * Change the alternative status of the configured bean.
-     * By default the configured bean is not an alternative.
+     * By default, the configured bean is not an alternative.
      *
      * @param value value for alternative property
      * @return self
@@ -319,10 +319,11 @@ public interface BeanConfigurator<T> {
 
     /**
      * Change the reserve status of the configured bean.
-     * By default the configured bean is not a reserve.
+     * By default, the configured bean is not a reserve.
      *
      * @param value value for reserve property
      * @return self
+     * @since 5.0
      */
     BeanConfigurator<T> reserve(boolean value);
 
@@ -342,4 +343,14 @@ public interface BeanConfigurator<T> {
      */
     BeanConfigurator<T> priority(int priority);
 
+    /**
+     * Change the eagerly initialized status of the configured bean.
+     * By default, the configured bean is not eagerly initialized.
+     *
+     * @param value value for eagerly initialized property
+     * @return self
+     * @since 5.0
+     */
+    BeanConfigurator<T> eager(boolean value);
+
 }

spec/src/main/asciidoc/core/definition.asciidoc

@@ -752,6 +752,20 @@ If a reserve managed bean declares an alternative producer, the container automa
 
 If an interceptor is a reserve, non-portable behavior results.
 
+[[eager_initialization]]
+
+=== Eager initialization
+
+A bean class of a managed bean, a producer method and a producer field may be annotated `@Eager`.
+This annotation marks the bean as _eagerly initialized_.
+
+Contextual instance of an eagerly initialized bean is created no later than at the moment the container fires <<startup_event, the `Startup` event>>.
+For example, it is as if an enabled bean existed that declared a synchronous observer with observed event type of `Startup`, no observed event qualifier, priority of `Integer.MIN_VALUE`, and this observer method obtained a contextual instance of the eagerly initialized bean.
+
+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.
+
 [[stereotypes]]
 
 === Stereotypes
@@ -769,7 +783,8 @@ A stereotype may also specify that:
 * all beans with the stereotype have defaulted bean names, or that
 * all beans with the stereotype are alternatives, or that
 * all beans with the stereotype have predefined `@Priority`, or that
-* all beans with the stereotype are reserves.
+* all beans with the stereotype are reserves, or that
+* all beans with the stereotype are eagerly initialized.
 
 A bean may declare zero, one or multiple stereotypes.
 
@@ -917,6 +932,26 @@ public @interface DefaultImpl {}
 
 If a stereotype declares both `@Alternative` and `@Reserve`, the container automatically detects the problem and treats it as a definition error.
 
+[[eager_init_stereotype]]
+
+===== Declaring an `@Eager` stereotype
+
+A stereotype may declare an `@Eager` annotation, which specifies that every bean with the stereotype is eagerly initialized.
+
+We may specify that all beans annotated with `@InitOnStartup` are `@ApplicationScoped` and eagerly initialized:
+
+[source, java]
+----
+@ApplicationScoped
+@Eager
+@Stereotype
+@Target(TYPE)
+@Retention(RUNTIME)
+public @interface InitOnStartup {}
+----
+
+If a stereotype declares both `@Eager` and a default scope for which eager initialization is not permitted (see <<eager_initialization>>), the container automatically detects the problem and treats it as a definition error.
+
 [[stereotypes_with_additional_stereotypes]]
 
 ===== Stereotypes with additional stereotypes

spec/src/main/asciidoc/core/injectionandresolution.asciidoc

@@ -835,6 +835,7 @@ The following built-in annotations define a `Literal` static nested class to sup
 * `jakarta.enterprise.inject.Specializes`
 * `jakarta.enterprise.inject.Vetoed`
 * `jakarta.enterprise.util.Nonbinding`
+* `jakarta.enterprise.context.Eager`
 * `jakarta.enterprise.context.Initialized`
 * `jakarta.enterprise.context.Destroyed`
 * `jakarta.enterprise.context.RequestScoped`

spec/src/main/asciidoc/core/spi_full.asciidoc

@@ -35,12 +35,14 @@ public interface BeanAttributes<T> {
     public Set<Class<? extends Annotation>> getStereotypes();
     public boolean isAlternative();
     public boolean isReserve();
+    public boolean isEager();
 }
 ----
 
 * `getTypes()`, `getQualifiers()`, `getScope()`, `getName()` and `getStereotypes()` must return the bean types, qualifiers, scope type, bean name and stereotypes of the bean, as defined in <<concepts>>.
 * `isAlternative()` must return `true` if the bean is an alternative, and `false` otherwise.
 * `isReserve()` must return `true` if the bean is a reserve, and `false` otherwise.
+* `isEager()` must return `true` if the bean is eagerly initialized, and `false` otherwise.
 
 The interface `jakarta.enterprise.inject.spi.Bean` defines everything the container needs to manage instances of a certain bean.
 
@@ -505,7 +507,7 @@ public BeanAttributes<?> createBeanAttributes(AnnotatedMember<?> member);
 
 The method `BeanManager.createBean()` returns a container provided implementation of `Bean`. The methods accept:
 
-* a `BeanAttributes`, which determines the bean types, qualifiers, scope, name and stereotypes of the returned `Bean`, the return values of `isAlternative()` and `isReserve()`, and
+* a `BeanAttributes`, which determines the bean types, qualifiers, scope, name and stereotypes of the returned `Bean`, the return values of `isAlternative()`, `isReserve()`, and `isEager()`, and
 * a class, which determines the return value of `Bean.getClass()`, and
 * an `InjectionTargetFactory`, which is used to obtain an `InjectionTarget`. The `InjectionTarget` is used to create and destroy instances of the bean, to perform dependency injection and lifecycle callbacks, and which determines the return value of `Bean.getInjectionPoints()`.
 
@@ -519,7 +521,7 @@ public <T> Bean<T> createBean(BeanAttributes<T> attributes, Class<T> beanClass,
 A second version of the method is provided to create a `Bean` from a producer.
 The method accepts:
 
-* a `BeanAttributes`, which determines the bean types, qualifiers, scope, name and stereotypes of the returned `Bean`, the return values of `isAlternative()` and `isReserve()`, and
+* a `BeanAttributes`, which determines the bean types, qualifiers, scope, name and stereotypes of the returned `Bean`, the return values of `isAlternative()`, `isReserve()`, and `isEager()`, and
 * a class, which determines the return value of `Bean.getClass()`, and
 * a `ProducerFactory`, which is used to obtain a `Producer`. The `Producer` is used to create and destroy instances of the bean, and which determines the return value of `Bean.getInjectionPoints()`.
 

spec/src/main/asciidoc/core/spi_lite.asciidoc

@@ -276,6 +276,7 @@ public interface BeanInfo {
     boolean isAlternative();
     boolean isReserve();
     Integer priority();
+    boolean isEager();
     String name();
     DisposerInfo disposer();
     Collection<StereotypeInfo> stereotypes();