Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ArC: update CDI documentation with references to CDI 4.0 and CDI Lite #33719

Merged
merged 1 commit into from
Jun 1, 2023
Merged

ArC: update CDI documentation with references to CDI 4.0 and CDI Lite #33719

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 8 additions & 7 deletions docs/src/main/asciidoc/cdi-integration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
manovotn marked this conversation as resolved.
Show resolved Hide resolved

The container is bootstrapped in multiple phases.
From a high level perspective these phases go as follows:
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -160,7 +161,7 @@ _Solution_: Use the `AdditionalBeanBuildItem` as described in <<additional_bean_
== Use Case - I Need To Transform Annotation Metadata

In some cases, it's useful to be able to modify the annotation metadata.
Quarkus provides a powerful alternative to https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html#process_annotated_type[`jakarta.enterprise.inject.spi.ProcessAnnotatedType`, window="_blank"].
Quarkus provides a powerful alternative to https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html#process_annotated_type[`jakarta.enterprise.inject.spi.ProcessAnnotatedType`, window="_blank"] and https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html#bce_enhancement[`jakarta.enterprise.inject.build.compatible.spi.Enhancement`, window="_blank"].
With an `AnnotationsTransformerBuildItem` it's possible to override the annotations that exist on bean classes.

NOTE: Keep in mind that annotation transformers must be produced _before_ the bean discovery starts.
Expand Down Expand Up @@ -279,7 +280,7 @@ void doSomethingWithNamedBeans(SynthesisFinishedBuildItem synthesisFinished, Bui
Sometimes it is practical to be able to register a _synthetic bean_.
Bean attributes of a synthetic bean are not derived from a Java class, method or field.
Instead, all the attributes are defined by an extension.
In regular CDI, this could be achieved using the https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html#after_bean_discovery[`AfterBeanDiscovery.addBean()`, window="_blank"] methods.
In regular CDI, this could be achieved using the https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html#after_bean_discovery[`AfterBeanDiscovery.addBean()`, window="_blank"] and https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0.html#bce_synthesis[`SyntheticComponents.addBean()`] methods.

_Solution_: If you need to register a synthetic bean then use the `SyntheticBeanBuildItem`.

Expand Down
18 changes: 10 additions & 8 deletions docs/src/main/asciidoc/cdi-reference.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ include::_attributes.adoc[]
:sectnumlevels: 4

Quarkus DI solution (also called ArC) 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.
It aims to implement the CDI Lite specification, with selected improvements on top.
It is not a CDI Full implementation and is not verified by the TCK yet.
It implements the CDI Lite specification, with selected improvements on top, and passes the CDI Lite TCK.
It does not implement CDI Full.
See also <<supported_features,the list of supported features>> and <<limitations,the list of limitations>>.

TIP: If you're new to CDI then we recommend you to read the xref:cdi.adoc[Introduction to CDI] first.
Expand All @@ -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:

Expand All @@ -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`.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -1104,7 +1106,7 @@ Some other features affect specification compatibility as well:
* <<unproxyable_classes_transformation,Transformation of unproxyable classes>>
* <<remove_unused_beans,Unused beans removal>>

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.
Expand Down
25 changes: 12 additions & 13 deletions docs/src/main/asciidoc/cdi.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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?

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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 <<cdi-reference.adoc#supported_features,the list of supported features>> and <<cdi-reference.adoc#limitations,the list of limitations>>.
On the other hand, there are quite a few <<cdi-reference#nonstandard_features,non-standard features>> and <<cdi-reference.adoc#build_time_apis,Quarkus-specific APIs>>.
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 <<cdi-reference.adoc#supported_features,the list of supported features>> and <<cdi-reference.adoc#limitations,the list of limitations>>.
There are also quite a few <<cdi-reference#nonstandard_features,non-standard features>> and <<cdi-reference.adoc#build_time_apis,Quarkus-specific APIs>>.

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.