From bfe7ce12d82b051506c3081eba7295eb860bcab8 Mon Sep 17 00:00:00 2001 From: Ladislav Thon Date: Wed, 31 May 2023 11:11:16 +0200 Subject: [PATCH] ArC: update CDI documentation with references to CDI 4.0 and CDI Lite --- docs/src/main/asciidoc/cdi-integration.adoc | 15 +++++++------ docs/src/main/asciidoc/cdi-reference.adoc | 18 ++++++++------- docs/src/main/asciidoc/cdi.adoc | 25 ++++++++++----------- 3 files changed, 30 insertions(+), 28 deletions(-) diff --git a/docs/src/main/asciidoc/cdi-integration.adoc b/docs/src/main/asciidoc/cdi-integration.adoc index b8730640860ca..cbd46b0c8f643 100644 --- a/docs/src/main/asciidoc/cdi-integration.adoc +++ b/docs/src/main/asciidoc/cdi-integration.adoc @@ -10,9 +10,10 @@ include::_attributes.adoc[] :numbered: :toclevels: 2 -ArC, the CDI container, is bootstrapped at build time. -The downside of this approach is that CDI Portable Extensions cannot be supported. -Nevertheless, the functionality can be achieved using the Quarkus-specific extensions API. +ArC, the CDI container in Quarkus, is bootstrapped at build time. +To integrate with the container, https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html#spi_lite[CDI Build Compatible Extensions, window="_blank"] can be used, as well as a Quarkus-specific extension API. +CDI Portable Extensions are not and cannot be supported. +This guide focuses on the Quarkus-specific extensions API. The container is bootstrapped in multiple phases. From a high level perspective these phases go as follows: @@ -90,8 +91,8 @@ NOTE: If no default scope is specified the `@Dependent` pseudo-scope is used. === _Reason 2_: Class Is Discovered but Has No Bean Defining Annotation -In Quarkus, the application is represented by a single bean archive with the https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html#default_bean_discovery[bean discovery mode `annotated`, window="_blank"]. -Therefore, bean classes that don't have a https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html#bean_defining_annotations[bean defining annotation, window="_blank"] are ignored. +In Quarkus, the application is represented by a single bean archive with the https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html#default_bean_discovery[bean discovery mode `annotated`, window="_blank"]. +Therefore, bean classes that don't have a https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html#bean_defining_annotations[bean defining annotation, window="_blank"] are ignored. Bean defining annotations are declared on the class-level and include scopes, stereotypes and `@Interceptor`. _Solution 1_: Use the `AutoAddScopeBuildItem`. This build item can be used to add a scope to a class that meets certain conditions. @@ -160,7 +161,7 @@ _Solution_: Use the `AdditionalBeanBuildItem` as described in <> and <>. TIP: If you're new to CDI then we recommend you to read the xref:cdi.adoc[Introduction to CDI] first. @@ -25,7 +25,7 @@ NOTE: Most of the existing CDI code should work just fine but there are some sma Bean discovery in CDI is a complex process which involves legacy deployment structures and accessibility requirements of the underlying module architecture. However, Quarkus is using a *simplified bean discovery*. -There is only single bean archive with the https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html#default_bean_discovery[bean discovery mode `annotated`, window="_blank"] and no visibility boundaries. +There is only single bean archive with the https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html#default_bean_discovery[bean discovery mode `annotated`, window="_blank"] and no visibility boundaries. The bean archive is synthesized from: @@ -35,7 +35,7 @@ The bean archive is synthesized from: * dependencies referenced by `quarkus.index-dependency` in `application.properties`, * and Quarkus integration code. -Bean classes that don't have a https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html#bean_defining_annotations[bean defining annotation, window="_blank"] are not discovered. +Bean classes that don't have a https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html#bean_defining_annotations[bean defining annotation, window="_blank"] are not discovered. This behavior is defined by CDI. But producer methods and fields and observer methods are discovered even if the declaring class is not annotated with a bean defining annotation (this behavior is different to what is defined in CDI). In fact, the declaring bean classes are considered annotated with `@Dependent`. @@ -222,15 +222,17 @@ public class CounterBean { ** Interceptors for lifecycle event callbacks: `@PostConstruct`, `@PreDestroy`, `@AroundConstruct` * Decorators * Events and observer methods, including asynchronous events and transactional observer methods +* Build Compatible Extensions +* `BeanContainer` [[limitations]] == Limitations * `@ConversationScoped` is not supported * Portable Extensions are not supported -* `BeanManager` - only the following methods are implemented: `getBeans()`, `createCreationalContext()`, `getReference()`, `getInjectableReference()` , `resolve()`, `getContext()`, `fireEvent()`, `getEvent()` and `createInstance()` +* `BeanManager`: in addition to the `BeanContainer` methods, only the following methods are supported: `getInjectableReference()`, `resolveDecorators()` * Specialization is not supported -* `beans.xml` descriptor content is ignored +* `beans.xml` descriptor content is ignored, except for the `bean-discovery-mode` attribute * Passivation and passivating scopes are not supported * Interceptor methods on superclasses are not implemented yet * `@Interceptors` is not supported @@ -1089,7 +1091,7 @@ Simply set the `quarkus.arc.dev-mode.monitoring-enabled` configuration property By default, ArC does not perform all validations required by the CDI specification. It also improves CDI usability in many ways, some of them being directly against the specification. -To be able to eventually pass the CDI Lite TCK, ArC also has a _strict_ mode. +To pass the CDI Lite TCK, ArC also has a _strict_ mode. This mode enables additional validations and disables certain improvements that conflict with the specification. To enable the strict mode, use the following configuration: @@ -1104,7 +1106,7 @@ Some other features affect specification compatibility as well: * <> * <> -To get a behavior closer to the specification, these features should also be disabled. +To get a behavior closer to the specification, these features should be disabled. Applications are recommended to use the default, non-strict mode, which makes CDI more convenient to use. The "strictness" of the strict mode (the set of additional validations and the set of disabled improvements on top of the CDI specification) may change over time. diff --git a/docs/src/main/asciidoc/cdi.adoc b/docs/src/main/asciidoc/cdi.adoc index d7ee40ad58124..f7fc301f48c72 100644 --- a/docs/src/main/asciidoc/cdi.adoc +++ b/docs/src/main/asciidoc/cdi.adoc @@ -6,12 +6,12 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Introduction to Contexts and Dependency Injection (CDI) include::_attributes.adoc[] :categories: core -:summary: Quarkus DI solution is based on the [Contexts and Dependency Injection for Java 2.0](https://docs.jboss.org/cdi/spec/2.0/cdi-spec) specification. This guide explains the basics of CDI. +:summary: Quarkus DI solution is based on the [Jakarta Contexts and Dependency Injection 4.0](https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html) specification. This guide explains the basics of CDI. :numbered: :sectnums: :sectnumlevels: 4 -In this guide we're going to describe the basic principles of the Quarkus programming model that is based on the https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html[Contexts and Dependency Injection for Java 2.0, window="_blank"] specification. +In this guide we're going to describe the basic principles of the Quarkus programming model that is based on the https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html[Jakarta Contexts and Dependency Injection 4.0, window="_blank"] specification. == OK. Let's start simple. What is a bean? @@ -101,7 +101,7 @@ public class Translator { == Can I use setter and constructor injection? Yes, you can. -In fact, in CDI the "setter injection" is superseded by more powerful https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html#initializer_methods[initializer methods, window="_blank"]. +In fact, in CDI the "setter injection" is superseded by more powerful https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html#initializer_methods[initializer methods, window="_blank"]. Initializers may accept multiple parameters and don't have to follow the JavaBean naming conventions. .Initialized and Constructor Injection Example @@ -131,7 +131,7 @@ It's also not necessary to add `@Inject` if there is only one constructor presen == You talked about some qualifiers? -https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html#qualifiers[Qualifiers, window="_blank"] are annotations that help the container to distinguish beans that implement the same type. +https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html#qualifiers[Qualifiers, window="_blank"] are annotations that help the container to distinguish beans that implement the same type. As we already said a bean is assignable to an injection point if it has all the required qualifiers. If you declare no qualifier at an injection point the `@Default` qualifier is assumed. @@ -160,7 +160,7 @@ public class SuperiorTranslator extends Translator { } } ---- -<1> `@Superior` is a https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html#defining_qualifier_types[qualifier annotation, window="_blank"]. +<1> `@Superior` is a https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html#defining_qualifier_types[qualifier annotation, window="_blank"]. This bean would be assignable to `@Inject @Superior Translator` and `@Inject @Superior SuperiorTranslator` but not to `@Inject Translator`. The reason is that `@Inject Translator` is automatically transformed to `@Inject @Default Translator` during typesafe resolution. @@ -213,7 +213,7 @@ Therefore, we recommend to stick with `@ApplicationScoped` by default unless the [[client_proxies]] == I don't understand the concept of client proxies. -Indeed, the https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html#client_proxies[client proxies, window="_blank"] could be hard to grasp, but they provide some useful functionality. +Indeed, the https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html#client_proxies[client proxies, window="_blank"] could be hard to grasp, but they provide some useful functionality. A client proxy is basically an object that delegates all method invocations to a target bean instance. It's a container construct that implements `io.quarkus.arc.ClientProxy` and extends the bean class. @@ -241,7 +241,7 @@ class Translator_ClientProxy extends Translator { <1> } } ---- -<1> The `Translator_ClientProxy` instance is always injected instead of a direct reference to a https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html#contextual_instance[contextual instance, window="_blank"] of the `Translator` bean. +<1> The `Translator_ClientProxy` instance is always injected instead of a direct reference to a https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html#contextual_instance[contextual instance, window="_blank"] of the `Translator` bean. Client proxies allow for: @@ -514,11 +514,10 @@ TIP: For more info about events/observers visit https://docs.jboss.org/weld/refe == Conclusion -In this guide, we've covered some basic topics of the Quarkus programming model that is based on the https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html[Contexts and Dependency Injection for Java 2.0, window="_blank"] specification. -However, a full CDI implementation is not used under the hood. -Quarkus only implements a subset of the CDI features - see also <> and <>. -On the other hand, there are quite a few <> and <>. -We believe that our efforts will drive the innovation of the CDI specification towards the build-time oriented developer stacks in the future. +In this guide, we've covered some basic topics of the Quarkus programming model that is based on the https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html[Jakarta Contexts and Dependency Injection 4.0, window="_blank"] specification. +Quarkus implements the CDI Lite specification, but not CDI Full. +See also <> and <>. +There are also quite a few <> and <>. TIP: If you wish to learn more about Quarkus-specific features and limitations there is a Quarkus xref:cdi-reference.adoc[CDI Reference Guide]. -We also recommend you to read the https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html[CDI specification] and the https://docs.jboss.org/weld/reference/latest/en-US/html/[Weld documentation] (Weld is a CDI Reference Implementation) to get acquainted with more complex topics. +We also recommend you to read the https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html[CDI specification] and the https://docs.jboss.org/weld/reference/latest/en-US/html/[Weld documentation] (Weld is a CDI Reference Implementation) to get acquainted with more complex topics.