Sync documentation of main branch

Author: actions-user

_generated-doc/main/config/quarkus-all-config.adoc

@@ -19455,6 +19455,29 @@ endif::add-copy-button-to-env-var[]
 |string
 |
 
+a| [[quarkus-hibernate-orm_quarkus-hibernate-orm-database-version-check-enabled]] [.property-path]##link:#quarkus-hibernate-orm_quarkus-hibernate-orm-database-version-check-enabled[`quarkus.hibernate-orm.database.version-check.enabled`]##
+
+`quarkus.hibernate-orm."persistence-unit-name".database.version-check.enabled`
+
+[.description]
+--
+Whether Hibernate ORM should check on startup
+that the version of the database matches the version configured on the dialect
+(either the default version, or the one set through `quarkus.datasource.db-version`).
+
+This should be set to `false` if the database is not available on startup.
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_HIBERNATE_ORM_DATABASE_VERSION_CHECK_ENABLED+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_HIBERNATE_ORM_DATABASE_VERSION_CHECK_ENABLED+++`
+endif::add-copy-button-to-env-var[]
+--
+|boolean
+|``true` if the dialect was set automatically by Quarkus, `false` if it was set explicitly`
+
 
 h|[[quarkus-hibernate-orm_section_quarkus-hibernate-orm-dialect]] [.section-name.section-level0]##link:#quarkus-hibernate-orm_section_quarkus-hibernate-orm-dialect[Dialect related configuration]##
 h|Type

_generated-doc/main/config/quarkus-hibernate-orm.adoc

@@ -595,6 +595,29 @@ endif::add-copy-button-to-env-var[]
 |string
 |
 
+a| [[quarkus-hibernate-orm_quarkus-hibernate-orm-database-version-check-enabled]] [.property-path]##link:#quarkus-hibernate-orm_quarkus-hibernate-orm-database-version-check-enabled[`quarkus.hibernate-orm.database.version-check.enabled`]##
+
+`quarkus.hibernate-orm."persistence-unit-name".database.version-check.enabled`
+
+[.description]
+--
+Whether Hibernate ORM should check on startup
+that the version of the database matches the version configured on the dialect
+(either the default version, or the one set through `quarkus.datasource.db-version`).
+
+This should be set to `false` if the database is not available on startup.
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_HIBERNATE_ORM_DATABASE_VERSION_CHECK_ENABLED+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_HIBERNATE_ORM_DATABASE_VERSION_CHECK_ENABLED+++`
+endif::add-copy-button-to-env-var[]
+--
+|boolean
+|``true` if the dialect was set automatically by Quarkus, `false` if it was set explicitly`
+
 
 h|[[quarkus-hibernate-orm_section_quarkus-hibernate-orm-dialect]] [.section-name.section-level0]##link:#quarkus-hibernate-orm_section_quarkus-hibernate-orm-dialect[Dialect related configuration]##
 h|Type

_generated-doc/main/config/quarkus-hibernate-orm_quarkus.hibernate-orm.adoc

@@ -595,6 +595,29 @@ endif::add-copy-button-to-env-var[]
 |string
 |
 
+a| [[quarkus-hibernate-orm_quarkus-hibernate-orm-database-version-check-enabled]] [.property-path]##link:#quarkus-hibernate-orm_quarkus-hibernate-orm-database-version-check-enabled[`quarkus.hibernate-orm.database.version-check.enabled`]##
+
+`quarkus.hibernate-orm."persistence-unit-name".database.version-check.enabled`
+
+[.description]
+--
+Whether Hibernate ORM should check on startup
+that the version of the database matches the version configured on the dialect
+(either the default version, or the one set through `quarkus.datasource.db-version`).
+
+This should be set to `false` if the database is not available on startup.
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_HIBERNATE_ORM_DATABASE_VERSION_CHECK_ENABLED+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_HIBERNATE_ORM_DATABASE_VERSION_CHECK_ENABLED+++`
+endif::add-copy-button-to-env-var[]
+--
+|boolean
+|``true` if the dialect was set automatically by Quarkus, `false` if it was set explicitly`
+
 
 h|[[quarkus-hibernate-orm_section_quarkus-hibernate-orm-dialect]] [.section-name.section-level0]##link:#quarkus-hibernate-orm_section_quarkus-hibernate-orm-dialect[Dialect related configuration]##
 h|Type

_versions/main/guides/cdi-integration.adoc

@@ -419,6 +419,73 @@ public class TestRecorder {
 ----
 <1> Pass a contextual reference of `Bar` to the constructor of `Foo`.
 
+=== Inactive Synthetic Beans
+
+In the case when one needs to register multiple synthetic beans at build time but only wants a subset of them active at runtime, it is useful to be able to mark a synthetic bean as _inactive_.
+This is done by configuring a "check active" procedure, which should be a `Supplier<ActiveResult>` obtained from a recorder:
+
+.Inactive Synthetic Bean - Build Step Example
+[source,java]
+----
+@BuildStep
+@Record(RUNTIME_INIT)
+SyntheticBeanBuildItem syntheticBean(TestRecorder recorder) {
+    return SyntheticBeanBuildItem.configure(Foo.class)
+            .scope(Singleton.class)
+            .startup() // <1>
+            .checkActive(recorder.isFooActive()) // <2>
+            .createWith(recorder.createFoo())
+            .done();
+}
+----
+<1> A bean that might be inactive is typically initialized eagerly, to make sure that an error is thrown at application startup.
+    If the bean is in fact inactive, but is not injected into an always-active bean, eager initialization is skipped and no error is thrown.
+<2> Configures the "check active" procedure.
+
+.Inactive Synthetic Bean - Recorder Example
+[source,java]
+----
+@Recorder
+public class TestRecorder {
+    public Supplier<ActiveResult> isFooActive() {
+        return () -> {
+            if (... should not be active ...) { // <1>
+                return ActiveResult.inactive("explanation"); // <2>
+            }
+            return ActiveResult.active();
+        };
+    }
+
+    public Function<SyntheticCreationalContext<Foo>, Foo> createFoo() {
+        return (context) -> {
+            return new Foo();
+        };
+    }
+}
+----
+<1> The condition when the synthetic bean should be inactive.
+<2> Proper explanation of why the bean is inactive.
+    Another inactive `ActiveResult` may also be provided as a cause, if this bean's inactivity stems from another bean's inactivity.
+
+If an inactive bean is injected somewhere, or is dynamically looked up, an `InactiveBeanException` is thrown.
+The error message contains the reason (from the `ActiveResult`), the cause chain (also from the `ActiveResult`), and possibly also a list of all injection points that resolve to this bean.
+
+If you want to handle the inactive case gracefully, you should always inject possibly inactive beans using `Instance<>`.
+You also need to check before obtaining the actual instance:
+
+[source,java]
+----
+import io.quarkus.arc.InjectableInstance;
+
+@Inject
+InjectableInstance<Foo> foo;
+
+if (foo.getHandle().getBean().isActive()) {
+    Foo foo = foo.get();
+    ...
+}
+----
+
 [[synthetic_observers]]
 == Use Case - Synthetic Observers
 

_versions/main/guides/hibernate-orm.adoc

@@ -205,11 +205,20 @@ or implicitly set by the Quarkus build process to a minimum supported version of
 Quarkus will try to check this preconfigured version against the actual database version on startup,
 leading to a startup failure when the actual version is lower.
 
-This is because Hibernate ORM may generate SQL that is invalid
-for versions of the database older than what is configured,
-which would lead to runtime exceptions.
+This is a safeguard: for versions of the database older than what is configured,
+Hibernate ORM may generate SQL that is invalid which would lead to runtime exceptions.
 
+// TODO disable the check by default when offline startup is opted in
+//   See https://github.com/quarkusio/quarkus/issues/13522
 If the database cannot be reached, a warning will be logged but startup will proceed.
+You can optionally disable the version check if you know the database won't be reachable on startup
+using <<quarkus-hibernate-orm_quarkus-hibernate-orm-database-version-check-enabled,`quarkus.hibernate-orm.database.version-check.enabled=false`>>.
+
+// TODO change the default to "always enabled" when we solve version detection problems
+//   See https://github.com/quarkusio/quarkus/issues/43703
+//   See https://github.com/quarkusio/quarkus/issues/42255
+The version check is disabled by default when a dialect is set explicitly,
+as a workaround for https://github.com/quarkusio/quarkus/issues/42255[#42255]/link:https://github.com/quarkusio/quarkus/issues/43703[#43703].
 ====
 
 [[hibernate-dialect-other-databases]]

_versions/main/guides/qute-reference.adoc

@@ -1710,15 +1710,31 @@ A CDI bean annotated with `@Named` can be referenced in any template through `cd
 NOTE: `@Named @Dependent` beans are shared across all expressions in a template for a single rendering operation, and destroyed after the rendering finished.
 
 All expressions with `cdi` and `inject` namespaces are validated during build.
-
 For the expression `cdi:personService.findPerson(10).name`, the implementation class of the injected bean must either declare the `findPerson` method or a matching <<template_extension_methods,template extension method>> must exist.
-
 For the expression `inject:foo.price`, the implementation class of the injected bean must either have the `price` property (e.g. a `getPrice()` method) or a matching <<template_extension_methods,template extension method>> must exist.
 
 NOTE: A `ValueResolver` is also generated for all beans annotated with `@Named` so that it's possible to access its properties without reflection.
 
 TIP: If your application serves xref:http-reference.adoc[HTTP requests] you can also inject the current `io.vertx.core.http.HttpServerRequest` via the `inject` namespace, e.g. `{inject:vertxRequest.getParam('foo')}`.
 
+Sometimes it may be necessary to access public methods and properties of a CDI bean that is not annotated with `@Named`.
+However, if you don't control the source of the bean it is not possible to add the `@Named` annotation.
+Nevertheless, it is possible to create an intermediate CDI bean annotated with `@Named`.
+This intermediate bean can inject the bean in question and make it accessible. 
+A Java record is a very convenient way to define such an intermediate CDI bean.
+
+[source,java]
+----
+@Named <1> <2>
+public record UserData(UserInfo info, @LoggedIn String username) { <3>
+}
+----
+<1> If no name is explicitly specified by the `value` member the https://jakarta.ee/specifications/cdi/4.1/jakarta-cdi-spec-4.1#default_name[default name is assigned] - the simple name of the bean class, after converting the first character to lower case. In this particular case, the default name is `userData`.
+<2> The `@Singleton` scope is added automatically.
+<3> All parameters of the canonical constructor are injection points. The accessor methods can be used to obtain the injected bean.
+
+And then in a template you can simply use `{cdi:userData.info}` or `{cdi:userData.username}`.
+
 [[typesafe_expressions]]
 === Type-safe Expressions
 

_versions/main/guides/rest-client.adoc

@@ -337,6 +337,89 @@ Furthermore, the client can also send arbitrarily large files if one of the foll
 * `File`
 * `Path`
 
+=== Getting other response properties
+
+==== Using RestResponse
+
+If you need to get more properties of the HTTP response than just the body, such as the status code
+or headers, you can make your method return `org.jboss.resteasy.reactive.RestResponse` from a method.
+An example of this could look like:
+
+[source,java]
+----
+package org.acme.rest.client;
+
+import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
+
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import org.jboss.resteasy.reactive.RestQuery;
+import org.jboss.resteasy.reactive.RestResponse;
+
+import java.util.Set;
+
+@Path("/extensions")
+@RegisterRestClient
+public interface ExtensionsService {
+
+    @GET
+    RestResponse<Set<Extension>> getByIdResponseProperties(@RestQuery String id);
+}
+----
+
+NOTE: You can also use the Jakarta REST type link:{jaxrsapi}/jakarta/ws/rs/core/Response.html[`Response`] but it is
+not strongly typed to your entity.
+
+== Create the Jakarta REST resource
+
+Create the `src/main/java/org/acme/rest/client/ExtensionsResource.java` file with the following content:
+
+
+[source,java]
+----
+package org.acme.rest.client;
+
+import org.eclipse.microprofile.rest.client.inject.RestClient;
+
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import java.util.Set;
+
+@Path("/extension")
+public class ExtensionsResource {
+
+    @RestClient // <1>
+    ExtensionsService extensionsService;
+
+
+    @GET
+    @Path("/id/{id}")
+    public Set<Extension> id(String id) {
+        return extensionsService.getById(id);
+    }
+
+    @GET
+    @Path("/properties")
+    public RestResponse<Set<Extension>> responseProperties(@RestQuery String id) {
+        RestResponse<Set<Extension>> clientResponse = extensionsService.getByIdResponseProperties(id); //<2>
+        String contentType = clientResponse.getHeaderString("Content-Type");
+        int status = clientResponse.getStatus();
+        String setCookie = clientResponse.getHeaderString("Set-Cookie");
+        Date lastModified = clientResponse.getLastModified();
+
+        Log.infof("content-Type: %s status: %s Last-Modified: %s Set-Cookie: %s", contentType, status, lastModified,
+                setCookie);
+
+        return RestResponse.fromResponse(clientResponse);
+    }
+}
+----
+
+There are two interesting parts in this listing:
+
+<1> the client stub is injected with the `@RestClient` annotation instead of the usual CDI `@Inject`
+<2> `org.jboss.resteasy.reactive.RestResponse` used as effective way of getting response properties via RestResponse directly from RestClient, 
+as described in <<Using RestResponse>>
 
 == Create the configuration
 
@@ -411,40 +494,6 @@ quarkus.rest-client.alpn=true
 quarkus.rest-client.extensions-api.alpn=true
 ----
 
-== Create the Jakarta REST resource
-
-Create the `src/main/java/org/acme/rest/client/ExtensionsResource.java` file with the following content:
-
-
-[source,java]
-----
-package org.acme.rest.client;
-
-import org.eclipse.microprofile.rest.client.inject.RestClient;
-
-import jakarta.ws.rs.GET;
-import jakarta.ws.rs.Path;
-import java.util.Set;
-
-@Path("/extension")
-public class ExtensionsResource {
-
-    @RestClient // <1>
-    ExtensionsService extensionsService;
-
-
-    @GET
-    @Path("/id/{id}")
-    public Set<Extension> id(String id) {
-        return extensionsService.getById(id);
-    }
-}
-----
-
-There are two interesting parts in this listing:
-
-<1> the client stub is injected with the `@RestClient` annotation instead of the usual CDI `@Inject`
-
 == Programmatic client creation with QuarkusRestClientBuilder
 
 Instead of annotating the client with `@RegisterRestClient`, and injecting