Merge pull request quarkusio#36380 from mkouba/static-init-config-validation-docs

Config: docs for config value mismatch detection

Author: mkouba

core/runtime/src/main/java/io/quarkus/runtime/annotations/StaticInitSafe.java

@@ -9,8 +9,6 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import org.eclipse.microprofile.config.inject.ConfigProperty;
-
 /**
  * Used to mark a configuration object as safe to be initialized during the STATIC INIT phase.
  * <p>

docs/src/main/asciidoc/config-reference.adoc

@@ -706,6 +706,68 @@ options exposed by a `org.eclipse.microprofile.config.Config` instance. Which me
 build configuration options since MicroProfile Config specification allows configuration sources not to expose all the property names they provide to users.
 ====
 
+== Config property values injected during static intialization phase
+
+Quarkus collects the config property values injected in CDI beans during xref:writing-extensions.adoc#bootstrap-three-phases[static intialization phase].
+The collected values are then compared with their runtime initialization counterparts and if a mismatch is detected the application startup fails.
+How can it happen?
+For example, let's have a CDI bean `org.acme.MyBean`.
+`MyBean` injects a `@ConfigProperty` of name `foo` and is initialized during the native build.
+The config property does not exist during the native build and so the default value `bar` is used.
+But later, when the application is started the property is defined with a system property: `-Dfoo=baz`.
+This would lead to inconsistent state and unexpected behavior.
+Therefore, Quarkus would fail in this situation by default.
+
+[source,java]
+----
+package org.acme;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.event.Observes;
+import jakarta.enterprise.context.Initialized;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+@ApplicationScoped
+public class MyBean {
+
+   @ConfigProperty(name = "foo", defaultValue = "bar") <1>
+   String foo;
+
+    void onInit(@Observes @Initialized(ApplicationScoped.class) Object event) { <2>
+       // this observer method is notified during STATIC_INIT...
+    }
+}
+----
+<1> The config property is injected when the bean is created and the value is fixed.
+<2> In this particular case, the observer `@Initialized(ApplicationScoped.class)` caused the initialization of the bean. However, there are other possibilities. For example, some extensions initialize components during static intialization phase.
+
+You can annotate an injected field/parameter with `@io.quarkus.runtime.annotations.StaticInitSafe` to mark the injected configuration object as safe to be initialized during the static intialization phase.
+
+[source,java]
+----
+package org.acme;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.event.Observes;
+import jakarta.enterprise.context.Initialized;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import io.quarkus.runtime.annotations.StaticInitSafe;
+
+@ApplicationScoped
+public class MyBeanNoFailure {
+
+   @StaticInitSafe <1>
+   @ConfigProperty(name = "foo", defaultValue = "bar")
+   String foo;
+
+    void onInit(@Observes @Initialized(ApplicationScoped.class) Object event) {
+       // this observer method is notified during STATIC_INIT...
+    }
+}
+----
+<1> Instructs Quarkus not to fail if a mismatch is detected.
+
+
 [[additional-information]]
 == Additional Information