Sync documentation of main branch

Author: actions-user

_versions/main/guides/dev-mode-differences.adoc

@@ -46,13 +46,6 @@ Examples of such operations are:
 * Running scheduled operations
 * Building a container
 
-[TIP]
-====
-A new Dev UI has been implemented in Quarkus 3.x.
-Not all the features are available yet.
-You can still access the previous version of the Dev UI using: http://localhost:8080/q/dev-ui/.
-====
-
 === Error pages
 
 In an effort to make development errors very easy to diagnose, Quarkus provides various detailed error pages when running in dev mode.

_versions/main/guides/funqy-gcp-functions.adoc

@@ -81,8 +81,6 @@ In this example, we will create two background functions and a cloud events func
 Background functions allow you to react to Google Cloud events like PubSub messages, Cloud Storage events, Firestore events, ...
 Cloud events functions allow you to react to supported events using the Cloud Events specification.
 
-NOTE: Quarkus supports Cloud Functions gen 1 and gen 2. For an overview of Cloud Functions gen 2 see https://cloud.google.com/functions/docs/2nd-gen/overview[this page] on the Google Cloud Functions documentation. To use gen 2 you must add the `--gen2` parameter.
-
 [source,java]
 ----
 import jakarta.inject.Inject;
@@ -231,8 +229,6 @@ You can also simply add a file to Cloud Storage using the command line of the we
 
 === Cloud Events Functions - Cloud Storage
 
-WARNING: Cloud Events Function is a feature of Cloud Functions gen 2 only.
-
 Before deploying your function, you need to create a bucket.
 
 [source,bash]
@@ -244,7 +240,7 @@ Then, use this command to deploy to Google Cloud Functions:
 
 [source,bash]
 ----
-gcloud functions deploy quarkus-example-cloud-event --gen2 \
+gcloud functions deploy quarkus-example-cloud-event \
   --entry-point=io.quarkus.funqy.gcp.functions.FunqyCloudEventsFunction \
   --runtime=java21 --trigger-bucket=example-cloud-event --source=target/deployment
 ----
@@ -324,8 +320,6 @@ This will call your PubSub background function with a Cloud Storage event `{"nam
 
 === Cloud Events Functions - Cloud Storage
 
-WARNING: Cloud Events Function is a feature of Cloud Functions gen 2 only.
-
 For cloud events functions, you launch the invoker with a target class of `io.quarkus.funqy.gcp.functions.FunqyCloudEventsFunction``.
 
 [source,bash,subs="attributes"]
@@ -457,8 +451,6 @@ class GreetingFunctionsStorageTest {
 
 === Cloud Events Functions - Cloud Storage
 
-WARNING: Cloud Events Function is a feature of Cloud Functions gen 2 only.
-
 [source,java]
 ----
 import static io.restassured.RestAssured.given;

_versions/main/guides/gcp-functions-http.adoc

@@ -63,13 +63,11 @@ one for Reactive routes and one for xref:funqy-http.adoc[Funqy HTTP].
 [NOTE]
 ====
 These various endpoints are for demonstration purposes.
-For real life applications, you should choose one of this technology and stick to it.
+For real life applications, you should choose one of these technologies and stick to it.
 ====
 
 If you don't need endpoints of each type, you can remove the corresponding extensions from your `pom.xml`.
 
-NOTE: Quarkus supports Cloud Functions gen 1 and gen 2. For an overview of Cloud Functions gen 2 see https://cloud.google.com/functions/docs/2nd-gen/overview[this page] on the Google Cloud Functions documentation. To use gen 2 you must and add the `--gen2` parameter.
-
 === The Jakarta REST endpoint
 
 [source,java]

_versions/main/guides/gcp-functions.adoc

@@ -58,8 +58,6 @@ gcloud auth login
 For this example project, we will create four functions, one `HttpFunction`, one `BackgroundFunction` (Storage event),
 one `RawBackgroundFunction` (PubSub event) and one `CloudEventsFunction` (storage event using the Cloud Events specification).
 
-NOTE: Quarkus supports Cloud Functions gen 1 and gen 2. For an overview of Cloud Functions gen 2 see https://cloud.google.com/functions/docs/2nd-gen/overview[this page] on the Google Cloud Functions documentation. To use gen 2 you must add the `--gen2` parameter.
-
 == Choose Your Function
 
 The `quarkus-google-cloud-functions` extension scans your project for a class that directly implements the Google Cloud `HttpFunction`, `BackgroundFunction`, `RawBackgroundFunction` or `CloudEventsFunction` interface.
@@ -193,8 +191,6 @@ public class RawBackgroundFunctionPubSubTest implements RawBackgroundFunction {
 
 === The CloudEventsFunction
 
-WARNING: `CloudEventsFunction` is a feature of Cloud Functions gen 2 only.
-
 This `CloudEventsFunction` is triggered by a Cloud Events Storage event, you can use any Cloud Events supported by Google Cloud instead.
 
 [source,java]
@@ -332,14 +328,12 @@ gcloud functions call quarkus-example-pubsub --data '{"data":{"greeting":"world"
 
 === The CloudEventsFunction
 
-WARNING: `CloudEventsFunction` is a feature of Cloud Functions gen 2 only.
-
 This is an example command to deploy your `CloudEventsFunction` to Google Cloud, as the function is triggered by a Storage event,
 it needs to use `--trigger-bucket` parameter with the name of a previously created bucket:
 
 [source,bash]
 ----
-gcloud functions deploy quarkus-example-cloud-event --gen2 \
+gcloud functions deploy quarkus-example-cloud-event \
   --entry-point=io.quarkus.gcp.functions.QuarkusCloudEventsFunction \
   --runtime=java21 --trigger-bucket=example-cloud-event --source=target/deployment
 ----
@@ -429,8 +423,6 @@ This will call your PubSub background function with a PubSubMessage `{"greeting"
 
 === The CloudEventsFunction
 
-IMPORTANT: `CloudEventsFunction` is a feature of Cloud Function gen 2 only.
-
 For cloud events functions, you launch the invoker with a target class of `io.quarkus.gcp.functions.QuarkusCloudEventsFunction`.
 
 [source,bash,subs="attributes"]
@@ -592,8 +584,6 @@ class RawBackgroundFunctionPubSubTestCase {
 
 === The CloudEventsFunction
 
-WARNING: Cloud Events Function is a feature of Cloud Functions gen 2 only.
-
 [source,java]
 ----
 import static io.restassured.RestAssured.given;

_versions/main/guides/websockets-next-reference.adoc

@@ -267,7 +267,29 @@ However, it may also accept the following parameters:
 The message object represents the data sent and can be accessed as either raw content (`String`, `JsonObject`, `JsonArray`, `Buffer` or `byte[]`) or deserialized high-level objects, which is the recommended approach.
 
 When receiving a `Multi`, the method is invoked once per connection, and the provided `Multi` receives the items transmitted by this connection.
-The method must subscribe to the `Multi` to receive these items (or return a Multi).
+If the method returns a `Multi` (constructed from the received one), Quarkus will automatically subscribe to it and write the emitted items until completion, failure, or cancellation.
+However, if your method does not return a `Multi`, you must subscribe to the incoming `Multi` to consume the data.
+
+Here are two examples:
+
+[source,java]
+----
+// No need to subscribe to the incoming Multi as the method returns a Multi derived from the incoming one
+@OnTextMessage
+public Multi<ChatMessage> stream(Multi<ChatMessage> incoming) {
+    return incoming.log();
+}
+
+// ...
+
+// Must subscribe to the incoming Multi as the method does not return a Multi, otherwise no data will be consumed
+@OnTextMessage
+public void stream(Multi<ChatMessage> incoming) {
+    incoming.subscribe().with(item -> log(item));
+}
+----
+
+See <<subscribe-or-not-subscribe>> to learn more about subscribing to the incoming `Multi`.
 
 ==== Supported return types
 
@@ -319,7 +341,9 @@ Multi<ResponseMessage> stream(Message m) {
 }
 ----
 
-When returning a Multi, Quarkus subscribes to the returned Multi automatically and writes the emitted items until completion, failure, or cancellation. Failure or cancellation terminates the connection.
+Methods returning `Uni` and `Multi` are considered non-blocking.
+In addition, Quarkus automatically subscribes to the returned `Multi` / `Uni` and writes the emitted items until completion, failure, or cancellation.
+Failure or cancellation terminates the connection.
 
 ==== Streams
 
@@ -340,7 +364,8 @@ public Multi<ChatMessage> stream(Multi<ChatMessage> incoming) {
 
 This approach allows bi-directional streaming.
 
-When the method returns `void`, it must subscribe to the incoming `Multi`:
+When the method returns `void`, and so does not return a `Multi`, the code must subscribe to the incoming `Multi`.
+Otherwise, no data will be consumed, and the connection will not be closed:
 
 [source, java]
 ----
@@ -350,6 +375,10 @@ public void stream(Multi<ChatMessage> incoming) {
 }
 ----
 
+Also note that the `stream` method will complete before the `Multi` completes.
+
+See <<subscribe-or-not-subscribe>> to learn more about subscribing to the incoming `Multi`.
+
 ==== Skipping reply
 
 When a method is intended to produce a message written to the client, it can emit `null`.
@@ -636,7 +665,19 @@ String param = connection.pathParam("foo");
 The `WebSocketConnection` provides both a blocking and a non-blocking method variants to send messages:
 
 - `sendTextAndAwait(String message)`: Sends a text message to the client and waits for the message to be sent. It's blocking and should only be called from an executor thread.
-- `sendText(String message)`: Sends a text message to the client. It returns a `Uni`. It's non-blocking, but you must subscribe to it.
+- `sendText(String message)`: Sends a text message to the client. It returns a `Uni`. It's non-blocking. Make sure you or Quarkus subscribes to the returned `Uni` to send the message.
+If you return the `Uni` from a method invoked by Quarkus (like with Quarkus REST, Quarkus WebSocket Next or Quarkus Messaging), it will subscribe to it and send the message.
+For example:
+
+[source,java]
+----
+@POST
+public Uni<Void> send() {
+    return connection.sendText("Hello!"); // Quarkus automatically subscribes to the returned Uni and sends the message.
+}
+----
+
+See <<subscribe-or-not-subscribe>> to learn more about subscribing to the `Uni`.
 
 [[list-open-connections]]
 ==== List open connections
@@ -655,7 +696,7 @@ class MyBean {
   OpenConnections connections;
 
   void logAllOpenConnections() {
-     Log.infof("Open connections: %s", connections.listAll()); <1>
+     Log.infof("Open connections: %s", connections.listAll()); // <1>
   }
 }
 ----
@@ -1078,7 +1119,17 @@ String param = connection.pathParam("foo");
 The `WebSocketClientConnection` provides both a blocking and a non-blocking method variants to send messages:
 
 - `sendTextAndAwait(String message)`: Sends a text message to the client and waits for the message to be sent. It's blocking and should only be called from an executor thread.
-- `sendText(String message)`: Sends a text message to the client. It returns a `Uni`. It's non-blocking, but you must subscribe to it.
+- `sendText(String message)`: Sends a text message to the client. It returns a `Uni`. It's non-blocking. Make sure you or Quarkus subscribes to the returned `Uni` to send the message.
+If you return the `Uni` from a method invoked by Quarkus (like with Quarkus REST, Quarkus WebSocket Next or Quarkus Messaging), it will subscribe to it and send the message.
+For example:
+
+[source,java]
+----
+@POST
+public Uni<Void> send() {
+    return connection.sendText("Hello!"); // Quarkus automatically subscribes to the returned Uni and sends the message.
+}
+----
 
 [[list-open-client-connections]]
 ==== List open client connections
@@ -1203,6 +1254,39 @@ quarkus.log.category."io.quarkus.websockets.next.traffic".level=DEBUG <3>
 <2> Set the number of characters of a text message payload which will be logged.
 <3> Enable `DEBUG` level is for the logger `io.quarkus.websockets.next.traffic`.
 
+[[subscribe-or-not-subscribe]]
+== When to subscribe to a `Uni` or `Multi`
+
+`Uni` and `Multi` are lazy types, which means that they do not start processing until they are subscribed to.
+
+When you get (from a parameter or from a method you called) a `Uni` or a `Multi`, whether you should subscribe to it depends on the context:
+
+- if you return the `Uni` or `Multi` in a method invoked by Quarkus (like with Quarkus REST, Quarkus WebSocket Next or Quarkus Messaging), Quarkus subscribes to it and processes the items emitted by the `Multi` or the item emitted by the `Uni`:
+
+[source, java]
+----
+@Incoming("...")
+@Outgoing("...")
+public Multi<String> process(Multi<String> input) {
+    // No need to subscribe to the input Multi, the `process` method is called by Quarkus (Messaging).
+    return input.map(String::toUpperCase);
+}
+----
+
+When a `Uni` or `Multi` is returned from a method annotated with `@OnOpen`, `@OnTextMessage`, `@OnBinaryMessage`, or `@OnClose`, Quarkus subscribes to it automatically.
+
+- if you do not return the `Uni` or `Multi` in a method invoked by Quarkus, you should subscribe to it:
+
+[source, java]
+----
+@Incoming("...")
+@Outgoing("...")
+public void process(Multi<String> input) {
+    input.map(String::toUpperCase)
+        .subscribe().with(s -> log(s));
+}
+----
+
 [[telemetry]]
 == Telemetry