[[packaging_deployment]]

== Packaging and deployment

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 using build compatible extensions.

[[bean_archive]]

=== Bean archives

Bean classes of enabled beans must be deployed in _bean archives_.

A bean archive has a _bean discovery mode_ of either `annotated` or `none`.
This is governed by presence of `beans.xml` file which can be either empty or it can declare the `bean-discovery-mode` attribute.
Default value for this attribute is `annotated`.

An archive which:

* contains a `beans.xml` file with the `bean-discovery-mode` of `none`, or,
* contains a portable extension or a build compatible extension and no `beans.xml` file

is not a bean archive.

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`

Any other archive which contains a `beans.xml` file is not portable in {cdi_lite}.
More kinds of bean archives exist in {cdi_full}.

Implementations that do not support {cdi_full} are required to ignore the content of the `beans.xml` file, except for the `bean-discovery-mode` attribute.
Implementations that do not support {cdi_full} are required to detect presence of an archive which contains a `beans.xml` file that has `bean-discovery-mode` attribute set to `all` and treat it as a deployment problem.

To ensure portability between {cdi_lite} and {cdi_full}, applications are encouraged to:

* always add a `beans.xml` file to an archive which contains classes with bean defining annotations;
* never add classes with bean defining annotations to an archive without `beans.xml`.

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:

* `META-INF/beans.xml`.

The container searches for beans in all bean archives discovered as described above.

If a bean class is deployed in two different bean archives, non-portable behavior results.
Portable applications must deploy each bean class in no more than one bean archive.

Implicit bean archives are likely to contain classes which are not deployed as beans.

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 the <<bce_discovery,`@Discovery`>> and <<bce_enhancement,`@Enhancement`>> phases of build compatible extensions.
* Next, the container must perform bean discovery, as defined in <<bean_discovery_steps>>.
  As part of that, the container must execute the <<bce_registration,`@Registration`>> and <<bce_synthesis,`@Synthesis`>> phases of build compatible extensions.
* Finally, the container must detect deployment problems by validating bean dependencies.
  As part of that, the container must execute the <<bce_validation,`@Validation`>> phase of 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

{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]]

=== Application shutdown lifecycle

When an application is stopped, the container must destroy all contexts.

[[type_bean_discovery]]

=== Type and Bean discovery

The container automatically discovers managed beans (according to the rules of <<what_classes_are_beans>>) in bean archives and searches the bean classes for producer methods, producer fields, disposer methods and observer methods.

[[type_discovery_steps]]

==== Type discovery

First the container must discover types.
The container discovers each Java class with a bean defining annotation in an implicit bean archive.

The container must also execute the `@Discovery` phase of build compatible extensions and discover all classes added using the `ScannedClasses` API.

When all types are discovered, the container must execute the `@Enhancement` phase of build compatible extensions and alter its metadata representation of discovered types accordingly.

[[bean_discovery_steps]]

==== Bean discovery

For every type in the set of discovered types (as defined in <<type_discovery_steps>>), the container must:

* 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>>.

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 the `@Registration` phase of build compatible extensions for each registered bean, interceptor, and observer method.

Next, the container must execute the `@Synthesis` phase of 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 the `@Registration` phase of build compatible extensions for each synthetic bean and synthetic observer method.
