diff --git a/docs/src/main/asciidoc/amqp-dev-services.adoc b/docs/src/main/asciidoc/amqp-dev-services.adoc index 09ce87e511bbb..2c1bb488b362e 100644 --- a/docs/src/main/asciidoc/amqp-dev-services.adoc +++ b/docs/src/main/asciidoc/amqp-dev-services.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: messaging :summary: Start AMQP automatically in dev and test modes. +:extensions: io.quarkus:quarkus-smallrye-reactive-messaging-amqp +:topics: messaging,amqp,devservices,tooling,testing,devmode Dev Services for AMQP automatically starts an AMQP 1.0 broker in dev mode and when running tests. So, you don't have to start a broker manually. diff --git a/docs/src/main/asciidoc/amqp-reference.adoc b/docs/src/main/asciidoc/amqp-reference.adoc index 0bc1cef14800f..44aa061a1958f 100644 --- a/docs/src/main/asciidoc/amqp-reference.adoc +++ b/docs/src/main/asciidoc/amqp-reference.adoc @@ -5,6 +5,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Reactive Messaging AMQP 1.0 Connector Reference Documentation include::_attributes.adoc[] +:categories: messaging +:extensions: io.quarkus:quarkus-smallrye-reactive-messaging-amqp +:topics: messaging,amqp This guide is the companion from the xref:amqp.adoc[Getting Started with AMQP 1.0]. It explains in more details the configuration and usage of the AMQP connector for reactive messaging. diff --git a/docs/src/main/asciidoc/amqp.adoc b/docs/src/main/asciidoc/amqp.adoc index 4c4f048302b22..7aa090e3aa773 100644 --- a/docs/src/main/asciidoc/amqp.adoc +++ b/docs/src/main/asciidoc/amqp.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: messaging :summary: This guide demonstrates how your Quarkus application can utilize SmallRye Reactive Messaging to interact with AMQP. +:extensions: io.quarkus:quarkus-smallrye-reactive-messaging-amqp +:topics: messaging,amqp This guide demonstrates how your Quarkus application can utilize SmallRye Reactive Messaging to interact with AMQP 1.0. diff --git a/docs/src/main/asciidoc/ansible.adoc b/docs/src/main/asciidoc/ansible.adoc index 696d5d4bed922..a2708dec90c8d 100644 --- a/docs/src/main/asciidoc/ansible.adoc +++ b/docs/src/main/asciidoc/ansible.adoc @@ -7,6 +7,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: command-line :summary: Build and deploy your Quarkus App using Ansible +:topics: ansible,devops Let’s see how to build and deploy a Quarkus app using https://docs.ansible.com/ansible/latest/index.html[Ansible]. We’ll see how we can automate the entire process, from the code checkout to the application compilation using Maven and then its deployment and start of the service, as a https://systemd.io/[systemd service], on the target system using Ansible and its collection for Quarkus. diff --git a/docs/src/main/asciidoc/apicurio-registry-dev-services.adoc b/docs/src/main/asciidoc/apicurio-registry-dev-services.adoc index cc6020d803a17..0eb728d1d844a 100644 --- a/docs/src/main/asciidoc/apicurio-registry-dev-services.adoc +++ b/docs/src/main/asciidoc/apicurio-registry-dev-services.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: messaging :summary: Start Apicurio Registry automatically in dev and test modes. +:topics: messaging,kafka,apicurio,registry,devservices,tooling,testing,devmode +:extensions: io.quarkus:quarkus-apicurio-registry-avro,io.quarkus:quarkus-smallrye-reactive-messaging-kafka If an extension for schema registry, such as `quarkus-apicurio-registry-avro` or `quarkus-confluent-registry-avro`, is present, Dev Services for Apicurio Registry automatically starts an Apicurio Registry instance in dev mode and when running tests. Also, all Kafka channels in SmallRye Reactive Messaging are automatically configured to use this registry. diff --git a/docs/src/main/asciidoc/appcds.adoc b/docs/src/main/asciidoc/appcds.adoc index 5811801c47bb0..543d7da0c8a7d 100644 --- a/docs/src/main/asciidoc/appcds.adoc +++ b/docs/src/main/asciidoc/appcds.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: core, cloud :summary: This reference guide explains how to enable AppCDS with Quarkus. +:topics: appcds,serverless +:extensions: io.quarkus:quarkus-core This reference guide explains how to enable Application Class Data Sharing in your Quarkus applications. diff --git a/docs/src/main/asciidoc/aws-lambda-http.adoc b/docs/src/main/asciidoc/aws-lambda-http.adoc index ccddd58c3e3a8..969d448df56aa 100644 --- a/docs/src/main/asciidoc/aws-lambda-http.adoc +++ b/docs/src/main/asciidoc/aws-lambda-http.adoc @@ -9,6 +9,8 @@ include::_attributes.adoc[] :categories: cloud :summary: This guide explains how you can deploy Vert.x Web, Servlet, or RESTEasy microservices as an AWS Lambda. :devtools-no-gradle: +:topics: aws,lambda,serverless,function,cloud +:extensions: io.quarkus:quarkus-amazon-lambda,io.quarkus:quarkus-amazon-lambda-http With Quarkus you can deploy your favorite Java HTTP frameworks as AWS Lambda's using either the https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html[AWS Gateway HTTP API] or https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html[AWS Gateway REST API]. This means that you can deploy your microservices written with RESTEasy Reactive (our Jakarta REST implementation), diff --git a/docs/src/main/asciidoc/aws-lambda-snapstart.adoc b/docs/src/main/asciidoc/aws-lambda-snapstart.adoc index 735ece2efd0a0..96a05da272353 100644 --- a/docs/src/main/asciidoc/aws-lambda-snapstart.adoc +++ b/docs/src/main/asciidoc/aws-lambda-snapstart.adoc @@ -7,6 +7,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: This document explains how to optimize your AWS Lambda application for SnapStart +:topics: aws,lambda,serverless,function,snapstart,cloud https://docs.aws.amazon.com/lambda/latest/dg/snapstart.html[SnapStart] is a snapshotting and restore mechanism reducing drastically the cold startup time of Java functions on AWS. This document explains the various settings you can use to leverage this feature. diff --git a/docs/src/main/asciidoc/aws-lambda.adoc b/docs/src/main/asciidoc/aws-lambda.adoc index 9e6e70a2129f0..ec05de3639b8b 100644 --- a/docs/src/main/asciidoc/aws-lambda.adoc +++ b/docs/src/main/asciidoc/aws-lambda.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: This guide explains how you can deploy Quarkus-based AWS Lambdas. +:topics: aws,lambda,serverless,function,cloud +:extensions: io.quarkus:quarkus-amazon-lambda The `quarkus-amazon-lambda` extension allows you to use Quarkus to build your AWS Lambdas. Your lambdas can use injection annotations from CDI or Spring and other Quarkus facilities as you need them. diff --git a/docs/src/main/asciidoc/azure-functions-http.adoc b/docs/src/main/asciidoc/azure-functions-http.adoc index 4316d91605134..a02be3bfb5bd6 100644 --- a/docs/src/main/asciidoc/azure-functions-http.adoc +++ b/docs/src/main/asciidoc/azure-functions-http.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: Deploy Vert.x Web, Servlet, or RESTEasy microservices as a Microsoft Azure Function. +:topics: azure,serverless,function,cloud +:extensions: io.quarkus:quarkus-azure-functions-http The `quarkus-azure-functions-http` extension allows you to write microservices with RESTEasy Reactive (our Jakarta REST implementation), Undertow (servlet), Reactive Routes, or xref:funqy-http.adoc[Funqy HTTP] and make these microservices deployable to the Azure Functions runtime. diff --git a/docs/src/main/asciidoc/azure-functions.adoc b/docs/src/main/asciidoc/azure-functions.adoc index c58f6ece1dc8e..743c9b867e046 100644 --- a/docs/src/main/asciidoc/azure-functions.adoc +++ b/docs/src/main/asciidoc/azure-functions.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: Integrate Quarkus with the Microsoft Azure functions that you have written. +:topics: azure,serverless,function,cloud +:extensions: io.quarkus:quarkus-azure-functions The `quarkus-azure-functions` extension is a simple integration point between Azure Functions and Quarkus. It interacts with Azure Functions runtime to bootstrap quarkus and turns any diff --git a/docs/src/main/asciidoc/build-analytics.adoc b/docs/src/main/asciidoc/build-analytics.adoc index ff94a46c57488..820c2d34f868b 100644 --- a/docs/src/main/asciidoc/build-analytics.adoc +++ b/docs/src/main/asciidoc/build-analytics.adoc @@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Build analytics :categories: analytics :summary: This guide presents what build analytics is and how to configure it. +:extensions: io.quarkus:quarkus-core The Quarkus team has limited knowledge, from Maven download numbers, of the remarkable growth of Quarkus and the number of users reporting issues/concerns. Still, we need more insight into the platforms, operating system, Java combinations, and build tools our users employ. The build analytics tool aims to provide us with this information. diff --git a/docs/src/main/asciidoc/building-my-first-extension.adoc b/docs/src/main/asciidoc/building-my-first-extension.adoc index 3cc1d82011258..e3a4f2d30aeca 100644 --- a/docs/src/main/asciidoc/building-my-first-extension.adoc +++ b/docs/src/main/asciidoc/building-my-first-extension.adoc @@ -7,6 +7,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: writing-extensions :summary: Learn step by step how to build a simple extension. +:topics: extensions Quarkus extensions enhance your application just as projects dependencies do. The role of the extensions is to leverage Quarkus paradigms to integrate seamlessly a library into Quarkus architecture - e.g. do more things at build time. diff --git a/docs/src/main/asciidoc/building-native-image.adoc b/docs/src/main/asciidoc/building-native-image.adoc index b29f6bb8799e1..8a2d72bc58b3c 100644 --- a/docs/src/main/asciidoc/building-native-image.adoc +++ b/docs/src/main/asciidoc/building-native-image.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: getting-started, native :summary: Build native executables with GraalVM or Mandrel. +:topics: native,graalvm,mandrel +:extensions: io.quarkus:quarkus-core This guide covers: diff --git a/docs/src/main/asciidoc/cache-redis-reference.adoc b/docs/src/main/asciidoc/cache-redis-reference.adoc index 917c8f8cf853f..9adb78fb05047 100644 --- a/docs/src/main/asciidoc/cache-redis-reference.adoc +++ b/docs/src/main/asciidoc/cache-redis-reference.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: data :summary: Use Redis as the Quarkus cache backend +:topics: redis,cache,data +:extensions: io.quarkus:quarkus-redis-cache,io.quarkus:quarkus-redis-client By default, Quarkus Cache uses Caffeine as backend. It's possible to use Redis instead. diff --git a/docs/src/main/asciidoc/cache.adoc b/docs/src/main/asciidoc/cache.adoc index 8a871d0d47ecc..b85ea2babbf30 100644 --- a/docs/src/main/asciidoc/cache.adoc +++ b/docs/src/main/asciidoc/cache.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: data :summary: This guide explains how to cache expensive method calls of your CDI beans using simple annotations. +:topics: cache,data +:extensions: io.quarkus:quarkus-cache In this guide, you will learn how to enable application data caching in any CDI managed bean of your Quarkus application. diff --git a/docs/src/main/asciidoc/camel.adoc b/docs/src/main/asciidoc/camel.adoc index 23342f625f202..823d5d830cdce 100644 --- a/docs/src/main/asciidoc/camel.adoc +++ b/docs/src/main/asciidoc/camel.adoc @@ -7,6 +7,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: integration :summary: This guide covers the systems integration with Apache Camel +:topics: camel,integration https://camel.apache.org/[Apache Camel] is the Swiss knife of integrating heterogeneous systems with more than a decade of history and a lively community of users and developers. diff --git a/docs/src/main/asciidoc/capabilities.adoc b/docs/src/main/asciidoc/capabilities.adoc index d98bef7068689..6ef79dbf6a48f 100644 --- a/docs/src/main/asciidoc/capabilities.adoc +++ b/docs/src/main/asciidoc/capabilities.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: writing-extensions :summary: How capabilities are implemented and used in Quarkus. +:topics: extensions +:extensions: io.quarkus:quarkus-core Quarkus extensions may provide certain capabilities and require certain capabilities to be provided by other extensions in an application to function properly. @@ -146,7 +148,7 @@ quarkusExtension { NOTE: It is possible to specify `onlyIfNot` conditions as well. . Conditions can also be set for required capabilities. **** -In this case, `io.quarkus.container.image.openshift.deployment.OpenshiftBuild` should be included in one of the extension deployment dependencies and implement `java.util.function.BooleanSupplier`. At build time, the Quarkus bootstrap will create an instance of it and register `io.quarkus.container.image.openshift` capability only if its `getAsBoolean()` method returns true. +In this case, `io.quarkus.container.image.openshift.deployment.OpenshiftBuild` should be included in one of the extension deployment dependencies and implement `java.util.function.BooleanSupplier`. At build time, the Quarkus bootstrap will create an instance of it and register `io.quarkus.container.image.openshift` capability only if its `getAsBoolean()` method returns true. An implementation of the `OpenshiftBuild` could look like this: [source,java] diff --git a/docs/src/main/asciidoc/cassandra.adoc b/docs/src/main/asciidoc/cassandra.adoc index e68ada8b38153..6889ff5feb002 100644 --- a/docs/src/main/asciidoc/cassandra.adoc +++ b/docs/src/main/asciidoc/cassandra.adoc @@ -7,6 +7,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: data :summary: This guide covers how to use the Apache Cassandra NoSQL database in Quarkus. +:topics: data,cassandra Apache Cassandra® is a free and open-source, distributed, wide column store, NoSQL database management system designed to handle large amounts of data across many commodity servers, providing diff --git a/docs/src/main/asciidoc/cdi-integration.adoc b/docs/src/main/asciidoc/cdi-integration.adoc index cbd46b0c8f643..2a7b4641079b1 100644 --- a/docs/src/main/asciidoc/cdi-integration.adoc +++ b/docs/src/main/asciidoc/cdi-integration.adoc @@ -9,6 +9,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :numbered: :toclevels: 2 +:topics: cdi,arc,injection +:extensions: io.quarkus:quarkus-arc 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. @@ -19,7 +21,7 @@ The container is bootstrapped in multiple phases. From a high level perspective these phases go as follows: 1. Initialization -2. Bean discovery +2. Bean discovery 3. Registration of synthetic components 4. Validation @@ -40,7 +42,7 @@ In the following sections we will describe all the relevant build items and comm Classes and annotations are the primary source of bean-level metadata. The initial metadata are read from the _bean archive index_, an immutable https://github.com/wildfly/jandex[Jandex index, window="_blank"] which is built from various sources during <>. However, extensions can add, remove or transform the metadata at certain stages of the bootstrap. -Moreover, extensions can also register <>. +Moreover, extensions can also register <>. This is an important aspect to realize when integrating CDI components in Quarkus. This way, extensions can turn classes, that would be otherwise ignored, into beans and vice versa. @@ -57,14 +59,14 @@ There are several reasons why a class is not recognized and also several ways to In the first step we should identify the _reason_. [[additional_bean_build_item]] -=== _Reason 1_: Class Is Not discovered +=== _Reason 1_: Class Is Not discovered Quarkus has a <>. It might happen that the class is not part of the application index. For example, classes from the _runtime module_ of a Quarkus extension are not indexed automatically. -_Solution_: Use the `AdditionalBeanBuildItem`. -This build item can be used to specify one or more additional classes to be analyzed during the discovery. +_Solution_: Use the `AdditionalBeanBuildItem`. +This build item can be used to specify one or more additional classes to be analyzed during the discovery. Additional bean classes are transparently added to the application index processed by the container. IMPORTANT: It is not possible to conditionally enable/disable additional beans via the `@IfBuildProfile`, `@UnlessBuildProfile`, `@IfBuildProperty` and `@UnlessBuildProperty` annotations as described in <> and <>. Extensions should inspect the configuration or the current profile and only produce an `AdditionalBeanBuildItem` if really needed. @@ -85,7 +87,7 @@ However, you can use `AdditionalBeanBuildItem.Builder.setUnremovable()` method t See also <> and <> for more details. It is aso possible to set the default scope via `AdditionalBeanBuildItem.Builder#setDefaultScope()`. -The default scope is only used if there is no scope declared on the bean class. +The default scope is only used if there is no scope declared on the bean class. NOTE: If no default scope is specified the `@Dependent` pseudo-scope is used. @@ -127,7 +129,7 @@ However, you can change the default behavior. See also <> and <> for more details. It is also possible to specify the default scope. -The default scope is only used if there is no scope declared on the bean class. +The default scope is only used if there is no scope declared on the bean class. NOTE: If no default scope is specified the `@Dependent` pseudo-scope is used. @@ -136,7 +138,7 @@ NOTE: If no default scope is specified the `@Dependent` pseudo-scope is used. The container attempts to <> during the build by default. This optimization allows for _framework-level dead code elimination_. -In few special cases, it's not possible to correctly identify an unused bean. +In few special cases, it's not possible to correctly identify an unused bean. In particular, Quarkus is not able to detect the usage of the `CDI.current()` static method yet. Extensions can eliminate possible false positives by producing an `UnremovableBeanBuildItem`. @@ -155,7 +157,7 @@ UnremovableBeanBuildItem unremovableBeans() { It is likely that the annotation class is not part of the application index. For example, classes from the _runtime module_ of a Quarkus extension are not indexed automatically. -_Solution_: Use the `AdditionalBeanBuildItem` as described in <>. +_Solution_: Use the `AdditionalBeanBuildItem` as described in <>. [[annotations_transformer_build_item]] == Use Case - I Need To Transform Annotation Metadata @@ -297,8 +299,8 @@ SyntheticBeanBuildItem syntheticBean() { ---- <1> Generate the bytecode of the `jakarta.enterprise.context.spi.Contextual#create(CreationalContext)` implementation. -The output of a bean configurator is recorded as bytecode. -Therefore, there are some limitations in how a synthetic bean instance is created at runtime. +The output of a bean configurator is recorded as bytecode. +Therefore, there are some limitations in how a synthetic bean instance is created at runtime. You can: 1. Generate the bytecode of the `Contextual#create(CreationalContext)` method directly via `ExtendedBeanConfigurator.creator(Consumer)`. @@ -344,7 +346,7 @@ Synthetic beans initialized during `RUNTIME_INIT` must not be accessed during `S [source,java] ---- @BuildStep -@Record(RUNTIME_INIT) +@Record(RUNTIME_INIT) @Consume(SyntheticBeansRuntimeInitBuildItem.class) <1> void accessFoo(TestRecorder recorder) { recorder.foo(); <2> @@ -411,7 +413,7 @@ IMPORTANT: A build step that consumes the `ObserverRegistrationPhaseBuildItem` s ---- @BuildStep void syntheticObserver(ObserverRegistrationPhaseBuildItem observerRegistrationPhase, - BuildProducer myBuildItem, + BuildProducer myBuildItem, BuildProducer observerConfigurationRegistry) { observerConfigurationRegistry.produce(new ObserverConfiguratorBuildItem(observerRegistrationPhase.getContext() .configure() @@ -424,8 +426,8 @@ void syntheticObserver(ObserverRegistrationPhaseBuildItem observerRegistrationPh } ---- -The output of a `ObserverConfigurator` is recorded as bytecode. -Therefore, there are some limitations in how a synthetic observer is invoked at runtime. +The output of a `ObserverConfigurator` is recorded as bytecode. +Therefore, there are some limitations in how a synthetic observer is invoked at runtime. Currently, you must generate the bytecode of the method body directly. [[generated_beans]] @@ -462,7 +464,7 @@ IMPORTANT: A build step that consumes the `ValidationPhaseBuildItem` should alwa ---- @BuildStep void validate(ValidationPhaseBuildItem validationPhase, - BuildProducer myBuildItem, + BuildProducer myBuildItem, BuildProducer errors) { if (someCondition) { errors.produce(new ValidationErrorBuildItem(new IllegalStateException())); @@ -606,7 +608,7 @@ NOTE: In theory, you can use < - + io.quarkus quarkus-extension-maven-plugin @@ -148,7 +150,7 @@ Conditional dependencies can also be configured in the Quarkus extension descrip - + io.quarkus quarkus-extension-maven-plugin diff --git a/docs/src/main/asciidoc/config-extending-support.adoc b/docs/src/main/asciidoc/config-extending-support.adoc index 80a84b2fa5aec..aca5e13344863 100644 --- a/docs/src/main/asciidoc/config-extending-support.adoc +++ b/docs/src/main/asciidoc/config-extending-support.adoc @@ -10,6 +10,8 @@ include::_attributes.adoc[] :numbered: :sectnums: :sectnumlevels: 4 +:topics: configuration +:extensions: io.quarkus:quarkus-core [[custom-config-source]] == Custom `ConfigSource` diff --git a/docs/src/main/asciidoc/config-mappings.adoc b/docs/src/main/asciidoc/config-mappings.adoc index f7822cc0bd885..89d8265828c00 100644 --- a/docs/src/main/asciidoc/config-mappings.adoc +++ b/docs/src/main/asciidoc/config-mappings.adoc @@ -10,6 +10,8 @@ include::_attributes.adoc[] :numbered: :sectnums: :sectnumlevels: 4 +:topics: configuration +:extensions: io.quarkus:quarkus-core With config mappings it is possible to group multiple configuration properties in a single interface that share the same prefix. diff --git a/docs/src/main/asciidoc/config-reference.adoc b/docs/src/main/asciidoc/config-reference.adoc index 2206592c4f7a9..52db5cfdcabda 100644 --- a/docs/src/main/asciidoc/config-reference.adoc +++ b/docs/src/main/asciidoc/config-reference.adoc @@ -10,6 +10,8 @@ include::_attributes.adoc[] :numbered: :sectnums: :sectnumlevels: 4 +:topics: configuration +:extensions: io.quarkus:quarkus-core IMPORTANT: The content of this guide has been revised and split into additional topics. Please check the <> section. diff --git a/docs/src/main/asciidoc/config-yaml.adoc b/docs/src/main/asciidoc/config-yaml.adoc index 33109f1b38aaa..4755ae64e36df 100644 --- a/docs/src/main/asciidoc/config-yaml.adoc +++ b/docs/src/main/asciidoc/config-yaml.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: core :summary: YAML as a Configuration Source. +:topics: configuration +:extensions: io.quarkus:quarkus-config-yaml https://en.wikipedia.org/wiki/YAML[YAML] is a very popular format. Kubernetes relies heavily on the YAML format to write the various resource descriptors. diff --git a/docs/src/main/asciidoc/config.adoc b/docs/src/main/asciidoc/config.adoc index 8f0b64e063f97..5ff455899013c 100644 --- a/docs/src/main/asciidoc/config.adoc +++ b/docs/src/main/asciidoc/config.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: core :summary: Hardcoded values in your code is a no go (even if we all did it at some point ;-)). In this guide, we learn how to configure your application. +:topics: configuration +:extensions: io.quarkus:quarkus-core IMPORTANT: The content of this guide and been revised and split into additional topics. Please check the <> section. diff --git a/docs/src/main/asciidoc/container-image.adoc b/docs/src/main/asciidoc/container-image.adoc index 3b0e10f14b21d..953637e0a9159 100644 --- a/docs/src/main/asciidoc/container-image.adoc +++ b/docs/src/main/asciidoc/container-image.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: Learn how to build and push container images with Jib, OpenShift or Docker as part of the Quarkus build. +:topics: devops,cloud +:extensions: io.quarkus:quarkus-container-image-openshift,io.quarkus:quarkus-container-image-jib,io.quarkus:quarkus-container-image-docker,io.quarkus:quarkus-container-image-buildpack Quarkus provides extensions for building (and pushing) container images. Currently, it supports: @@ -138,7 +140,7 @@ The creation of such objects is being taken care of by the Quarkus Kubernetes ex [#buildpack] === Buildpack -The extension `quarkus-container-image-buildpack` is using buildpacks in order to perform container image builds. +The extension `quarkus-container-image-buildpack` is using buildpacks in order to perform container image builds. Under the hood buildpacks will use a Docker daemon for the actual build. While buildpacks support alternatives to Docker, this extension will only work with Docker. diff --git a/docs/src/main/asciidoc/context-propagation.adoc b/docs/src/main/asciidoc/context-propagation.adoc index d3ebafa9ceed8..deffd04652f2f 100644 --- a/docs/src/main/asciidoc/context-propagation.adoc +++ b/docs/src/main/asciidoc/context-propagation.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: core :summary: Learn more about how you can pass contextual information with SmallRye Context Propagation. +:topics: context-propagation +:extensions: io.quarkus:quarkus-core Traditional blocking code uses link:https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/ThreadLocal.html[`ThreadLocal`] variables to store contextual objects in order to avoid diff --git a/docs/src/main/asciidoc/continuous-testing.adoc b/docs/src/main/asciidoc/continuous-testing.adoc index ab794ab3a6db9..6be909bc95387 100644 --- a/docs/src/main/asciidoc/continuous-testing.adoc +++ b/docs/src/main/asciidoc/continuous-testing.adoc @@ -10,6 +10,8 @@ include::_attributes.adoc[] :numbered: :sectnums: :sectnumlevels: 4 +:topics: testing,dev-ui,tooling,devmode +:extensions: io.quarkus:quarkus-core Learn how to use continuous testing in your Quarkus Application. diff --git a/docs/src/main/asciidoc/credentials-provider.adoc b/docs/src/main/asciidoc/credentials-provider.adoc index 7a5c745b6007a..579ea95715fc9 100644 --- a/docs/src/main/asciidoc/credentials-provider.adoc +++ b/docs/src/main/asciidoc/credentials-provider.adoc @@ -8,6 +8,7 @@ include::_attributes.adoc[] :categories: security :summary: This guides explains how to use the Vault credentials provider or implement your own custom one. :extension-status: preview +:topics: security,credentials Interacting with a datastore typically implies first connecting using credentials. Those credentials will allow the client to be identified, authenticated and eventually authorized. @@ -147,14 +148,14 @@ Here is a simple example: @Unremovable public class MyCredentialsProvider implements CredentialsProvider { - @Override - public Map getCredentials(String credentialsProviderName) { + @Override + public Map getCredentials(String credentialsProviderName) { - Map properties = new HashMap<>(); - properties.put(USER_PROPERTY_NAME, "hibernate_orm_test"); - properties.put(PASSWORD_PROPERTY_NAME, "hibernate_orm_test"); - return properties; - } + Map properties = new HashMap<>(); + properties.put(USER_PROPERTY_NAME, "hibernate_orm_test"); + properties.put(PASSWORD_PROPERTY_NAME, "hibernate_orm_test"); + return properties; + } } ---- @@ -189,6 +190,7 @@ public Map getCredentials(String credentialsProviderName) { System.out.println("MyCredentialsProvider called with foo=" + config.getValue(credentialsProviderName + ".foo", String.class)); ... +} ---- == New Credentials Provider extension diff --git a/docs/src/main/asciidoc/databases-dev-services.adoc b/docs/src/main/asciidoc/databases-dev-services.adoc index 0cb80afb59227..f30efd79d9f48 100644 --- a/docs/src/main/asciidoc/databases-dev-services.adoc +++ b/docs/src/main/asciidoc/databases-dev-services.adoc @@ -6,6 +6,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Dev Services for Databases :categories: data, tooling include::_attributes.adoc[] +:topics: devservices,data,database,datasource,tooling,testing,devmode +:extensions: io.quarkus:quarkus-agroal,io.quarkus:quarkus-reactive-mysql-client,io.quarkus:quarkus-reactive-oracle-client,io.quarkus:quarkus-reactive-pg-client,io.quarkus:quarkus-jdbc-db2,io.quarkus:quarkus-jdbc-derby,io.quarkus:quarkus-jdbc-h2,io.quarkus:quarkus-jdbc-mariadb,io.quarkus:quarkus-jdbc-mssql,io.quarkus:quarkus-jdbc-mysql,io.quarkus:quarkus-jdbc-oracle,io.quarkus:quarkus-jdbc-postgresql When testing or running in dev mode Quarkus can provide you with a zero-config database out of the box, a feature we refer to as Dev Services. Depending on your database type you may need Docker installed in order to use this feature. diff --git a/docs/src/main/asciidoc/datasource.adoc b/docs/src/main/asciidoc/datasource.adoc index fb5c57e747b2d..6781dcbe5eaf6 100644 --- a/docs/src/main/asciidoc/datasource.adoc +++ b/docs/src/main/asciidoc/datasource.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :diataxis-type: reference :categories: data,getting-started,reactive +:topics: data,database,datasource,sql,jdbc,reactive +:extensions: io.quarkus:quarkus-agroal,io.quarkus:quarkus-reactive-mysql-client,io.quarkus:quarkus-reactive-oracle-client,io.quarkus:quarkus-reactive-pg-client,io.quarkus:quarkus-reactive-db2-client,io.quarkus:quarkus-reactive-pg-client,io.quarkus:quarkus-reactive-mssql-client,io.quarkus:quarkus-jdbc-db2,io.quarkus:quarkus-jdbc-derby,io.quarkus:quarkus-jdbc-h2,io.quarkus:quarkus-jdbc-mariadb,io.quarkus:quarkus-jdbc-mssql,io.quarkus:quarkus-jdbc-mysql,io.quarkus:quarkus-jdbc-oracle,io.quarkus:quarkus-jdbc-postgresql Use a unified configuration model to define data sources for Java Database Connectivity (JDBC) and Reactive drivers. diff --git a/docs/src/main/asciidoc/deploying-to-azure-cloud.adoc b/docs/src/main/asciidoc/deploying-to-azure-cloud.adoc index c611f4e7e37c5..138ab12b8a035 100644 --- a/docs/src/main/asciidoc/deploying-to-azure-cloud.adoc +++ b/docs/src/main/asciidoc/deploying-to-azure-cloud.adoc @@ -7,6 +7,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: Deploy a Quarkus application to the Microsoft Azure cloud platform. +:topics: devops,azure,cloud,deployment This guide covers: diff --git a/docs/src/main/asciidoc/deploying-to-google-cloud.adoc b/docs/src/main/asciidoc/deploying-to-google-cloud.adoc index 9bc36ffa2f090..534901043c870 100644 --- a/docs/src/main/asciidoc/deploying-to-google-cloud.adoc +++ b/docs/src/main/asciidoc/deploying-to-google-cloud.adoc @@ -7,6 +7,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: This guide explains how to deploy a Quarkus application to Google Cloud. +:topics: devops,google,gcp,cloud,deployment This guide covers: diff --git a/docs/src/main/asciidoc/deploying-to-heroku.adoc b/docs/src/main/asciidoc/deploying-to-heroku.adoc index e9c7feeabdb1e..73637d12be8b8 100644 --- a/docs/src/main/asciidoc/deploying-to-heroku.adoc +++ b/docs/src/main/asciidoc/deploying-to-heroku.adoc @@ -7,6 +7,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: Deploy your Quarkus applications on Heroku. +:topics: devops,heroku,cloud,deployment In this guide you will learn how to deploy a Quarkus based web application as a web-dyno to Heroku. @@ -152,7 +153,7 @@ git add pom.xml git commit -am "Add container-image-docker extension." ---- -The image we are going to build needs to be named accordingly to work with Heroku's registry and deployment. +The image we are going to build needs to be named accordingly to work with Heroku's registry and deployment. We get the generated name via `heroku info` and pass it on to the (local) build: [source,bash] diff --git a/docs/src/main/asciidoc/deploying-to-kubernetes.adoc b/docs/src/main/asciidoc/deploying-to-kubernetes.adoc index 06eb2d82c4dd8..18f6d31c88800 100644 --- a/docs/src/main/asciidoc/deploying-to-kubernetes.adoc +++ b/docs/src/main/asciidoc/deploying-to-kubernetes.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud, native :summary: This guide covers how to deploy a native application on Kubernetes. +:topics: devops,kubernetes,cloud,deployment +:extensions: io.quarkus:quarkus-kubernetes Quarkus offers the ability to automatically generate Kubernetes resources based on sane defaults and user-supplied configuration using https://github.com/dekorateio/dekorate/[dekorate]. It currently supports generating resources for vanilla <<#kubernetes,Kubernetes>>, <<#openshift,OpenShift>> and <<#knative,Knative>>. @@ -191,7 +193,7 @@ spec: ... ---- -The `app.quarkus.io/commit-id`, `app.quarkus.io/build-timestamp` labels and the `app.kubernetes.io/version` annotation might change every time we re-build the Kubernetes manifests which can be problematic when we want to deploy these resources using a Git-Ops tool (because these tools will detect differences and hence will perform a re-deployment). +The `app.quarkus.io/commit-id`, `app.quarkus.io/build-timestamp` labels and the `app.kubernetes.io/version` annotation might change every time we re-build the Kubernetes manifests which can be problematic when we want to deploy these resources using a Git-Ops tool (because these tools will detect differences and hence will perform a re-deployment). To make the generated resources Git-Ops friendly and only produce idempotent resources (resources that won't change every time we build the sources), we need to add the following property: @@ -209,7 +211,7 @@ quarkus.kubernetes.output-directory=target/kubernetes-with-idempotent [NOTE] ==== -Note that the property `quarkus.kubernetes.output-directory` is relative to the current project location. +Note that the property `quarkus.kubernetes.output-directory` is relative to the current project location. ==== === Changing the generated deployment resource @@ -266,7 +268,7 @@ To specify the namespace in your manifest customize with the following property [source,properties] ---- -quarkus.kubernetes.namespace=mynamespace +quarkus.kubernetes.namespace=mynamespace ---- === Defining a Docker registry @@ -895,7 +897,7 @@ implementation("io.quarkus:quarkus-kubernetes-client") ---- To access the API server from within a Kubernetes cluster, some RBAC related resources are required (e.g. a ServiceAccount, a RoleBinding). -To ease the usage of the `kubernetes-client` extension, the `kubernetes` extension is going to generate a RoleBinding resource that binds a cluster role named "view" to the application ServiceAccount resource. It's important to note that the cluster role "view" won't be generated automatically, so it's expected that you have this cluster role with name "view" already installed in your cluster. +To ease the usage of the `kubernetes-client` extension, the `kubernetes` extension is going to generate a RoleBinding resource that binds a cluster role named "view" to the application ServiceAccount resource. It's important to note that the cluster role "view" won't be generated automatically, so it's expected that you have this cluster role with name "view" already installed in your cluster. On the other hand, you can fully customize the roles, subjects and role bindings to generate using the properties under `quarkus.kubernetes.rbac.role-bindings`, and if present, the `kubernetes-client` extension will use it and hence won't generate any RoleBinding resource. @@ -918,7 +920,7 @@ quarkus.kubernetes.rbac.roles.my-role.policy-rules.0.verbs=list <1> In this example, the role "my-role" will be generated with a policy rule to get the list of deployments. -By default, if one role is configured, a RoleBinding resource will be generated as well to link this role with the ServiceAccount resource. +By default, if one role is configured, a RoleBinding resource will be generated as well to link this role with the ServiceAccount resource. Moreover, you can have more control over the RBAC resources to be generated: @@ -940,9 +942,9 @@ quarkus.kubernetes.rbac.role-bindings.my-role-binding.role-name=my-role <1> In this example, the role "my-role" will be generated with the specified policy rules. <2> Also, the service account "my-service-account" will be generated. -<3> And we can configure the generated RoleBinding resource by selecting the role to be used and the subject. +<3> And we can configure the generated RoleBinding resource by selecting the role to be used and the subject. -Finally, we can also generate the cluster wide role resource of "ClusterRole" kind and a "ClusterRoleBinding" resource as follows: +Finally, we can also generate the cluster wide role resource of "ClusterRole" kind and a "ClusterRoleBinding" resource as follows: [source,properties] ---- @@ -1094,7 +1096,7 @@ quarkus extension remove kubernetes,jib quarkus extension add openshift oc new-project quarkus-project -quarkus build -Dquarkus.container-image.build=true +quarkus build -Dquarkus.container-image.build=true oc new-app --name=greeting quarkus-project/kubernetes-quickstart:1.0.0-SNAPSHOT oc expose svc/greeting @@ -1109,7 +1111,7 @@ curl /greeting ./mvnw quarkus:add-extension -Dextensions="openshift" oc new-project quarkus-project -./mvnw clean package -Dquarkus.container-image.build=true +./mvnw clean package -Dquarkus.container-image.build=true oc new-app --name=greeting quarkus-project/kubernetes-quickstart:1.0.0-SNAPSHOT oc expose svc/greeting @@ -1124,7 +1126,7 @@ curl /greeting ./gradlew addExtension --extensions="openshift" oc new-project quarkus-project -./gradlew build -Dquarkus.container-image.build=true +./gradlew build -Dquarkus.container-image.build=true oc new-app --name=greeting quarkus-project/kubernetes-quickstart:1.0.0-SNAPSHOT oc expose svc/greeting @@ -1382,7 +1384,7 @@ Finally, all you need to do is to configure your favorite IDE to attach the java Sometimes it's desirable to either provide additional resources (e.g. a ConfigMap, a Secret, a Deployment for a database) or provide custom ones that will be used as a `base` for the generation process. Those resources can be added under `src/main/kubernetes` directory and can be named after the target environment (e.g. kubernetes.json, openshift.json, knative.json, or the yml equivalents). The correlation between provided and generated files is done by file name. -So, a `kubernetes.json`/`kubernetes.yml` file added in `src/main/kubernetes` will only affect the generated `kubernetes.json`/`kubernetes.yml`. An `openshift.json`/`openshift.yml` file added in `src/main/kubernetes` will only affect the generated `openshift.json`/`openshift.yml`. +So, a `kubernetes.json`/`kubernetes.yml` file added in `src/main/kubernetes` will only affect the generated `kubernetes.json`/`kubernetes.yml`. An `openshift.json`/`openshift.yml` file added in `src/main/kubernetes` will only affect the generated `openshift.json`/`openshift.yml`. A `knative.json`/`knative.yml` file added in `src/main/kubernetes` will only affect the generated `knative.json`/`knative.yml` and so on. The provided file may be either in json or yaml format and may contain one or more resources. These resources will end up in both generated formats (json and yaml). For example, a secret added in `src/main/kubernetes/kubernetes.yml` will be added to both the generated `kubernetes.yml` and `kubernetes.json`. Note: At the time of writing there is no mechanism in place that allows a one-to-many relationship between provided and generated files. Minikube is not an exception to the rule above, so if you want to customize the generated minikube manifests, the file placed under `src/main/kubernetes` will have to be named `minikube.json` or `minikube.yml` (naming it `kubernetes.yml` or `kubernetes.json` will result in having only the generated `kubernetes.yml` and `kubernetes.json` affected). @@ -1521,13 +1523,13 @@ To enable Service Binding for supported extensions, add the `quarkus-kubernetes- Workload Projection is a process of obtaining the configuration for services from the Kubernetes cluster. This configuration takes the form of directory structures that follow certain conventions and is attached to an application or to a service as a mounted volume. The `kubernetes-service-binding` extension uses this directory structure to create configuration sources, which allows you to configure additional modules, such as databases or message brokers. -During application development, users can use workload projection to connect their application to a development database, or other locally-run services, without changing the actual application code or configuration. +During application development, users can use workload projection to connect their application to a development database, or other locally-run services, without changing the actual application code or configuration. For an example of a workload projection where the directory structure is included in the test resources and passed to integration test, see the link:https://github.com/quarkusio/quarkus/tree/e7efe6b3efba91b9c4ae26f9318f8397e23e7505/integration-tests/kubernetes-service-binding-jdbc/src/test/resources/k8s-sb[Kubernetes Service Binding datasource] GitHub repository. [NOTE] ==== -* The `k8s-sb` directory is the root of all service bindings. In this example, only one database called `fruit-db` is intended to be bound. This binding database has the `type` file, that indicates `postgresql` as the database type, while the other files in the directory provide the necessary information to establish the connection. +* The `k8s-sb` directory is the root of all service bindings. In this example, only one database called `fruit-db` is intended to be bound. This binding database has the `type` file, that indicates `postgresql` as the database type, while the other files in the directory provide the necessary information to establish the connection. * After your Quarkus project obtains information from `SERVICE_BINDING_ROOT` environment variables that are set by OpenShift, you can locate generated configuration files that are present in the file system and use them to map the configuration-file values to properties of certain extensions. ==== @@ -1620,10 +1622,10 @@ NOTE: Automatic service binding can be generated for a limited number of service .Operators that support the service auto-binding [%autowidth,%noheader,stripes=even] |==== -| | Operator | API Version | Kind -| `postgresql` | link:https://operatorhub.io/operator/postgresql[CrunchyData Postgres] | postgres-operator.crunchydata.com/v1beta1 | PostgresCluster -| `mysql` | link:https://operatorhub.io/operator/percona-xtradb-cluster-operator[Percona XtraDB Cluster] | pxc.percona.com/v1-9-0 | PerconaXtraDBCluster -| `mongo` | link:https://operatorhub.io/operator/percona-server-mongodb-operator[Percona Mongo] | psmdb.percona.com/v1-9-0 | PerconaServerMongoDB +| | Operator | API Version | Kind +| `postgresql` | link:https://operatorhub.io/operator/postgresql[CrunchyData Postgres] | postgres-operator.crunchydata.com/v1beta1 | PostgresCluster +| `mysql` | link:https://operatorhub.io/operator/percona-xtradb-cluster-operator[Percona XtraDB Cluster] | pxc.percona.com/v1-9-0 | PerconaXtraDBCluster +| `mongo` | link:https://operatorhub.io/operator/percona-server-mongodb-operator[Percona Mongo] | psmdb.percona.com/v1-9-0 | PerconaServerMongoDB |==== @@ -1730,7 +1732,7 @@ The following example shows that for a named datasource, the datasource name is quarkus.datasource.fruits-db.db-kind=postgresql ---- -This has the same effect as the following configuration: +This has the same effect as the following configuration: [source,properties] ---- diff --git a/docs/src/main/asciidoc/deploying-to-openshift.adoc b/docs/src/main/asciidoc/deploying-to-openshift.adoc index 33de117872abb..268d699a4b74a 100644 --- a/docs/src/main/asciidoc/deploying-to-openshift.adoc +++ b/docs/src/main/asciidoc/deploying-to-openshift.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud, native :summary: This guide covers how to deploy a native application on OpenShift. +:topics: devops,kubernetes,openshift,cloud,deployment +:extensions: io.quarkus:quarkus-openshift This guide covers generating and deploying OpenShift resources based on sane default and user supplied configuration. diff --git a/docs/src/main/asciidoc/dev-mode-differences.adoc b/docs/src/main/asciidoc/dev-mode-differences.adoc index 158ff0de45947..ed3312ac24a32 100644 --- a/docs/src/main/asciidoc/dev-mode-differences.adoc +++ b/docs/src/main/asciidoc/dev-mode-differences.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: architecture :summary: How dev mode differs from a production application +:topics: internals,devmode +:extensions: io.quarkus:quarkus-core This document explains how the dev mode in Quarkus differs from a production application. diff --git a/docs/src/main/asciidoc/dev-services.adoc b/docs/src/main/asciidoc/dev-services.adoc index a2f76497e215a..6e8517de9f7c4 100644 --- a/docs/src/main/asciidoc/dev-services.adoc +++ b/docs/src/main/asciidoc/dev-services.adoc @@ -7,6 +7,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: core :summary: A list of all extensions that support Dev Services and their configuration options. +:topics: devservices,tooling,testing,devmode Quarkus supports the automatic provisioning of unconfigured services in development and test mode. We refer to this capability as Dev Services. From a developer's perspective this means that if you include an extension and don't configure it then @@ -77,7 +78,7 @@ include::{generated-dir}/config/quarkus-keycloak-devservices-keycloak-keycloak-b == Kubernetes -The Kubernetes Dev Service will be enabled when `kubernetes-client` extension is present in your application, and +The Kubernetes Dev Service will be enabled when `kubernetes-client` extension is present in your application, and the API server address has not been explicitly configured. More information can be found in the xref:kubernetes-dev-services.adoc[Kubernetes Dev Services Guide]. diff --git a/docs/src/main/asciidoc/dev-ui-v2.adoc b/docs/src/main/asciidoc/dev-ui-v2.adoc index c13f494b9d681..597f1e22d31cd 100644 --- a/docs/src/main/asciidoc/dev-ui-v2.adoc +++ b/docs/src/main/asciidoc/dev-ui-v2.adoc @@ -25,7 +25,7 @@ image::dev-ui-overview-v2.png[alt=Dev UI overview,role="center"] It allows you to: - quickly visualize all the extensions currently loaded -- view extension statuses and go directly to extension documentation +- view extension statuses and go directly to extension documentation - view and change `Configuration` - manage and visualize `Continuous Testing` - view `Dev Services` information @@ -44,7 +44,7 @@ So you can always start with that :) Extensions can: -- <> +- <> - <> - <> - <> @@ -97,7 +97,7 @@ public CardPageBuildItem pages(NonApplicationRootPathBuildItem nonApplicationRoo [NOTE] .Note about icons -If you find your icon at https://fontawesome.com/search?o=r&m=free[Font awesome], you can map as follow: Example `` will map to `font-awesome-solid:house`, so `fa` becomes `font-awesome` and for the icon name, remove the `fa-`; +If you find your icon at https://fontawesome.com/search?o=r&m=free[Font awesome], you can map as follow: Example `` will map to `font-awesome-solid:house`, so `fa` becomes `font-awesome` and for the icon name, remove the `fa-`; ==== Embedding external content @@ -107,13 +107,13 @@ image::dev-ui-extension-openapi-embed-v2.png[alt=Dev UI embedded page,role="cent If you do not want to embed the content, you can use the `.doNotEmbed()` on the Page Builder, this will then open the link in a new tab. -==== Runtime external links +==== Runtime external links -The example above assumes you know the link to use at build time. There might be cases where you only know this at runtime. In that case you can use a <> Method that returns the link to add, and use that when creating the link. Rather than using the `.url` method on the page builder, use the `.dynamicUrlJsonRPCMethodName("yourJsonRPCMethodName")`. +The example above assumes you know the link to use at build time. There might be cases where you only know this at runtime. In that case you can use a <> Method that returns the link to add, and use that when creating the link. Rather than using the `.url` method on the page builder, use the `.dynamicUrlJsonRPCMethodName("yourJsonRPCMethodName")`. ==== Adding labels -You can add an option label to the link in the card using one of the builder methods on the page builder. These labels can be +You can add an option label to the link in the card using one of the builder methods on the page builder. These labels can be - static (known at build time) `.staticLabel("staticLabelValue")` - dynamic (loaded at runtime) `.dynamicLabelJsonRPCMethodName("yourJsonRPCMethodName")` @@ -145,7 +145,7 @@ There are a few options to add full page content in Dev UI. Starting from the mo If you have some data that is known at build time that you want to display you can use one of the following builders in `Page`: -- <> +- <> - <> - <> - <> @@ -291,7 +291,7 @@ export class QwcArcBeans extends LitElement { // <3> customElements.define('qwc-arc-beans', QwcArcBeans); // <10> ---- -<1> You can import Classes and/or functions from other libraries. +<1> You can import Classes and/or functions from other libraries. In this case we use the `LitElement` class and `html` & `css` functions from `Lit` <2> Build time data as defined in the Build step and can be imported using the key and always from `build-time-data`. All keys added in your Build step will be available. <3> The component should be named in the following format: Qwc (stands for Quarkus Web Component) then Extension Name then Page Title, all concatenated with Camel Case. This will also match the file name format as described earlier. The component should also extend `LitComponent`. @@ -305,7 +305,7 @@ In this case we use the `LitElement` class and `html` & `css` functions from `Li ===== Using Vaadin UI components for rendering -Dev UI makes extensive usage of https://vaadin.com/docs/latest/components[Vaadin web components] as UI Building blocks. +Dev UI makes extensive usage of https://vaadin.com/docs/latest/components[Vaadin web components] as UI Building blocks. As an example, the Arc Beans are rendered using a https://vaadin.com/docs/latest/components/grid[Vaadin Grid]: @@ -374,7 +374,7 @@ export class QwcArcBeans extends LitElement { resizable> `; - + } else { return html`No beans found`; } @@ -412,10 +412,10 @@ export class QwcArcBeans extends LitElement { }else if(bean.kind.toLowerCase() === "synthetic"){ level = "contrast"; } - + return html` ${level - ? html`${kind}` + ? html`${kind}` : html`${kind}` }`; } @@ -434,7 +434,7 @@ export class QwcArcBeans extends LitElement { return html` ${bean.interceptorInfos.map(interceptor => html`
- ${interceptor.interceptorClass.name} + ${interceptor.interceptorClass.name} ${interceptor.priority}
` )} @@ -522,7 +522,7 @@ You can use any combination of small, primary, pill, with icon and clickable wit Custom colours - +
@@ -548,7 +548,7 @@ You can use any combination of small, primary, pill, with icon and clickable wit
-
+
Default icon @@ -689,7 +689,7 @@ import 'qui-code-block'; [source,html] ----
- @@ -703,7 +703,7 @@ or fetching the contents from a URL: [source,html] ----
- @@ -723,7 +723,7 @@ import 'qui-ide-link'; [source,html] ---- -[${sourceClassNameFull}]; @@ -868,7 +868,7 @@ Now, in your Runtime module create the JsonRPC Service. This class will default The return object in these methods can be: -- primitives or `String`, +- primitives or `String`, - `io.vertx.core.json.JsonArray` - `io.vertx.core.json.JsonObject` - any other POJO that can be serializable to Json @@ -903,7 +903,7 @@ https://github.com/quarkusio/quarkus/blob/main/extensions/cache/runtime/src/main *Webcomponent (Javascript) part* -Now you can use the JsonRPC controller to access the `getAll` method (and any other methods in you JsonRPC Service) +Now you can use the JsonRPC controller to access the `getAll` method (and any other methods in you JsonRPC Service) [source,javascript] ---- @@ -975,7 +975,7 @@ Java side of streaming data: public class JokesJsonRPCService { private final BroadcastProcessor jokeStream = BroadcastProcessor.create(); - + @PostConstruct void init() { Multi.createFrom().ticks().every(Duration.ofHours(4)).subscribe().with((item) -> { @@ -1007,7 +1007,7 @@ this._observer = this.jsonRpc.streamJokes().onNext(jsonRpcResponse => { //<1> this._observer.cancel(); //<2> ---- -<1> You can call the method (optionally passing in parameters) and then provide the code that will be called on the next event. +<1> You can call the method (optionally passing in parameters) and then provide the code that will be called on the next event. <2> Make sure to keep an instance of the observer to cancel later if needed. https://github.com/phillip-kruger/quarkus-jokes/blob/main/deployment/src/main/resources/dev-ui/qwc-jokes-web-components.js[Example code] @@ -1076,7 +1076,7 @@ static properties = { extensionName: {type: String}, description: {type: String}, guide: {type: String}, - namespace: {type: String} + namespace: {type: String} } ---- @@ -1237,4 +1237,4 @@ public class SomeTest extends DevUIJsonRPCTest { Assertions.assertEquals("changedByTest", applicationName); } } ----- \ No newline at end of file +---- diff --git a/docs/src/main/asciidoc/doc-concept.adoc b/docs/src/main/asciidoc/doc-concept.adoc index 23871758114fe..7cc84e5fc4651 100644 --- a/docs/src/main/asciidoc/doc-concept.adoc +++ b/docs/src/main/asciidoc/doc-concept.adoc @@ -9,6 +9,7 @@ include::_attributes.adoc[] :diataxis-type: concept :categories: contributing :fn-diataxis: footnote:diataxis[Procida, D. Diátaxis documentation framework. https://diataxis.fr/] +:topics: internals,documentation Quarkus documentation is structured into four distinct content types: concepts, how-tos, tutorials, and references. The composition and structure of Quarkus docs follow the Diátaxis systematic documentation framework for technical documentation authoring. @@ -16,7 +17,7 @@ Each content type resolves a different user need, fulfills a different purpose, == Diátaxis documentation framework -We chose to align Quarkus docs with the Diátaxis documentation framework{fn-diataxis}, which defines a core content structure that addresses the different needs users have when consulting docs. +We chose to align Quarkus docs with the Diátaxis documentation framework{fn-diataxis}, which defines a core content structure that addresses the different needs users have when consulting docs. image::diataxis-framework.png[The content types in the Diátaxis documentation framework{fn-diataxis},width=40%, align=left] @@ -46,11 +47,11 @@ You can cite design decisions, historical reasons, and technical constraints to > How-to guides are _directions_ that take the reader through the steps required to solve a real-world problem. How-to guides are _goal-oriented_. -Good how-to guides: +Good how-to guides: - guide (walk-through) or demonstrate how to complete a task. -- assume you have enough context to begin the task. -- describes the concrete steps necessary to complete a task, but these steps +- assume you have enough context to begin the task. +- describes the concrete steps necessary to complete a task, but these steps could be in the middle of a larger task. - do not explain concepts, they rely on other documents (like concepts) to do that. - are adaptable to real-world use cases. @@ -61,15 +62,15 @@ Good how-to guides: > Reference guides are _technical descriptions_ of the machinery and how to operate it. Reference material is _information-oriented_. -Good reference guides: +Good reference guides: - are concise and to the point. They state, describe, and inform. -- are consistent (to the extent possible) with other reference guides. +- are consistent (to the extent possible) with other reference guides. Following the template helps here. -- remain focused on describing their topic. +- remain focused on describing their topic. They don't explain or provide additional context from other sources. - provide examples or illustrations that help readers understand what is being described. -- are kept up to date. While configuration reference material is generated, +- are kept up to date. While configuration reference material is generated, extension references that describe how configuration should be applied must be accurate to be useful. @@ -78,13 +79,13 @@ Good reference guides: > Tutorials are _lessons_ that take the reader by the hand through a series of steps to complete a project of some kind. Tutorials are _learning-oriented_. -Good tutorials: +Good tutorials: - provide a learning experience, giving the reader something they can do. - get the reader started (they do not create an expert). - provide the reader with concrete steps to follow that each have a comprehensible result. - are reliable and consistent (they work for all users, every time). -- include only enough information to complete the task. +- include only enough information to complete the task. They delegate to other documentation types (concepts or reference) to provide additional context. - focus on one way of doing the task. Alternative approaches are explored in other document types (a how-to guide, for example). diff --git a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc b/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc index fbb6376d7d11c..8c522b2cb95f6 100644 --- a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc +++ b/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc @@ -8,6 +8,7 @@ include::_attributes.adoc[] :diataxis-type: howto :categories: contributing :fn-diataxis: footnote:diataxis[Procida, D. Diátaxis documentation framework. https://diataxis.fr/] +:topics: internals,documentation Contribute to the documentation by using the recommended diataxis content types, steps, workflow, and style guidance to ensure the content successfully renders on the Quarkus website portal. @@ -56,7 +57,7 @@ include::_attributes.adoc[] <3> :categories: security,web <5> <6> ---- -<1> Set the `id` value to be the same as the file name but without the extension. +<1> Set the `id` value to be the same as the file name but without the extension. <2> For information about how to create a good title for each content type, see xref:{doc-guides}/doc-reference.adoc#titles-and-headings[Titles and headings] on the "Quarkus style and content guidelines" page. <3> The `_attributes.adoc` include is required to ensure that attributes get resolved and the table of contents is generated. <4> Specify the diataxis type: `concept`, `howto`, `reference`, or `tutorial`. diff --git a/docs/src/main/asciidoc/doc-create-tutorial.adoc b/docs/src/main/asciidoc/doc-create-tutorial.adoc index a1bccc9ced1e0..ed8a37fb2ff59 100644 --- a/docs/src/main/asciidoc/doc-create-tutorial.adoc +++ b/docs/src/main/asciidoc/doc-create-tutorial.adoc @@ -8,6 +8,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :diataxis-type: tutorial :categories: contributing +:topics: internals,documentation Create a new tutorial that guides users through creating, running, and testing a Quarkus application that uses annotations from an imaginary extension. diff --git a/docs/src/main/asciidoc/doc-reference.adoc b/docs/src/main/asciidoc/doc-reference.adoc index 0957c97df24a8..9e6329705d137 100644 --- a/docs/src/main/asciidoc/doc-reference.adoc +++ b/docs/src/main/asciidoc/doc-reference.adoc @@ -8,6 +8,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :diataxis-type: reference :categories: contributing +:topics: internals,documentation Guidelines are provided to help you to contribute clear and consistent content that is also sourced in the required diataxis structure and composition of Quarkus documentation. @@ -137,7 +138,7 @@ Suffix:: Use a suffix that reflects the document type (optional): - `-concept.adoc` for concept documents - `-howto.adoc` for how-to guides -- `-reference.adoc` for references +- `-reference.adoc` for references - `-tutorial.adoc` for tutorials [[doc-structure]] diff --git a/docs/src/main/asciidoc/duplicated-context.adoc b/docs/src/main/asciidoc/duplicated-context.adoc index bb90a8a5811df..ae09214957784 100644 --- a/docs/src/main/asciidoc/duplicated-context.adoc +++ b/docs/src/main/asciidoc/duplicated-context.adoc @@ -8,6 +8,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :diataxis-type: concept :categories: core, architecture +:topics: internals,extensions When using a traditional, blocking, and synchronous framework, processing of each request is performed in a dedicated thread. So, the same thread is used for the entire processing. diff --git a/docs/src/main/asciidoc/elasticsearch-dev-services.adoc b/docs/src/main/asciidoc/elasticsearch-dev-services.adoc index b02a6c2704cbd..2ede49bdb9c1f 100644 --- a/docs/src/main/asciidoc/elasticsearch-dev-services.adoc +++ b/docs/src/main/asciidoc/elasticsearch-dev-services.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: data :summary: Start Elasticsearch automatically in dev and test modes +:topics: data,search,elasticsearch,nosql,devservices,tooling,testing,devmode +:extensions: io.quarkus:quarkus-elasticsearch-java-client,io.quarkus:quarkus-elasticsearch-rest-client,io.quarkus:quarkus-hibernate-search-orm-elasticsearch If any Elasticsearch-related extension is present (e.g. `quarkus-elasticsearch-rest-client` or `quarkus-hibernate-search-orm-elasticsearch`), Dev Services for Elasticsearch automatically starts an Elasticsearch server in dev mode and when running tests. diff --git a/docs/src/main/asciidoc/elasticsearch.adoc b/docs/src/main/asciidoc/elasticsearch.adoc index 90224df387134..5013776a04cda 100644 --- a/docs/src/main/asciidoc/elasticsearch.adoc +++ b/docs/src/main/asciidoc/elasticsearch.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: data :summary: This guide covers how to interact with an Elasticsearch cluster using the low level REST client or the Elasticsearch Java client. +:topics: data,search,elasticsearch,nosql +:extensions: io.quarkus:quarkus-elasticsearch-java-client,io.quarkus:quarkus-elasticsearch-rest-client Elasticsearch is a well known full text search engine and NoSQL datastore. diff --git a/docs/src/main/asciidoc/extension-codestart.adoc b/docs/src/main/asciidoc/extension-codestart.adoc index 538647d43dc4e..78d63ff702a73 100644 --- a/docs/src/main/asciidoc/extension-codestart.adoc +++ b/docs/src/main/asciidoc/extension-codestart.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: writing-extensions :summary: Provide users with initial code for extensions when generating Quarkus applications on code.quarkus.io and all the Quarkus tooling. This guide explains how to create and configure a Codestart for an extension. +:topics: extensions,codestarts +:extensions: io.quarkus:quarkus-core This guide explains how to create and configure a Quarkus Codestart for an extension. diff --git a/docs/src/main/asciidoc/extension-metadata.adoc b/docs/src/main/asciidoc/extension-metadata.adoc index d48bad282bb1f..738c463a5be09 100644 --- a/docs/src/main/asciidoc/extension-metadata.adoc +++ b/docs/src/main/asciidoc/extension-metadata.adoc @@ -5,6 +5,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Quarkus Extension Metadata include::_attributes.adoc[] +:categories: writing-extensions +:topics: extensions,codestarts +:extensions: io.quarkus:quarkus-core Quarkus extensions are distributed as Maven JAR artifacts that application and other libraries may depend on. When a Quarkus application project is built, tested or edited using the Quarkus dev tools, Quarkus extension JAR artifacts will be identified on the application classpath by the presence of the Quarkus extension metadata files in them. This document describes the purpose of each Quarkus extension metadata file and its content. diff --git a/docs/src/main/asciidoc/extension-registry-user.adoc b/docs/src/main/asciidoc/extension-registry-user.adoc index 2a2d88c2f5783..9d0663d436649 100644 --- a/docs/src/main/asciidoc/extension-registry-user.adoc +++ b/docs/src/main/asciidoc/extension-registry-user.adoc @@ -7,6 +7,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: architecture :summary: Learn more about the notion of extension registry and how you can use your own. +:topics: internals,extensions The Quarkus dev tools, such as the xref:cli-tooling.adoc[Quarkus CLI], the xref:maven-tooling.adoc[Maven] and the xref:gradle-tooling.adoc[Gradle] plugins, or https://code.quarkus.io[code.quarkus.io] can be used to list and search the Quarkus ecosystem for extensions that match a certain criteria. That includes the xref:platform.adoc[Quarkus platform] extensions and various other extensions contributed by the community, many of which are hosted on the https://github.com/quarkiverse[Quarkiverse Hub]. diff --git a/docs/src/main/asciidoc/flyway.adoc b/docs/src/main/asciidoc/flyway.adoc index 78bdfd88c07a7..877aade8cd639 100644 --- a/docs/src/main/asciidoc/flyway.adoc +++ b/docs/src/main/asciidoc/flyway.adoc @@ -9,6 +9,8 @@ include::_attributes.adoc[] :summary: This guide covers how to use the Flyway extension to manage your schema migrations. :migrations-path: src/main/resources/db/migration :config-file: application.properties +:topics: flyway,data,schema-migration,database +:extensions: io.quarkus:quarkus-flyway https://flywaydb.org/[Flyway] is a popular database migration tool that is commonly used in JVM environments. diff --git a/docs/src/main/asciidoc/funqy-aws-lambda-http.adoc b/docs/src/main/asciidoc/funqy-aws-lambda-http.adoc index ff843ff5fb853..406777e416c32 100644 --- a/docs/src/main/asciidoc/funqy-aws-lambda-http.adoc +++ b/docs/src/main/asciidoc/funqy-aws-lambda-http.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: This guide explains Funqy's AWS Lambda HTTP binding. +:topics: aws,lambda,serverless,function,cloud,funqy +:extensions: io.quarkus:quarkus-funqy-http,io.quarkus:quarkus-amazon-lambda-http If you want to allow HTTP clients to invoke on your Funqy functions on AWS Lambda, Quarkus allows you to expose multiple Funqy functions through HTTP deployed as one AWS Lambda. This approach does add overhead over the diff --git a/docs/src/main/asciidoc/funqy-aws-lambda.adoc b/docs/src/main/asciidoc/funqy-aws-lambda.adoc index e0a2d9f568cff..f440ba57646e1 100644 --- a/docs/src/main/asciidoc/funqy-aws-lambda.adoc +++ b/docs/src/main/asciidoc/funqy-aws-lambda.adoc @@ -9,6 +9,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: This guide explains Funqy's AWS Lambda binding. +:topics: aws,lambda,serverless,function,cloud,funqy +:extensions: io.quarkus:quarkus-funqy-amazon-lambda The guide walks through quickstart code to show you how you can deploy Funqy functions to AWS Lambda. diff --git a/docs/src/main/asciidoc/funqy-azure-functions-http.adoc b/docs/src/main/asciidoc/funqy-azure-functions-http.adoc index 47d3a31984844..cc0a6ad34b3ed 100644 --- a/docs/src/main/asciidoc/funqy-azure-functions-http.adoc +++ b/docs/src/main/asciidoc/funqy-azure-functions-http.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: Use Funqy HTTP binding with Microsoft Azure Functions to deploy your serverless Quarkus applications. +:topics: azure,serverless,function,cloud,funqy +:extensions: io.quarkus:quarkus-azure-functions-http You can use xref:funqy-http.adoc[Funqy HTTP] on Azure Functions. This allows you to invoke on multiple Funqy functions using HTTP deployed as one Azure Function. diff --git a/docs/src/main/asciidoc/funqy-gcp-functions-http.adoc b/docs/src/main/asciidoc/funqy-gcp-functions-http.adoc index f72418f707e43..99d5a62b5d692 100644 --- a/docs/src/main/asciidoc/funqy-gcp-functions-http.adoc +++ b/docs/src/main/asciidoc/funqy-gcp-functions-http.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: This guide explains Funqy's Google Cloud Platform Functions HTTP binding. +:topics: google,gcp,serverless,function,cloud,funqy +:extensions: io.quarkus:quarkus-funqy-http,io.quarkus:quarkus-google-cloud-functions-http If you want to allow HTTP clients to invoke your Funqy functions on Google Cloud Functions, Quarkus allows you to expose multiple Funqy functions through HTTP deployed as one Google Cloud Function. This approach does add overhead over the diff --git a/docs/src/main/asciidoc/funqy-gcp-functions.adoc b/docs/src/main/asciidoc/funqy-gcp-functions.adoc index 9a8070c3749e6..5a6b9fa9329dd 100644 --- a/docs/src/main/asciidoc/funqy-gcp-functions.adoc +++ b/docs/src/main/asciidoc/funqy-gcp-functions.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: This guide explains Funqy's Google Cloud Platform Functions binding. +:topics: google,gcp,serverless,function,cloud,funqy +:extensions: io.quarkus:quarkus-funqy-http,io.quarkus:quarkus-funqy-google-cloud-functions The guide walks through quickstart code to show you how you can deploy Funqy functions to Google Cloud Functions. diff --git a/docs/src/main/asciidoc/funqy-http.adoc b/docs/src/main/asciidoc/funqy-http.adoc index 894d84623c4a4..e6aa35f736291 100644 --- a/docs/src/main/asciidoc/funqy-http.adoc +++ b/docs/src/main/asciidoc/funqy-http.adoc @@ -8,6 +8,8 @@ include::_attributes.adoc[] :categories: cloud :summary: This guide explains Funqy's HTTP binding. :extension-status: preview +:topics: serverless,function,cloud,funqy +:extensions: io.quarkus:quarkus-funqy-http The guide walks through quickstart code to show you how you can deploy Funqy as a standalone service and invoke on Funqy functions using HTTP. diff --git a/docs/src/main/asciidoc/funqy-knative-events.adoc b/docs/src/main/asciidoc/funqy-knative-events.adoc index 031506756ed76..f9e458e9d65c9 100644 --- a/docs/src/main/asciidoc/funqy-knative-events.adoc +++ b/docs/src/main/asciidoc/funqy-knative-events.adoc @@ -8,6 +8,8 @@ include::_attributes.adoc[] :categories: cloud :summary: This guide explains Funqy's Knative Events binding. :devtools-no-gradle: +:topics: serverless,function,cloud,funqy +:extensions: io.quarkus:quarkus-funqy-knative-events Quarkus Funqy link:https://knative.dev/docs/eventing[Knative Events] builds off of the xref:funqy-http.adoc[Funqy HTTP] extension to allow you to route and process Knative Events within a Funqy function. diff --git a/docs/src/main/asciidoc/funqy.adoc b/docs/src/main/asciidoc/funqy.adoc index 1723981be0272..b82fa9421c6a2 100644 --- a/docs/src/main/asciidoc/funqy.adoc +++ b/docs/src/main/asciidoc/funqy.adoc @@ -8,6 +8,7 @@ include::_attributes.adoc[] :categories: cloud :summary: This guide explains basics of the Funqy framework, a simple portable cross-provider cloud function API. :extension-status: preview +:topics: serverless,function,cloud,funqy Quarkus Funqy is part of Quarkus's serverless strategy and aims to provide a portable Java API to write functions deployable to various FaaS environments like AWS Lambda, Azure Functions, Google Cloud Functions, Knative, and Knative Events (Cloud Events). @@ -72,7 +73,7 @@ public class GreetingFunction { == Async Reactive Types -Funqy supports the https://smallrye.io/smallrye-mutiny[Smallrye Mutiny] `Uni` reactive type as a return type. The only requirement is that +Funqy supports the https://smallrye.io/smallrye-mutiny[SmallRye Mutiny] `Uni` reactive type as a return type. The only requirement is that the `Uni` must fill out the generic type. [source, java] diff --git a/docs/src/main/asciidoc/gcp-functions-http.adoc b/docs/src/main/asciidoc/gcp-functions-http.adoc index de92afa715900..5a947083368d2 100644 --- a/docs/src/main/asciidoc/gcp-functions-http.adoc +++ b/docs/src/main/asciidoc/gcp-functions-http.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: This guide explains how you can deploy Vert.x Web, Servlet, or RESTEasy microservices as a Google Cloud Function. +:topics: google,gcp,serverless,function,cloud +:extensions: io.quarkus:quarkus-google-cloud-functions-http The `quarkus-google-cloud-functions-http` extension allows you to write microservices with RESTEasy Reactive (Jakarta REST), Undertow (Servlet), Reactive Routes, or xref:funqy-http.adoc[Funqy HTTP], and make these microservices deployable to the Google Cloud Functions runtime. diff --git a/docs/src/main/asciidoc/gcp-functions.adoc b/docs/src/main/asciidoc/gcp-functions.adoc index 136852b1d00ca..d0ce3a5a1fe97 100644 --- a/docs/src/main/asciidoc/gcp-functions.adoc +++ b/docs/src/main/asciidoc/gcp-functions.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: This guide explains how you can deploy Quarkus-based Google Cloud Functions. +:topics: google,gcp,serverless,function,cloud +:extensions: io.quarkus:quarkus-google-cloud-functions The `quarkus-google-cloud-functions` extension allows you to use Quarkus to build your Google Cloud Functions. Your functions can use injection annotations from CDI or Spring and other Quarkus facilities as you need them. diff --git a/docs/src/main/asciidoc/getting-started-dev-services.adoc b/docs/src/main/asciidoc/getting-started-dev-services.adoc index ace01fc77c6dc..ef39883cf2d74 100644 --- a/docs/src/main/asciidoc/getting-started-dev-services.adoc +++ b/docs/src/main/asciidoc/getting-started-dev-services.adoc @@ -9,6 +9,7 @@ include::_attributes.adoc[] :diataxis-type: tutorial :categories: getting-started, data, core :summary: Discover some of the features that make developing with Quarkus a joyful experience. +:topics: getting-started,devservices This tutorial shows you how to create an application which writes to and reads from a database. You will use Dev Services, so you will not actually download, configure, or even start the database yourself. diff --git a/docs/src/main/asciidoc/getting-started-reactive.adoc b/docs/src/main/asciidoc/getting-started-reactive.adoc index 5ae2dc045aa83..2d4ce722dfd11 100644 --- a/docs/src/main/asciidoc/getting-started-reactive.adoc +++ b/docs/src/main/asciidoc/getting-started-reactive.adoc @@ -5,8 +5,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Getting Started With Reactive include::_attributes.adoc[] -:categories: getting-started +:categories: getting-started,reactive :summary: Learn more about developing reactive applications with Quarkus. +:topics: getting-started,reactive _Reactive_ is a set of principles to build robust, efficient, and concurrent applications and systems. These principles let you handle more load than traditional approaches while using the resources (CPU and memory) more efficiently while also reacting to failures gracefully. diff --git a/docs/src/main/asciidoc/getting-started-testing.adoc b/docs/src/main/asciidoc/getting-started-testing.adoc index f2536c3b73ec8..9b95c931b7e05 100644 --- a/docs/src/main/asciidoc/getting-started-testing.adoc +++ b/docs/src/main/asciidoc/getting-started-testing.adoc @@ -11,6 +11,7 @@ include::_attributes.adoc[] :numbered: :sectnums: :sectnumlevels: 4 +:topics: getting-started,testing,tooling Learn how to test your Quarkus Application. @@ -426,7 +427,7 @@ Alternatively or additionally to an interceptor, you can enrich *all* your `@Qua * `io.quarkus.test.junit.callback.QuarkusTestAfterTestExecutionCallback` * `io.quarkus.test.junit.callback.QuarkusTestAfterEachCallback` -Optionally, you can enable these callbacks also for the `@QuarkusIntegrationTest` tests if the property `quarkus.test.enable-callbacks-for-integration-tests` is `true`. +Optionally, you can enable these callbacks also for the `@QuarkusIntegrationTest` tests if the property `quarkus.test.enable-callbacks-for-integration-tests` is `true`. Such a callback implementation has to be registered as a "service provider" as defined by `java.util.ServiceLoader`. @@ -1536,8 +1537,8 @@ public class Foo { @Inject Charlie charlie; <2> - - @ConfigProperty(name = "bar") + + @ConfigProperty(name = "bar") boolean bar; <3> public String ping() { @@ -1622,16 +1623,16 @@ public class FooTest { So what exactly does the `QuarkusComponentTest` do? It starts the CDI container and registers a dedicated xref:config-reference.adoc[configuration object]. -If the test instance lifecycle is `Lifecycle#PER_METHOD` (default) then the container is started during the `before each` test phase and stopped during the `after each` test phase. -However, if the test instance lifecycle is `Lifecycle#PER_CLASS` then the container is started during the `before all` test phase and stopped during the `after all` test phase. +If the test instance lifecycle is `Lifecycle#PER_METHOD` (default) then the container is started during the `before each` test phase and stopped during the `after each` test phase. +However, if the test instance lifecycle is `Lifecycle#PER_CLASS` then the container is started during the `before all` test phase and stopped during the `after all` test phase. The fields annotated with `@Inject` and `@InjectMock` are injected after a test instance is created. Finally, the CDI request context is activated and terminated per each test method. === Auto Mocking Unsatisfied Dependencies -Unlike in regular CDI environments the test does not fail if a component injects an unsatisfied dependency. +Unlike in regular CDI environments the test does not fail if a component injects an unsatisfied dependency. Instead, a synthetic bean is registered automatically for each combination of required type and qualifiers of an injection point that resolves to an unsatisfied dependency. -The bean has the `@Singleton` scope so it's shared across all injection points with the same required type and qualifiers. +The bean has the `@Singleton` scope so it's shared across all injection points with the same required type and qualifiers. The injected reference is an _unconfigured_ Mockito mock. You can inject the mock in your test and leverage the Mockito API to configure the behavior. @@ -1672,17 +1673,17 @@ public class FooTest { public void testPing() { assertEquals("OK", foo.ping()); } - + @ApplicationScoped static class Foo { - + @SimpleBinding <1> String ping() { return "ok"; } - + } - + @SimpleBinding @Interceptor static class SimpleInterceptor { <2> @@ -1730,14 +1731,14 @@ public class FooTest { @ApplicationScoped static class Foo { - + @SimpleBinding <1> String ping() { return "ok"; } - + } } ---- -<1> The interceptor bindings of the resulting interceptor are specified by annotating the method with the interceptor binding types. +<1> The interceptor bindings of the resulting interceptor are specified by annotating the method with the interceptor binding types. <2> Defines the interception type. diff --git a/docs/src/main/asciidoc/getting-started.adoc b/docs/src/main/asciidoc/getting-started.adoc index f76500792ae0f..357fdafa2aeb5 100644 --- a/docs/src/main/asciidoc/getting-started.adoc +++ b/docs/src/main/asciidoc/getting-started.adoc @@ -10,6 +10,7 @@ include::_attributes.adoc[] :numbered: :sectnums: :sectnumlevels: 4 +:topics: getting-started Learn how to create a Hello World Quarkus app. This guide covers: diff --git a/docs/src/main/asciidoc/gradle-tooling.adoc b/docs/src/main/asciidoc/gradle-tooling.adoc index 6452911c75704..da6d68ef02551 100644 --- a/docs/src/main/asciidoc/gradle-tooling.adoc +++ b/docs/src/main/asciidoc/gradle-tooling.adoc @@ -9,6 +9,7 @@ include::_attributes.adoc[] :categories: tooling, native :summary: Develop and build your Quarkus application with Gradle :devtools-no-maven: +:topics: gradle,tooling Use Gradle to create a new project, add or remove extensions, launch development mode, debug your application, and build your application into a jar, native executable, or container-friendly executable. Import your project into your favorite IDE using Gradle project metadata. diff --git a/docs/src/main/asciidoc/grpc-getting-started.adoc b/docs/src/main/asciidoc/grpc-getting-started.adoc index dd13c07ec2e18..d6d007773d446 100644 --- a/docs/src/main/asciidoc/grpc-getting-started.adoc +++ b/docs/src/main/asciidoc/grpc-getting-started.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: serialization :summary: This guide explains how to start using gRPC in your Quarkus application. +:topics: grpc +:extensions: io.quarkus:quarkus-grpc This page explains how to start using gRPC in your Quarkus application. While this page describes how to configure it with Maven, it is also possible to use Gradle. @@ -229,7 +231,7 @@ Further docs explain how to enable and use each of them. Now that we have the generated classes let's implement our _hello_ service. -With Quarkus, implementing a service requires to implement the generated service interface based on Mutiny, a Reactive Programming API integrated in Quarkus, and expose it as a CDI bean. +With Quarkus, implementing a service requires to implement the generated service interface based on Mutiny, a Reactive Programming API integrated in Quarkus, and expose it as a CDI bean. Learn more about Mutiny on the xref:mutiny-primer.adoc[Mutiny guide]. The service class must be annotated with the `@io.quarkus.grpc.GrpcService` annotation. diff --git a/docs/src/main/asciidoc/grpc-kubernetes.adoc b/docs/src/main/asciidoc/grpc-kubernetes.adoc index 6b8193aadc627..ee092e2e6caca 100644 --- a/docs/src/main/asciidoc/grpc-kubernetes.adoc +++ b/docs/src/main/asciidoc/grpc-kubernetes.adoc @@ -7,9 +7,11 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: serialization :summary: This guide explains how to deploy your gRPC services in Quarkus to Kubernetes. +:topics: grpc,kubernetes +:extensions: io.quarkus:quarkus-grpc,io.quarkus:quarkus-kubernetes -This page explains how to deploy your gRPC service in Quarkus in Kubernetes. -We'll continue with the example from xref:grpc-getting-started.adoc[the Getting Started gRPC guide]. +This page explains how to deploy your gRPC service in Quarkus in Kubernetes. +We'll continue with the example from xref:grpc-getting-started.adoc[the Getting Started gRPC guide]. == Configuring your project to use the Quarkus Kubernetes extension @@ -82,7 +84,7 @@ implementation("io.quarkus:quarkus-smallrye-health") TIP: More information about the health extension can be found in xref:microprofile-health.adoc[the Microprofile Health guide]. -By the default, this extension will configure the probes to use the HTTP server (which is provided by some extensions like the Quarkus RESTEasy reactive extension). Internally, this probe will also use xref:grpc-service-implementation.adoc#health[the generated gRPC Health services]. +By the default, this extension will configure the probes to use the HTTP server (which is provided by some extensions like the Quarkus RESTEasy reactive extension). Internally, this probe will also use xref:grpc-service-implementation.adoc#health[the generated gRPC Health services]. If your application does not use any Quarkus extension that exposes an HTTP server, you can still configure the probes to directly use the gRPC Health service by adding the property `quarkus.kubernetes.readiness-probe.grpc-action-enabled=true` into your configuration: diff --git a/docs/src/main/asciidoc/grpc-service-consumption.adoc b/docs/src/main/asciidoc/grpc-service-consumption.adoc index a05c32c1bde93..4483f07f2dae3 100644 --- a/docs/src/main/asciidoc/grpc-service-consumption.adoc +++ b/docs/src/main/asciidoc/grpc-service-consumption.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: serialization :summary: This guide explains how to consume gRPC services in your Quarkus application. +:topics: grpc +:extensions: io.quarkus:quarkus-grpc gRPC clients can be injected in your application code. @@ -247,7 +249,7 @@ quarkus.grpc.clients.hello.ssl.trust-store=tls/ca.pem === Client Stub Deadlines If you need to configure a deadline for a gRPC stub, i.e. to specify a duration of time after which the stub will always return the status error `DEADLINE_EXCEEDED`. -You can specify the deadline via the `quarkus.grpc.clients."service-name".deadline` configuration property, e.g.: +You can specify the deadline via the `quarkus.grpc.clients."service-name".deadline` configuration property, e.g.: [source,properties] ---- diff --git a/docs/src/main/asciidoc/grpc-service-implementation.adoc b/docs/src/main/asciidoc/grpc-service-implementation.adoc index f49e1161aead9..2d870aed2c917 100644 --- a/docs/src/main/asciidoc/grpc-service-implementation.adoc +++ b/docs/src/main/asciidoc/grpc-service-implementation.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: serialization :summary: This guide explains how to implement gRPC services in your Quarkus application. +:topics: grpc +:extensions: io.quarkus:quarkus-grpc gRPC service implementations exposed as CDI beans are automatically registered and served by quarkus-grpc. diff --git a/docs/src/main/asciidoc/grpc-virtual-threads.adoc b/docs/src/main/asciidoc/grpc-virtual-threads.adoc index 9f4445b003c38..0b3d657ddb304 100644 --- a/docs/src/main/asciidoc/grpc-virtual-threads.adoc +++ b/docs/src/main/asciidoc/grpc-virtual-threads.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :runonvthread: https://javadoc.io/doc/io.smallrye.common/smallrye-common-annotation/latest/io/smallrye/common/annotation/RunOnVirtualThread.html :blocking_annotation: https://javadoc.io/doc/io.smallrye.reactive/smallrye-reactive-messaging-api/latest/io/smallrye/reactive/messaging/annotations/Blocking.html +:topics: grpc,virtual-threads +:extensions: io.quarkus:quarkus-grpc This guide explains how to benefit from Java virtual threads when implementing a gRPC service. @@ -151,4 +153,4 @@ public class TestServiceImpl implements TestService { .Limitations ==== The gRPC methods receiving _streams_, such as a `Multi` cannot use `@RunOnVirtualThread`, as the method must not be blocking and produce its result (`Multi` or `Uni`) immediately. -==== \ No newline at end of file +==== diff --git a/docs/src/main/asciidoc/grpc-xds.adoc b/docs/src/main/asciidoc/grpc-xds.adoc index e073fe917faff..da28d6f1d45fd 100644 --- a/docs/src/main/asciidoc/grpc-xds.adoc +++ b/docs/src/main/asciidoc/grpc-xds.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: serialization :summary: This page explains how to enable xDS gRPC usage in your Quarkus application. +:topics: grpc,xds +:extensions: io.quarkus:quarkus-grpc-xds This page explains how to enable xDS gRPC usage in your Quarkus application. diff --git a/docs/src/main/asciidoc/grpc.adoc b/docs/src/main/asciidoc/grpc.adoc index 7e6af77c5b405..12c908ac2c665 100644 --- a/docs/src/main/asciidoc/grpc.adoc +++ b/docs/src/main/asciidoc/grpc.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: serialization :summary: Entry point for everything gRPC. +:topics: grpc +:extensions: io.quarkus:quarkus-grpc,io.quarkus:quarkus-grpc-xds https://grpc.io/[gRPC] is a high-performance RPC framework. It can efficiently connect services implemented using various languages and frameworks. diff --git a/docs/src/main/asciidoc/hibernate-orm-panache-kotlin.adoc b/docs/src/main/asciidoc/hibernate-orm-panache-kotlin.adoc index 7625154010820..8a45bc598b384 100644 --- a/docs/src/main/asciidoc/hibernate-orm-panache-kotlin.adoc +++ b/docs/src/main/asciidoc/hibernate-orm-panache-kotlin.adoc @@ -8,13 +8,15 @@ include::_attributes.adoc[] :categories: data, alt-languages :summary: This explains the specifics of using Hibernate ORM with Panache in a Kotlin project. :config-file: application.properties +:topics: data,hibernate-orm,panache,kotlin,sql,jdbc +:extensions: io.quarkus:quarkus-hibernate-orm-panache-kotlin,io.quarkus:quarkus-hibernate-orm-panache,io.quarkus:quarkus-hibernate-orm Hibernate ORM is the de facto standard Jakarta Persistence (formerly known as JPA) implementation and is well-known in the Java ecosystem. Hibernate ORM with Panache offers a new layer atop this familiar framework. This guide will not dive in to the specifics of either as those are already covered in the xref:hibernate-orm-panache.adoc[Hibernate ORM with Panache guide]. In this guide, we'll cover the Kotlin specific changes needed to use Hibernate ORM with Panache in your Kotlin-based Quarkus applications. -NOTE: When using the kotlin version of Hibernate ORM with Panache, note that the `PanacheEntity`, `PanacheQuery` and `PanacheRepository` are in a different package: `io.quarkus.hibernate.orm.panache.kotlin`. +NOTE: When using the Kotlin version of Hibernate ORM with Panache, note that the `PanacheEntity`, `PanacheQuery` and `PanacheRepository` are in a different package: `io.quarkus.hibernate.orm.panache.kotlin`. == First: an example diff --git a/docs/src/main/asciidoc/hibernate-orm-panache.adoc b/docs/src/main/asciidoc/hibernate-orm-panache.adoc index a26c101fd1030..6377bc904f97c 100644 --- a/docs/src/main/asciidoc/hibernate-orm-panache.adoc +++ b/docs/src/main/asciidoc/hibernate-orm-panache.adoc @@ -8,6 +8,8 @@ include::_attributes.adoc[] :categories: data :summary: Hibernate ORM is the de facto Jakarta Persistence implementation and offers you the full breadth of an Object Relational Mapper. It makes complex mappings possible, but it does not make simple and common mappings trivial. Panache focuses on making your entities trivial and fun to write. :config-file: application.properties +:topics: data,hibernate-orm,panache,sql,jdbc +:extensions: io.quarkus:quarkus-hibernate-orm-panache,io.quarkus:quarkus-hibernate-orm Hibernate ORM is the de facto Jakarta Persistence (formerly known as JPA) implementation and offers you the full breadth of an Object Relational Mapper. It makes complex mappings possible, but it does not make simple and common mappings trivial. @@ -944,7 +946,7 @@ matching the values returned by the select clause: ---- import io.quarkus.runtime.annotations.RegisterForReflection; -@RegisterForReflection +@RegisterForReflection public class RaceWeight { public final String race; public final Double weight; @@ -1198,7 +1200,7 @@ public class PanacheFunctionalityTest { // We can even mock your custom methods Mockito.when(Person.findOrdered()).thenReturn(Collections.emptyList()); Assertions.assertTrue(Person.findOrdered().isEmpty()); - + // Mocking a void method Person.voidMethod(); diff --git a/docs/src/main/asciidoc/hibernate-orm.adoc b/docs/src/main/asciidoc/hibernate-orm.adoc index fb61012dc90d1..c76ac5894639b 100644 --- a/docs/src/main/asciidoc/hibernate-orm.adoc +++ b/docs/src/main/asciidoc/hibernate-orm.adoc @@ -8,6 +8,8 @@ include::_attributes.adoc[] :categories: data :summary: Hibernate ORM is the de facto Jakarta Persistence implementation and offers you the full breath of an Object Relational Mapper. It works beautifully in Quarkus. :config-file: application.properties +:topics: data,hibernate-orm,sql,jdbc +:extensions: io.quarkus:quarkus-hibernate-orm Hibernate ORM is the de facto standard Jakarta Persistence (formerly known as JPA) implementation and offers you the full breadth of an Object Relational Mapper. It works beautifully in Quarkus. @@ -944,7 +946,7 @@ public class FruitResource { return entityManager.createNamedQuery("Fruits.findAll", Fruit.class) .getResultList().toArray(new Fruit[0]); } - + } ---- @@ -968,7 +970,7 @@ public class CustomTenantResolver implements TenantResolver { public String getDefaultTenantId() { return "base"; } - + @Override public String resolveTenantId() { String path = context.request().path(); @@ -981,7 +983,7 @@ public class CustomTenantResolver implements TenantResolver { return parts[1]; } - + } ---- <1> Annotate the TenantResolver implementation with the `@PersistenceUnitExtension` qualifier @@ -1026,7 +1028,7 @@ The following setup will use the xref:flyway.adoc[Flyway] extension to achieve t ==== SCHEMA approach The same data source will be used for all tenants and a schema has to be created for every tenant inside that data source. -CAUTION: Some databases like MariaDB/MySQL do not support database schemas. In these cases you have to use the DATABASE approach below. +CAUTION: Some databases like MariaDB/MySQL do not support database schemas. In these cases you have to use the DATABASE approach below. [source,properties] ---- @@ -1035,7 +1037,7 @@ quarkus.hibernate-orm.database.generation=none # Enable SCHEMA approach and use default datasource quarkus.hibernate-orm.multitenant=SCHEMA -# You could use a non-default datasource by using the following setting +# You could use a non-default datasource by using the following setting # quarkus.hibernate-orm.multitenant-schema-datasource=other # The default data source used for all tenant schemas @@ -1081,7 +1083,7 @@ INSERT INTO mycompany.known_fruits(id, name) VALUES (3, 'Blackberries'); ==== DATABASE approach -For every tenant you need to create a named data source with the same identifier that is returned by the `TenantResolver`. +For every tenant you need to create a named data source with the same identifier that is returned by the `TenantResolver`. [source,properties] ---- diff --git a/docs/src/main/asciidoc/hibernate-reactive-panache.adoc b/docs/src/main/asciidoc/hibernate-reactive-panache.adoc index 7ba55fe448308..37ce51721a101 100644 --- a/docs/src/main/asciidoc/hibernate-reactive-panache.adoc +++ b/docs/src/main/asciidoc/hibernate-reactive-panache.adoc @@ -8,6 +8,8 @@ include::_attributes.adoc[] :categories: data :summary: Simplified reactive ORM layer based on Hibernate Reactive. :config-file: application.properties +:topics: data,hibernate-reactive,panache,sql +:extensions: io.quarkus:quarkus-hibernate-reactive-panache,io.quarkus:quarkus-hibernate-reactive link:https://hibernate.org/reactive/[Hibernate Reactive] is the only reactive Jakarta Persistence (formerly known as JPA) implementation and offers you the full breadth of an Object Relational Mapper allowing you to access your database over reactive drivers. diff --git a/docs/src/main/asciidoc/hibernate-reactive.adoc b/docs/src/main/asciidoc/hibernate-reactive.adoc index 9a23bda4676b3..212838179e2e1 100644 --- a/docs/src/main/asciidoc/hibernate-reactive.adoc +++ b/docs/src/main/asciidoc/hibernate-reactive.adoc @@ -8,6 +8,8 @@ include::_attributes.adoc[] :config-file: application.properties :reactive-doc-url-prefix: https://hibernate.org/reactive/documentation/1.1/reference/html_single/#getting-started :extension-status: preview +:topics: data,hibernate-reactive,panache,sql +:extensions: io.quarkus:quarkus-hibernate-reactive-panache,io.quarkus:quarkus-hibernate-reactive link:https://hibernate.org/reactive/[Hibernate Reactive] is a reactive API for Hibernate ORM, supporting non-blocking database drivers and a reactive style of interaction with the database. diff --git a/docs/src/main/asciidoc/hibernate-search-orm-elasticsearch.adoc b/docs/src/main/asciidoc/hibernate-search-orm-elasticsearch.adoc index 520433bbbecdc..f0e999d807b23 100644 --- a/docs/src/main/asciidoc/hibernate-search-orm-elasticsearch.adoc +++ b/docs/src/main/asciidoc/hibernate-search-orm-elasticsearch.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: data :summary: Hibernate Search allows you to index your entities in an Elasticsearch cluster and easily offer full text search in all your Hibernate ORM-based applications. +:topics: data,hibernate-search,elasticsearch,search,nosql +:extensions: io.quarkus:quarkus-hibernate-search-orm-elasticsearch You have a Hibernate ORM-based application? You want to provide a full-featured full-text search to your users? You're at the right place. diff --git a/docs/src/main/asciidoc/http-reference.adoc b/docs/src/main/asciidoc/http-reference.adoc index 642c75c9212b5..763ea0fae48fb 100644 --- a/docs/src/main/asciidoc/http-reference.adoc +++ b/docs/src/main/asciidoc/http-reference.adoc @@ -10,7 +10,8 @@ include::_attributes.adoc[] :numbered: :sectnums: :sectnumlevels: 4 - +:topics: http,web,webjars,vertx,servlet,undertow +:extensions: io.quarkus:quarkus-vertx-http This document explains various HTTP features that you can use in Quarkus. diff --git a/docs/src/main/asciidoc/ide-tooling.adoc b/docs/src/main/asciidoc/ide-tooling.adoc index 6ab775495c930..d9531c39808de 100644 --- a/docs/src/main/asciidoc/ide-tooling.adoc +++ b/docs/src/main/asciidoc/ide-tooling.adoc @@ -7,6 +7,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: getting-started :summary: Learn more about Quarkus integrations in IDEs. +:topics: ide,tooling The following IDEs have support for the community developed Quarkus Tools: diff --git a/docs/src/main/asciidoc/infinispan-client-reference.adoc b/docs/src/main/asciidoc/infinispan-client-reference.adoc index a6fcee3da0771..6a49859d9c4fd 100644 --- a/docs/src/main/asciidoc/infinispan-client-reference.adoc +++ b/docs/src/main/asciidoc/infinispan-client-reference.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: data :summary: Infinispan is an in memory distributed data store and cache server that offers flexible deployment options and robust capabilities for storing, managing, and processing data. +:topics: data,infinispan +:extensions: io.quarkus:quarkus-infinispan-client Infinispan is a distributed, in-memory key/value store that provides Quarkus applications with a highly configurable and independently scalable data layer. diff --git a/docs/src/main/asciidoc/infinispan-client.adoc b/docs/src/main/asciidoc/infinispan-client.adoc index f787de4bd232c..06e08e5624225 100644 --- a/docs/src/main/asciidoc/infinispan-client.adoc +++ b/docs/src/main/asciidoc/infinispan-client.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: data :summary: This guide covers how to use Infinispan with Quarkus. +:topics: data,infinispan +:extensions: io.quarkus:quarkus-infinispan-client This guide demonstrates how your Quarkus application can connect to an Infinispan server using the Infinispan Client extension. diff --git a/docs/src/main/asciidoc/infinispan-dev-services.adoc b/docs/src/main/asciidoc/infinispan-dev-services.adoc index c88f079dcc94d..c2dfc3140a3ad 100644 --- a/docs/src/main/asciidoc/infinispan-dev-services.adoc +++ b/docs/src/main/asciidoc/infinispan-dev-services.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: data :summary: Start Infinispan automatically in dev and test modes. +:topics: devservices,data,infinispan,tooling,testing,devmode +:extensions: io.quarkus:quarkus-infinispan-client Quarkus supports a feature called Dev Services that allows you to create various datasources without any config. If you have docker running and have not configured `quarkus.infinispan-client.hosts`, diff --git a/docs/src/main/asciidoc/init-tasks.adoc b/docs/src/main/asciidoc/init-tasks.adoc index 082214330c88e..b29a45a398d40 100644 --- a/docs/src/main/asciidoc/init-tasks.adoc +++ b/docs/src/main/asciidoc/init-tasks.adoc @@ -6,6 +6,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Initialization tasks :categories: initialization :summary: This reference guide explains how to configure initialization tasks +:topics: init,kubernetes,openshift,liquibase,flyway +:extensions: io.quarkus:quarkus-kubernetes,io.quarkus:quarkus-openshift,io.quarkus:quarkus-flyway,io.quarkus:quarkus-liquibase There are often initialization tasks performed by Quarkus extensions that are meant to be run once. For example, Flyway or Liquibase initialization falls into that category. But what happens when the scaling @@ -13,8 +15,8 @@ needs of an application requires more instances of the application to run? Or wh restarts ? A common environment where both of these cases are pretty common is Kubernetes. To address these challenges, -Quarkus allows externalization of such tasks as Kubernetes https://kubernetes.io/docs/concepts/workloads/controllers/job/[Jobs] and uses https://kubernetes.io/docs/concepts/workloads/pods/init-containers/[init containers] to ensure that an -application instance only starts once the initialization jobs have finished. With this approach even if an +Quarkus allows externalization of such tasks as Kubernetes https://kubernetes.io/docs/concepts/workloads/controllers/job/[Jobs] and uses https://kubernetes.io/docs/concepts/workloads/pods/init-containers/[init containers] to ensure that an +application instance only starts once the initialization jobs have finished. With this approach even if an application has multiple replicas, the initialization logic will only run once. This approach is reflected in the manifests generated by xref:kubernetes.adoc[Kubernetes extension]. @@ -36,7 +38,7 @@ or on Openshift: quarkus.openshift.init-task-defaults.enabled=false ---- -**Note**: All the configuration options in this guide are available on both OpenShift and Kubernetes. The rest of the guide will use Kubernetes(`quarkus.kubernetes` prefix) +**Note**: All the configuration options in this guide are available on both OpenShift and Kubernetes. The rest of the guide will use Kubernetes(`quarkus.kubernetes` prefix) configuration prefix, but all the configuration options are also available for OpenShift(`quarkus.openshift` prefix) too. In the case where we need to disable a particular task, we can use the following property: @@ -131,11 +133,11 @@ quarkus.kubernetes.init-containers.wait-for-flyway=my/wait-for-image:1.0 === Configuring permissions For an init container to be able to perform the `wait for job` it needs to be able to perform `get` operations on the job resource. -This is done automatically and the generated manifests include the required `Role` and `RoleBinding` resources. +This is done automatically and the generated manifests include the required `Role` and `RoleBinding` resources. If for any reason additional permissions are required either by the init container or the job, they can be configured with through the xref:deploying-to-kuberentes.adoc#generating-rbac-resources[Kubernetes RBAC configuration]. -**Note**: The application, the init container and the job use the same `ServiceAccount` and therefore, share the same permissions. +**Note**: The application, the init container and the job use the same `ServiceAccount` and therefore, share the same permissions. == Extension providing Initialization Tasks diff --git a/docs/src/main/asciidoc/jms.adoc b/docs/src/main/asciidoc/jms.adoc index 629d29b56ec4e..c304466b2eae4 100644 --- a/docs/src/main/asciidoc/jms.adoc +++ b/docs/src/main/asciidoc/jms.adoc @@ -8,7 +8,8 @@ include::_attributes.adoc[] :categories: messaging :summary: This guide demonstrates how your Quarkus application can use JMS messaging with AMQP 1.0 using Apache Qpid JMS, or using Apache ActiveMQ Artemis JMS. :extension-status: preview - +:topics: messaging,jms,artemis,qpid,activemq +:extensions: org.amqphub.quarkus:quarkus-qpid-jms,io.quarkiverse.artemis:quarkus-artemis-jms This guide demonstrates how your Quarkus application can use JMS messaging via the Apache Qpid JMS AMQP client, or alternatively the Apache ActiveMQ Artemis JMS client. diff --git a/docs/src/main/asciidoc/jreleaser.adoc b/docs/src/main/asciidoc/jreleaser.adoc index 6a1ae287f2c5a..afe40f060fac7 100644 --- a/docs/src/main/asciidoc/jreleaser.adoc +++ b/docs/src/main/asciidoc/jreleaser.adoc @@ -10,6 +10,7 @@ include::_attributes.adoc[] :numbered: :sectnums: :sectnumlevels: 4 +:topics: tooling This guide covers packaging and releasing CLI applications using the link:https://jreleaser.org[JReleaser] tool. diff --git a/docs/src/main/asciidoc/kafka-dev-services.adoc b/docs/src/main/asciidoc/kafka-dev-services.adoc index e48283d851827..b6d32ba55e997 100644 --- a/docs/src/main/asciidoc/kafka-dev-services.adoc +++ b/docs/src/main/asciidoc/kafka-dev-services.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: messaging :summary: Start Apache Kafka automatically in dev and test modes. +:topics: messaging,kafka,devservices,tooling,testing,devmode +:extensions: io.quarkus:quarkus-kafka-client,io.quarkus:quarkus-smallrye-reactive-messaging-kafka If any Kafka-related extension is present (e.g. `quarkus-smallrye-reactive-messaging-kafka`), Dev Services for Kafka automatically starts a Kafka broker in dev mode and when running tests. So, you don't have to start a broker manually. diff --git a/docs/src/main/asciidoc/kafka-dev-ui.adoc b/docs/src/main/asciidoc/kafka-dev-ui.adoc index 049c884fd95c3..2625df6a7e224 100644 --- a/docs/src/main/asciidoc/kafka-dev-ui.adoc +++ b/docs/src/main/asciidoc/kafka-dev-ui.adoc @@ -7,8 +7,10 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: messaging :summary: Dev UI extension for Apache Kafka for development purposes. +:topics: messaging,kafka,dev-ui,devmode +:extensions: io.quarkus:quarkus-kafka-client,io.quarkus:quarkus-smallrye-reactive-messaging-kafka -If any Kafka-related extension is present (e.g. `quarkus-smallrye-reactive-messaging-kafka`), +If any Kafka-related extension is present (e.g. `quarkus-smallrye-reactive-messaging-kafka`), the Quarkus Dev UI is extended with a Kafka broker management UI. It is connected automatically to the Kafka broker configured for the application. diff --git a/docs/src/main/asciidoc/kafka-reactive-getting-started.adoc b/docs/src/main/asciidoc/kafka-reactive-getting-started.adoc index 90f3234693cad..cb4c541a3c9c1 100644 --- a/docs/src/main/asciidoc/kafka-reactive-getting-started.adoc +++ b/docs/src/main/asciidoc/kafka-reactive-getting-started.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: messaging :summary: This guide demonstrates how your Quarkus application can utilize SmallRye Reactive Messaging to interact with Apache Kafka. +:topics: messaging,kafka,reactive-messaging +:extensions: io.quarkus:quarkus-smallrye-reactive-messaging-kafka This guide demonstrates how your Quarkus application can utilize SmallRye Reactive Messaging to interact with Apache Kafka. diff --git a/docs/src/main/asciidoc/kafka-schema-registry-avro.adoc b/docs/src/main/asciidoc/kafka-schema-registry-avro.adoc index 05c9c0f98ac86..51d3a68b84cb4 100644 --- a/docs/src/main/asciidoc/kafka-schema-registry-avro.adoc +++ b/docs/src/main/asciidoc/kafka-schema-registry-avro.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: messaging :summary: Use Apache Kafka, Avro serialized records, and connect to a schema registry. +:topics: messaging,kafka,apicurio,registry +:extensions: io.quarkus:quarkus-apicurio-registry-avro,io.quarkus:quarkus-smallrye-reactive-messaging-kafka This guide shows how your Quarkus application can use Apache Kafka, https://avro.apache.org/docs/current/[Avro] serialized records, and connect to a schema registry (such as the https://docs.confluent.io/platform/current/schema-registry/index.html[Confluent Schema Registry] or https://www.apicur.io/registry/[Apicurio Registry]). diff --git a/docs/src/main/asciidoc/kafka-streams.adoc b/docs/src/main/asciidoc/kafka-streams.adoc index 9c832ac6ca8e2..e5cc5fa70d8fa 100644 --- a/docs/src/main/asciidoc/kafka-streams.adoc +++ b/docs/src/main/asciidoc/kafka-streams.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: messaging :summary: This guide demonstrates how your Quarkus application can utilize the Apache Kafka Streams API to implement stream processing applications based on Apache Kafka. +:topics: messaging,kafka,kafka-streams +:extensions: io.quarkus:quarkus-kafka-streams This guide demonstrates how your Quarkus application can utilize the Apache Kafka Streams API to implement stream processing applications based on Apache Kafka. @@ -466,7 +468,7 @@ TIP: Alternatively, you can use `kafka.bootstrap.servers` instead of `quarkus.ka [NOTE] ==== -Once you are ready to promote your application into production, consider changing the above configuration values. While `cache.max.bytes.buffering=10240` will move your records faster through the topology, the default value of `10485760` is more throughput-friendly. Also condider increasing `metadata.max.age.ms` from `500`, which will update cluster metadata quickly, but will generate a lot of redundant requests, to a value closer to the default of `300000`. A `commit.interval.ms` of `1000` is good for exactly-once processing, but might generate excessive load for the default at-least-once processing with the default value of `30000`. +Once you are ready to promote your application into production, consider changing the above configuration values. While `cache.max.bytes.buffering=10240` will move your records faster through the topology, the default value of `10485760` is more throughput-friendly. Also condider increasing `metadata.max.age.ms` from `500`, which will update cluster metadata quickly, but will generate a lot of redundant requests, to a value closer to the default of `300000`. A `commit.interval.ms` of `1000` is good for exactly-once processing, but might generate excessive load for the default at-least-once processing with the default value of `30000`. ==== All the properties within the `kafka-streams` namespace are passed through as-is to the Kafka Streams engine. diff --git a/docs/src/main/asciidoc/kafka.adoc b/docs/src/main/asciidoc/kafka.adoc index a76c98778f8a5..e3782c07e51ae 100644 --- a/docs/src/main/asciidoc/kafka.adoc +++ b/docs/src/main/asciidoc/kafka.adoc @@ -10,6 +10,8 @@ include::_attributes.adoc[] :numbered: :sectnums: :sectnumlevels: 4 +:topics: messaging,kafka,reactive-messaging +:extensions: io.quarkus:quarkus-smallrye-reactive-messaging-kafka This reference guide demonstrates how your Quarkus application can utilize SmallRye Reactive Messaging to interact with Apache Kafka. @@ -350,12 +352,12 @@ If `throttled.unprocessed-record-max-age.ms` is set to less than or equal to `0` Such a setting might lead to running out of memory if there are "poison pill" messages (that are never acked). This strategy is the default if `enable.auto.commit` is not explicitly set to true. -- `checkpoint` allows persisting consumer offsets on a **state store**, instead of committing them back to the Kafka broker. -Using the `CheckpointMetadata` API, consumer code can persist a _processing state_ with the record offset to mark the progress of a consumer. -When the processing continues from a previously persisted offset, it seeks the Kafka consumer to that offset and also restores the persisted state, continuing the stateful processing from where it left off. -The checkpoint strategy holds locally the processing state associated with the latest offset, and persists it periodically to the state store (period specified by `auto.commit.interval.ms` (default: 5000)). -The connector will be marked as unhealthy if no processing state is persisted to the state store in `checkpoint.unsynced-state-max-age.ms` (default: 10000). -If `checkpoint.unsynced-state-max-age.ms` is set to less than or equal to 0, it does not perform any health check verification. +- `checkpoint` allows persisting consumer offsets on a **state store**, instead of committing them back to the Kafka broker. +Using the `CheckpointMetadata` API, consumer code can persist a _processing state_ with the record offset to mark the progress of a consumer. +When the processing continues from a previously persisted offset, it seeks the Kafka consumer to that offset and also restores the persisted state, continuing the stateful processing from where it left off. +The checkpoint strategy holds locally the processing state associated with the latest offset, and persists it periodically to the state store (period specified by `auto.commit.interval.ms` (default: 5000)). +The connector will be marked as unhealthy if no processing state is persisted to the state store in `checkpoint.unsynced-state-max-age.ms` (default: 10000). +If `checkpoint.unsynced-state-max-age.ms` is set to less than or equal to 0, it does not perform any health check verification. For more information, see <> - `latest` commits the record offset received by the Kafka consumer as soon as the associated message is acknowledged (if the offset is higher than the previously committed offset). @@ -713,17 +715,17 @@ The `checkpoint` commit strategy is an experimental feature and can change in th ==== Smallrye Reactive Messaging `checkpoint` commit strategy allows consumer applications to process messages in a stateful manner, while also respecting Kafka consumer scalability. -An incoming channel with `checkpoint` commit strategy persists consumer offsets on an external +An incoming channel with `checkpoint` commit strategy persists consumer offsets on an external <>, such as a relational database or a key-value store. -As a result of processing consumed records, the consumer application can accumulate an internal state for each topic-partition assigned to the Kafka consumer. +As a result of processing consumed records, the consumer application can accumulate an internal state for each topic-partition assigned to the Kafka consumer. This local state will be periodically persisted to the state store and will be associated with the offset of the record that produced it. -This strategy does not commit any offsets to the Kafka broker, so when new partitions get assigned to the consumer, -i.e. consumer restarts or consumer group instances scale, +This strategy does not commit any offsets to the Kafka broker, so when new partitions get assigned to the consumer, +i.e. consumer restarts or consumer group instances scale, the consumer resumes the processing from the latest _checkpointed_ offset with its saved state. The `@Incoming` channel consumer code can manipulate the processing state through the `CheckpointMetadata` API. -For example, a consumer calculating the moving average of prices received on a Kafka topic would look the following: +For example, a consumer calculating the moving average of prices received on a Kafka topic would look the following: [source,java] ---- @@ -746,20 +748,20 @@ public class MeanCheckpointConsumer { public CompletionStage consume(Message record) { // Get the `CheckpointMetadata` from the incoming message CheckpointMetadata checkpoint = CheckpointMetadata.fromMessage(record); - + // `CheckpointMetadata` allows transforming the processing state // Applies the given function, starting from the value `0.0` when no previous state exists checkpoint.transform(new AveragePrice(), average -> average.update(record.getPayload()), /* persistOnAck */ true); - + // `persistOnAck` flag set to true, ack will persist the processing state // associated with the latest offset (per partition). return record.ack(); } - + static class AveragePrice { long count; double mean; - + AveragePrice update(double newPrice) { mean += ((newPrice - mean) / ++count); return this; @@ -768,25 +770,25 @@ public class MeanCheckpointConsumer { } ---- -The `transform` method applies the transformation function to the current state, producing a changed state and registering it locally for checkpointing. -By default, the local state is persisted to the state store periodically, period specified by `auto.commit.interval.ms`, (default: 5000). -If `persistOnAck` flag is given, the latest state is persisted to the state store eagerly on message acknowledgment. +The `transform` method applies the transformation function to the current state, producing a changed state and registering it locally for checkpointing. +By default, the local state is persisted to the state store periodically, period specified by `auto.commit.interval.ms`, (default: 5000). +If `persistOnAck` flag is given, the latest state is persisted to the state store eagerly on message acknowledgment. The `setNext` method works similarly directly setting the latest state. -The checkpoint commit strategy tracks when a processing state is last persisted for each topic-partition. +The checkpoint commit strategy tracks when a processing state is last persisted for each topic-partition. If an outstanding state change can not be persisted for `checkpoint.unsynced-state-max-age.ms` (default: 10000), the channel is marked unhealthy. [[state-stores]] ==== State stores -State store implementations determine where and how the processing states are persisted. +State store implementations determine where and how the processing states are persisted. This is configured by the `mp.messaging.incoming.[channel-name].checkpoint.state-store` property. -The serialization of state objects depends on the state store implementation. +The serialization of state objects depends on the state store implementation. In order to instruct state stores for serialization can require configuring the class name of state objects using `mp.messaging.incoming.[channel-name].checkpoint.state-type` property. Quarkus provides following state store implementations: -- `quarkus-redis`: Uses the xref:redis-reference.adoc[`quarkus-redis-client`] extension to persist processing states. +- `quarkus-redis`: Uses the xref:redis-reference.adoc[`quarkus-redis-client`] extension to persist processing states. Jackson is used to serialize processing state in Json. For complex objects it is required to configure the `checkpoint.state-type` property with the class name of the object. By default, the state store uses the default redis client, but if a xref:redis-reference.adoc#default-and-named-clients[named client] is to be used, the client name can be specified using the `mp.messaging.incoming.[channel-name].checkpoint.quarkus-redis.client-name` property. Processing states will be stored in Redis using the key naming scheme `[consumer-group-id]:[topic]:[partition]`. @@ -807,8 +809,8 @@ quarkus.redis.my-redis.hosts=redis://localhost:7000 quarkus.redis.my-redis.password= ---- -- `quarkus-hibernate-reactive`: Uses the xref:hibernate-reactive.adoc[`quarkus-hibernate-reactive`] extension to persist processing states. -Processing state objects are required to be a Jakarta Persistence entity and extend the `CheckpointEntity` class, +- `quarkus-hibernate-reactive`: Uses the xref:hibernate-reactive.adoc[`quarkus-hibernate-reactive`] extension to persist processing states. +Processing state objects are required to be a Jakarta Persistence entity and extend the `CheckpointEntity` class, which handles object identifiers composed of the consumer group id, topic and partition. Therefore, the class name of the entity needs to be configured using the `checkpoint.state-type` property. @@ -846,7 +848,7 @@ public class AveragePriceEntity extends CheckpointEntity { ---- - `quarkus-hibernate-orm`: Uses the xref:hibernate-orm.adoc[`quarkus-hibernate-orm`] extension to persist processing states. -It is similar to the previous state store, but it uses Hibernate ORM instead of Hibernate Reactive. +It is similar to the previous state store, but it uses Hibernate ORM instead of Hibernate Reactive. When configured, it can use a named `persistence-unit` for the checkpointing state store: @@ -865,7 +867,7 @@ quarkus.hibernate-orm."prices".datasource=prices quarkus.hibernate-orm."prices".packages=org.acme ---- -For instructions on how to implement custom state stores, +For instructions on how to implement custom state stores, see https://smallrye.io/smallrye-reactive-messaging/3.22.0/kafka/receiving-kafka-records/#implementing-state-stores[Implementing State Stores]. == Sending messages to Kafka @@ -2690,9 +2692,9 @@ public class FruitStore { } ---- <1> Inject the Hibernate Reactive `Session` -<2> Hibernate Reactive `Session` and `Panache` APIs require an active CDI Request context. +<2> Hibernate Reactive `Session` and `Panache` APIs require an active CDI Request context. `@ActivateRequestContext` annotation creates a new request context and destroys it when the `Uni` returned from the method completes. -If `Panache` is not used, `Mutiny.SessionFactory` can be injected and used similarly without the need of activating the request context or closing the session manually. +If `Panache` is not used, `Mutiny.SessionFactory` can be injected and used similarly without the need of activating the request context or closing the session manually. <3> Requests a new transaction. The transaction completes when the passed action completes. <4> Persist the entity. It returns a `Uni`. <5> Switch back to a `Uni`. diff --git a/docs/src/main/asciidoc/kotlin.adoc b/docs/src/main/asciidoc/kotlin.adoc index 17ef00743b057..644dbb97176c2 100644 --- a/docs/src/main/asciidoc/kotlin.adoc +++ b/docs/src/main/asciidoc/kotlin.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: alt-languages :summary: This guide explains how to use Kotlin. +:topics: kotlin +:extensions: io.quarkus:quarkus-kotlin https://kotlinlang.org/[Kotlin] is a very popular programming language that targets the JVM (amongst other environments). Kotlin has experienced a surge in popularity the last few years making it the most popular JVM language, except for Java of course. diff --git a/docs/src/main/asciidoc/kubernetes-client.adoc b/docs/src/main/asciidoc/kubernetes-client.adoc index ca75c11fc8b91..6dcaeb41828fa 100644 --- a/docs/src/main/asciidoc/kubernetes-client.adoc +++ b/docs/src/main/asciidoc/kubernetes-client.adoc @@ -7,7 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: This guide demonstrates how to use the Fabric8 Kubernetes client to interact with your Kubernetes cluster. - +:topics: kubernetes,openshift,kubernetes-client +:extensions: io.quarkus:quarkus-kubernetes-client Quarkus includes the `kubernetes-client` extension which enables the use of the https://github.com/fabric8io/kubernetes-client[Fabric8 Kubernetes Client] in native mode while also making it easier to work with. diff --git a/docs/src/main/asciidoc/kubernetes-config.adoc b/docs/src/main/asciidoc/kubernetes-config.adoc index b824b17d4e48b..0654b09431b6c 100644 --- a/docs/src/main/asciidoc/kubernetes-config.adoc +++ b/docs/src/main/asciidoc/kubernetes-config.adoc @@ -7,7 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: Use ConfigMaps as a configuration source for your Quarkus applications. - +:topics: kubernetes,openshift,configuration,configmap +:extensions: io.quarkus:quarkus-kubernetes-config Quarkus includes the `kubernetes-config` extension which allows developers to use Kubernetes https://cloud.google.com/kubernetes-engine/docs/concepts/configmap[ConfigMaps] and https://cloud.google.com/kubernetes-engine/docs/concepts/secret[Secrets] as a configuration source, without having to mount them into the https://kubernetes.io/docs/concepts/workloads/pods/pod/[Pod] running the Quarkus application or make any other modifications to their Kubernetes `Deployment` (or OpenShift `DeploymentConfig`). diff --git a/docs/src/main/asciidoc/kubernetes-dev-services.adoc b/docs/src/main/asciidoc/kubernetes-dev-services.adoc index 15e23210c6b47..bd2e9bfa0e48f 100644 --- a/docs/src/main/asciidoc/kubernetes-dev-services.adoc +++ b/docs/src/main/asciidoc/kubernetes-dev-services.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: cloud :summary: Start a Kubernetes API server automatically in dev and test modes. +:topics: devservices,kubernetes,tooling,testing,devmode +:extensions: io.quarkus:quarkus-kubernetes-client Dev Services for Kubernetes automatically starts a Kubernetes API server in dev mode and when running tests. So you don't have to start a Kubernetes cluster manually. @@ -19,7 +21,7 @@ Dev Services for Kubernetes is automatically enabled unless: - `quarkus.kubernetes-client.devservices.enabled` is set to `false` - the `api-server-url` is configured - a valid Kube config file is found and `quarkus.kubernetes-client.devservices.override-kubeconfig` is not set to `true` -- you include the `quarkus-test-kubernetes-client` dependency +- you include the `quarkus-test-kubernetes-client` dependency Dev Services for Kubernetes relies on Docker to start the API server. If your environment does not support Docker, you will need to start the Kubernetes cluster manually, or connect to an already running Kubernetes cluster. diff --git a/docs/src/main/asciidoc/lifecycle.adoc b/docs/src/main/asciidoc/lifecycle.adoc index 400cdc552b90d..539b59006bb73 100644 --- a/docs/src/main/asciidoc/lifecycle.adoc +++ b/docs/src/main/asciidoc/lifecycle.adoc @@ -8,6 +8,8 @@ include::_attributes.adoc[] :categories: core :keywords: lifecycle event :summary: You often need to execute custom actions when the application starts and clean up everything when the application stops. This guide explains how to be notified when an application stops or starts. +:topics: lifecycle,observers +:extensions: io.quarkus:quarkus-core,io.quarkus:quarkus-arc You often need to execute custom actions when the application starts and clean up everything when the application stops. This guide explains how to: diff --git a/docs/src/main/asciidoc/liquibase-mongodb.adoc b/docs/src/main/asciidoc/liquibase-mongodb.adoc index a9e37fcab7f21..81c112257a617 100644 --- a/docs/src/main/asciidoc/liquibase-mongodb.adoc +++ b/docs/src/main/asciidoc/liquibase-mongodb.adoc @@ -5,8 +5,11 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Using Liquibase MongoDB include::_attributes.adoc[] +:categories: data :change-log: src/main/resources/db/changeLog.xml :config-file: application.properties +:topics: data,schema-migration,liquibase,mongodb +:extensions: io.quarkus:quarkus-liquibase-mongodb https://www.liquibase.org/[Liquibase] is an open source tool for database schema change management, it allows managing MongoDB databases via it's https://github.com/liquibase/liquibase-mongodb[MongoDB Extension]. diff --git a/docs/src/main/asciidoc/liquibase.adoc b/docs/src/main/asciidoc/liquibase.adoc index 7b240c995e921..133226eb895c0 100644 --- a/docs/src/main/asciidoc/liquibase.adoc +++ b/docs/src/main/asciidoc/liquibase.adoc @@ -9,6 +9,8 @@ include::_attributes.adoc[] :summary: This guide covers how to use the Liquibase extension to manage your schema migrations. :change-log: src/main/resources/db/changeLog.xml :config-file: application.properties +:topics: data,schema-migration,liquibase +:extensions: io.quarkus:quarkus-liquibase https://www.liquibase.org/[Liquibase] is an open source tool for database schema change management. diff --git a/docs/src/main/asciidoc/logging.adoc b/docs/src/main/asciidoc/logging.adoc index 1754ca8a8b1eb..7bc595abbcd02 100644 --- a/docs/src/main/asciidoc/logging.adoc +++ b/docs/src/main/asciidoc/logging.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: core,getting-started,observability :diataxis-type: reference +:topics: logging,observability +:extensions: io.quarkus:quarkus-core Read about the use of logging API in Quarkus, configuring logging output, and using logging adapters to unify the output from other logging APIs. @@ -441,7 +443,7 @@ For details about its configuration, see the xref:#quarkus-log-logging-log-confi To log events to a file on the application's host, use the Quarkus file log handler. The file log handler is disabled by default, so you must first enable it. -The Quarkus file log handler supports log file rotation. +The Quarkus file log handler supports log file rotation. Log file rotation ensures effective log file management over time by maintaining a specified number of backup log files, while also keeping the primary log file up-to-date and manageable. Log file rotation ensures effective log file management over time by maintaining a specified number of backup log files, while keeping the primary log file up-to-date and manageable. diff --git a/docs/src/main/asciidoc/lra.adoc b/docs/src/main/asciidoc/lra.adoc index 89a804aa51d38..4a4445e678fc3 100644 --- a/docs/src/main/asciidoc/lra.adoc +++ b/docs/src/main/asciidoc/lra.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: data :summary: This guides covers the usage of LRA to coordinate activities across services. +:topics: data,lra,narayana +:extensions: io.quarkus:quarkus-narayana-lra == Introduction diff --git a/docs/src/main/asciidoc/mailer-reference.adoc b/docs/src/main/asciidoc/mailer-reference.adoc index 2a4946c4f38da..399c63c259b9d 100644 --- a/docs/src/main/asciidoc/mailer-reference.adoc +++ b/docs/src/main/asciidoc/mailer-reference.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: miscellaneous :summary: This reference guide explains in more details the configuration and usage of the Quarkus Mailer. +:topics: mail,mailer +:extensions: io.quarkus:quarkus-mailer This guide is the companion from the xref:mailer.adoc[Mailer Getting Started Guide]. It explains in more details the configuration and usage of the Quarkus Mailer. diff --git a/docs/src/main/asciidoc/mailer.adoc b/docs/src/main/asciidoc/mailer.adoc index 4c1fbd60a764d..44cb28b56c25b 100644 --- a/docs/src/main/asciidoc/mailer.adoc +++ b/docs/src/main/asciidoc/mailer.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: miscellaneous :summary: Learn more about how you can send email from a Quarkus application with our reactive email client. +:topics: mail,mailer +:extensions: io.quarkus:quarkus-mailer This guide demonstrates how your Quarkus application can send emails using an SMTP server. This is a getting started guide. diff --git a/docs/src/main/asciidoc/management-interface-reference.adoc b/docs/src/main/asciidoc/management-interface-reference.adoc index fd7e0ca4bd7b0..345592ca61f9d 100644 --- a/docs/src/main/asciidoc/management-interface-reference.adoc +++ b/docs/src/main/asciidoc/management-interface-reference.adoc @@ -10,6 +10,8 @@ include::_attributes.adoc[] :numbered: :sectnums: :sectnumlevels: 4 +:topics: management,observability +:extensions: io.quarkus:quarkus-vertx-http By default, Quarkus exposes the _management_ endpoints under `/q` on the main HTTP server. The same HTTP server provides the application endpoints and the management endpoints. diff --git a/docs/src/main/asciidoc/maven-tooling.adoc b/docs/src/main/asciidoc/maven-tooling.adoc index f0e278d80f2ef..55958a8b97966 100644 --- a/docs/src/main/asciidoc/maven-tooling.adoc +++ b/docs/src/main/asciidoc/maven-tooling.adoc @@ -9,6 +9,7 @@ include::_attributes.adoc[] :categories: tooling, native :summary: Develop and build your Quarkus application with Maven :devtools-no-gradle: +:topics: maven,tooling Use Maven to create a new project, add or remove extensions, launch development mode, debug your application, and build your application into a jar, native executable, or container-friendly executable. Import your project into your favorite IDE using Maven project metadata. @@ -1063,23 +1064,23 @@ Here is an example `info` output for a simple project: ---- [aloubyansky@localhost code-with-quarkus]$ mvn quarkus:info [INFO] Scanning for projects... -[INFO] +[INFO] [INFO] ---------------------< org.acme:code-with-quarkus >--------------------- [INFO] Building code-with-quarkus 1.0.0-SNAPSHOT [INFO] --------------------------------[ jar ]--------------------------------- -[INFO] +[INFO] [INFO] --- quarkus-maven-plugin:{quarkus-version}:info (default-cli) @ code-with-quarkus --- [WARNING] quarkus:info goal is experimental, its options and output may change in future versions [INFO] Quarkus platform BOMs: <1> [INFO] {quarkus-platform-groupid}:quarkus-bom:pom:{quarkus-version} [INFO] {quarkus-platform-groupid}:quarkus-camel-bom:pom:{quarkus-version} -[INFO] +[INFO] [INFO] Extensions from {quarkus-platform-groupid}:quarkus-bom: <2> [INFO] io.quarkus:quarkus-resteasy-reactive -[INFO] +[INFO] [INFO] Extensions from {quarkus-platform-groupid}:quarkus-camel-bom: <3> [INFO] org.apache.camel.quarkus:camel-quarkus-rabbitmq -[INFO] +[INFO] [INFO] Extensions from registry.quarkus.io: <4> [INFO] io.quarkiverse.prettytime:quarkus-prettytime:0.2.1 ---- @@ -1103,13 +1104,13 @@ NOTE: `quarkus:info` will also report Quarkus extensions that aren't found in th [INFO] Quarkus platform BOMs: [INFO] {quarkus-platform-groupid}:quarkus-bom:pom:{quarkus-version} [INFO] {quarkus-platform-groupid}:quarkus-camel-bom:pom:{quarkus-version} | unnecessary <1> -[INFO] +[INFO] [INFO] Extensions from {quarkus-platform-groupid}:quarkus-bom: [INFO] io.quarkus:quarkus-resteasy-reactive:2.6.3.Final | misaligned <2> -[INFO] +[INFO] [INFO] Extensions from {quarkus-platform-groupid}:quarkus-camel-bom: [INFO] org.apache.camel.quarkus:camel-quarkus-rabbitmq -[INFO] +[INFO] [INFO] Extensions from registry.quarkus.io: [INFO] io.quarkiverse.prettytime:quarkus-prettytime:0.2.1 [INFO] @@ -1136,14 +1137,14 @@ Assuming we have a project including Kogito, Camel and core Quarkus extensions a ---- [aloubyansky@localhost code-with-quarkus]$ mvn quarkus:update [INFO] Scanning for projects... -[INFO] +[INFO] [INFO] ---------------------< org.acme:code-with-quarkus >--------------------- [INFO] Building code-with-quarkus 1.0.0-SNAPSHOT [INFO] --------------------------------[ jar ]--------------------------------- -[INFO] +[INFO] [INFO] --- quarkus-maven-plugin:{quarkus-version}:update (default-cli) @ code-with-quarkus --- [WARNING] quarkus:update goal is experimental, its options and output might change in future versions -[INFO] +[INFO] [INFO] Recommended Quarkus platform BOM updates: <1> [INFO] Update: {quarkus-platform-groupid}:quarkus-bom:pom:2.7.1.Final -> {quarkus-version} [INFO] Update: {quarkus-platform-groupid}:quarkus-camel-bom:pom:2.7.1.Final -> {quarkus-version} @@ -1160,10 +1161,10 @@ If we modify the project to remove all the Camel Quarkus extensions from the pro [INFO] Recommended Quarkus platform BOM updates: <1> [INFO] Update: {quarkus-platform-groupid}:quarkus-bom:pom:2.7.1.Final -> {quarkus-version} [INFO] Remove: {quarkus-platform-groupid}:quarkus-camel-bom:pom:2.7.1.Final <2> -[INFO] +[INFO] [INFO] Extensions from {quarkus-platform-groupid}:quarkus-bom: [INFO] Update: io.quarkus:quarkus-resteasy-reactive:2.6.3.Final -> remove version (managed) <3> -[INFO] +[INFO] [INFO] Extensions from registry.quarkus.io: [INFO] Update: io.quarkiverse.prettytime:quarkus-prettytime:0.2.0 -> 0.2.1 <4> ---- diff --git a/docs/src/main/asciidoc/messaging-virtual-threads.adoc b/docs/src/main/asciidoc/messaging-virtual-threads.adoc index ccf8a9f0b6ad6..2612dcb74220f 100644 --- a/docs/src/main/asciidoc/messaging-virtual-threads.adoc +++ b/docs/src/main/asciidoc/messaging-virtual-threads.adoc @@ -5,6 +5,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Quarkus Virtual Thread support with Reactive Messaging include::_attributes.adoc[] +:categories: messaging +:topics: messaging,kafka,reactive-messaging,virtual-threads +:extensions: io.quarkus:quarkus-smallrye-reactive-messaging-kafka :runonvthread: https://javadoc.io/doc/io.smallrye.common/smallrye-common-annotation/latest/io/smallrye/common/annotation/RunOnVirtualThread.html :rm_blocking_annotation: https://javadoc.io/doc/io.smallrye.reactive/smallrye-reactive-messaging-api/latest/io/smallrye/reactive/messaging/annotations/Blocking.html :rm_blocking_docs: http://smallrye.io/smallrye-reactive-messaging/4.8.0/concepts/blocking/ diff --git a/docs/src/main/asciidoc/mongodb-panache-kotlin.adoc b/docs/src/main/asciidoc/mongodb-panache-kotlin.adoc index 7a28074d3724e..95bf7aa870947 100644 --- a/docs/src/main/asciidoc/mongodb-panache-kotlin.adoc +++ b/docs/src/main/asciidoc/mongodb-panache-kotlin.adoc @@ -8,6 +8,8 @@ include::_attributes.adoc[] :categories: data, alt-languages :summary: This guide covers the usage of MongoDB using active records and repositories in a Kotlin project. :config-file: application.properties +:topics: data,mongodb,nosql,panache,kotlin +:extensions: io.quarkus:quarkus-mongodb-panache-kotlin,io.quarkus:quarkus-mongodb-panache,io.quarkus:quarkus-mongodb-client MongoDB is a well known NoSQL Database that is widely used. MongoDB with Panache offers a new layer atop this familiar framework. This guide will not dive in to the specifics of either as those are already diff --git a/docs/src/main/asciidoc/mongodb-panache.adoc b/docs/src/main/asciidoc/mongodb-panache.adoc index ad8bcf4c1a8e9..0acbb0a762fe9 100644 --- a/docs/src/main/asciidoc/mongodb-panache.adoc +++ b/docs/src/main/asciidoc/mongodb-panache.adoc @@ -9,6 +9,8 @@ include::_attributes.adoc[] :summary: This guide covers the usage of MongoDB using active records and repositories. :config-file: application.properties :mongodb-doc-root-url: https://www.mongodb.com/docs/drivers/java/sync/current +:topics: data,mongodb,nosql,panache,kotlin +:extensions: io.quarkus:quarkus-mongodb-panache,io.quarkus:quarkus-mongodb-client MongoDB is a well known NoSQL Database that is widely used, but using its raw API can be cumbersome as you need to express your entities and your queries as a MongoDB link:{mongodb-doc-root-url}/fundamentals/data-formats/documents/#document[`Document`]. @@ -1260,14 +1262,14 @@ this file manually in some cases. == Multitenancy -"Multitenancy is a software architecture where a single software instance can serve multiple, distinct user groups. Software-as-a-service (SaaS) +"Multitenancy is a software architecture where a single software instance can serve multiple, distinct user groups. Software-as-a-service (SaaS) offerings are an example of multitenant architecture." (link:https://www.redhat.com/en/topics/cloud-computing/what-is-multitenancy#:~:text=Multitenancy%20is%20a%20software%20architecture,an%20example%20of%20multitenant%20architecture.[Red Hat]). MongoDB with Panache currently supports the database per tenant approach, it's similar to schema per tenant approach when compared to SQL databases. === Writing the application -In order to resolve the tenant from incoming requests and map it to a specific database, you must create an implementation +In order to resolve the tenant from incoming requests and map it to a specific database, you must create an implementation of the `io.quarkus.mongodb.panache.common.MongoDatabaseResolver` interface. [source,java] @@ -1280,26 +1282,26 @@ public class CustomMongoDatabaseResolver implements MongoDatabaseResolver { @Inject RoutingContext context; - + @Override public String resolve() { return context.request().getHeader("X-Tenant"); } - + } ---- <1> The bean is made `@RequestScoped` as the tenant resolution depends on the incoming request. [IMPORTANT] ==== -The database selection priority order is as follow: `@MongoEntity(database="mizain")`, `MongoDatabaseResolver`, +The database selection priority order is as follow: `@MongoEntity(database="mizain")`, `MongoDatabaseResolver`, and then `quarkus.mongodb.database` property. ==== [NOTE] ==== -If you also use xref:security-openid-connect-multitenancy.adoc[OIDC multitenancy], then if the OIDC tenantID and MongoDB -database are the same and must be extracted from the Vert.x `RoutingContext` you can pass the tenant id from the OIDC `TenantResolver` +If you also use xref:security-openid-connect-multitenancy.adoc[OIDC multitenancy], then if the OIDC tenantID and MongoDB +database are the same and must be extracted from the Vert.x `RoutingContext` you can pass the tenant id from the OIDC `TenantResolver` to the MongoDB with Panache `MongoDatabaseResolver` as a `RoutingContext` attribute, for example: [source,java] @@ -1367,7 +1369,7 @@ public class PersonResource { } ---- -From the classes above, we have enough to persist and fetch persons from different databases, so it's possible to see how it works. +From the classes above, we have enough to persist and fetch persons from different databases, so it's possible to see how it works. === Configuring the application @@ -1424,7 +1426,7 @@ public class PanacheMongoMultiTenancyTest { // creating person 1 Response createPerson1Response = callCreatePersonEndpoint(endpoint, TENANT_1, person1); assertResponse(createPerson1Response, 201); - + // checking person 1 creation Response getPerson1ByIdResponse = callGetPersonByIdEndpoint(endpoint, person1.id, TENANT_1); assertResponse(getPerson1ByIdResponse, 200, person1); diff --git a/docs/src/main/asciidoc/mongodb.adoc b/docs/src/main/asciidoc/mongodb.adoc index f2b7727741f3b..cd3cbfc4b3d14 100644 --- a/docs/src/main/asciidoc/mongodb.adoc +++ b/docs/src/main/asciidoc/mongodb.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: data :summary: This guide covers how to use MongoDB in Quarkus. +:topics: data,mongodb,nosql +:extensions: io.quarkus:quarkus-mongodb-client MongoDB is a well known NoSQL Database that is widely used. diff --git a/docs/src/main/asciidoc/mutiny-primer.adoc b/docs/src/main/asciidoc/mutiny-primer.adoc index 78753c348d8b6..69c1c429af5ba 100644 --- a/docs/src/main/asciidoc/mutiny-primer.adoc +++ b/docs/src/main/asciidoc/mutiny-primer.adoc @@ -5,6 +5,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Mutiny - Async for bare mortal include::_attributes.adoc[] +:categories: reactive +:topics: mutiny,reactive +:extensions: io.quarkus:quarkus-mutiny https://smallrye.io/smallrye-mutiny[Mutiny] is an intuitive, reactive programming library. It is the primary model to write reactive applications with Quarkus. diff --git a/docs/src/main/asciidoc/native-and-ssl.adoc b/docs/src/main/asciidoc/native-and-ssl.adoc index f61b72f2f230b..8ba2bbaafcc7a 100644 --- a/docs/src/main/asciidoc/native-and-ssl.adoc +++ b/docs/src/main/asciidoc/native-and-ssl.adoc @@ -8,6 +8,7 @@ include::_attributes.adoc[] :categories: core, native, security :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. :devtools-no-gradle: +:topics: native,ssl We are quickly moving to an SSL-everywhere world so being able to use SSL is crucial. diff --git a/docs/src/main/asciidoc/native-reference.adoc b/docs/src/main/asciidoc/native-reference.adoc index 80acfde8fac39..d2fba7cbe0721 100644 --- a/docs/src/main/asciidoc/native-reference.adoc +++ b/docs/src/main/asciidoc/native-reference.adoc @@ -7,6 +7,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Native Reference Guide include::_attributes.adoc[] :categories: native +:topics: native This guide is a companion to the xref:building-native-image.adoc[Building a Native Executable], diff --git a/docs/src/main/asciidoc/openapi-swaggerui.adoc b/docs/src/main/asciidoc/openapi-swaggerui.adoc index f8743e2bbb558..e355c05f8d687 100644 --- a/docs/src/main/asciidoc/openapi-swaggerui.adoc +++ b/docs/src/main/asciidoc/openapi-swaggerui.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: web :summary: This guide explains how to use the OpenAPI extension to generate an OpenAPI descriptor and get a Swagger UI frontend to test your REST endpoints. +:topics: rest,openapi,swagger-ui,dev-ui +:extensions: io.quarkus:quarkus-smallrye-openapi This guide explains how your Quarkus application can expose its API description through an OpenAPI specification and how you can test it via a user-friendly UI named Swagger UI. @@ -511,7 +513,7 @@ To supply your own logo, you need to place a file called `logo.png` in `src/main This will set the logo for all UIs (not just swagger ui), so in this case also GraphQL-UI and Health-UI (if included). -If you only want to apply this logo to swagger-ui (and not globally to all UIs) call the file `smallrye-open-api-ui.png` +If you only want to apply this logo to swagger-ui (and not globally to all UIs) call the file `smallrye-open-api-ui.png` rather than `logo.png`. ==== CSS @@ -520,7 +522,7 @@ To supply your own css that override/enhance style in the html, you need to plac This will add that css to all UIs (not just swagger ui), so in this case also GraphQL-UI and Health-UI (if included). -If you only want to apply this style to swagger-ui (and not globally to all UIs) call the file `smallrye-open-api-ui.css` +If you only want to apply this style to swagger-ui (and not globally to all UIs) call the file `smallrye-open-api-ui.css` rather than `style.css`. For more information on styling, read this blog entry: https://quarkus.io/blog/stylish-api/ diff --git a/docs/src/main/asciidoc/opentelemetry.adoc b/docs/src/main/asciidoc/opentelemetry.adoc index 669f54e51f43d..899a1ed320a61 100644 --- a/docs/src/main/asciidoc/opentelemetry.adoc +++ b/docs/src/main/asciidoc/opentelemetry.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: observability :summary: This guide explains how your Quarkus application can utilize OpenTelemetry to provide distributed tracing for interactive web applications. +:topics: observability,opentelemetry +:extensions: io.quarkus:quarkus-opentelemetry This guide explains how your Quarkus application can utilize https://opentelemetry.io/[OpenTelemetry] (OTel) to provide distributed tracing for interactive web applications. diff --git a/docs/src/main/asciidoc/opentracing.adoc b/docs/src/main/asciidoc/opentracing.adoc index 999a41adbc36f..88fb99d143a77 100644 --- a/docs/src/main/asciidoc/opentracing.adoc +++ b/docs/src/main/asciidoc/opentracing.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: observability :summary: This guide explains how your Quarkus application can utilize OpenTracing to provide distributed tracing for interactive web applications. +:topics: observability,opentracing +:extensions: io.quarkus:quarkus-smallrye-opentracing This guide explains how your Quarkus application can utilize OpenTracing to provide distributed tracing for interactive web applications. @@ -314,7 +316,7 @@ Following the xref:mongodb.adoc[MongoDB guide], the command listener will be reg [source, properties] ---- -# Enable tracing commands in mongodb client +# Enable tracing commands in mongodb client quarkus.mongodb.tracing.enabled=true ---- @@ -342,8 +344,8 @@ The zipkin compatibility mode will be activated after defining the config proper [source, properties] ---- -# Enable zipkin compatibility mode -quarkus.jaeger.zipkin.compatibility-mode=true +# Enable zipkin compatibility mode +quarkus.jaeger.zipkin.compatibility-mode=true ---- [[configuration-reference]] diff --git a/docs/src/main/asciidoc/performance-measure.adoc b/docs/src/main/asciidoc/performance-measure.adoc index 51ca1c4b1e1b9..f18d708c94edd 100644 --- a/docs/src/main/asciidoc/performance-measure.adoc +++ b/docs/src/main/asciidoc/performance-measure.adoc @@ -7,6 +7,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: miscellaneous :summary: This guide explains how to best measure the footprint of a Quarkus application. +:topics: internals,performance This guide covers: @@ -54,7 +55,7 @@ it is very misleading in environments like Kubernetes/OpenShift. === Measuring Memory Correctly on Docker -In order to measure memory correctly **DO NOT use docker stat or anything derived from it** (e.g. ctop). This approach only measures a subset of the in-use resident pages, while the Linux Kernel, cgroups and cloud orchestration providers will utilize the full resident set in their accounting (determining whether a process is over the limits and should be killed). +In order to measure memory correctly **DO NOT use docker stat or anything derived from it** (e.g. ctop). This approach only measures a subset of the in-use resident pages, while the Linux Kernel, cgroups and cloud orchestration providers will utilize the full resident set in their accounting (determining whether a process is over the limits and should be killed). To measure accurately, a similar set of steps for measuring RSS on Linux should be performed. The docker `top` command allows running a `ps` command on the container host machine against the processes in the container instance. By utilizing this in combination with formatting output parameters, the rss value can be returned: @@ -69,7 +70,7 @@ For example: PID RSS COMMAND 2531 27m ./application -Dquarkus.http.host=0.0.0.0 ---- - + Alternatively, one can jump directly into a privileged shell (root on the host), and execute a `ps` command directly: [source,shell] diff --git a/docs/src/main/asciidoc/picocli.adoc b/docs/src/main/asciidoc/picocli.adoc index fc950d446b953..d5c16186b001a 100644 --- a/docs/src/main/asciidoc/picocli.adoc +++ b/docs/src/main/asciidoc/picocli.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: command-line :summary: Simplify command line applications creation with the Picocli extension. +:topics: command-line,cli,picocli +:extensions: io.quarkus:quarkus-picocli https://picocli.info/[Picocli] is an open source tool for creating rich command line applications. @@ -202,7 +204,7 @@ This event will be generated in `QuarkusApplication` class created by this exten ---- @CommandLine.Command public class EntryCommand implements Runnable { - + @CommandLine.Option(names = "-c", description = "JDBC connection string") String connectionString; diff --git a/docs/src/main/asciidoc/platform.adoc b/docs/src/main/asciidoc/platform.adoc index 5034d0d19082f..6b14645a13c3e 100644 --- a/docs/src/main/asciidoc/platform.adoc +++ b/docs/src/main/asciidoc/platform.adoc @@ -7,6 +7,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: architecture :summary: Learn more about what we call a Platform in the Quarkus world. +:topics: internals,platform The Quarkus extension ecosystem consists of the Quarkus extensions developed and maintained by the community, including the Quarkus core development team. While the Quarkus ecosystem (sometimes also referred to as the "Quarkus universe") includes all the Quarkus extensions ever developed, there is also a concept of a Quarkus platform. diff --git a/docs/src/main/asciidoc/podman.adoc b/docs/src/main/asciidoc/podman.adoc index da73b95fb9fde..fedc6a2767307 100644 --- a/docs/src/main/asciidoc/podman.adoc +++ b/docs/src/main/asciidoc/podman.adoc @@ -4,6 +4,8 @@ and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Using Podman with Quarkus +:categories: tooling +:topics: podman,devops,tooling include::_attributes.adoc[] https://podman.io/[Podman] is a daemonless and rootless container engine for developing, managing, and running OCI Containers on your Linux system or other OS. diff --git a/docs/src/main/asciidoc/pulsar-dev-services.adoc b/docs/src/main/asciidoc/pulsar-dev-services.adoc index 3a40ab216db97..302f470f37749 100644 --- a/docs/src/main/asciidoc/pulsar-dev-services.adoc +++ b/docs/src/main/asciidoc/pulsar-dev-services.adoc @@ -4,6 +4,10 @@ and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Dev Services for Pulsar +include::_attributes.adoc[] +:categories: messaging +:topics: messaging,reactive-messaging,pulsar,devservices,tooling,testing,devmode +:extensions: io.quarkus:quarkus-smallrye-reactive-messaging-pulsar With Quarkus Smallrye Reactive Messaging Pulsar extension (`quarkus-smallrye-reactive-messaging-pulsar`) Dev Services for Pulsar automatically starts a Pulsar broker in dev mode and when running tests. diff --git a/docs/src/main/asciidoc/pulsar-getting-started.adoc b/docs/src/main/asciidoc/pulsar-getting-started.adoc index 22525f7a75a80..2a0dfde3bad50 100644 --- a/docs/src/main/asciidoc/pulsar-getting-started.adoc +++ b/docs/src/main/asciidoc/pulsar-getting-started.adoc @@ -6,6 +6,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Getting Started to SmallRye Reactive Messaging with Apache Pulsar include::_attributes.adoc[] :categories: messaging +:topics: messaging,reactive-messaging,pulsar +:extensions: io.quarkus:quarkus-smallrye-reactive-messaging-pulsar :summary: This guide demonstrates how your Quarkus application can utilize SmallRye Reactive Messaging to interact with Apache Pulsar. This guide demonstrates how your Quarkus application can utilize SmallRye Reactive Messaging to interact with Apache Pulsar. diff --git a/docs/src/main/asciidoc/pulsar.adoc b/docs/src/main/asciidoc/pulsar.adoc index 529684251e09d..0e1297ff71f15 100644 --- a/docs/src/main/asciidoc/pulsar.adoc +++ b/docs/src/main/asciidoc/pulsar.adoc @@ -10,6 +10,8 @@ include::_attributes.adoc[] :numbered: :sectnums: :sectnumlevels: 4 +:topics: messaging,reactive-messaging,pulsar +:extensions: io.quarkus:quarkus-smallrye-reactive-messaging-pulsar This reference guide demonstrates how your Quarkus application can utilize SmallRye Reactive Messaging to interact with Apache Pulsar. diff --git a/docs/src/main/asciidoc/quarkus-maven-plugin.adoc b/docs/src/main/asciidoc/quarkus-maven-plugin.adoc index ae1c766b2691f..3201dca12ac5e 100644 --- a/docs/src/main/asciidoc/quarkus-maven-plugin.adoc +++ b/docs/src/main/asciidoc/quarkus-maven-plugin.adoc @@ -5,6 +5,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Quarkus Maven Plugin include::_attributes.adoc[] +:topics: maven,tooling The Quarkus Maven Plugin builds the Quarkus applications, and provides helpers to launch dev mode or build native executables. For more information about how to use the Quarkus Maven Plugin, please refer to the xref:maven-tooling.adoc[Maven Tooling guide]. diff --git a/docs/src/main/asciidoc/quarkus-reactive-architecture.adoc b/docs/src/main/asciidoc/quarkus-reactive-architecture.adoc index 486e48f4bddb4..5a35c153f49da 100644 --- a/docs/src/main/asciidoc/quarkus-reactive-architecture.adoc +++ b/docs/src/main/asciidoc/quarkus-reactive-architecture.adoc @@ -7,6 +7,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: architecture :summary: Learn more about Quarkus reactive architecture. +:topics: internals,reactive Quarkus is reactive. It's even more than this: Quarkus unifies reactive and imperative programming. diff --git a/docs/src/main/asciidoc/quarkus-runtime-base-image.adoc b/docs/src/main/asciidoc/quarkus-runtime-base-image.adoc index c891734ead830..9d94a898fc410 100644 --- a/docs/src/main/asciidoc/quarkus-runtime-base-image.adoc +++ b/docs/src/main/asciidoc/quarkus-runtime-base-image.adoc @@ -5,6 +5,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Quarkus Base Runtime Image include::_attributes.adoc[] +:categories: tooling +:topics: docker,podman,images To ease the containerization of native executables, Quarkus provides a base image providing the requirements to run these executables. The `quarkus-micro-image:2.0` image is: diff --git a/docs/src/main/asciidoc/quartz.adoc b/docs/src/main/asciidoc/quartz.adoc index 7bb4f8b913ef7..4c76a5449c0f7 100644 --- a/docs/src/main/asciidoc/quartz.adoc +++ b/docs/src/main/asciidoc/quartz.adoc @@ -8,6 +8,8 @@ include::_attributes.adoc[] :categories: miscellaneous :summary: You need clustering support for your scheduled tasks? This guide explains how to use the Quartz extension for that. :extension-status: preview +:topics: scheduling,cronjob,quartz +:extensions: io.quarkus:quarkus-quartz Modern applications often need to run specific tasks periodically. In this guide, you learn how to schedule periodic clustered tasks using the http://www.quartz-scheduler.org/[Quartz] extension. @@ -154,7 +156,7 @@ public class TaskBean { @Inject org.quartz.Scheduler quartz; <1> - + void onStart(@Observes StartupEvent event) throws SchedulerException { JobDetail job = JobBuilder.newJob(MyJob.class) .withIdentity("myJob", "myGroup") @@ -169,23 +171,23 @@ public class TaskBean { .build(); quartz.scheduleJob(job, trigger); <2> } - + @Transactional void performTask() { Task task = new Task(); task.persist(); } - + // A new instance of MyJob is created by Quartz for every job execution public static class MyJob implements Job { @Inject TaskBean taskBean; - + public void execute(JobExecutionContext context) throws JobExecutionException { taskBean.performTask(); <3> } - + } } ---- @@ -193,7 +195,7 @@ public class TaskBean { <2> Schedule a new job using the Quartz API. <3> Invoke the `TaskBean#performTask()` method from the job. Jobs are also xref:cdi.adoc[container-managed] beans if they belong to a link:cdi-reference[bean archive]. -NOTE: By default, the scheduler is not started unless a `@Scheduled` business method is found. You may need to force the start of the scheduler for "pure" programmatic scheduling. See also <>. +NOTE: By default, the scheduler is not started unless a `@Scheduled` business method is found. You may need to force the start of the scheduler for "pure" programmatic scheduling. See also <>. == Updating the application configuration file diff --git a/docs/src/main/asciidoc/qute-reference.adoc b/docs/src/main/asciidoc/qute-reference.adoc index a686e8a200115..9950e247f45c8 100644 --- a/docs/src/main/asciidoc/qute-reference.adoc +++ b/docs/src/main/asciidoc/qute-reference.adoc @@ -10,6 +10,8 @@ include::_attributes.adoc[] :numbered: :sectnums: :sectnumlevels: 4 +:topics: templating,qute +:extensions: io.quarkus:quarkus-qute,io.quarkus:quarkus-resteasy-qute,io.quarkus:quarkus-resteasy-reactive-qute Qute is a templating engine designed specifically to meet the Quarkus needs. The usage of reflection is minimized to reduce the size of native images. @@ -67,7 +69,7 @@ LOG.info(Qute.fmt("Hello {name}!").data("name", "Foo")); // => Hello Foo! and the message template is only evaluated if the log level INFO is used for the specific logger ---- -NOTE: Please read the javadoc of the `io.quarkus.qute.Qute` class for more details. +NOTE: Please read the javadoc of the `io.quarkus.qute.Qute` class for more details. [[hello_world_example]] == Hello World Example @@ -89,7 +91,7 @@ Then, we will need to parse the contents into a *template definition* Java objec A template definition is an instance of `io.quarkus.qute.Template`. If using Qute "standalone" you'll need to create an instance of `io.quarkus.qute.Engine` first. -The `Engine` represents a central point for template management with dedicated configuration. +The `Engine` represents a central point for template management with dedicated configuration. Let's use the convenient builder: [source,java] @@ -118,7 +120,7 @@ hello.data("name", "Jim").render(); <1> <2> <1> `Template.data(String, Object)` is a convenient method that creates a template instance and sets the data in one step. <2> `TemplateInstance.render()` triggers a synchronous rendering, i.e. the current thread is blocked until the rendering is finished. However, there are also asynchronous ways to trigger the rendering and consume the results. For example, there is the `TemplateInstance.renderAsync()` method that returns `CompletionStage` or `TemplateInstance.createMulti()` that returns Mutiny's `Multi`. -So the workflow is simple: +So the workflow is simple: 1. Create the template contents (`hello.html`), 2. Parse the template definition (`io.quarkus.qute.Template`), @@ -177,11 +179,11 @@ The content of a tag must start with: * a digit, or * an alphabet character, or -* underscore, or +* underscore, or * a built-in command: `#`, `!`, `@`, `/`. If it does not start with any of the above it is ignored by the parser. - + .Tag Examples [source,html] ---- @@ -197,7 +199,7 @@ If it does not start with any of the above it is ignored by the parser. ---- <1> Parsed: an expression that starts with underscore. <2> Parsed: a comment -<3> Ignored: starts with whitespace. +<3> Ignored: starts with whitespace. <4> Ignored: starts with `{`. <5> Ignored: starts with `"`. @@ -225,7 +227,7 @@ Likewise, a line that contains an _expression_ or a _non-whitespace character_ i ---- <1> This is a standalone line and will be removed. -<2> Not a standalone line - contains an expression and non-whitespace characters +<2> Not a standalone line - contains an expression and non-whitespace characters <3> Not a standalone line - contains no section tag/parameter declaration <4> This is a standalone line. @@ -235,8 +237,8 @@ Likewise, a line that contains an _expression_ or a _non-whitespace character_ i
    -
  • Foo 100
    • - +
  • Foo 100
    • +
@@ -251,10 +253,10 @@ In this case, all whitespace characters from a standalone line will be printed t
    - +
  • Foo 100
    • - - + +
@@ -280,14 +282,14 @@ Namespace expressions are resolved differently - see also < {item.name} <2> {item['name']} <3> -{global:colors} <4> +{global:colors} <4> ---- <1> no namespace, one part: `name` <2> no namespace, two parts: `item`, `name` <3> equivalent to `{item.name}` but using the bracket notation <4> namespace `global`, one part: `colors` -A part of an expression can be a _virtual method_ in which case the name can be followed by a list of comma-separated parameters in parentheses. +A part of an expression can be a _virtual method_ in which case the name can be followed by a list of comma-separated parameters in parentheses. A parameter of a virtual method can be either a nested expression or a <> value. We call these methods _"virtual"_ because they do not have to be backed by a real Java method. You can learn more about virtual methods in the <>. @@ -307,16 +309,16 @@ You can learn more about virtual methods in the < {#for item in item.derivedItems} <2>
  • - {item.name} <3> + {item.name} <3> is derived from {data:item.name} <4>
    • @@ -490,7 +492,7 @@ The only difference is that for virtual methods a value resolver consumes parame

    {item.buildName(item.name,5)}

    <1> ---- -<1> `buildName(item.name,5)` represents a virtual method with name `buildName` and two parameters: `item.name` and `5` . The virtual method could be evaluated by a value resolver generated for the following Java class: +<1> `buildName(item.name,5)` represents a virtual method with name `buildName` and two parameters: `item.name` and `5` . The virtual method could be evaluated by a value resolver generated for the following Java class: + [source,java] ---- @@ -535,7 +537,7 @@ If a part of an expression resolves to a `Uni`, a `CompletionStage` is first cre IMPORTANT: Note that each `Uni#subscribeAsCompletionStage()` results in a new subscription. You might need to configure memoization of the `Uni` item or failure before it's used as template data, i.e. `myUni.memoize().indefinitely()`. -It can happen that a `CompletionStage` never completes or a `Uni` emits no item/failure. +It can happen that a `CompletionStage` never completes or a `Uni` emits no item/failure. In this case, the rendering methods (such as `TemplateInstance#render()` and `TemplateInstance#createUni()`) fail after a specific timeout. The timeout can be specified as a template instance `timeout` attribute. If no `timeout` attribute is set the global rendering timeout is used. @@ -639,11 +641,11 @@ A start tag can define parameters with optional names, e.g. `{#if item.isActive} Parameters are separated by one or more spaces. Names are separated from the values by the equals sign. Names and values can be prefixed and suffixed with any number of spaces, e.g. `{#let id='Foo'}` and `{#let id = 'Foo'}` are equivalents where the name of the parameter is `id` and the value is `Foo`. -Values can be grouped using parentheses, e.g. `{#let id=(item.id ?: 42)}` where the name is `id` and the value is `item.id ?: 42`. +Values can be grouped using parentheses, e.g. `{#let id=(item.id ?: 42)}` where the name is `id` and the value is `item.id ?: 42`. Sections can interpret parameter values in any way, e.g. take the value as is. However, in most cases, the parameter value is registered as an <> and evaluated before use. -A section may contain several content *blocks*. +A section may contain several content *blocks*. The "main" block is always present. Additional/nested blocks also start with `#` and can have parameters too - `{#else if item.isActive}`. A section helper that defines the logic of a section can "execute" any of the blocks and evaluate the parameters. @@ -685,7 +687,7 @@ The other form is using the name `for` and specifies the alias used to reference [source] ---- {#for item in items} <1> - {item.name} + {item.name} {/for} ---- <1> `item` is the alias used for the iteration element. @@ -714,7 +716,7 @@ For example, the `hasNext` key must be prefixed with `it_` inside an `{#each}` s {#if it_hasNext}
    {/if} <2> {/each} ---- -<1> `it_count` represents one-based index. +<1> `it_count` represents one-based index. <2> `
    ` is only rendered if the iteration has more elements. And must be used in a form of `{item_hasNext}` inside a `{#for}` section with the `item` element alias. @@ -727,12 +729,12 @@ And must be used in a form of `{item_hasNext}` inside a `{#for}` section with th {#if item_hasNext}
    {/if} <2> {/for} ---- -<1> `item_count` represents one-based index. +<1> `item_count` represents one-based index. <2> `
    ` is only rendered if the iteration has more elements. [TIP] ==== -The iteration metadata prefix is configurable either via `EngineBuilder.iterationMetadataPrefix()` for standalone Qute or via the `quarkus.qute.iteration-metadata-prefix` configuration property in a Quarkus application. Three special constants can be used: +The iteration metadata prefix is configurable either via `EngineBuilder.iterationMetadataPrefix()` for standalone Qute or via the `quarkus.qute.iteration-metadata-prefix` configuration property in a Quarkus application. Three special constants can be used: 1. `` - the alias of an iterated element suffixed with an underscore is used (default) 2. `` - the alias of an iterated element suffixed with a question mark is used @@ -787,11 +789,11 @@ You can also use the following operators in a condition: |=== |Operator |Aliases |Precedence (higher wins) -|logical complement -|`!` +|logical complement +|`!` | 4 -|greater than +|greater than |`gt`, `>` | 3 @@ -799,7 +801,7 @@ You can also use the following operators in a condition: |`ge`, `>=` | 3 -|less than +|less than |`lt`, `<` | 3 @@ -807,11 +809,11 @@ You can also use the following operators in a condition: |`le`, `\<=` | 3 -|equals -|`eq`, `==`, `is` +|equals +|`eq`, `==`, `is` | 2 -|not equals +|not equals |`ne`, `!=` | 2 @@ -844,7 +846,7 @@ Multiple conditions are also supported. ---- Precedence rules can be overridden by parentheses. - + .Parentheses example [source] ---- @@ -912,7 +914,7 @@ The parameters of an `is`/`case` block are not evaluated as expressions but comp [source] ---- {#when machine.status} - {#is ON} + {#is ON} It's running. <1> {#is in OFF BROKEN} It's broken or OFF. <2> @@ -930,11 +932,11 @@ The following operators are supported in `is`/`case` block conditions: |=== |Operator |Aliases |Example -|not equal -|`!=`, `not`, `ne` +|not equal +|`!=`, `not`, `ne` |`{#is not 10}`,`{#case != 10}` -|greater than +|greater than |`gt`, `>` |`{#case le 10}` @@ -942,7 +944,7 @@ The following operators are supported in `is`/`case` block conditions: |`ge`, `>=` |`{#is >= 10}` -|less than +|less than |`lt`, `<` |`{#is < 10}` @@ -982,7 +984,7 @@ If a key of a section parameter, such as the name of the local variable, ends wi [source,html] ---- {#let enabled?=true} <1> <2> - {#if enabled}ON{/if} + {#if enabled}ON{/if} {/let} ---- <1> `true` is effectively a _default value_ that is only used if the parent scope does not define `enabled` already. @@ -1061,7 +1063,7 @@ This section can be used to include another template and possibly override some ---- -<1> Include a template with id `foo`. The included template can reference data from the current context. +<1> Include a template with id `foo`. The included template can reference data from the current context. <2> It's also possible to define optional parameters that can be used in the included template. _Template inheritance_ makes it possible to reuse template layouts. @@ -1174,7 +1176,7 @@ For example, we can call the user tag defined below with `{#test 'Martin' readon ---- <1> `it` is replaced with the first unnamed parameter of the tag. <2> `readonly` is a named parameter. -<3> `_args` represents arguments metadata. +<3> `_args` represents arguments metadata. The result would be: @@ -1302,9 +1304,9 @@ An interesting use case would be a fragment that can be used multiple-times insi {/fragment}

    My page

    -

    This document +

    This document {#include $strong val='contains' /} <2> -a lot of +a lot of {#include $strong val='information' /} <3> !

    ---- @@ -1320,9 +1322,9 @@ The snippet above renders something like: [source,html] ----

    My page

    -

    This document +

    This document contains -a lot of +a lot of information !

    ---- @@ -1408,11 +1410,11 @@ template.data(foo).renderAsync().whenComplete((result, failure) -> { <1> } }; ---- -<1> Register a callback that is executed once the rendering is finished. +<1> Register a callback that is executed once the rendering is finished. There are also two methods that return https://smallrye.io/smallrye-mutiny/[Mutiny] types. `TemplateInstance.createUni()` returns a new `Uni` object. -If you call `createUni()` the template is not rendered right away. +If you call `createUni()` the template is not rendered right away. Instead, every time `Uni.subscribe()` is called a new rendering of the template is triggered. .`TemplateInstance.createUni()` Example @@ -1423,7 +1425,7 @@ template.data(foo).createUni().subscribe().with(System.out::println); `TemplateInstance.createMulti()` returns a new `Multi` object. Each item represents a part/chunk of the rendered template. -Again, `createMulti()` does not trigger rendering. +Again, `createMulti()` does not trigger rendering. Instead, every time a computation is triggered by a subscriber the template is rendered again. .`TemplateInstance.createMulti()` Example @@ -1492,7 +1494,7 @@ However, you can disable this functionality via `io.quarkus.qute.EngineBuilder.s TIP: In Quarkus, a dedicated config property can be used instead: `quarkus.qute.strict-rendering`. If you really need to use an expression which can potentially lead to a "not found" error, you can use _default values_ and _safe expressions_ in order to suppress the error. -A default value is used if the previous part of an expression cannot be resolved or resolves to `null`. +A default value is used if the previous part of an expression cannot be resolved or resolves to `null`. You can use the elvis operator to output the default value: `{foo.bar ?: 'baz'}`, which is effectively the same as the following virtual method: `{foo.bar.or('baz')}`. A safe expression ends with the `??` suffix and results in `null` if the expression cannot be resolved. It can be very useful e.g. in `{#if}` sections: `{#if valueNotFound??}Only rendered if valueNotFound is truthy!{/if}`. @@ -1512,7 +1514,7 @@ If you want to use Qute in your Quarkus application, add the following dependenc ---- In Quarkus, a preconfigured engine instance is provided and available for injection - a bean with scope `@ApplicationScoped`, bean type `io.quarkus.qute.Engine` and qualifier `@Default` is registered automatically. -Moreover, all templates located in the `src/main/resources/templates` directory are validated and can be easily injected. +Moreover, all templates located in the `src/main/resources/templates` directory are validated and can be easily injected. [source,java] ---- @@ -1522,7 +1524,7 @@ import io.quarkus.qute.Location; class MyBean { - @Inject + @Inject Template items; <1> @Location("detail/items2_v1.html") <2> @@ -1533,7 +1535,7 @@ class MyBean { } ---- <1> If there is no `Location` qualifier provided, the field name is used to locate the template. In this particular case, the container will attempt to locate a template with path `src/main/resources/templates/items.html`. -<2> The `Location` qualifier instructs the container to inject a template from a path relative from `src/main/resources/templates`. In this case, the full path is `src/main/resources/templates/detail/items2_v1.html`. +<2> The `Location` qualifier instructs the container to inject a template from a path relative from `src/main/resources/templates`. In this case, the full path is `src/main/resources/templates/detail/items2_v1.html`. <3> Inject the configured `Engine` instance. === Engine Customization @@ -1577,19 +1579,19 @@ public class CustomSectionFactory implements SectionHelperFactory getDefaultAliases() { return List.of("custom"); } - + @Override public ParametersInfo getParameters() { // Param "foo" is required return ParametersInfo.builder().addParameter("foo").build(); <3> } - + @Override public Scope initializeBlock(Scope outerScope, BlockInfo block) { block.addExpression("foo", block.getParameter("foo")); return outerScope; } - + @Override public CustomSectionHelper initialize(SectionInitContext context) { @@ -1597,7 +1599,7 @@ public class CustomSectionFactory implements SectionHelperFactory - + @Inject ItemManager manager; @@ -1693,7 +1695,7 @@ For the expression `inject:foo.price`, the implementation class of the injected 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')}`. +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')}`. [[typesafe_expressions]] === Type-safe Expressions @@ -1730,7 +1732,7 @@ Type variables are not handled in a special way and should never be used. ---- <1> Parameter declaration - maps `foo` to `org.acme.Foo`. <2> Not validated - not matching a param declaration. -<3> This expression is validated. `org.acme.Foo` must have a property `message` or a matching template extension method must exist. +<3> This expression is validated. `org.acme.Foo` must have a property `message` or a matching template extension method must exist. <4> Likewise, the Java type of the object resolved from `foo.message` must have a property `toLowerCase` or a matching template extension method must exist. IMPORTANT: A value resolver is automatically generated for all types used in parameter declarations so that it's possible to access its properties without reflection. @@ -1773,7 +1775,7 @@ However, the infix notation is not supported in default values unless the parent IMPORTANT: The type of a default value is not validated in <>. -.More Parameter Declarations Examples +.More Parameter Declarations Examples [source] ---- {@int pages} <1> @@ -1786,8 +1788,8 @@ IMPORTANT: The type of a default value is not validated in < `String` is replaced with `java.lang.String`: `{@java.util.List strings}` <3> The wildcard is ignored and the upper bound is used instead: `{@java.util.Map}` <4> The wildcard is ignored and the `java.lang.Object` is used instead: `{@java.util.Optional}` -<5> The type is `java.lang.String`, the key is `name` and the default value is `Quarkus`. - +<5> The type is `java.lang.String`, the key is `name` and the default value is `Quarkus`. + [[typesafe_templates]] === Type-safe Templates @@ -1849,7 +1851,7 @@ public class ItemResource { TIP: By default, the templates defined in a class annotated with `@CheckedTemplate` can only contain type-safe expressions, i.e. expressions that can be validated at build time. You can use `@CheckedTemplate(requireTypeSafeExpressions = false)` to relax this requirement. ==== Top-level Type-safe Templates - + You can also declare a top-level Java class annotated with `@CheckedTemplate`: .Top-level checked templates @@ -1965,7 +1967,7 @@ public class ItemResource { You can also define a type-safe <> in your Java code. A _native static_ method with the name that contains a dollar sign `$` denotes a method that represents a fragment of a type-safe template. -The name of the fragment is derived from the annotated method name. +The name of the fragment is derived from the annotated method name. The part before the last occurence of a dollar sign `$` is the method name of the related type-safe template. The part after the last occurence of a dollar sign is the fragment identifier. The strategy defined by the relevant `CheckedTemplate#defaultName()` is honored when constructing the defaulted names. @@ -2031,7 +2033,7 @@ Methods that do not meet the following requirements are ignored. A template extension method: * must not be `private` -* must be static, +* must be static, * must not return `void`. If there is no namespace defined the class of the first parameter that is not annotated with `@TemplateAttribute` is used to match the base object. Otherwise, the namespace is used to match an expression. @@ -2110,7 +2112,7 @@ static String itemProperty(Item item, String name) { <1> ---- <1> A additional string method parameter is used to pass the actual property name. -Finally, `matchNames()` can be used to specify a collection of matching names. +Finally, `matchNames()` can be used to specify a collection of matching names. An additional string method parameter is mandatory as well. @@ -2170,7 +2172,7 @@ public class StringExtensions { static String format(String fmt, Object... args) { return String.format(fmt, args); } - + static String reverse(String val) { return new StringBuilder(val).reverse().toString(); } @@ -2258,12 +2260,12 @@ TIP: A list element can be accessed directly via an index: `{list.10}` or even ` ** `{item.name + '_' + mySuffix}` ** `{name + 10}` -===== Config +===== Config * `config:` or `config:[]`: Returns the config value for the given property name ** `{config:foo}` or `{config:['property.with.dot.in.name']}` -* `config:property(name)`: Returns the config value for the given property name; the name can be obtained dynamically by an expression +* `config:property(name)`: Returns the config value for the given property name; the name can be obtained dynamically by an expression ** `{config:property('quarkus.foo')}` ** `{config:property(foo.getPropertyName())}` @@ -2315,7 +2317,7 @@ class Item { public Item(BigDecimal price) { this.price = price; } - + public BigDecimal getDiscountedPrice() { return price.multiply(new BigDecimal("0.9")); } @@ -2364,7 +2366,7 @@ By default, the namespace is the FQCN of the target class where dots and dollar For example, the namespace for a class with name `org.acme.Foo` is `org_acme_Foo`. The static field `Foo.AGE` can be accessed via `{org_acme_Foo:AGE}`. The static method `Foo.computeValue(int number)` can be accessed via `{org_acme_Foo:computeValue(10)}`. - + NOTE: A namespace can only consist of alphanumeric characters and underscores. .Class Annotated With `@TemplateData` @@ -2432,13 +2434,13 @@ enum Color { RED, GREEN, BLUE } @TemplateGlobal <1> public class Globals { - + static int age = 40; - + static Color[] myColors() { return new Color[] { Color.RED, Color.BLUE }; } - + @TemplateGlobal(name = "currentUser") <2> static String user() { return "Mia"; @@ -2671,7 +2673,7 @@ The message bundles can be used at runtime: ---- <1> `msg` is the default namespace. <2> `hello_name` is the message key. -<3> `Lucie` is the parameter of the message bundle interface method. +<3> `Lucie` is the parameter of the message bundle interface method. <4> It is also possible to obtain a localized message for a key resolved at runtime using a reserved key `message`. The validation is skipped in this case though. @@ -2703,14 +2705,14 @@ NOTE: The bundle name is also used as a part of the name of a localized file, e. ==== Bundle Name and Message Keys Message keys are used directly in templates. -The bundle name is used as a namespace in template expressions. -The `@MessageBundle` can be used to define the default strategy used to generate message keys from method names. +The bundle name is used as a namespace in template expressions. +The `@MessageBundle` can be used to define the default strategy used to generate message keys from method names. However, the `@Message` can override this strategy and even define a custom key. -By default, the annotated element's name is used as-is. +By default, the annotated element's name is used as-is. Other possibilities are: 1. De-camel-cased and hyphenated; e.g. `helloName()` -> `hello-name` -2. De-camel-cased and parts separated by underscores; e.g. `helloName()` -> `hello_name`. +2. De-camel-cased and parts separated by underscores; e.g. `helloName()` -> `hello_name`. ==== Validation @@ -2793,10 +2795,10 @@ Alternatively, you can specify the `locale` attribute of a template instance. ---- @Singleton public class MyBean { - + @Inject Template hello; - + String render() { return hello.instance().setAttribute("locale", Locale.forLanguageTag("cs")).render(); <1> } @@ -2814,10 +2816,10 @@ The `@Localized` qualifier can be used to inject a localized message bundle inte ---- @Singleton public class MyBean { - + @Localized("cs") <1> AppMessages msg; - + String render() { return msg.hello_name("Jachym"); } @@ -2870,7 +2872,7 @@ include::{generated-dir}/config/quarkus-qute.adoc[leveloffset=+1, opts=optional] [[standalone]] == Qute Used as a Standalone Library -Qute is primarily designed as a Quarkus extension. +Qute is primarily designed as a Quarkus extension. However. it is possible to use it as a "standalone" library. In this case, some features are not available and some additional configuration is needed. @@ -2890,14 +2892,14 @@ Sections:: * No section helpers are registered by default. * The default set of value resolvers can be registered via the convenient `EngineBuilder.addDefaultSectionHelpers()` method and the `EngineBuilder.addDefaults()` method respectively. -Value resolvers:: +Value resolvers:: * No <> are generated automatically. ** <> will not work. ** <> and <> annotations are ignored. * The default set of value resolvers can be registered via the convenient `EngineBuilder.addDefaultValueResolvers()` method and the `EngineBuilder.addDefaults()` method respectively. + NOTE: Not all functionality provided by the built-in extension methods is covered by the default value resolvers. However, a custom value resolver can be easily built via the `ValueResolver.builder()`. -* It's recommended to register a `ReflectionValueResolver` instance via `Engine.addValueResolver(new ReflectionValueResolver())` so that Qute can access object properties and call public methods. +* It's recommended to register a `ReflectionValueResolver` instance via `Engine.addValueResolver(new ReflectionValueResolver())` so that Qute can access object properties and call public methods. + NOTE: Keep in mind that reflection may not work correctly in some restricted environments or may require additional configuration, e.g. registration in case of a GraalVM native image. diff --git a/docs/src/main/asciidoc/qute.adoc b/docs/src/main/asciidoc/qute.adoc index d8e9bdf415c1f..00a841fda1e1e 100644 --- a/docs/src/main/asciidoc/qute.adoc +++ b/docs/src/main/asciidoc/qute.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: miscellaneous :summary: Learn more about how you can use templating in your applications with the Qute template engine. +:topics: templating,qute +:extensions: io.quarkus:quarkus-qute,io.quarkus:quarkus-resteasy-qute,io.quarkus:quarkus-resteasy-reactive-qute Qute is a templating engine designed specifically to meet the Quarkus needs. The usage of reflection is minimized to reduce the size of native images. diff --git a/docs/src/main/asciidoc/rabbitmq-dev-services.adoc b/docs/src/main/asciidoc/rabbitmq-dev-services.adoc index 8454327bd5b15..c99349f7dd1e5 100644 --- a/docs/src/main/asciidoc/rabbitmq-dev-services.adoc +++ b/docs/src/main/asciidoc/rabbitmq-dev-services.adoc @@ -5,6 +5,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Dev Services for RabbitMQ include::_attributes.adoc[] +:categories: messaging +:topics: messaging,reactive-messaging,rabbitmq,devservices,tooling,testing,devmode +:extensions: io.quarkus:quarkus-smallrye-reactive-messaging-rabbitmq Dev Services for RabbitMQ automatically starts a RabbitMQ broker in dev mode and when running tests. So, you don't have to start a broker manually. diff --git a/docs/src/main/asciidoc/rabbitmq-reference.adoc b/docs/src/main/asciidoc/rabbitmq-reference.adoc index 84271eff319e7..586e338c046fc 100644 --- a/docs/src/main/asciidoc/rabbitmq-reference.adoc +++ b/docs/src/main/asciidoc/rabbitmq-reference.adoc @@ -5,6 +5,10 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Reactive Messaging RabbitMQ Connector Reference Documentation include::_attributes.adoc[] +:extension-status: preview +:categories: messaging +:topics: messaging,reactive-messaging,rabbitmq,devservices,tooling,testing,devmode +:extensions: io.quarkus:quarkus-smallrye-reactive-messaging-rabbitmq This guide is the companion from the xref:rabbitmq.adoc[Getting Started with RabbitMQ]. It explains in more details the configuration and usage of the RabbitMQ connector for reactive messaging. @@ -19,6 +23,8 @@ IMPORTANT: The RabbitMQ connector supports AMQP 0-9-1, which is very different f AMQP 1.0 connector. You can use the AMQP 1.0 connector with RabbitMQ as described in the xref:amqp-reference.adoc[AMQP 1.0 connector reference], albeit with *reduced functionality*. +include::{includes}/extension-status.adoc[] + == RabbitMQ connector extension To use the connector, you need to add the `quarkus-smallrye-reactive-messaging-rabbitmq` extension. diff --git a/docs/src/main/asciidoc/rabbitmq.adoc b/docs/src/main/asciidoc/rabbitmq.adoc index f0d1117ff45cf..cdb57e832454e 100644 --- a/docs/src/main/asciidoc/rabbitmq.adoc +++ b/docs/src/main/asciidoc/rabbitmq.adoc @@ -6,6 +6,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Getting Started to SmallRye Reactive Messaging with RabbitMQ :extension-status: preview include::_attributes.adoc[] +:categories: messaging +:topics: messaging,reactive-messaging,rabbitmq,devservices,tooling,testing,devmode +:extensions: io.quarkus:quarkus-smallrye-reactive-messaging-rabbitmq This guide demonstrates how your Quarkus application can utilize SmallRye Reactive Messaging to interact with RabbitMQ. diff --git a/docs/src/main/asciidoc/reactive-event-bus.adoc b/docs/src/main/asciidoc/reactive-event-bus.adoc index c7f4d069d811d..8d6197323bab1 100644 --- a/docs/src/main/asciidoc/reactive-event-bus.adoc +++ b/docs/src/main/asciidoc/reactive-event-bus.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: messaging :summary: This guide explains how different beans can interact using the event bus. +:topics: messaging,event-bus,vert.x +:extensions: io.quarkus:quarkus-vertx Quarkus allows different beans to interact using asynchronous events, thus promoting loose-coupling. The messages are sent to _virtual addresses_. diff --git a/docs/src/main/asciidoc/reactive-routes.adoc b/docs/src/main/asciidoc/reactive-routes.adoc index 0ba73e339f2b1..496ffac6e7e7a 100644 --- a/docs/src/main/asciidoc/reactive-routes.adoc +++ b/docs/src/main/asciidoc/reactive-routes.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: web :summary: This guide demonstrates how to use reactive routes. +:topics: http,web,routing +:extensions: io.quarkus:quarkus-reactive-routes Reactive routes propose an alternative approach to implement HTTP endpoints where you declare and chain _routes_. This approach became very popular in the JavaScript world, with frameworks like Express.Js or Hapi. @@ -78,8 +80,8 @@ public class MyDeclarativeRoutes { void hello(RoutingContext rc) { // <3> rc.response().end("hello"); } - - @Route(path = "/world") + + @Route(path = "/world") String helloWorld() { // <4> return "Hello world!"; } @@ -214,20 +216,20 @@ public class SimpleRoutes { } } ---- -<1> The `path` value is used as a prefix for any route method declared on the class where `Route#path()` is used. +<1> The `path` value is used as a prefix for any route method declared on the class where `Route#path()` is used. <2> The value of `produces()` is used for content-based routing for all routes where `Route#produces()` is empty. == Reactive Route Methods A route method must be a non-private non-static method of a CDI bean. -If the annotated method returns `void` then it has to accept at least one argument - see the supported types below. +If the annotated method returns `void` then it has to accept at least one argument - see the supported types below. If the annotated method does not return `void` then the arguments are optional. NOTE: Methods that return `void` must __end__ the response or the HTTP request to this route will never end. Some methods of `RoutingExchange` do it for you, others not and you must call the `end()` method of the response by yourself, please refer to its JavaDoc for more information. -A route method can accept arguments of the following types: +A route method can accept arguments of the following types: * `io.vertx.ext.web.RoutingContext` * `io.quarkus.vertx.web.RoutingExchange` @@ -240,10 +242,10 @@ Furthermore, it is possible to inject the `HttpServerRequest` parameters into me [options="header",cols="1,1"] |=== -|Parameter Type | Obtained via +|Parameter Type | Obtained via //------------- -|`java.lang.String` |`routingContext.request().getParam()` -|`java.util.Optional` |`routingContext.request().getParam()` +|`java.lang.String` |`routingContext.request().getParam()` +|`java.util.Optional` |`routingContext.request().getParam()` |`java.util.List` |`routingContext.request().params().getAll()` |=== @@ -260,10 +262,10 @@ The `HttpServerRequest` headers can be injected into method parameters annotated [options="header",cols="1,1"] |=== -|Parameter Type | Obtained via +|Parameter Type | Obtained via //------------- -|`java.lang.String` |`routingContext.request().getHeader()` -|`java.util.Optional` |`routingContext.request().getHeader()` +|`java.lang.String` |`routingContext.request().getHeader()` +|`java.util.Optional` |`routingContext.request().getHeader()` |`java.util.List` |`routingContext.request().headers().getAll()` |=== @@ -280,13 +282,13 @@ The request body can be injected into a method parameter annotated with `@io.qua [options="header",cols="1,1"] |=== -|Parameter Type | Obtained via +|Parameter Type | Obtained via //------------- -|`java.lang.String` |`routingContext.getBodyAsString()` -|`io.vertx.core.buffer.Buffer` |`routingContext.getBody()` -|`io.vertx.core.json.JsonObject` |`routingContext.getBodyAsJson()` -|`io.vertx.core.json.JsonArray` |`routingContext.getBodyAsJsonArray()` -|any other type |`routingContext.getBodyAsJson().mapTo(MyPojo.class)` +|`java.lang.String` |`routingContext.getBodyAsString()` +|`io.vertx.core.buffer.Buffer` |`routingContext.getBody()` +|`io.vertx.core.json.JsonObject` |`routingContext.getBodyAsJson()` +|`io.vertx.core.json.JsonArray` |`routingContext.getBodyAsJsonArray()` +|any other type |`routingContext.getBodyAsJson().mapTo(MyPojo.class)` |=== .Request Body Example @@ -299,7 +301,7 @@ Person createPerson(@Body Person person, @Param("id") Optional primaryKe } ---- -A failure handler can declare a single method parameter whose type extends `Throwable`. +A failure handler can declare a single method parameter whose type extends `Throwable`. The type of the parameter is used to match the result of `RoutingContext#failure()`. .Failure Handler Example @@ -781,7 +783,7 @@ Also see xref:openapi-swaggerui.adoc[the OpenAPI Guide]. === Adding MicroProfile OpenAPI Annotations -You can use link:https://github.com/eclipse/microprofile-open-api[MicroProfile OpenAPI] to better document your schema, +You can use link:https://github.com/eclipse/microprofile-open-api[MicroProfile OpenAPI] to better document your schema, for instance, adding header info, or specifying the return type on `void` methods might be useful: [source, java] @@ -803,21 +805,21 @@ public class MyDeclarativeRoutes { // neither path nor regex is set - match a path derived from the method name @Route(methods = Route.HttpMethod.GET) - @APIResponse(responseCode="200", - description="Say hello", + @APIResponse(responseCode="200", + description="Say hello", content=@Content(mediaType="application/json", schema=@Schema(type=SchemaType.STRING))) // <2> void hello(RoutingContext rc) { rc.response().end("hello"); } - - @Route(path = "/world") + + @Route(path = "/world") String helloWorld() { return "Hello world!"; } @Route(path = "/greetings", methods = HttpMethod.GET) - @APIResponse(responseCode="200", - description="Greeting", + @APIResponse(responseCode="200", + description="Greeting", content=@Content(mediaType="application/json", schema=@Schema(type=SchemaType.STRING))) void greetings(RoutingExchange ex) { ex.ok("hello " + ex.getParam("name").orElse("world")); diff --git a/docs/src/main/asciidoc/reactive-sql-clients.adoc b/docs/src/main/asciidoc/reactive-sql-clients.adoc index 5ca5ef3922837..8a0d4eaaf2eae 100644 --- a/docs/src/main/asciidoc/reactive-sql-clients.adoc +++ b/docs/src/main/asciidoc/reactive-sql-clients.adoc @@ -8,6 +8,8 @@ include::_attributes.adoc[] :categories: data :summary: This guide covers how to use the Reactive SQL Clients in Quarkus. :config-file: application.properties +:topics: data,database,reactive,sql +:extensions: io.quarkus:quarkus-reactive-mysql-client,io.quarkus:quarkus-reactive-oracle-client,io.quarkus:quarkus-reactive-pg-client,io.quarkus:quarkus-reactive-db2-client,io.quarkus:quarkus-reactive-pg-client,io.quarkus:quarkus-reactive-mssql-client The Reactive SQL Clients have a straightforward API focusing on scalability and low-overhead. Currently, the following database servers are supported: diff --git a/docs/src/main/asciidoc/reaugmentation.adoc b/docs/src/main/asciidoc/reaugmentation.adoc index d95d0bee6b687..4e36e653dad3d 100644 --- a/docs/src/main/asciidoc/reaugmentation.adoc +++ b/docs/src/main/asciidoc/reaugmentation.adoc @@ -7,10 +7,11 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: tooling :summary: Use mutable jars to rebuild your application with different build time configurations. +:topics: mutable-jars,tooling == What is augmentation? -Quarkus application configuration may include two types of configuration options: +Quarkus application configuration may include two types of configuration options: - Build time options, handled during the application build time; - Runtime options, that may be adjusted after the application has been built but before it has been launched. diff --git a/docs/src/main/asciidoc/redis-dev-services.adoc b/docs/src/main/asciidoc/redis-dev-services.adoc index 1daf74defbc98..0572c08e4343a 100644 --- a/docs/src/main/asciidoc/redis-dev-services.adoc +++ b/docs/src/main/asciidoc/redis-dev-services.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: data :summary: Start Redis automatically in dev and test modes. +:topics: data,redis,nosql,devservices,tooling,testing,devmode +:extensions: io.quarkus:quarkus-redis-client Quarkus supports a feature called Dev Services that allows you to create various datasources without any config. What that means practically, is that if you have docker running and have not configured `quarkus.redis.hosts`, diff --git a/docs/src/main/asciidoc/redis-reference.adoc b/docs/src/main/asciidoc/redis-reference.adoc index fa25027b7ce45..940a6ca793280 100644 --- a/docs/src/main/asciidoc/redis-reference.adoc +++ b/docs/src/main/asciidoc/redis-reference.adoc @@ -8,6 +8,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :numbered: :sectnums: +:categories: data +:topics: data,redis,nosql +:extensions: io.quarkus:quarkus-redis-client Redis is an in-memory data store used as a database, cache, streaming engine, and message broker. The Quarkus Redis extension allows integrating Quarkus applications with Redis. diff --git a/docs/src/main/asciidoc/redis.adoc b/docs/src/main/asciidoc/redis.adoc index 71a3beca1d5ce..12afc6a99e075 100644 --- a/docs/src/main/asciidoc/redis.adoc +++ b/docs/src/main/asciidoc/redis.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc :extension-status: preview include::_attributes.adoc[] :categories: data +:topics: data,redis,nosql +:extensions: io.quarkus:quarkus-redis-client :summary: This guide covers how to use a Redis datastore in Quarkus. This guide demonstrates how your Quarkus application can connect to a Redis server using the Redis Client extension. diff --git a/docs/src/main/asciidoc/rest-client-multipart.adoc b/docs/src/main/asciidoc/rest-client-multipart.adoc index c6a15e0739517..17def53f8ea96 100644 --- a/docs/src/main/asciidoc/rest-client-multipart.adoc +++ b/docs/src/main/asciidoc/rest-client-multipart.adoc @@ -6,7 +6,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Using the legacy REST Client with Multipart include::_attributes.adoc[] :categories: web -:summary: This guide explains how to use the RESTEasy REST Client to send multipart REST requests, typically to upload documents. +:summary: This guide explains how to use the RESTEasy Classic REST Client to send multipart REST requests, typically to upload documents. +:topics: rest,rest-client,multipart,resteasy-classic +:extensions: io.quarkus:quarkus-rest-client,io.quarkus:quarkus-resteasy-multipart [WARNING] ==== diff --git a/docs/src/main/asciidoc/rest-client-reactive.adoc b/docs/src/main/asciidoc/rest-client-reactive.adoc index 1ea2c89ee5be3..4d1af8480e4d3 100644 --- a/docs/src/main/asciidoc/rest-client-reactive.adoc +++ b/docs/src/main/asciidoc/rest-client-reactive.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: web :summary: This guide explains how to use the RESTEasy Reactive REST Client. +:topics: rest,rest-client,resteasy-reactive +:extensions: io.quarkus:quarkus-rest-client-reactive,io.quarkus:quarkus-rest-client-reactive-jackson,io.quarkus:quarkus-rest-client-reactive-jsonb This guide explains how to use the REST Client Reactive in order to interact with REST APIs. REST Client Reactive is the REST Client implementation compatible with RESTEasy Reactive. @@ -1103,7 +1105,7 @@ public class TestClientRequestFilter implements ResteasyReactiveClientRequestFil == Customizing the ObjectMapper in REST Client Reactive Jackson -The REST Client Reactive supports adding a custom ObjectMapper to be used only the Client using the annotation `@ClientObjectMapper`. +The REST Client Reactive supports adding a custom ObjectMapper to be used only the Client using the annotation `@ClientObjectMapper`. A simple example is to provide a custom ObjectMapper to the REST Client Reactive Jackson extension by doing: @@ -1127,7 +1129,7 @@ public interface ExtensionsService { <1> The method must be annotated with `@ClientObjectMapper`. <2> It's must be a static method. Also, the parameter `defaultObjectMapper` will be resolved via CDI. If not found, it will throw an exception at runtime. -<3> In this example, we're creating a copy of the default object mapper. You should *NEVER* modify the default object mapper, but create a copy instead. +<3> In this example, we're creating a copy of the default object mapper. You should *NEVER* modify the default object mapper, but create a copy instead. == Exception handling diff --git a/docs/src/main/asciidoc/rest-client.adoc b/docs/src/main/asciidoc/rest-client.adoc index bfdfb027ec1c0..aaeb8dc4321a3 100644 --- a/docs/src/main/asciidoc/rest-client.adoc +++ b/docs/src/main/asciidoc/rest-client.adoc @@ -6,7 +6,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Using the legacy REST Client include::_attributes.adoc[] :categories: web -:summary: This guide explains how to use the RESTEasy REST Client in order to interact with REST APIs (JSON and other) with very little effort. +:summary: This guide explains how to use the RESTEasy Classic REST Client in order to interact with REST APIs (JSON and other) with very little effort. +:topics: rest,rest-client,resteasy-classic +:extensions: io.quarkus:quarkus-rest-client,io.quarkus:quarkus-rest-client-jackson,io.quarkus:quarkus-rest-client-jsonb [WARNING] ==== @@ -347,11 +349,11 @@ A HTTP server can redirect a response to another location by sending a response - `quarkus.rest-client.follow-redirects` to enable redirection for all REST clients. - `quarkus.rest-client..follow-redirects` to enable redirection for a specific REST client. -If this property is true, then REST Client will perform a new request that it receives a redirection response from the HTTP server. +If this property is true, then REST Client will perform a new request that it receives a redirection response from the HTTP server. Additionally, we can limit the number of redirections using the property "max-redirects". -One important note is that according to the https://www.rfc-editor.org/rfc/rfc2616#section-10.3.8[RFC2616] specs, by default the redirection will only happen for GET or HEAD methods. +One important note is that according to the https://www.rfc-editor.org/rfc/rfc2616#section-10.3.8[RFC2616] specs, by default the redirection will only happen for GET or HEAD methods. == Async Support diff --git a/docs/src/main/asciidoc/rest-data-panache.adoc b/docs/src/main/asciidoc/rest-data-panache.adoc index 2b06557157124..210afc6168505 100644 --- a/docs/src/main/asciidoc/rest-data-panache.adoc +++ b/docs/src/main/asciidoc/rest-data-panache.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: web :summary: Hibernate ORM REST Data with Panache simplifies the creation of CRUD applications based on Jakarta REST and Hibernate ORM. +:topics: rest,hibernate-orm,panache,mongodb,sql,jdbc,nosql +:extensions: io.quarkus:quarkus-hibernate-orm-rest-data-panache,io.quarkus:quarkus-hibernate-reactive-rest-data-panache,io.quarkus:quarkus-mongodb-rest-data-panache A lot of web applications are monotonous CRUD applications with REST APIs that are tedious to write. To streamline this task, REST Data with Panache extension can generate the basic CRUD endpoints for your entities and repositories. @@ -425,7 +427,7 @@ public class Person extends PanacheEntity { } ---- -In this example, we have added a named query to list all the persons that contains some text in the `name` field. +In this example, we have added a named query to list all the persons that contains some text in the `name` field. Next, we can set a query param `namedQuery` when listing the entities using the generated resource with the name of the named query that we want to use, for example, calling `http://localhost:8080/people?namedQuery=Person.containsInName&name=ter` would return all the persons which name contains the text "ter". @@ -433,7 +435,7 @@ For more information about how named queries work, go to the xref:hibernate-orm- == Resource Method Before/After Listeners -REST Data with Panache supports the subscription to the following resource method hooks: +REST Data with Panache supports the subscription to the following resource method hooks: * Before/After add resource * Before/After update resource diff --git a/docs/src/main/asciidoc/rest-json.adoc b/docs/src/main/asciidoc/rest-json.adoc index 5c4c6a24619f0..c55c6061eeb42 100644 --- a/docs/src/main/asciidoc/rest-json.adoc +++ b/docs/src/main/asciidoc/rest-json.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: web, serialization :summary: JSON is now the lingua franca between microservices. In this guide, we see how you can get your REST services to consume and produce JSON payloads. +:topics: rest,json,resteasy-reactive +:extensions: io.quarkus:quarkus-resteasy-reactive-jackson,io.quarkus:quarkus-resteasy-reactive-jsonb,io.quarkus:quarkus-resteasy-reactive JSON is now the _lingua franca_ between microservices. @@ -226,7 +228,7 @@ public class RegisterCustomModuleCustomizer implements ObjectMapperCustomizer { Users can even provide their own `ObjectMapper` bean if they so choose. If this is done, it is very important to manually inject and apply all `io.quarkus.jackson.ObjectMapperCustomizer` beans in the CDI producer that produces `ObjectMapper`. -Failure to do so will prevent Jackson specific customizations provided by various extensions from being applied. +Failure to do so will prevent Jackson specific customizations provided by various extensions from being applied. [source,java] ---- diff --git a/docs/src/main/asciidoc/resteasy-reactive-migration.adoc b/docs/src/main/asciidoc/resteasy-reactive-migration.adoc index fca208c2f84d3..86eb5742cf200 100644 --- a/docs/src/main/asciidoc/resteasy-reactive-migration.adoc +++ b/docs/src/main/asciidoc/resteasy-reactive-migration.adoc @@ -5,6 +5,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Migrating to RESTEasy Reactive include::_attributes.adoc[] +:categories: web +:topics: rest,rest-client,resteasy-reactive +:extensions: io.quarkus:quarkus-resteasy-reactive,io.quarkus:quarkus-resteasy-reactive-jackson,io.quarkus:quarkus-resteasy-reactive-jsonb,io.quarkus:quarkus-rest-client-reactive,io.quarkus:quarkus-rest-client-reactive-jackson,io.quarkus:quarkus-rest-client-reactive-jsonb Migrating from RESTEasy Classic to RESTEasy Reactive is straightforward in most cases, however there are a few cases that require some attention. This document provides a list of issues users attempting the migration should be aware of. diff --git a/docs/src/main/asciidoc/resteasy-reactive-virtual-threads.adoc b/docs/src/main/asciidoc/resteasy-reactive-virtual-threads.adoc index 7f22696688f97..0230546877a83 100644 --- a/docs/src/main/asciidoc/resteasy-reactive-virtual-threads.adoc +++ b/docs/src/main/asciidoc/resteasy-reactive-virtual-threads.adoc @@ -9,6 +9,8 @@ include::_attributes.adoc[] :diataxis-type: howto :categories: web, core :summary: How to use virtual threads in a REST application +:topics: rest,resteasy-reactive,virtual-threads +:extensions: io.quarkus:quarkus-resteasy-reactive,io.quarkus:quarkus-resteasy-reactive-jackson,io.quarkus:quarkus-resteasy-reactive-jsonb,io.quarkus:quarkus-rest-client-reactive,io.quarkus:quarkus-rest-client-reactive-jackson,io.quarkus:quarkus-rest-client-reactive-jsonb In this guide, we see how you can use virtual threads in a REST application. Because virtual threads are all about I/O, we will also use the REST client. diff --git a/docs/src/main/asciidoc/resteasy-reactive.adoc b/docs/src/main/asciidoc/resteasy-reactive.adoc index 7904da36ee0b7..873436fd8942e 100644 --- a/docs/src/main/asciidoc/resteasy-reactive.adoc +++ b/docs/src/main/asciidoc/resteasy-reactive.adoc @@ -6,6 +6,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Writing REST Services with RESTEasy Reactive include::_attributes.adoc[] :categories: web +:topics: rest,resteasy-reactive,virtual-threads +:extensions: io.quarkus:quarkus-resteasy-reactive,io.quarkus:quarkus-resteasy-reactive-jackson,io.quarkus:quarkus-resteasy-reactive-jsonb,io.quarkus:quarkus-rest-client-reactive,io.quarkus:quarkus-rest-client-reactive-jackson,io.quarkus:quarkus-rest-client-reactive-jsonb :summary: Discover how to develop highly scalable reactive REST services with Jakarta REST and RESTEasy Reactive. :jaxrsapi: https://javadoc.io/doc/jakarta.ws.rs/jakarta.ws.rs-api/3.1.0/jakarta.ws.rs :jaxrsspec: https://jakarta.ee/specifications/restful-ws/3.1/jakarta-restful-ws-spec-3.1.html diff --git a/docs/src/main/asciidoc/resteasy.adoc b/docs/src/main/asciidoc/resteasy.adoc index 7d608174e0cf0..7a61e59a37da9 100644 --- a/docs/src/main/asciidoc/resteasy.adoc +++ b/docs/src/main/asciidoc/resteasy.adoc @@ -5,6 +5,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = RESTEasy Classic include::_attributes.adoc[] +:categories: web +:topics: rest,resteasy-classic +:extensions: io.quarkus:quarkus-resteasy,io.quarkus:quarkus-resteasy-jackson,io.quarkus:quarkus-resteasy-jsonb [WARNING] ==== diff --git a/docs/src/main/asciidoc/scheduler-reference.adoc b/docs/src/main/asciidoc/scheduler-reference.adoc index daa83f030cb74..b999361cdb397 100644 --- a/docs/src/main/asciidoc/scheduler-reference.adoc +++ b/docs/src/main/asciidoc/scheduler-reference.adoc @@ -10,6 +10,8 @@ include::_attributes.adoc[] :numbered: :sectnums: :sectnumlevels: 4 +:topics: scheduling,cronjob +:extensions: io.quarkus:quarkus-scheduler Modern applications often need to run specific tasks periodically. There are two scheduler extensions in Quarkus. @@ -17,7 +19,7 @@ The `quarkus-scheduler` extension brings the API and a lightweight in-memory sch The `quarkus-quartz` extension implements the API from the `quarkus-scheduler` extension and contains a scheduler implementation based on the Quartz library. You will only need `quarkus-quartz` for more advanced scheduling use cases, such as persistent tasks and clustering. -NOTE: If you add the `quarkus-quartz` dependency to your project the lightweight scheduler implementation from the `quarkus-scheduler` extension is automatically disabled. +NOTE: If you add the `quarkus-quartz` dependency to your project the lightweight scheduler implementation from the `quarkus-scheduler` extension is automatically disabled. == Scheduled Methods @@ -41,7 +43,7 @@ class Jobs { @Scheduled(every = "1s") void everySecond() { - // ..do something + // ..do something } } @@ -131,7 +133,7 @@ void myMethod() { } ==== Intervals An interval trigger defines a period between invocations. -The period expression is based on the ISO-8601 duration format `PnDTnHnMn.nS` and the value of `@Scheduled#every()` is parsed with `java.time.Duration#parse(CharSequence)`. +The period expression is based on the ISO-8601 duration format `PnDTnHnMn.nS` and the value of `@Scheduled#every()` is parsed with `java.time.Duration#parse(CharSequence)`. However, if an expression starts with a digit then the `PT` prefix is added automatically. So for example, `15m` can be used instead of `PT15M` and is parsed as "15 minutes". @@ -202,7 +204,7 @@ void everyTwoSeconds() { } NOTE: The final value is always rounded to full second. `@Scheduled#delayed()` is a text alternative to the properties above. -The period expression is based on the ISO-8601 duration format `PnDTnHnMn.nS` and the value is parsed with `java.time.Duration#parse(CharSequence)`. +The period expression is based on the ISO-8601 duration format `PnDTnHnMn.nS` and the value is parsed with `java.time.Duration#parse(CharSequence)`. However, if an expression starts with a digit, the `PT` prefix is added automatically. So for example, `15s` can be used instead of `PT15S` and is parsed as "15 seconds". @@ -256,7 +258,7 @@ The specified bean class must implement `io.quarkus.scheduler.Scheduled.SkipPred [source,java] ---- class Jobs { - + @Scheduled(every = "1s", skipExecutionIf = MyPredicate.class) <1> void everySecond() { // do something every second... @@ -286,7 +288,7 @@ class Jobs { @Inject MyService service; - + @Scheduled(every = "1s") void everySecond() { if (service.isStarted()) { @@ -303,14 +305,14 @@ TIP: A CDI event of type `io.quarkus.scheduler.SkippedExecution` is fired when a [[non-blocking-methods]] === Non-blocking Methods -By default, a scheduled method is executed on the main executor for blocking tasks. +By default, a scheduled method is executed on the main executor for blocking tasks. As a result, a technology that is designed to run on a Vert.x event loop (such as Hibernate Reactive) cannot be used inside the method body. For this reason, a scheduled method that returns `java.util.concurrent.CompletionStage` or `io.smallrye.mutiny.Uni`, or is annotated with `@io.smallrye.common.annotation.NonBlocking` is executed on the Vert.x event loop instead. [source,java] ---- class Jobs { - + @Scheduled(every = "1s") Uni everySecond() { <1> // ...do something async @@ -383,10 +385,10 @@ class MyJobs { }) .schedule(); <3> } - + void removeMyJob() { scheduler.unscheduleJob("myJob"); <4> - } + } } ---- <1> This is a programmatic alternative to a method annotated with `@Scheduled(identity = "myJob", cron = "0/5 * * * * ?")`. @@ -407,7 +409,7 @@ You can even disable the scheduler for particular <> section. [NOTE] ==== -Some OIDC providers do not support link:https://openid.net/specs/openid-connect-session-1_0.html#RPLogout[RP-initiated logout] specification and do not return an OpenID Connect well-known `end_session_endpoint` metadata property. +Some OIDC providers do not support link:https://openid.net/specs/openid-connect-session-1_0.html#RPLogout[RP-initiated logout] specification and do not return an OpenID Connect well-known `end_session_endpoint` metadata property. However, this is not a problem for Quarkus because the specific logout mechanisms of such OIDC providers only differ in how the logout URL query parameters are named. According to the https://openid.net/specs/openid-connect-session-1_0.html#RPLogout[RP-initiated logout] specification, the `quarkus.oidc.logout.post-logout-path` property is represented as a `post_logout_redirect_uri` query parameter, which is not recognized by the providers that do not support this specification. @@ -838,7 +840,7 @@ quarkus.oidc.application-type=web-app quarkus.oidc.logout.backchannel.path=/back-channel-logout ---- -The absolute `back-channel logout` URL is calculated by adding `quarkus.oidc.back-channel-logout.path` to the current endpoint URL, for example, `http://localhost:8080/back-channel-logout`. +The absolute `back-channel logout` URL is calculated by adding `quarkus.oidc.back-channel-logout.path` to the current endpoint URL, for example, `http://localhost:8080/back-channel-logout`. You will need to configure this URL in the admin console of your OIDC provider. You will also need to configure a token age property for the logout token verification to succeed if your OpenID Connect Provider does not set an expiry claim in the current logout token. @@ -906,10 +908,10 @@ More useful methods will be added to it over time. ==== Session management -By default, logout is based on the expiration time of the ID token issued by the OIDC provider. When the ID token expires, the current user session at the Quarkus endpoint is invalidated and the user is redirected to the OIDC provider again to authenticate. +By default, logout is based on the expiration time of the ID token issued by the OIDC provider. When the ID token expires, the current user session at the Quarkus endpoint is invalidated and the user is redirected to the OIDC provider again to authenticate. If the session at the OIDC provider is still active, users are automatically re-authenticated without needing to provide their credentials again. -The current user session can be automatically extended by enabling the `quarkus.oidc.token.refresh-expired` property. +The current user session can be automatically extended by enabling the `quarkus.oidc.token.refresh-expired` property. If set to `true`, when the current ID token expires, a refresh token grant will be used to refresh the ID token as well as access and refresh tokens. [TIP] @@ -922,25 +924,25 @@ If you work with a Quarkus OIDC `web-app` application, then it is the Quarkus OI To use the refresh token, you should carefully configure the session cookie age. The session age should be longer than the ID token lifespan and close to or equal to the refresh token lifespan. -You calculate the session age by adding the lifespan value of the current ID token and the values of the `quarkus.oidc.authentication.session-age-extension` and `quarkus.oidc.token.lifespan-grace` properties. +You calculate the session age by adding the lifespan value of the current ID token and the values of the `quarkus.oidc.authentication.session-age-extension` and `quarkus.oidc.token.lifespan-grace` properties. [TIP] -- -You use only the `quarkus.oidc.authentication.session-age-extension` property to significantly extend the session lifespan, if required. +You use only the `quarkus.oidc.authentication.session-age-extension` property to significantly extend the session lifespan, if required. You use the `quarkus.oidc.token.lifespan-grace` property only for taking some small clock skews into consideration. -- -When the current authenticated user returns to the protected Quarkus endpoint and the ID token associated with the session cookie has expired, then, by default, the user is automatically redirected to the OIDC Authorization endpoint to re-authenticate. +When the current authenticated user returns to the protected Quarkus endpoint and the ID token associated with the session cookie has expired, then, by default, the user is automatically redirected to the OIDC Authorization endpoint to re-authenticate. The OIDC provider might challenge the user again if the session between the user and this OIDC provider is still active, which might happen if the session is configured to last longer than the ID token. -If the `quarkus.oidc.token.refresh-expired` is set to `true`, then the expired ID token (as well as the access token) is refreshed by using the refresh token returned with the initial authorization code grant response. -This refresh token might also be recycled (refreshed) itself as part of this process. +If the `quarkus.oidc.token.refresh-expired` is set to `true`, then the expired ID token (as well as the access token) is refreshed by using the refresh token returned with the initial authorization code grant response. +This refresh token might also be recycled (refreshed) itself as part of this process. As a result, the new session cookie is created and the session is extended. [NOTE] -- -In instances where the user is not very active, you can use the `quarkus.oidc.authentication.session-age-extension` property to help handle expired ID tokens. -If the ID token expires, the session cookie might not be returned to the Quarkus endpoint during the next user request as the cookie lifespan would have elapsed. -Quarkus assumes that this request is the first authentication request. +In instances where the user is not very active, you can use the `quarkus.oidc.authentication.session-age-extension` property to help handle expired ID tokens. +If the ID token expires, the session cookie might not be returned to the Quarkus endpoint during the next user request as the cookie lifespan would have elapsed. +Quarkus assumes that this request is the first authentication request. Set `quarkus.oidc.authentication.session-age-extension` to be _reasonably_ long for your barely-active users and in accordance with your security policies. -- @@ -975,8 +977,8 @@ To support the integration with such OAuth2 servers, `quarkus-oidc` needs to be [NOTE] -- -Even though you configure the extension to support the authorization code flows without `IdToken`, an internal `IdToken` is generated to standardize the way `quarkus-oidc` operates. -You use an `IdToken` to support the authentication session and to avoid redirecting the user to the provider, such as GitHub, on every request. +Even though you configure the extension to support the authorization code flows without `IdToken`, an internal `IdToken` is generated to standardize the way `quarkus-oidc` operates. +You use an `IdToken` to support the authentication session and to avoid redirecting the user to the provider, such as GitHub, on every request. In this case, the session lifespan is set to 5 minutes, which you can can extend further as described in the <> section. This simplifies how you handle an application that supports multiple OIDC providers. @@ -985,7 +987,7 @@ This simplifies how you handle an application that supports multiple OIDC provid The next step is to ensure that the returned access token can be useful and is valid to the current Quarkus endpoint. The first way is to call the OAuth2 provider introspection endpoint by configuring `quarkus.oidc.introspection-path`, if the provider offers such an endpoint. In this case you can use the access token as a source of roles using `quarkus.oidc.roles.source=accesstoken`. -If no introspection endpoint is present, you can attempt instead to request <> from the provider as it will at least validate the access token. +If no introspection endpoint is present, you can attempt instead to request <> from the provider as it will at least validate the access token. To do so, specify `quarkus.oidc.token.verify-access-token-with-user-info=true`. You also need to set the `quarkus.oidc.user-info-path` property to a URL endpoint that fetches the user info (or to an endpoint protected by the access token). For GitHub, since it does not have an introspection endpoint, requesting the UserInfo is required. @@ -1138,8 +1140,8 @@ You must ensure that the callback path you enter in the GitHub OAuth application === Listening to important authentication events You can register the `@ApplicationScoped` bean which will observe important OIDC authentication events. -When a user logs in for the first time, reauthenticates, or refreshes the session, the listener is updated. -In the future, more events might be reported. +When a user logs in for the first time, reauthenticates, or refreshes the session, the listener is updated. +In the future, more events might be reported. For example: [source, java] @@ -1171,14 +1173,14 @@ For information about Authorization Code Flow access token propagation to downst == Integration considerations Your application secured by OIDC integrates in an environment where it can be called from single-page applications, needs to work with well-known OIDC providers, run behind HTTP Reverse Proxy, require external and internal access, etc. - + This section discusses these considerations. === Single-page applications You can check if implementing single-page applications (SPAs) the way it is suggested in the xref:security-oidc-bearer-token-authentication.adoc#single-page-applications[Single-page applications] section of the "OpenID Connect (OIDC) Bearer token authentication" guide meets your requirements. -If you prefer to use SPAs and JavaScript APIs such as `Fetch` or `XMLHttpRequest`(XHR) with Quarkus web applications, be aware that OpenID Connect providers might not support cross-origin resource sharing (CORS) for authorization endpoints where the users are authenticated after a redirect from Quarkus. +If you prefer to use SPAs and JavaScript APIs such as `Fetch` or `XMLHttpRequest`(XHR) with Quarkus web applications, be aware that OpenID Connect providers might not support cross-origin resource sharing (CORS) for authorization endpoints where the users are authenticated after a redirect from Quarkus. This will lead to authentication failures if the Quarkus application and the OpenID Connect provider are hosted on different HTTP domains, ports, or both. In such cases, set the `quarkus.oidc.authentication.java-script-auto-redirect` property to `false`, which will instruct Quarkus to return a `499` status code and a `WWW-Authenticate` header with the `OIDC` value. @@ -1227,7 +1229,7 @@ Future callQuarkusService() async { === Cross-origin resource sharing -If you plan to consume this application from a single-page application running on a different domain, you need to configure cross-origin resource sharing (CORS). +If you plan to consume this application from a single-page application running on a different domain, you need to configure cross-origin resource sharing (CORS). For more information, see the xref:http-reference.adoc#cors-filter[CORS filter] section of the "HTTP reference" guide. === Calling Cloud provider services @@ -1334,7 +1336,7 @@ Next, if you would like, you can register this Keycloak SAML Provider as a Defau Now configure the Quarkus OIDC `web-app` application to point to the Keycloak `quarkus` realm, `quarkus.oidc.auth-server-url=http://localhost:8180/realms/quarkus` and you are ready to start authenticating your Quarkus users to the Okta SAML 2.0 provider using an OIDC to SAML bridge provided by Keycloak OIDC and Okta SAML 2.0 providers. -You can configure other OIDC providers to provide a SAML bridge similarly to how it can be done for Keycloak. +You can configure other OIDC providers to provide a SAML bridge similarly to how it can be done for Keycloak. [[integration-testing]] == Testing diff --git a/docs/src/main/asciidoc/security-oidc-configuration-properties-reference.adoc b/docs/src/main/asciidoc/security-oidc-configuration-properties-reference.adoc index ac56880885d10..438a9f72a3ec4 100644 --- a/docs/src/main/asciidoc/security-oidc-configuration-properties-reference.adoc +++ b/docs/src/main/asciidoc/security-oidc-configuration-properties-reference.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :diataxis-type: reference :categories: security +:topics: security,oidc +:extensions: io.quarkus:quarkus-oidc As a Quarkus developer, you configure the Quarkus OpenID Connect (OIDC) extension by setting the following properties in the `src/main/resources/application.properties` file. diff --git a/docs/src/main/asciidoc/security-openid-connect-client-reference.adoc b/docs/src/main/asciidoc/security-openid-connect-client-reference.adoc index f875bc2f8931a..1688c6ffecb20 100644 --- a/docs/src/main/asciidoc/security-openid-connect-client-reference.adoc +++ b/docs/src/main/asciidoc/security-openid-connect-client-reference.adoc @@ -5,6 +5,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = OpenID Connect (OIDC) and OAuth2 Client and Filters Reference Guide include::_attributes.adoc[] +:categories: security +:topics: security,oidc,client +:extensions: io.quarkus:quarkus-oidc-client This reference guide explains how to use: diff --git a/docs/src/main/asciidoc/security-openid-connect-client.adoc b/docs/src/main/asciidoc/security-openid-connect-client.adoc index 2a1670dca3fe5..62a63de2f71a4 100644 --- a/docs/src/main/asciidoc/security-openid-connect-client.adoc +++ b/docs/src/main/asciidoc/security-openid-connect-client.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: security :summary: This guide explains how to use OpenID Connect and OAuth2 Client and Filters to acquire, refresh and propagate access tokens. +:topics: security,oidc,client +:extensions: io.quarkus:quarkus-oidc-client This quickstart demonstrates how to use `OpenID Connect Client Reactive Filter` to acquire and propagate access tokens as `HTTP Authorization Bearer` access tokens, alongside `OpenID Token Propagation Reactive Filter` which propagates the incoming `HTTP Authorization Bearer` access tokens. diff --git a/docs/src/main/asciidoc/security-openid-connect-dev-services.adoc b/docs/src/main/asciidoc/security-openid-connect-dev-services.adoc index f91f0c0671348..100df919f26ad 100644 --- a/docs/src/main/asciidoc/security-openid-connect-dev-services.adoc +++ b/docs/src/main/asciidoc/security-openid-connect-dev-services.adoc @@ -8,6 +8,8 @@ include::_attributes.adoc[] :categories: security :keywords: sso oidc security keycloak :summary: Start Keycloak or other providers automatically in dev and test modes. +:topics: security,oidc,keycloak,devservices,tooling,testing,devmode +:extensions: io.quarkus:quarkus-oidc This guide covers the Dev Services and UI for OpenID Connect (OIDC) Keycloak provider and explains how to support Dev Services and UI for other OpenID Connect providers. It also describes Dev UI for all OpenID Connect providers which have already been started before Quarkus is launched in a dev mode. diff --git a/docs/src/main/asciidoc/security-openid-connect-multitenancy.adoc b/docs/src/main/asciidoc/security-openid-connect-multitenancy.adoc index 58034abdb8603..9622829047e1a 100644 --- a/docs/src/main/asciidoc/security-openid-connect-multitenancy.adoc +++ b/docs/src/main/asciidoc/security-openid-connect-multitenancy.adoc @@ -8,6 +8,8 @@ include::_attributes.adoc[] :categories: security :keywords: sso oidc oauth2 security :summary: This guide demonstrates how your OpenID Connect application can support multi-tenancy so that you can serve multiple tenants from a single application. +:topics: security,oidc,multitenancy +:extensions: io.quarkus:quarkus-oidc This guide demonstrates how your OpenID Connect (OIDC) application can support multi-tenancy so that you can serve multiple tenants from a single application. Tenants can be distinct realms or security domains within the same OpenID Provider or even distinct OpenID Providers. diff --git a/docs/src/main/asciidoc/security-openid-connect-providers.adoc b/docs/src/main/asciidoc/security-openid-connect-providers.adoc index bcc54c2b451e5..31b5a8b0d56d8 100644 --- a/docs/src/main/asciidoc/security-openid-connect-providers.adoc +++ b/docs/src/main/asciidoc/security-openid-connect-providers.adoc @@ -10,6 +10,8 @@ include::_attributes.adoc[] :categories: security,web :keywords: oidc github twitter google facebook mastodon microsoft apple spotify twitch :toclevels: 3 +:topics: security,oidc,github,twitter,google,facebook,mastodon,microsoft,apple,spotify,twitch +:extensions: io.quarkus:quarkus-oidc This document explains how to configure well-known social OIDC and OAuth2 providers. diff --git a/docs/src/main/asciidoc/security-overview.adoc b/docs/src/main/asciidoc/security-overview.adoc index fac303f37048c..a262cc671367a 100644 --- a/docs/src/main/asciidoc/security-overview.adoc +++ b/docs/src/main/asciidoc/security-overview.adoc @@ -8,6 +8,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :diataxis-type: concept :categories: security +:topics: security Quarkus Security is a framework that provides the architecture, multiple authentication and authorization mechanisms, and other tools for you to build secure and production-quality Java applications. diff --git a/docs/src/main/asciidoc/security-proactive-authentication.adoc b/docs/src/main/asciidoc/security-proactive-authentication.adoc index b924a493021d5..0fbc81236a902 100644 --- a/docs/src/main/asciidoc/security-proactive-authentication.adoc +++ b/docs/src/main/asciidoc/security-proactive-authentication.adoc @@ -8,6 +8,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :diataxis-type: concept :categories: security,web +:topics: security,authentication +:extensions: io.quarkus:quarkus-vertx-http Proactive authentication is enabled in Quarkus by default. This means that if an incoming request has a credential then that request will always be authenticated, even if the target page does not require authentication. diff --git a/docs/src/main/asciidoc/security-properties.adoc b/docs/src/main/asciidoc/security-properties.adoc index f3a2c099991be..dc6d3d36a78d1 100644 --- a/docs/src/main/asciidoc/security-properties.adoc +++ b/docs/src/main/asciidoc/security-properties.adoc @@ -7,6 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :categories: security :summary: This guide demonstrates how your Quarkus application can use a .properties file to store your user identities. +:topics: security,identity-providers +:extensions: io.quarkus:quarkus-elytron-security-properties-file Quarkus provides support for properties file-based authentication intended for development and testing purposes. It is not recommended to use this authentication in production as, at present, only plain-text and MD5 hashed passwords are used, and properties files are generally too limited. diff --git a/docs/src/main/asciidoc/security-testing.adoc b/docs/src/main/asciidoc/security-testing.adoc index 629f9f3cd8aab..234bc9d736d37 100644 --- a/docs/src/main/asciidoc/security-testing.adoc +++ b/docs/src/main/asciidoc/security-testing.adoc @@ -5,6 +5,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Security Testing include::_attributes.adoc[] +:categories: security +:topics: security,testing +:extensions: io.quarkus:quarkus-test-security This document describes how to test Quarkus Security. diff --git a/docs/src/main/asciidoc/security-vulnerability-detection.adoc b/docs/src/main/asciidoc/security-vulnerability-detection.adoc index 303348de8536b..4d11529ac6d30 100644 --- a/docs/src/main/asciidoc/security-vulnerability-detection.adoc +++ b/docs/src/main/asciidoc/security-vulnerability-detection.adoc @@ -8,6 +8,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::_attributes.adoc[] :diataxis-type: concept :categories: security,contributing +:topics: security,vulnerability Most of the Quarkus tags are registered in the US link:https://nvd.nist.gov[National Vulnerability Database (NVD)] in Common Platform Enumeration (CPE) name format. diff --git a/docs/src/main/asciidoc/security-webauthn.adoc b/docs/src/main/asciidoc/security-webauthn.adoc index 88231393c1873..878b2398069ff 100644 --- a/docs/src/main/asciidoc/security-webauthn.adoc +++ b/docs/src/main/asciidoc/security-webauthn.adoc @@ -5,11 +5,13 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// [id="security-webauthn"] = Using Security with WebAuthn -:extension-status: preview - include::_attributes.adoc[] +:extension-status: preview +:categories: security +:topics: security,webauthn,authorization +:extensions: io.quarkus:quarkus-security-webauthn -This guide demonstrates how your Quarkus application can use WebAuthn authentication instead of +This guide demonstrates how your Quarkus application can use WebAuthn authentication instead of passwords. include::{includes}/extension-status.adoc[] @@ -235,7 +237,7 @@ import io.vertx.ext.auth.webauthn.PublicKeyCredential; @Table(uniqueConstraints = @UniqueConstraint(columnNames = {"userName", "credID"})) @Entity public class WebAuthnCredential extends PanacheEntity { - + /** * The username linked to this authenticator */ @@ -284,16 +286,16 @@ public class WebAuthnCredential extends PanacheEntity { */ @OneToMany(mappedBy = "webAuthnCredential") public List x5c = new ArrayList<>(); - + public String fmt; - + // owning side @OneToOne public User user; public WebAuthnCredential() { } - + public WebAuthnCredential(Authenticator authenticator, User user) { aaguid = authenticator.getAaguid(); if(authenticator.getAttestationCertificates() != null) @@ -320,7 +322,7 @@ public class WebAuthnCredential extends PanacheEntity { public static Uni> findByUserName(String userName) { return list("userName", userName); } - + public static Uni> findByCredID(String credID) { return list("credID", credID); } @@ -345,10 +347,10 @@ import io.quarkus.hibernate.reactive.panache.PanacheEntity; @Entity public class WebAuthnCertificate extends PanacheEntity { - + @ManyToOne public WebAuthnCredential webAuthnCredential; - + /** * The list of X509 certificates encoded as base64url. */ @@ -494,7 +496,7 @@ public class MyWebAuthnSetup implements WebAuthnUserProvider { return ret; }); } - + @Override public Set getRoles(String userId) { if(userId.equals("admin")) { @@ -539,11 +541,11 @@ in `src/main/resources/META-INF/resources/index.html`: overflow: hidden; background-color: #333; } - + nav > ul > li { float: left; } - + nav > ul > li > a { display: block; color: white; @@ -551,13 +553,13 @@ in `src/main/resources/META-INF/resources/index.html`: padding: 14px 16px; text-decoration: none; } - + nav > ul > li > a:hover { background-color: #111; } - +