Merge pull request quarkusio#40435 from mkouba/websockets-next-javado…

…c-clarify-01

WebSockets Next: javadoc clarifications

extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/BinaryMessageCodec.java

@@ -6,8 +6,27 @@
 /**
  * Used to encode and decode binary messages.
  *
+ * <h2>Special types of messages</h2>
+ *
+ * Some types of messages bypass the encoding/decoding process:
+ * <ul>
+ * <li>{@code java.lang.Buffer},</li>
+ * <li>{@code byte[]},</li>
+ * <li>{@code java.lang.String},</li>
+ * <li>{@code io.vertx.core.json.JsonObject}.</li>
+ * <li>{@code io.vertx.core.json.JsonArray}.</li>
+ * </ul>
+ * The encoding/decoding details are described in {@link OnBinaryMessage}.
+ *
+ * <h2>CDI beans</h2>
+ * Implementation classes must be CDI beans. Qualifiers are ignored. {@link jakarta.enterprise.context.Dependent} beans are
+ * reused during encoding/decoding.
+ *
+ * <h2>Lifecycle and concurrency</h2>
+ * Codecs are shared accross all WebSocket connections. Therefore, implementations should be either stateless or thread-safe.
+ *
  * @param <T>
- * @see BinaryMessage
+ * @see OnBinaryMessage
  */
 @Experimental("This API is experimental and may change in the future")
 public interface BinaryMessageCodec<T> extends MessageCodec<T, Buffer> {

extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/MessageCodec.java

@@ -7,26 +7,10 @@
 /**
  * Used to encode and decode messages.
  *
- * <h2>Special types of messages</h2>
- * Some types of messages bypass the encoding/decoding process:
- * <ul>
- * <li>{@code java.lang.Buffer},</li>
- * <li>{@code byte[]},</li>
- * <li>{@code java.lang.String},</li>
- * <li>{@code io.vertx.core.json.JsonObject}.</li>
- * <li>{@code io.vertx.core.json.JsonArray}.</li>
- * </ul>
- * The encoding/decoding details are described in {@link BinaryMessage} and {@link TextMessage}.
- *
- * <h2>CDI beans</h2>
- * Implementation classes must be CDI beans. Qualifiers are ignored. {@link jakarta.enterprise.context.Dependent} beans are
- * reused during encoding/decoding.
- *
- * <h2>Lifecycle and concurrency</h2>
- * Codecs are shared accross all WebSocket connections. Therefore, implementations should be either stateless or thread-safe.
- *
  * @param <T>
  * @param <MESSAGE>
+ * @see TextMessageCodec
+ * @see BinaryMessageCodec
  */
 @Experimental("This API is experimental and may change in the future")
 public interface MessageCodec<T, MESSAGE> {

extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/OnBinaryMessage.java

@@ -9,13 +9,37 @@
 import io.smallrye.common.annotation.Experimental;
 
 /**
- * {@link WebSocket} and {@link WebSocketClient} endpoint methods annotated with this annotation consume binary messages.
+ * {@link WebSocket} and {@link WebSocketClient} endpoint methods annotated with this annotation consume binary messages. An
+ * endpoint may declare at most one method annotated with this annotation.
+ *
+ * <h2>Execution model</h2>
+ *
+ * <ul>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.RunOnVirtualThread} are considered blocking and should be
+ * executed on a virtual thread.</li>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.Blocking} are considered blocking and should be executed on a
+ * worker thread.</li>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.NonBlocking} are considered non-blocking and should be
+ * executed on an event loop thread.</li>
+ * </ul>
+ *
+ * Execution model for methods which don't declare any of the annotation listed above is derived from the return type:
  * <p>
+ * <ul>
+ * <li>Methods returning {@code void} are considered blocking and should be executed on a worker thread.</li>
+ * <li>Methods returning {@link io.smallrye.mutiny.Uni} or {@link io.smallrye.mutiny.Multi} are considered non-blocking and
+ * should be executed on an event loop thread.</li>
+ * <li>Methods returning any other type are considered blocking and should be executed on a worker thread.</li>
+ * </ul>
+ *
+ * <h2>Method parameters</h2>
+ *
  * The method must accept exactly one message parameter. A binary message is always represented as a
  * {@link io.vertx.core.buffer.Buffer}. Therefore, the following conversion rules
  * apply. The types listed below are handled specifically. For all other types a {@link BinaryMessageCodec} is used to encode
  * and decode input and output messages. By default, the first input codec that supports the message type is used; codecs with
  * higher priority go first. However, a specific codec can be selected with {@link #codec()} and {@link #outputCodec()}.
+ * <p>
  * <ul>
  * <li>{@code java.lang.Buffer} is used as is,</li>
  * <li>{@code byte[]} is encoded with {@link io.vertx.core.buffer.Buffer#buffer(byte[])} and decoded with
@@ -34,8 +58,6 @@
  * <li>{@link HandshakeRequest}</li>
  * <li>{@link String} parameters annotated with {@link PathParam}</li>
  * </ul>
- * <p>
- * An endpoint may declare at most one method annotated with this annotation.
  */
 @Retention(RUNTIME)
 @Target(METHOD)

extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/OnClose.java

@@ -10,9 +10,30 @@
 
 /**
  * {@link WebSocket} and {@link WebSocketClient} endpoint methods annotated with this annotation are invoked when a connection
- * is closed.
+ * is closed. An endpoint may declare at most one method annotated with this annotation. The method must return {@code void} or
+ * {@code io.smallrye.mutiny.Uni<Void>}.
+ *
+ * <h2>Execution model</h2>
+ *
+ * <ul>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.RunOnVirtualThread} are considered blocking and should be
+ * executed on a virtual thread.</li>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.Blocking} are considered blocking and should be executed on a
+ * worker thread.</li>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.NonBlocking} are considered non-blocking and should be
+ * executed on an event loop thread.</li>
+ * </ul>
+ *
+ * Execution model for methods which don't declare any of the annotation listed above is derived from the return type:
  * <p>
- * The method must return {@code void} or {@code io.smallrye.mutiny.Uni<Void>}.
+ * <ul>
+ * <li>Methods returning {@code void} are considered blocking and should be executed on a worker thread.</li>
+ * <li>Methods returning {@code io.smallrye.mutiny.Uni<Void>} are considered non-blocking and should be executed on an event
+ * loop thread.</li>
+ * </ul>
+ *
+ * <h2>Method parameters</h2>
+ *
  * The method may accept the following parameters:
  * <ul>
  * <li>{@link WebSocketConnection}/{@link WebSocketClientConnection}; depending on the endpoint type</li>
@@ -21,8 +42,6 @@
  * </ul>
  * Note that it's not possible to send a message to the current connection as the socket is already closed when the method
  * invoked. However, it is possible to send messages to other open connections.
- * <p>
- * An endpoint may declare at most one method annotated with this annotation.
  */
 @Retention(RUNTIME)
 @Target(METHOD)

extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/OnError.java

@@ -13,8 +13,32 @@
  * occurs.
  * <p>
  * It is used when an endpoint callback throws a runtime error, or when a conversion errors occurs, or when a returned
- * {@link io.smallrye.mutiny.Uni} receives a failure.
+ * {@link io.smallrye.mutiny.Uni} receives a failure. An endpoint may declare multiple methods annotated with this annotation.
+ * However, each method must declare a different error
+ * parameter. The method that declares a most-specific supertype of the actual exception is selected.
+ *
+ * <h2>Execution model</h2>
+ *
+ * <ul>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.RunOnVirtualThread} are considered blocking and should be
+ * executed on a virtual thread.</li>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.Blocking} are considered blocking and should be executed on a
+ * worker thread.</li>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.NonBlocking} are considered non-blocking and should be
+ * executed on an event loop thread.</li>
+ * </ul>
+ *
+ * Execution model for methods which don't declare any of the annotation listed above is derived from the return type:
  * <p>
+ * <ul>
+ * <li>Methods returning {@code void} are considered blocking and should be executed on a worker thread.</li>
+ * <li>Methods returning {@link io.smallrye.mutiny.Uni} or {@link io.smallrye.mutiny.Multi} are considered non-blocking and
+ * should be executed on an event loop thread.</li>
+ * <li>Methods returning any other type are considered blocking and should be executed on a worker thread.</li>
+ * </ul>
+ *
+ * <h2>Method parameters</h2>
+ *
  * The method must accept exactly one "error" parameter, i.e. a parameter that is assignable from {@link java.lang.Throwable}.
  * The method may also accept the following parameters:
  * <ul>
@@ -23,9 +47,9 @@
  * <li>{@link String} parameters annotated with {@link PathParam}</li>
  * </ul>
  * <p>
- * An endpoint may declare multiple methods annotated with this annotation. However, each method must declare a different error
- * parameter. The method that declares a most-specific supertype of the actual exception is selected.
- * <p>
+ *
+ * <h2>Global error handlers</h2>
+ *
  * This annotation can be also used to declare a global error handler, i.e. a method that is not declared on a
  * {@link WebSocket}/{@link WebSocketClient} endpoint. Such a method may not accept {@link PathParam} paremeters. If a global
  * error handler accepts {@link WebSocketConnection} then it's only applied to server-side errors. If a global error

extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/OnOpen.java

@@ -10,16 +10,36 @@
 
 /**
  * {@link WebSocket} and {@link WebSocketClient} endpoint methods annotated with this annotation are invoked when a new
- * connection is opened.
+ * connection is opened. An endpoint may declare at most one method annotated with this annotation.
+ *
+ * <h2>Execution model</h2>
+ *
+ * <ul>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.RunOnVirtualThread} are considered blocking and should be
+ * executed on a virtual thread.</li>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.Blocking} are considered blocking and should be executed on a
+ * worker thread.</li>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.NonBlocking} are considered non-blocking and should be
+ * executed on an event loop thread.</li>
+ * </ul>
+ *
+ * Execution model for methods which don't declare any of the annotation listed above is derived from the return type:
  * <p>
+ * <ul>
+ * <li>Methods returning {@code void} are considered blocking and should be executed on a worker thread.</li>
+ * <li>Methods returning {@link io.smallrye.mutiny.Uni} or {@link io.smallrye.mutiny.Multi} are considered non-blocking and
+ * should be executed on an event loop thread.</li>
+ * <li>Methods returning any other type are considered blocking and should be executed on a worker thread.</li>
+ * </ul>
+ *
+ * <h2>Method parameters</h2>
+ *
  * The method may accept the following parameters:
  * <ul>
  * <li>{@link WebSocketConnection}/{@link WebSocketClientConnection}; depending on the endpoint type</li>
  * <li>{@link HandshakeRequest}</li>
  * <li>{@link String} parameters annotated with {@link PathParam}</li>
  * </ul>
- * <p>
- * An endpoint may declare at most one method annotated with this annotation.
  */
 @Retention(RUNTIME)
 @Target(METHOD)

extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/OnPongMessage.java

@@ -9,7 +9,30 @@
 import io.smallrye.common.annotation.Experimental;
 
 /**
- * {@link WebSocket} and {@link WebSocketClient} endpoint methods annotated with this annotation consume pong messages.
+ * {@link WebSocket} and {@link WebSocketClient} endpoint methods annotated with this annotation consume pong messages. An
+ * endpoint may declare at most one method annotated with this annotation.
+ *
+ * <h2>Execution model</h2>
+ *
+ * <ul>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.RunOnVirtualThread} are considered blocking and should be
+ * executed on a virtual thread.</li>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.Blocking} are considered blocking and should be executed on a
+ * worker thread.</li>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.NonBlocking} are considered non-blocking and should be
+ * executed on an event loop thread.</li>
+ * </ul>
+ *
+ * Execution model for methods which don't declare any of the annotation listed above is derived from the return type:
+ * <p>
+ * <ul>
+ * <li>Methods returning {@code void} are considered blocking and should be executed on a worker thread.</li>
+ * <li>Methods returning {@link io.smallrye.mutiny.Uni} or {@link io.smallrye.mutiny.Multi} are considered non-blocking and
+ * should be executed on an event loop thread.</li>
+ * <li>Methods returning any other type are considered blocking and should be executed on a worker thread.</li>
+ * </ul>
+ *
+ * <h2>Method parameters</h2>
  *
  * The method must accept exactly one pong message parameter represented as a {@link io.vertx.core.buffer.Buffer}. The method
  * may also accept the following parameters:
@@ -19,7 +42,7 @@
  * <li>{@link String} parameters annotated with {@link PathParam}</li>
  * </ul>
  * <p>
- * An endpoint may declare at most one method annotated with this annotation.
+ *
  */
 @Retention(RUNTIME)
 @Target(METHOD)

extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/OnTextMessage.java

@@ -9,13 +9,37 @@
 import io.smallrye.common.annotation.Experimental;
 
 /**
- * {@link WebSocket} and {@link WebSocketClient} endpoint methods annotated with this annotation consume text messages.
+ * {@link WebSocket} and {@link WebSocketClient} endpoint methods annotated with this annotation consume text messages. An
+ * endpoint may declare at most one method annotated with this annotation.
+ *
+ * <h2>Execution model</h2>
+ *
+ * <ul>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.RunOnVirtualThread} are considered blocking and should be
+ * executed on a virtual thread.</li>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.Blocking} are considered blocking and should be executed on a
+ * worker thread.</li>
+ * <li>Methods annotated with {@link io.smallrye.common.annotation.NonBlocking} are considered non-blocking and should be
+ * executed on an event loop thread.</li>
+ * </ul>
+ *
+ * Execution model for methods which don't declare any of the annotation listed above is derived from the return type:
  * <p>
+ * <ul>
+ * <li>Methods returning {@code void} are considered blocking and should be executed on a worker thread.</li>
+ * <li>Methods returning {@link io.smallrye.mutiny.Uni} or {@link io.smallrye.mutiny.Multi} are considered non-blocking and
+ * should be executed on an event loop thread.</li>
+ * <li>Methods returning any other type are considered blocking and should be executed on a worker thread.</li>
+ * </ul>
+ *
+ * <h2>Method parameters</h2>
+ *
  * The method must accept exactly one message parameter. A text message is always represented as a {@link String}. Therefore,
- * the following conversion rules apply. The types listed
- * below are handled specifically. For all other types a {@link TextMessageCodec} is used to encode and decode input and
- * output messages. By default, the first input codec that supports the message type is used; codecs with higher priority go
- * first. However, a specific codec can be selected with {@link #codec()} and {@link #outputCodec()}.
+ * the following conversion rules apply. The types listed below are handled specifically. For all other types a
+ * {@link TextMessageCodec} is used to encode and decode input and output messages. By default, the first input codec that
+ * supports the message type is used; codecs with higher priority go first. However, a specific codec can be selected with
+ * {@link #codec()} and {@link #outputCodec()}.
+ * <p>
  * <ul>
  * <li>{@code java.lang.String} is used as is,</li>
  * <li>{@code io.vertx.core.json.JsonObject} is encoded with {@link io.vertx.core.json.JsonObject#encode()} and decoded with
@@ -26,15 +50,13 @@
  * {@link io.vertx.core.buffer.Buffer#buffer(String)},</li>
  * <li>{@code byte[]} is first converted to {@link io.vertx.core.buffer.Buffer} and then converted as defined above.</li>
  * </ul>
- * <p>
+ *
  * The method may also accept the following parameters:
  * <ul>
  * <li>{@link WebSocketConnection}/{@link WebSocketClientConnection}; depending on the endpoint type</li>
  * <li>{@link HandshakeRequest}</li>
  * <li>{@link String} parameters annotated with {@link PathParam}</li>
  * </ul>
- * <p>
- * An endpoint may declare at most one method annotated with this annotation.
  */
 @Retention(RUNTIME)
 @Target(METHOD)

extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/PathParam.java

@@ -14,6 +14,8 @@
  *
  * @see WebSocketConnection#pathParam(String)
  * @see WebSocket
+ * @see WebSocketClientConnection#pathParam(String)
+ * @see WebSocketClient
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.PARAMETER)

extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/TextMessageCodec.java

@@ -5,8 +5,27 @@
 /**
  * Used to encode and decode text messages.
  *
+ * <h2>Special types of messages</h2>
+ *
+ * Some types of messages bypass the encoding/decoding process:
+ * <ul>
+ * <li>{@code java.lang.Buffer},</li>
+ * <li>{@code byte[]},</li>
+ * <li>{@code java.lang.String},</li>
+ * <li>{@code io.vertx.core.json.JsonObject}.</li>
+ * <li>{@code io.vertx.core.json.JsonArray}.</li>
+ * </ul>
+ * The encoding/decoding details are described in {@link OnTextMessage}.
+ *
+ * <h2>CDI beans</h2>
+ * Implementation classes must be CDI beans. Qualifiers are ignored. {@link jakarta.enterprise.context.Dependent} beans are
+ * reused during encoding/decoding.
+ *
+ * <h2>Lifecycle and concurrency</h2>
+ * Codecs are shared accross all WebSocket connections. Therefore, implementations should be either stateless or thread-safe.
+ *
  * @param <T>
- * @see TextMessage
+ * @see OnTextMessage
  */
 @Experimental("This API is experimental and may change in the future")
 public interface TextMessageCodec<T> extends MessageCodec<T, String> {

extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/WebSocket.java

@@ -12,7 +12,7 @@
 import io.smallrye.common.annotation.Experimental;
 
 /**
- * Denotes a WebSocket endpoint.
+ * Denotes a WebSocket server endpoint.
  * <p>
  * An endpoint must declare a method annotated with {@link OnTextMessage}, {@link OnBinaryMessage}, {@link OnPongMessage} or
  * {@link OnOpen}. An endpoint may declare a method annotated with {@link OnClose}.