Package io.quarkus.websockets.next

Annotation Interface OnTextMessage

@Retention(RUNTIME) @Target(METHOD) @Experimental("This API is experimental and may change in the future") public @interface OnTextMessage
WebSocket and WebSocketClient endpoint methods annotated with this annotation consume text messages. An endpoint may declare at most one method annotated with this annotation.

Execution model

  • Methods annotated with RunOnVirtualThread are considered blocking and should be executed on a virtual thread.
  • Methods annotated with Blocking are considered blocking and should be executed on a worker thread.
  • Methods annotated with NonBlocking are considered non-blocking and should be executed on an event loop thread.
Execution model for methods which don't declare any of the annotation listed above is derived from the return type:

  • Methods returning void are considered blocking and should be executed on a worker thread.
  • Methods returning Uni or Multi are considered non-blocking and should be executed on an event loop thread.
  • Methods returning any other type are considered blocking and should be executed on a worker thread.

Method parameters

The method must accept exactly one message parameter. A text message is always represented as a String. Therefore, the following conversion rules apply. The types listed below are handled specifically. For all other types a 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 codec() and outputCodec().

  • java.lang.String is used as is,
  • io.vertx.core.json.JsonObject is encoded with JsonObject.encode() and decoded with {@link io.vertx.core.json.JsonObject#JsonObject(String))}.
  • io.vertx.core.json.JsonArray is encoded with JsonArray.encode() and decoded with {@link io.vertx.core.json.JsonArray#JsonArray(String))}.
  • java.lang.Buffer is encoded with Buffer.toString() and decoded with Buffer.buffer(String),
  • byte[] is first converted to Buffer and then converted as defined above.
The method may also accept the following parameters:

  • Element Details

    • broadcast

      boolean broadcast
      Broadcasting is only supported for server endpoints annotated with WebSocket.
      Returns:
      true if all the connected clients should receive the objects returned by the annotated method
      See Also:
      Default:
      false

    • codec

      Class<? extends TextMessageCodec> codec
      The codec used for input messages.

      By default, the first codec that supports the message type is used; codecs with higher priority go first. Note that, if specified, the codec is also used for output messages unless outputCodec() returns a non-default value.

      Default:
      io.quarkus.websockets.next.TextMessageCodec.class

    • outputCodec

      Class<? extends TextMessageCodec> outputCodec
      The codec used for output messages.

      By default, the same codec as for the input message is used.

      Default:
      io.quarkus.websockets.next.TextMessageCodec.class