From 393de6138051da55185c7a7048102e835ad5aa5b Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Tue, 13 Jun 2023 01:59:15 +0000 Subject: [PATCH] Sync documentation of main branch --- _data/versioned/main/index/quarkus.yaml | 40 +++++++------- .../main/config/quarkus-all-build-items.adoc | 3 + .../guides/_includes/devtools/create-app.adoc | 2 +- _versions/main/guides/kubernetes-client.adoc | 43 +++++++++++++++ .../main/guides/reactive-sql-clients.adoc | 55 +++++++++++++++++++ 5 files changed, 122 insertions(+), 21 deletions(-) diff --git a/_data/versioned/main/index/quarkus.yaml b/_data/versioned/main/index/quarkus.yaml index 3e37f18b4c0..6a5665d942f 100644 --- a/_data/versioned/main/index/quarkus.yaml +++ b/_data/versioned/main/index/quarkus.yaml @@ -5,7 +5,7 @@ types: - title: Authorization of web endpoints filename: security-authorize-web-endpoints-reference.adoc summary: Quarkus has an integrated pluggable web security layer. - categories: "web, security" + categories: "security, web" id: security-authorize-web-endpoints-reference type: reference url: /guides/security-authorize-web-endpoints-reference @@ -18,7 +18,7 @@ types: - title: Command Mode Applications filename: command-mode-reference.adoc summary: This reference guide explains how to develop command line applications with Quarkus. - categories: "command-line, core" + categories: "core, command-line" type: reference url: /guides/command-mode-reference - title: Configuration Reference Guide @@ -131,14 +131,14 @@ types: - title: Authentication mechanisms in Quarkus filename: security-authentication-mechanisms-concept.adoc summary: "The Quarkus Security framework supports multiple authentication mechanisms, which you can use to secure your applications." - categories: "web, security" + categories: "security, web" id: security-authentication-mechanisms-concept type: concepts url: /guides/security-authentication-mechanisms-concept - title: Basic authentication filename: security-basic-authentication-concept.adoc summary: HTTP Basic authentication is one of the least resource-demanding techniques that enforce access controls to web resources. - categories: "web, security" + categories: "security, web" id: security-basic-authentication-concept type: concepts url: /guides/security-basic-authentication-concept @@ -152,21 +152,21 @@ types: - title: OpenID Connect (OIDC) Bearer authentication filename: security-oidc-bearer-token-authentication-concept.adoc summary: Secure HTTP access to Jakarta REST (formerly known as JAX-RS) endpoints in your application with Bearer authentication by using the Quarkus OpenID Connect (OIDC) extension. - categories: "web, security" + categories: "security, web" id: security-oidc-bearer-token-authentication-concept type: concepts url: /guides/security-oidc-bearer-token-authentication-concept - title: OpenID Connect authorization code flow mechanism for protecting web applications filename: security-oidc-code-flow-authentication-concept.adoc summary: "To protect your web applications, you can use the authorization code flow mechanism provided by the Quarkus OpenID Connect (OIDC) extension." - categories: "web, security" + categories: "security, web" id: security-oidc-code-flow-authentication-concept type: concepts url: /guides/security-oidc-code-flow-authentication-concept - title: Proactive authentication filename: security-proactive-authentication-concept.adoc summary: Proactive authentication is enabled in Quarkus by default. - categories: "web, security" + categories: "security, web" id: security-proactive-authentication-concept type: concepts url: /guides/security-proactive-authentication-concept @@ -243,7 +243,7 @@ types: - title: Configure data sources in Quarkus filename: datasource.adoc summary: Use a unified configuration model to define datasources for Java Database Connectivity (JDBC) and Reactive drivers. - categories: "getting-started, data, reactive" + categories: "getting-started, reactive, data" id: datasources type: tutorial url: /guides/datasource @@ -276,7 +276,7 @@ types: - title: Protect a web application by using OpenID Connect (OIDC) authorization code flow filename: security-oidc-code-flow-authentication-tutorial.adoc summary: "With the Quarkus OpenID Connect (OIDC) extension, you can protect application HTTP endpoints by using the OIDC Authorization Code Flow mechanism." - categories: "web, security" + categories: "security, web" id: security-oidc-code-flow-authentication-tutorial type: tutorial url: /guides/security-oidc-code-flow-authentication-tutorial @@ -289,7 +289,7 @@ types: - title: Secure a Quarkus application with Basic authentication and Jakarta Persistence filename: security-basic-authentication-tutorial.adoc summary: Secure your Quarkus application endpoints by combining the built-in Quarkus Basic authentication with the Jakarta Persistence identity provider to enable role-based access control (RBAC). - categories: "getting-started, security" + categories: "security, getting-started" id: security-basic-authentication-tutorial type: tutorial url: /guides/security-basic-authentication-tutorial @@ -345,7 +345,7 @@ types: - title: AppCDS filename: appcds.adoc summary: This reference guide explains how to enable AppCDS with Quarkus. - categories: "cloud, core" + categories: "core, cloud" type: guide url: /guides/appcds - title: Application Data Caching @@ -484,7 +484,7 @@ types: - title: Deploying on OpenShift filename: deploying-to-openshift.adoc summary: This guide covers how to deploy a native application on OpenShift. - categories: "native, cloud" + categories: "cloud, native" id: deploy-openshift type: guide url: /guides/deploying-to-openshift @@ -751,7 +751,7 @@ types: - title: Kubernetes extension filename: deploying-to-kubernetes.adoc summary: This guide covers how to deploy a native application on Kubernetes. - categories: "native, cloud" + categories: "cloud, native" id: deploy-kubernetes type: guide url: /guides/deploying-to-kubernetes @@ -961,7 +961,7 @@ types: - title: Simplified Hibernate ORM with Panache and Kotlin filename: hibernate-orm-panache-kotlin.adoc summary: This explains the specifics of using Hibernate ORM with Panache in a Kotlin project. - categories: "data, alt-languages" + categories: "alt-languages, data" type: guide url: /guides/hibernate-orm-panache-kotlin - title: Simplified Hibernate Reactive with Panache @@ -979,13 +979,13 @@ types: - title: Simplified MongoDB with Panache and Kotlin filename: mongodb-panache-kotlin.adoc summary: This guide covers the usage of MongoDB using active records and repositories in a Kotlin project. - categories: "data, alt-languages" + categories: "alt-languages, data" type: guide url: /guides/mongodb-panache-kotlin - title: SmallRye Fault Tolerance filename: smallrye-fault-tolerance.adoc summary: This guide demonstrates how your Quarkus application can utilize the SmallRye Fault Tolerance specification through the SmallRye Fault Tolerance extension. - categories: "web, observability" + categories: "observability, web" type: guide url: /guides/smallrye-fault-tolerance - title: SmallRye GraphQL @@ -1015,14 +1015,14 @@ types: - title: Testing Your Application filename: getting-started-testing.adoc summary: "This guide covers testing in JVM mode, native mode, and injection of resources into tests" - categories: "tooling, native, core" + categories: "tooling, core, native" id: testing type: guide url: /guides/getting-started-testing - title: Tips for writing native applications filename: writing-native-applications-tips.adoc summary: This guide is a collection of tips to help you solve the problems you encounter when compiling applications to native executable. - categories: "native, core, writing-extensions" + categories: "writing-extensions, core, native" type: guide url: /guides/writing-native-applications-tips - title: Update projects to the latest version of Quarkus @@ -1158,7 +1158,7 @@ types: - title: Using SSL With Native Executables filename: native-and-ssl.adoc summary: "In this guide, we will discuss how you can get your native images to support SSL, as native images don't support it out of the box." - categories: "native, security, core" + categories: "security, core, native" type: guide url: /guides/native-and-ssl - title: Using Security with .properties File @@ -1265,7 +1265,7 @@ types: - title: Validation with Hibernate Validator filename: validation.adoc summary: This guide covers how to use Hibernate Validator/Bean Validation in your REST services. - categories: "web, data" + categories: "data, web" type: guide url: /guides/validation - title: Writing JSON REST Services diff --git a/_generated-doc/main/config/quarkus-all-build-items.adoc b/_generated-doc/main/config/quarkus-all-build-items.adoc index 733e56df084..2969281d92e 100644 --- a/_generated-doc/main/config/quarkus-all-build-items.adoc +++ b/_generated-doc/main/config/quarkus-all-build-items.adoc @@ -1375,6 +1375,9 @@ a| `Config config` :: +++No Javadoc found+++ a| https://github.com/quarkusio/quarkus/blob/main/extensions/kubernetes-client/spi/src/main/java/io/quarkus/kubernetes/client/spi/KubernetesClientCapabilityBuildItem.java[`io.quarkus.kubernetes.client.spi.KubernetesClientCapabilityBuildItem`, window="_blank"] :: +++No Javadoc found+++ a| `boolean generateRbac` :: +++No Javadoc found+++ +a| https://github.com/quarkusio/quarkus/blob/main/extensions/kubernetes-client/spi/src/main/java/io/quarkus/kubernetes/client/spi/KubernetesResourcesBuildItem.java[`io.quarkus.kubernetes.client.spi.KubernetesResourcesBuildItem`, window="_blank"] :: +++No Javadoc found+++ +a| `String[] resourceClasses` :: +++No Javadoc found+++ + |=== == Kubernetes Service Binding - SPI [%header,cols=2*] diff --git a/_versions/main/guides/_includes/devtools/create-app.adoc b/_versions/main/guides/_includes/devtools/create-app.adoc index 97bde8fc294..fe67902418d 100644 --- a/_versions/main/guides/_includes/devtools/create-app.adoc +++ b/_versions/main/guides/_includes/devtools/create-app.adoc @@ -62,7 +62,7 @@ _For more information about how to install the Quarkus CLI and use it, please re ---- mvn {quarkus-platform-groupid}:quarkus-maven-plugin:{quarkus-version}:create \ ifdef::create-app-stream[] - -DplatformVersion={create-app-stream} \ + -DplatformVersion={quarkus-version} \ endif::[] -DprojectGroupId={create-app-group-id} \ ifdef::create-app-extensions[] diff --git a/_versions/main/guides/kubernetes-client.adoc b/_versions/main/guides/kubernetes-client.adoc index 3e8074bc4d9..20e6f2df149 100644 --- a/_versions/main/guides/kubernetes-client.adoc +++ b/_versions/main/guides/kubernetes-client.adoc @@ -61,6 +61,8 @@ In dev mode and when running tests, xref:kubernetes-dev-services.adoc[Dev Servic Quarkus provides multiple integration points for influencing the Kubernetes Client provided as a CDI bean. +==== Kubernetes Client Config customization + The first integration point is the use of the `io.quarkus.kubernetes.client.KubernetesConfigCustomizer` interface. When such a bean exists, it allows for arbitrary customizations of the `io.fabric8.kubernetes.client.Config` created by Quarkus (which takes into account the `quarkus.kubernetes-client.*` properties). @@ -82,6 +84,47 @@ public class KubernetesClientProducer { } ---- +==== Kubernetes Client ObjectMapper customization + +The Fabric8 Kubernetes Client uses its own `ObjectMapper` instance for serialization and deserialization of Kubernetes resources. +This mapper is provided to the client through a `KubernetesSerialization` instance that's injected into +the `KubernetesClient` bean. + +If for some reason you must customize the default `ObjectMapper` bean provided by this extension and used by the Kubernetes Client, you can do so by declaring a bean that implements the `KubernetesClientObjectMapperCustomizer` interface. + +The following code snippet contains an example of a `KubernetesClientObjectMapperCustomizer` to set the `ObjectMapper` locale: + +[source,java] +---- +@Singleton +public static class Customizer implements KubernetesClientObjectMapperCustomizer { + @Override + public void customize(ObjectMapper objectMapper) { + objectMapper.setLocale(Locale.ROOT); + } +} +---- + +Furthermore, if you must replace the default `ObjectMapper` bean used by the Kubernetes Client that the extension creates automatically, you can do so by declaring a bean of type `@KubernetesClientObjectMapper`. +The following code snippet shows how you can declare this bean: + +[source,java] +---- +@Singleton +public class KubernetesObjectMapperProducer { + @KubernetesClientObjectMapper + @Singleton + @Produces + public ObjectMapper kubernetesClientObjectMapper() { + return new ObjectMapper(); + } +} +---- + + +WARNING: The static `io.fabric8.kubernetes.client.utils.Serialization` utils class is deprecated and should not be used. +Access to `Serialization.jsonMapper()` should be replaced by the usage of @KubernetesClientObjectMapperCustomizer` declared beans. + == Testing To make testing against a mock Kubernetes API extremely simple, Quarkus provides the `WithKubernetesTestServer` annotation which automatically launches diff --git a/_versions/main/guides/reactive-sql-clients.adoc b/_versions/main/guides/reactive-sql-clients.adoc index 0db980ae938..f85e1e5707a 100644 --- a/_versions/main/guides/reactive-sql-clients.adoc +++ b/_versions/main/guides/reactive-sql-clients.adoc @@ -698,7 +698,10 @@ A typical configuration with several connections would look like: ---- quarkus.datasource.reactive.url=postgresql://host1:5432/default,postgresql://host2:5432/default,postgresql://host3:5432/default ---- + This can also be written with indexed property syntax: + +[source,properties] ---- quarkus.datasource.reactive.url[0]=postgresql://host1:5432/default quarkus.datasource.reactive.url[1]=postgresql://host2:5432/default @@ -771,6 +774,58 @@ public class CustomPgPoolCreator implements PgPoolCreator { } ---- +== Pipelining + +The PostgreSQL and MariaDB/MySQL clients support pipelining of queries at the connection level. +The feature consists in sending multiple queries on the same database connection without waiting for the corresponding responses. + +In some use cases, query pipelining can improve database access performance. + +Here's an example for PostgreSQL: + +[source,java] +---- +import jakarta.inject.Inject; + +import io.smallrye.mutiny.Uni; +import io.vertx.mutiny.pgclient.PgPool; + +public class PipeliningExample { + + @Inject + PgPool client; + + public Uni favoriteFruitAndVegetable() { + // Explicitely acquire a connection + return client.withConnection(conn -> { + Uni favoriteFruit = conn.query("SELECT name FROM fruits WHERE preferred IS TRUE").execute() + .onItem().transform(rows -> rows.iterator().next().getString("name")); + Uni favoriteVegetable = conn.query("SELECT name FROM vegetables WHERE preferred IS TRUE").execute() + .onItem().transform(rows -> rows.iterator().next().getString("name")); + // favoriteFruit and favoriteVegetable unis will be subscribed at the same time + return Uni.combine().all().unis(favoriteFruit, favoriteVegetable) + .combinedWith(PipeliningExample::formatMessage); + }); + } + + private static String formatMessage(String fruit, String vegetable) { + return String.format("The favorite fruit is %s and the favorite vegetable is %s", fruit, vegetable); + } +} +---- + +The maximum number of pipelined queries is configured with the `pipelining-limit` property: + +[source,properties] +---- +# For PostgreSQL +quarkus.datasource.reactive.postgresql.pipelining-limit=256 +# For MariaDB/MySQL +quarkus.datasource.reactive.mysql.pipelining-limit=256 +---- + +By default, `pipelining-limit` is set to 256. + == Configuration Reference === Common Datasource