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

Document SyntheticBeanBuildItem #10721

Merged
merged 2 commits into from
Jul 15, 2020
Merged

Document SyntheticBeanBuildItem #10721

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3b7ae7b
Document SyntheticBeanBuildItem
mkouba Jul 14, 2020
f12c24e
Docs - update the "Expose your components via CDI" section
mkouba Jul 15, 2020
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
37 changes: 32 additions & 5 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 @@ -721,10 +721,17 @@ NOTE: A bean registration that is a result of an `AdditionalBeanBuildItem` is re

=== Synthetic Beans

Sometimes it is very useful to register a synthetic bean, i.e. a bean that doesn't need to have a corresponding java class.
In CDI, this could be achieved using `AfterBeanDiscovery.addBean()` methods.
In Quarkus, we produce a `BeanRegistrarBuildItem` and leverage the `io.quarkus.arc.processor.BeanConfigurator` API to build a synthetic bean definition.
Sometimes it is very useful 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, the attributes are specified by an extension.
In CDI, this could be achieved using the `AfterBeanDiscovery.addBean()` methods.
In Quarkus, there are three ways to register a synthetic bean.

==== `BeanRegistrarBuildItem`

A build step can produce a `BeanRegistrarBuildItem` and leverage the `io.quarkus.arc.processor.BeanConfigurator` API to build a synthetic bean definition.

.`BeanRegistrarBuildItem` Example
[source,java]
----
@BuildStep
Expand All @@ -743,9 +750,12 @@ NOTE: The output of a `BeanConfigurator` is recorded as bytecode. Therefore ther

TIP: You can easily filter all class-based beans via the convenient `BeanStream` returned from the `RegistrationContext.beans()` method.

If an extension needs to produce other build items during the "bean registration" phase it should use the `BeanRegistrationPhaseBuildItem` instead.
==== `BeanRegistrationPhaseBuildItem`

If a build step *needs to produce other build items during the registration* it should use the `BeanRegistrationPhaseBuildItem`.
The reason is that injected objects are only valid during a `@BuildStep` method invocation.

.`BeanRegistrationPhaseBuildItem` Example
[source,java]
----
@BuildStep
Expand All @@ -757,7 +767,24 @@ void syntheticBean(BeanRegistrationPhaseBuildItem beanRegistrationPhase,
}
----

NOTE: See `BeanRegistrationPhaseBuildItem` javadoc for more information.
NOTE: See the `BeanRegistrationPhaseBuildItem` javadoc for more information.

==== `SyntheticBeanBuildItem`

Finally, a build step can produce a `SyntheticBeanBuildItem` to register a synthetic bean whose instance can be easily *produced through a <<writing-extensions.adoc#bytecode-recording,recorder>>*.
The extended `BeanConfigurator` accepts either a `io.quarkus.runtime.RuntimeValue` or a `java.util.function.Supplier`.

.`SyntheticBeanBuildItem` Example
[source,java]
----
@BuildStep
@Record(STATIC_INIT)
SyntheticBeanBuildItem syntheticBean(TestRecorder recorder) {
return SyntheticBeanBuildItem.configure(Foo.class).scope(Singleton.class)
.runtimeValue(recorder.createFoo())
.done();
}
----


=== Annotation Transformations
Expand Down