Package io.quarkus.websockets.next

Annotation Interface OnBinaryMessage

@Retention(RUNTIME) @Target(METHOD) @Experimental("This API is experimental and may change in the future") public @interface OnBinaryMessage
WebSocket and WebSocketClient endpoint methods annotated with this annotation consume binary 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 binary message is always represented as a Buffer. Therefore, the following conversion rules apply. The types listed below are handled specifically. For all other types a 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 codec() and outputCodec().

  • java.lang.Buffer is used as is,
  • byte[] is encoded with Buffer.buffer(byte[]) and decoded with Buffer.getBytes(),
  • java.lang.String is encoded with Buffer.buffer(String) and decoded with Buffer.toString(),
  • io.vertx.core.json.JsonObject is encoded with JsonObject.toBuffer() and decoded with JsonObject(io.vertx.core.buffer.Buffer).
  • io.vertx.core.json.JsonArray is encoded with JsonArray.toBuffer() and decoded with JsonArray(io.vertx.core.buffer.Buffer).

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 BinaryMessageCodec> 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.BinaryMessageCodec.class

    • outputCodec

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

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

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