CDI Lite packaging, deployment and lifecycle specification

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

@@ -18,9 +18,10 @@
  * <li>{@link Validation @Validation}</li>
  * </ul>
  * <p>
- * Extension methods may declare arbitrary number of parameters. Which parameters may be declared depends
- * on the particular execution phase and is documented in the corresponding extension annotation.
- * All the parameters will be provided by the container when the extension method is executed.
+ * Extension methods may declare arbitrary number of parameters. In each execution phase, different types
+ * of parameters may be declared, as documented in the corresponding extension annotation. All the parameters
+ * will be provided by the container when the extension method is invoked. If an extension method declares
+ * a parameter of a type unsupported in the execution phase, the container treats it as a deployment problem.
  * <p>
  * Extension methods may be assigned a priority using {@link jakarta.annotation.Priority @Priority}.
  * Extension methods with smaller priority values are invoked first. Extension methods without specified priority

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/package-info.java

@@ -0,0 +1,13 @@
+/**
+ * <p>The build compatible extension SPI. See:</p>
+ *
+ * <ul>
+ * <li>{@link jakarta.enterprise.inject.build.compatible.spi.BuildCompatibleExtension}</li>
+ * <li>{@link jakarta.enterprise.inject.build.compatible.spi.Discovery}</li>
+ * <li>{@link jakarta.enterprise.inject.build.compatible.spi.Enhancement}</li>
+ * <li>{@link jakarta.enterprise.inject.build.compatible.spi.Registration}</li>
+ * <li>{@link jakarta.enterprise.inject.build.compatible.spi.Synthesis}</li>
+ * <li>{@link jakarta.enterprise.inject.build.compatible.spi.Validation}</li>
+ * </ul>
+ */
+package jakarta.enterprise.inject.build.compatible.spi;

spec/src/main/asciidoc/core/packagingdeployment.asciidoc

@@ -2,15 +2,16 @@
 
 == Packaging and deployment
 
-Before an application is started, or during application startup, the container must perform _bean discovery_, execute build compatible extensions, and detect definition errors and deployment problems.
+At deployment time, the container must perform _bean discovery_, execute <<spi_lite,build compatible extensions>>, and detect definition errors and deployment problems.
+The term _deployment time_ in {cdi_lite} means before the application is started, such as during application compilation, or during application startup at latest.
 
 Bean discovery is the process of determining:
 
 * Bean archives within application, and any beans contained within them
 * Which alternatives and interceptors are _enabled_
 * The _ordering_ of enabled interceptors
 
-Additional beans may be registered programmatically via <<spi_lite>>.
+Additional beans may be registered programmatically using build compatible extensions.
 
 [[bean_archive]]
 
@@ -34,8 +35,11 @@ An _implicit bean archive_ is:
 * an archive which contains a `beans.xml` file that is empty, or,
 * an archive which contains a `beans.xml` file that has `bean-discovery-mode` attribute set to `annotated`
 
-When determining which archives are bean archives, the container must consider all JAR archives available through implementation-specific means.
-Implementations are required to document how the candidate JAR archives are found.
+Any other archive which contains a `beans.xml` file is not portable in {cdi_lite}.
+More kinds of bean archives exist in {cdi_full}.
+
+When determining which archives are bean archives, the container must consider all archives that constitute the application.
+Implementations are encouraged to document how the candidate archives are found in more detail.
 
 The `beans.xml` file must be named:
 
@@ -50,14 +54,27 @@ Implicit bean archives are likely to contain classes which are not deployed as b
 
 An extension may be deployed in any archive, including those that are not bean archives.
 
+[[deployment]]
+
+=== Deployment
+
+At deployment time, the container performs the following steps:
+
+* First, the container must perform type discovery, as defined in <<type_discovery_steps>>.
+  As part of that, the container must execute <<bce_discovery,`@Discovery`>> and <<bce_enhancement,`@Enhancement`>> extension methods on build compatible extensions.
+* Next, the container must perform bean discovery, as defined in <<bean_discovery_steps>>.
+  As part of that, the container must execute <<bce_registration,`@Registration`>> and <<bce_synthesis,`@Synthesis`>> extension methods on build compatible extensions.
+* Finally, the container must detect deployment problems by validating bean dependencies.
+  As part of that, the container must execute <<bce_validation,`@Validation`>> extension methods on build compatible extensions.
+
+At any step, the container must abort deployment if any definition errors or deployment problems exist, as defined in <<exceptions>>.
+
 [[initialization]]
 
 === Application initialization lifecycle
 
-// TODO related to https://github.com/eclipse-ee4j/cdi/issues/482
-// also related to https://github.com/eclipse-ee4j/cdi/issues/496
-// Capture init process WRT build compatible extensions + type discovery + bean discovery
-// see <<initialization>> for format that is used for CDI Full
+{cdi_lite} does not require the container to perform any other initialization during application startup.
+With deployment complete, the container begins directing requests to the application.
 
 [[shutdown]]
 
@@ -78,9 +95,9 @@ The container automatically discovers managed beans (according to the rules of <
 First the container must discover types.
 The container discovers each Java class with a bean defining annotation in an implicit bean archive.
 
-// TODO at this point, we should probably mention build compatible extensions and how you can get notified of events and change these types
-// we should mention Enhancement phase here and link to the relevant doc part
-// related to https://github.com/eclipse-ee4j/cdi/issues/483
+The container must also execute `@Discovery` extension methods on build compatible extensions and discover all classes added using the `ScannedClasses` API.
+
+When all types are discovered, the container must execute `@Enhancement` extension methods on build compatible extensions and alter its metadata representation of discovered types accordingly.
 
 [[bean_discovery_steps]]
 
@@ -91,24 +108,19 @@ For every type in the set of discovered types (as defined in <<type_discovery_st
 * inspect the type metadata to determine if it is a bean, and then
 * detect definition errors by validating the class and its metadata, and then
 * determine which alternatives and interceptors are enabled, according to the rules defined in <<enablement>>.
-// TODO mention any events we fire for build compatible extensions at this point - Processing
-// e.g. if we have an equivalent of ProcessBeanAttributes and/or ProcessBean
-// related to https://github.com/eclipse-ee4j/cdi/issues/483
 
-For each enabled bean, the container must search the class for producer methods and fields, as defined in <<producer_method>> and in <<producer_field>>, including resources, and for each producer:
-
-// TODO mention any events we fire for build compatible extensions at this point - Processing
-// e.g. if we have an equivalent of ProcessInjectionPoint and/or ProcessProducer and/or ProcessBeanAttributes and/or ProcessBean
-// related to https://github.com/eclipse-ee4j/cdi/issues/483
-
-For each enabled bean, the container must search the class for observer methods, and for each observer method:
-
-// TODO mention build compatible extension equivalent - Processing
-// e.g. if we have an equivalent of ProcessObserverMethod
-// related to https://github.com/eclipse-ee4j/cdi/issues/483
+For each enabled bean, the container must search the class for producer methods and fields, as defined in <<producer_method>> and in <<producer_field>>, including resources, and for disposer methods as defined in <<disposer_method>>, and for observer methods.
 
 Then, the container registers the `Bean` and `ObserverMethod` objects:
 
 * For each enabled bean that is not an interceptor, the container registers an instance of the `Bean` interface defined in <<bean>>.
 * For each enabled interceptor, the container registers an instance of the `Interceptor` interface defined in <<interceptor>>.
 * For each observer method of every enabled bean, the container registers an instance of the `ObserverMethod` interface defined in <<observer_method>>.
+
+The container must execute all `@Registration` extension methods on build compatible extensions for each registered bean, interceptor, and observer method.
+
+Next, the container must execute all `@Synthesis` extension methods on build compatible extensions.
+For each registered synthetic bean, the container registers an instance of the `Bean` interface.
+For each registered synthetic observer, the container registers an instance of the `ObserverMethod` interface.
+
+Finally, the container must execute all `@Registration` extension methods on build compatible extensions for each synthetic bean and synthetic observer method.

spec/src/main/asciidoc/core/packagingdeployment_full.asciidoc

@@ -3,7 +3,8 @@
 == Packaging and deployment in {cdi_full}
 
 This chapter replaces <<packaging_deployment>> for the purpose of {cdi_full}.
-In case of overlap, the <<packaging_deployment>> chapter should be considered merely informative.
+The <<packaging_deployment>> chapter should be considered merely informative.
+In {cdi_full}, the term _deployment time_ always means during application startup.
 
 When an application is started, the container must perform _bean discovery_, detect definition errors and deployment problems and raise events that allow portable extensions to integrate with the deployment lifecycle.
 
@@ -108,7 +109,7 @@ First the container must discover types.
 The container discovers:
 
 * each Java class, interface (excluding the special kind of interface declaration _annotation type_) or enum deployed in an explicit bean archive, and
-* each Java class with a bean defining annotation in an implicit bean archive.
+* each Java class with a bean defining annotation in an implicit bean archive,
 
 that is not excluded from discovery by an _exclude filter_ as defined in <<exclude_filters>>.
 

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

@@ -884,6 +884,10 @@ Lifecycle events described below can be grouped into two categories:
 
 Note that the chronological order of these events is specified in <<initialization_full>>.
 
+As these lifecycle events are fired, the container must also execute <<spi_lite,build compatible extensions>>.
+Which phase of build compatible extensions should be executed when is indicated in the description of the corresponding lifecycle events.
+Build compatible extensions annotated `@SkipIfPortableExtensionPresent` must be ignored in {cdi_full}, if given portable extension is present.
+
 [[before_bean_discovery]]
 
 ==== `BeforeBeanDiscovery` event
@@ -928,6 +932,7 @@ If any observer method of the `BeforeBeanDiscovery` event throws an exception, t
 
 If any `BeforeBeanDiscovery` method is called outside of the observer method invocation, an `IllegalStateException` is thrown.
 
+The container must execute the `@Discovery` phase of build compatible extensions at this time.
 
 [[after_type_discovery]]
 
@@ -1026,6 +1031,7 @@ If any observer method of the `AfterBeanDiscovery` event throws an exception, th
 
 If any `AfterBeanDiscovery` method is called outside of the observer method invocation, an `IllegalStateException` is thrown.
 
+The container must execute the `@Synthesis` phase of build compatible extensions at this time.
 
 [[bean_configurator]]
 
@@ -1096,6 +1102,8 @@ If any `AfterDeploymentValidation` method is called outside of the observer meth
 
 The container must not allow any request to be processed by the deployment until all observers of this event return.
 
+The container must execute the `@Validation` phase of build compatible extensions at this time.
+
 [[before_shutdown]]
 
 ==== `BeforeShutdown` event
@@ -1175,6 +1183,8 @@ If any observer method of a `ProcessAnnotatedType` event throws an exception, th
 
 If any `ProcessAnnotatedType` method is called outside of the observer method invocation, an `IllegalStateException` is thrown.
 
+The container must execute the `@Enhancement` phase of build compatible extensions at this time.
+
 [[process_injection_point]]
 
 ==== `ProcessInjectionPoint` event
@@ -1397,6 +1407,8 @@ If any observer method of a `ProcessBean` event throws an exception, the excepti
 
 If any `ProcessBean` method is called outside of the observer method invocation, an `IllegalStateException` is thrown.
 
+The container must execute the bean-related part of `@Registration` phase of build compatible extensions at this time.
+
 [[process_producer]]
 
 ==== `ProcessProducer` event
@@ -1497,6 +1509,8 @@ If any observer method of a `ProcessObserverMethod` event throws an exception, t
 
 If any `ProcessObserverMethod` method is called outside of the observer method invocation, an `IllegalStateException` is thrown.
 
+The container must execute the observer-related part of `@Registration` phase of build compatible extensions at this time.
+
 [[configurators]]
 
 === Configurators interfaces