From 0aa09ef97952c321336dee69434da8737eb0e8c2 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Wed, 11 Dec 2024 01:56:42 +0000 Subject: [PATCH] Sync documentation of main branch --- .../main/config/quarkus-all-config.adoc | 2 +- .../main/config/quarkus-kafka-client.adoc | 2 +- .../quarkus-kafka-client_quarkus.kafka.adoc | 2 +- ...afka-client_quarkus.kafka.devservices.adoc | 2 +- .../main/guides/command-mode-reference.adoc | 2 +- _versions/main/guides/kafka-dev-services.adoc | 4 +- _versions/main/guides/native-reference.adoc | 8 +-- _versions/main/guides/rest-client.adoc | 32 +++++++++ .../main/guides/smallrye-fault-tolerance.adoc | 4 +- .../guides/websockets-next-reference.adoc | 12 ++-- _versions/main/guides/writing-extensions.adoc | 69 +++++++++++++++++++ 11 files changed, 122 insertions(+), 17 deletions(-) diff --git a/_generated-doc/main/config/quarkus-all-config.adoc b/_generated-doc/main/config/quarkus-all-config.adoc index 2018f7db50b..4d789edc563 100644 --- a/_generated-doc/main/config/quarkus-all-config.adoc +++ b/_generated-doc/main/config/quarkus-all-config.adoc @@ -32976,7 +32976,7 @@ Kafka dev service container type. Redpanda, Strimzi and kafka-native container providers are supported. Default is redpanda. -For Redpanda: See https://docs.redpanda.com/current/get-started/quick-start/ and https://hub.docker.com/r/vectorized/redpanda +For Redpanda: See https://docs.redpanda.com/current/get-started/quick-start/ and https://hub.docker.com/r/redpandadata/redpanda For Strimzi: See https://github.com/strimzi/test-container and https://quay.io/repository/strimzi-test-container/test-container diff --git a/_generated-doc/main/config/quarkus-kafka-client.adoc b/_generated-doc/main/config/quarkus-kafka-client.adoc index 7b114937db2..6908f054b66 100644 --- a/_generated-doc/main/config/quarkus-kafka-client.adoc +++ b/_generated-doc/main/config/quarkus-kafka-client.adoc @@ -134,7 +134,7 @@ Kafka dev service container type. Redpanda, Strimzi and kafka-native container providers are supported. Default is redpanda. -For Redpanda: See https://docs.redpanda.com/current/get-started/quick-start/ and https://hub.docker.com/r/vectorized/redpanda +For Redpanda: See https://docs.redpanda.com/current/get-started/quick-start/ and https://hub.docker.com/r/redpandadata/redpanda For Strimzi: See https://github.com/strimzi/test-container and https://quay.io/repository/strimzi-test-container/test-container diff --git a/_generated-doc/main/config/quarkus-kafka-client_quarkus.kafka.adoc b/_generated-doc/main/config/quarkus-kafka-client_quarkus.kafka.adoc index 7b114937db2..6908f054b66 100644 --- a/_generated-doc/main/config/quarkus-kafka-client_quarkus.kafka.adoc +++ b/_generated-doc/main/config/quarkus-kafka-client_quarkus.kafka.adoc @@ -134,7 +134,7 @@ Kafka dev service container type. Redpanda, Strimzi and kafka-native container providers are supported. Default is redpanda. -For Redpanda: See https://docs.redpanda.com/current/get-started/quick-start/ and https://hub.docker.com/r/vectorized/redpanda +For Redpanda: See https://docs.redpanda.com/current/get-started/quick-start/ and https://hub.docker.com/r/redpandadata/redpanda For Strimzi: See https://github.com/strimzi/test-container and https://quay.io/repository/strimzi-test-container/test-container diff --git a/_generated-doc/main/config/quarkus-kafka-client_quarkus.kafka.devservices.adoc b/_generated-doc/main/config/quarkus-kafka-client_quarkus.kafka.devservices.adoc index f81fbfe3128..7d8f6cc1d5f 100644 --- a/_generated-doc/main/config/quarkus-kafka-client_quarkus.kafka.devservices.adoc +++ b/_generated-doc/main/config/quarkus-kafka-client_quarkus.kafka.devservices.adoc @@ -63,7 +63,7 @@ Kafka dev service container type. Redpanda, Strimzi and kafka-native container providers are supported. Default is redpanda. -For Redpanda: See https://docs.redpanda.com/current/get-started/quick-start/ and https://hub.docker.com/r/vectorized/redpanda +For Redpanda: See https://docs.redpanda.com/current/get-started/quick-start/ and https://hub.docker.com/r/redpandadata/redpanda For Strimzi: See https://github.com/strimzi/test-container and https://quay.io/repository/strimzi-test-container/test-container diff --git a/_versions/main/guides/command-mode-reference.adoc b/_versions/main/guides/command-mode-reference.adoc index 14f8f2f1831..074fe72adc8 100644 --- a/_versions/main/guides/command-mode-reference.adoc +++ b/_versions/main/guides/command-mode-reference.adoc @@ -255,7 +255,7 @@ Consequently, mocking CDI beans with `QuarkusMock` or `@InjectMock` is not suppo It is possible to mock CDI beans by leveraging xref:getting-started-testing.adoc#testing_different_profiles[test profiles] though. -For instance, in the following test, the singleton `CdiBean1` will be mocked by `MockedCdiBean1`: +For instance, in the following test, the launched application would receive a mocked singleton `CdiBean1`. The implementation `MockedCdiBean1` is provided by the test: [source,java] ---- diff --git a/_versions/main/guides/kafka-dev-services.adoc b/_versions/main/guides/kafka-dev-services.adoc index cbe41d890c6..590f2ffda87 100644 --- a/_versions/main/guides/kafka-dev-services.adoc +++ b/_versions/main/guides/kafka-dev-services.adoc @@ -56,8 +56,8 @@ Dev Services for Kafka supports https://redpanda.com[Redpanda], https://github/o and https://strimzi.io[Strimzi] (in https://github.com/apache/kafka/blob/trunk/config/kraft/README.md[Kraft] mode) images. **Redpanda** is a Kafka compatible event streaming platform. -Because it provides a fast startup times, Dev Services defaults to Redpanda images from `vectorized/redpanda`. -You can select any version from https://hub.docker.com/r/vectorized/redpanda. +Because it provides a fast startup times, Dev Services defaults to Redpanda images from `redpandadata/redpanda`. +You can select any version from https://hub.docker.com/r/redpandadata/redpanda. **kafka-native** provides images of standard Apache Kafka distribution compiled to native binary using Quarkus and GraalVM. While still being _experimental_, it provides very fast startup times with small footprint. diff --git a/_versions/main/guides/native-reference.adoc b/_versions/main/guides/native-reference.adoc index f4e6e491bf8..a9e8baa6341 100644 --- a/_versions/main/guides/native-reference.adoc +++ b/_versions/main/guides/native-reference.adoc @@ -598,7 +598,7 @@ invoke Maven's `verify` goal with `-DskipITs=false -Dquarkus.test.integration-te generate the native image configuration. For example: -[source,bash] +[source,bash,subs=attributes+] ---- $ ./mvnw verify -DskipITs=false -Dquarkus.test.integration-test-profile=test-with-native-agent ... @@ -660,7 +660,7 @@ This can be useful to verify that the native integration tests work as expected, assuming that the JVM unit tests have generated the correct native image configuration. The typical workflow here would be to first run the integration tests with the native image agent as shown in the previous section: -[source,bash] +[source,bash,subs=attributes+] ---- $ ./mvnw verify -DskipITs=false -Dquarkus.test.integration-test-profile=test-with-native-agent ... @@ -671,7 +671,7 @@ $ ./mvnw verify -DskipITs=false -Dquarkus.test.integration-test-profile=test-wit And then request a native build passing in the configuration apply flag. A message during the native build process will indicate that the native image agent generated configuration files are being applied: -[source,bash] +[source,bash,subs=attributes+] ---- $ ./mvnw verify -Dnative -Dquarkus.native.agent-configuration-apply ... @@ -702,7 +702,7 @@ and confirm that the class and/or package making the call or being accessed is n If the missing entry is related to some resource, you should inspect the Quarkus build debug output and verify which resource patterns are being discarded, e.g. -[source,bash] +[source,bash,subs=attributes+] ---- $ ./mvnw -X verify -DskipITs=false -Dquarkus.test.integration-test-profile=test-with-native-agent ... diff --git a/_versions/main/guides/rest-client.adoc b/_versions/main/guides/rest-client.adoc index 71900e4abfd..3c2c2a2be1d 100644 --- a/_versions/main/guides/rest-client.adoc +++ b/_versions/main/guides/rest-client.adoc @@ -325,6 +325,38 @@ public interface ExtensionsService { } ---- +=== Dynamic base URLs + +The REST client allows for a per invocation override of the base URL using the `io.quarkus.rest.client.reactive.Url` annotation. + +Here is a simple example: + +[source, java] +---- +package org.acme.rest.client; + +import org.eclipse.microprofile.rest.client.inject.RegisterRestClient; + +import jakarta.ws.rs.GET; +import jakarta.ws.rs.Path; +import jakarta.ws.rs.PathParam; +import jakarta.ws.rs.QueryParam; +import java.util.Set; + +import io.quarkus.rest.client.reactive.Url; + +@Path("/extensions") +@RegisterRestClient +public interface ExtensionsService { + + @GET + @Path("/stream/{stream}") + Set getByStream(@Url String url, @PathParam("stream") String stream, @QueryParam("id") String id); +} +---- + +When the `url` parameter is non-null, it will override the base URL that is configured for the client (the default base URL configuration is still mandatory). + === Sending large payloads The REST Client is capable of sending arbitrarily large HTTP bodies without buffering the contents in memory, if one of the following types is used: diff --git a/_versions/main/guides/smallrye-fault-tolerance.adoc b/_versions/main/guides/smallrye-fault-tolerance.adoc index 42c47a9d441..71a0d095308 100644 --- a/_versions/main/guides/smallrye-fault-tolerance.adoc +++ b/_versions/main/guides/smallrye-fault-tolerance.adoc @@ -576,7 +576,7 @@ implementation("io.quarkus:quarkus-smallrye-fault-tolerance") == Additional resources SmallRye Fault Tolerance has more features than shown here. -Please check the link:https://smallrye.io/docs/smallrye-fault-tolerance/6.7.0/index.html[SmallRye Fault Tolerance documentation] to learn about them. +Please check the link:https://smallrye.io/docs/smallrye-fault-tolerance/6.7.1/index.html[SmallRye Fault Tolerance documentation] to learn about them. In Quarkus, you can use the SmallRye Fault Tolerance optional features out of the box. @@ -608,7 +608,7 @@ quarkus.fault-tolerance.mp-compatibility=true ---- ==== -The link:https://smallrye.io/docs/smallrye-fault-tolerance/6.7.0/reference/programmatic-api.html[programmatic API] is present and integrated with the declarative, annotation-based API. +The link:https://smallrye.io/docs/smallrye-fault-tolerance/6.7.1/reference/programmatic-api.html[programmatic API] is present and integrated with the declarative, annotation-based API. You can use the `Guard`, `TypedGuard` and `@ApplyGuard` APIs out of the box. Support for Kotlin is present (assuming you use the Quarkus extension for Kotlin), so you can guard your `suspend` functions with fault tolerance annotations. diff --git a/_versions/main/guides/websockets-next-reference.adoc b/_versions/main/guides/websockets-next-reference.adoc index 1ff21130b0d..899010757a9 100644 --- a/_versions/main/guides/websockets-next-reference.adoc +++ b/_versions/main/guides/websockets-next-reference.adoc @@ -240,15 +240,19 @@ WebSocket Next supports _blocking_ and _non-blocking_ logic, akin to Quarkus RES Here are the rules governing execution: * Methods annotated with `@RunOnVirtualThread`, `@Blocking` or `@Transactional` are considered blocking. +* Methods declared in a class annotated with `@RunOnVirtualThread` are considered blocking. * Methods annotated with `@NonBlocking` are considered non-blocking. -* Methods declared on a class annotated with `@Transactional` are considered blocking unless annotated with `@NonBlocking`. +* Methods declared in a class annotated with `@Transactional` are considered blocking unless annotated with `@NonBlocking`. * If the method does not declare any of the annotations listed above the execution model is derived from the return type: ** Methods returning `Uni` and `Multi` are considered non-blocking. ** Methods returning `void` or any other type are considered blocking. -* Kotlin `suspend` functions are always considered non-blocking and may not be annotated with `@Blocking`, `@NonBlocking` or `@RunOnVirtualThread`. +* Kotlin `suspend` functions are always considered non-blocking and may not be annotated with `@Blocking`, `@NonBlocking` + or `@RunOnVirtualThread` and may not be in a class annotated with `@RunOnVirtualThread`. * Non-blocking methods must execute on the connection's event loop thread. -* Blocking methods must execute on a worker thread unless annotated with `@RunOnVirtualThread`. -* Methods annotated with `@RunOnVirtualThread` must execute on a virtual thread, each invocation spawns a new virtual thread. +* Blocking methods must execute on a worker thread unless annotated with `@RunOnVirtualThread` or in a class annotated + with `@RunOnVirtualThread`. +* Methods annotated with `@RunOnVirtualThread` or declared in class annotated with `@RunOnVirtualThread` must execute on + a virtual thread, each invocation spawns a new virtual thread. ==== Method parameters diff --git a/_versions/main/guides/writing-extensions.adoc b/_versions/main/guides/writing-extensions.adoc index 5e6f84dcf83..5ef15c1907b 100644 --- a/_versions/main/guides/writing-extensions.adoc +++ b/_versions/main/guides/writing-extensions.adoc @@ -1584,6 +1584,75 @@ If bytecode recording isn't sufficient, link:https://github.com/quarkusio/gizmo/ Extensions often need a way to determine whether a given class is part of the application's runtime classpath. The proper way for an extension to perform this check is to use `io.quarkus.bootstrap.classloading.QuarkusClassLoader.isClassPresentAtRuntime`. +[[generating-resources]] +=== Generating Resources + +It is possible to generate resources using extensions, in some scenarios you need to generate a resource into `META-INF` directory, the resource can be a service for SPI or a simple HTML, CSS, Javascript files. + +[source,java] +---- +/** + * This build step aggregates all the produced service providers + * and outputs them as resources. + */ +@BuildStep +public void produceServiceFiles( + BuildProducer generatedStaticResourceProducer, + BuildProducer generatedResourceProducer +) throws IOException { + + generatedResourceProducer.produce( // <1> + new GeneratedResourceBuildItem( + "META-INF/services/io.quarkus.services.GreetingService", + """ + public class HelloService implements GreetingService { + + @Override + public void do() { + System.out.println("Hello!"); + } + } + """.getBytes(StandardCharsets.UTF_8))); + + + generatedStaticResourceProducer.produce( // <2> + new GeneratedStaticResourceBuildItem( + "/index.js", + "console.log('Hello World!')".getBytes(StandardCharsets.UTF_8)) + ); +} +---- + +1. Producing a SPI service implementation as a resource in META-INF/services +2. Producing a static resource (e.g., JavaScript file) served by Vertx + +==== Key Points + +. **`GeneratedResourceBuildItem`** +* Generates resources that are persisted in production mode. +* In development and other non-production modes, the resources are kept in memory and loaded using the `QuarkusClassLoader`. + +. **`GeneratedStaticResourceBuildItem`** +* Generates static resources (e.g., files like JavaScript, HTML, or CSS) served by Vertx. +* In development mode, Quarkus serves these resources using a Vertx handler backed by a classloader-based filesystem. + +==== Differences Between `GeneratedResourceBuildItem` and `GeneratedStaticResourceBuildItem` + +While both are used to generate resources, their purposes and behaviors differ: + +**`GeneratedResourceBuildItem`:** + +* Used for resources required at runtime (e.g., SPI service definitions). +* Persisted only in production mode; otherwise, stored in memory. + +**`GeneratedStaticResourceBuildItem`:** + +* Designed for serving static resources via HTTP (e.g., JavaScript or CSS files). +* In development mode, these resources are served dynamically using Vertx. +* Generates a `GeneratedResourceBuildItem`. +* Generates a `AdditionalStaticResourceBuildItem` only on normal mode. + +By using these build items appropriately, you can generate and manage resources effectively within your Quarkus extension. //// TODO: config integration ////