From acdbc2a144b2f986ae285d18ae343e327b7ebacb Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Thu, 9 Jan 2025 02:11:50 +0000 Subject: [PATCH] Sync documentation of main branch --- .../main/infra/quarkus-all-build-items.adoc | 4 ++ _versions/main/guides/datasource.adoc | 13 ++++++ .../main/guides/deploying-to-kubernetes.adoc | 2 +- _versions/main/guides/kubernetes-client.adoc | 36 +++++++-------- _versions/main/guides/security-webauthn.adoc | 3 +- .../guides/websockets-next-reference.adoc | 45 +++++++++++++------ 6 files changed, 66 insertions(+), 37 deletions(-) diff --git a/_generated-doc/main/infra/quarkus-all-build-items.adoc b/_generated-doc/main/infra/quarkus-all-build-items.adoc index 67c2a9486d8..298b1fd5736 100644 --- a/_generated-doc/main/infra/quarkus-all-build-items.adoc +++ b/_generated-doc/main/infra/quarkus-all-build-items.adoc @@ -9598,6 +9598,10 @@ _No Javadoc found_ _No Javadoc found_ +`io.quarkus.websockets.next.deployment.Callback onPingMessage` + +_No Javadoc found_ + `io.quarkus.websockets.next.deployment.Callback onPongMessage` _No Javadoc found_ diff --git a/_versions/main/guides/datasource.adoc b/_versions/main/guides/datasource.adoc index 83f02c99e9d..b86be090ced 100644 --- a/_versions/main/guides/datasource.adoc +++ b/_versions/main/guides/datasource.adoc @@ -294,6 +294,19 @@ AgroalDataSource defaultDataSource; In the above example, the type is `AgroalDataSource`, a `javax.sql.DataSource` subtype. Because of this, you can also use `javax.sql.DataSource` as the injected type. +===== Oracle considerations + +As documented in https://github.com/quarkusio/quarkus/issues/36265[issue #36265], +Oracle has a very weird behavior of committing the uncommitted transactions on connection closing. + +Which means that when stopping Quarkus for instance, in progress transactions might be committed even if incomplete. + +Given that is not the expected behavior and that it could lead to data loss, we added an interceptor that rolls back any unfinished transactions at connection close, +provided you are not using XA (in which case the transaction manager handles things for you). + +If this behavior introduced in 3.18 causes issues for your specific workload, you can disable it by setting the `-Dquarkus-oracle-no-automatic-rollback-on-connection-close` system property to `true`. +Please take the time to report your use case in our https://github.com/quarkusio/quarkus/issues[issue tracker] so that we can adjust this behavior if needed. + [[reactive-datasource]] ==== Reactive datasource diff --git a/_versions/main/guides/deploying-to-kubernetes.adoc b/_versions/main/guides/deploying-to-kubernetes.adoc index 8ab61ce549e..db6df8d52e5 100644 --- a/_versions/main/guides/deploying-to-kubernetes.adoc +++ b/_versions/main/guides/deploying-to-kubernetes.adoc @@ -301,7 +301,7 @@ of secret that contains the required credentials. Quarkus can automatically gene quarkus.kubernetes.generate-image-pull-secret=true ---- -More specifically a `Secret`like the one bellow is genrated: +More specifically a `Secret` like the one below is generated: [source,yaml] ---- diff --git a/_versions/main/guides/kubernetes-client.adoc b/_versions/main/guides/kubernetes-client.adoc index 6fd8a07919a..c0fa53f968d 100644 --- a/_versions/main/guides/kubernetes-client.adoc +++ b/_versions/main/guides/kubernetes-client.adoc @@ -474,41 +474,35 @@ public class OpenShiftClientProducer { } ---- -Mock support is also provided in a similar fashion: +Mock support is also provided in a similar fashion by using the `@WithKubernetesTestServer` explained in the previous section: [source, java] ---- -@QuarkusTestResource(OpenShiftMockServerTestResource.class) +@WithKubernetesTestServer @QuarkusTest public class OpenShiftClientTest { - @MockServer - private OpenShiftMockServer mockServer; -... ----- - -Or by using the `@WithOpenShiftTestServer` similar to the `@WithKubernetesTestServer` explained in the -previous section: - -[source, java] ----- -@WithOpenShiftTestServer -@QuarkusTest -public class OpenShiftClientTest { + @KubernetesTestServer + KubernetesServer mockServer; + @Inject + OpenShiftClient client; - @OpenShiftTestServer - private OpenShiftServer mockOpenShiftServer; -... + @Test + public void testInteractionWithAPIServer() { + RestAssured.when().get("/route/test").then() + .body("size()", is(2)); + } +} ---- -To use this feature, you have to add a dependency on `quarkus-test-openshift-client`: +To use this feature, you have to add a dependency on `quarkus-test-kubernetes-client`: [source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"] .pom.xml ---- io.quarkus - quarkus-test-openshift-client + quarkus-test-kubernetes-client test ---- @@ -516,7 +510,7 @@ To use this feature, you have to add a dependency on `quarkus-test-openshift-cli [source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"] .build.gradle ---- -testImplementation("io.quarkus:quarkus-test-openshift-client") +testImplementation("io.quarkus:quarkus-test-kubernetes-client") ---- == Configuration Reference diff --git a/_versions/main/guides/security-webauthn.adoc b/_versions/main/guides/security-webauthn.adoc index dfb35722bf7..0f5bb7b1fdb 100644 --- a/_versions/main/guides/security-webauthn.adoc +++ b/_versions/main/guides/security-webauthn.adoc @@ -1179,6 +1179,7 @@ import io.quarkus.test.security.webauthn.WebAuthnEndpointHelper; import io.quarkus.test.security.webauthn.WebAuthnHardware; import io.restassured.RestAssured; import io.restassured.filter.Filter; +import io.restassured.filter.cookie.CookieFilter; import io.restassured.specification.RequestSpecification; import io.vertx.core.json.JsonObject; @@ -1207,7 +1208,7 @@ public class WebAuthnResourceTest { } private void testWebAuthn(String username, User user, Endpoint endpoint) { - Filter cookieFilter = new RenardeCookieFilter(); + Filter cookieFilter = new CookieFilter(); WebAuthnHardware token = new WebAuthnHardware(url); verifyLoggedOut(cookieFilter); diff --git a/_versions/main/guides/websockets-next-reference.adoc b/_versions/main/guides/websockets-next-reference.adoc index 899010757a9..aa30b17a835 100644 --- a/_versions/main/guides/websockets-next-reference.adoc +++ b/_versions/main/guides/websockets-next-reference.adoc @@ -79,7 +79,7 @@ implementation("io.quarkus:quarkus-websockets-next") Both the <> and <> define _endpoints_ that are used to consume and send messages. The endpoints are implemented as CDI beans and support injection. -Endpoints declare <> annotated with `@OnTextMessage`, `@OnBinaryMessage`, `@OnPong`, `@OnOpen`, `@OnClose` and `@OnError`. +Endpoints declare <> annotated with `@OnTextMessage`, `@OnBinaryMessage`, `@OnPingMessage`, `@OnPongMessage`, `@OnOpen`, `@OnClose` and `@OnError`. These methods are used to handle various WebSocket events. Typically, a method annotated with `@OnTextMessage` is called when the connected client sends a message to the server and vice versa. @@ -210,6 +210,7 @@ A WebSocket endpoint may declare: * At most one `@OnTextMessage` method: Handles the text messages from the connected client/server. * At most one `@OnBinaryMessage` method: Handles the binary messages from the connected client/server. +* At most one `@OnPingMessage` method: Handles the ping messages from the connected client/server. * At most one `@OnPongMessage` method: Handles the pong messages from the connected client/server. * At most one `@OnOpen` method: Invoked when a connection is opened. * At most one `@OnClose` method: Executed when the connection is closed. @@ -551,39 +552,55 @@ Item find(Item item) { 1. Specify the codec to use for the deserialization of the incoming message 2. Specify the codec to use for the serialization of the outgoing message -=== Ping/pong messages +=== Ping/Pong messages A https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.2[ping message] may serve as a keepalive or to verify the remote endpoint. A https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.3[pong message] is sent in response to a ping message and it must have an identical payload. -Server/client endpoints automatically respond to a ping message sent from the client/server. -In other words, there is no need for `@OnPingMessage` callback declared on an endpoint. +==== Sending ping messages -The server can send ping messages to a connected client. -`WebSocketConnection`/`WebSocketClientConnection` declare methods to send ping messages; there is a non-blocking variant: `sendPing(Buffer)` and a blocking variant: `sendPingAndAwait(Buffer)`. -By default, the ping messages are not sent automatically. -However, the configuration properties `quarkus.websockets-next.server.auto-ping-interval` and `quarkus.websockets-next.client.auto-ping-interval` can be used to set the interval after which, the server/client sends a ping message to a connected client/server automatically. +Ping messages are optional and not sent by default. However, server and client endpoints can be configured to automatically send ping messages on an interval. [source,properties] ---- quarkus.websockets-next.server.auto-ping-interval=2 <1> +quarkus.websockets-next.client.auto-ping-interval=10 <2> ---- -<1> Sends a ping message from the server to a connected client every 2 seconds. +<1> Sends a ping message from the server to each connected client every 2 seconds. +<2> Sends a ping message from all connected client instances to their remote servers every 10 seconds. -The `@OnPongMessage` annotation is used to define a callback that consumes pong messages sent from the client/server. -An endpoint must declare at most one method annotated with `@OnPongMessage`. +Servers and clients can send ping messages programmatically at any time using `WebSocketConnection` or `WebSocketClientConnection`. +There is a non-blocking variant: `Sender#sendPing(Buffer)` and a blocking variant: `Sender#sendPingAndAwait(Buffer)`. + +==== Sending pong messages + +Server and client endpoints will always respond to a ping message sent from the remote party with a corresponding pong message, using the application data from the ping message. +This behavior is built-in and requires no additional code or configuration. + +Servers and clients can send unsolicited pong messages that may serve as a unidirectional heartbeat using `WebSocketConnection` or `WebSocketClientConnection`. There is a non-blocking variant: `Sender#sendPong(Buffer)` and a blocking variant: `Sender#sendPongAndAwait(Buffer)`. + +==== Handling ping/pong messages + +Because ping messages are handled automatically and pong messages require no response, it is not necessary to write handlers for these messages to comply with the WebSocket protocol. +However, it is sometimes useful to know when ping or pong messages are received by an endpoint. + +The `@OnPingMessage` and `@OnPongMessage` annotations can be used to define callbacks that consume ping or pong messages sent from the remote party. +An endpoint may declare at most one `@OnPingMessage` callback and at most one `@OnPongMessage` callback. The callback method must return either `void` or `Uni` (or be a Kotlin `suspend` function returning `Unit`), and it must accept a single parameter of type `Buffer`. [source,java] ---- +@OnPingMessage +void ping(Buffer data) { + // an incoming ping that will automatically receive a pong +} + @OnPongMessage void pong(Buffer data) { - // .... + // an incoming pong in response to the last ping sent } ---- -NOTE: The server/client can also send unsolicited pong messages that may serve as a unidirectional heartbeat. There is a non-blocking variant: `WebSocketConnection#sendPong(Buffer)` and also a blocking variant: `WebSocketConnection#sendPongAndAwait(Buffer)`. - [[inbound-processing-mode]] === Inbound processing mode