io.quarkus.websockets.next.OnBinaryMessage Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of quarkus-websockets-next Show documentation
Implementation of the WebSocket API with enhanced efficiency and usability
There is a newer version: 3.17.2
Show newest version
package io.quarkus.websockets.next;

import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import io.smallrye.common.annotation.Experimental;

/**
 * {@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.
 *
 * Execution model
 *
 * 
 * Methods annotated with {@link io.smallrye.common.annotation.RunOnVirtualThread} are considered blocking and should be
 * executed on a virtual thread.
 * Methods annotated with {@link io.smallrye.common.annotation.Blocking} are considered blocking and should be executed on a
 * worker thread.
 * Methods annotated with {@link io.smallrye.common.annotation.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 {@code void} are considered blocking and should be executed on a worker thread.
 * 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.
 * 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
 * {@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()}.
 * 
 * 

 * {@code java.lang.Buffer} is used as is,
 * {@code byte[]} is encoded with {@link io.vertx.core.buffer.Buffer#buffer(byte[])} and decoded with
 * {@link io.vertx.core.buffer.Buffer#getBytes()},
 * {@code java.lang.String} is encoded with {@link io.vertx.core.buffer.Buffer#buffer(String)} and decoded with
 * {@link io.vertx.core.buffer.Buffer#toString()},
 * {@code io.vertx.core.json.JsonObject} is encoded with {@link io.vertx.core.json.JsonObject#toBuffer()} and decoded with
 * {@link io.vertx.core.json.JsonObject#JsonObject(io.vertx.core.buffer.Buffer)}.
 * {@code io.vertx.core.json.JsonArray} is encoded with {@link io.vertx.core.json.JsonArray#toBuffer()} and decoded with
 * {@link io.vertx.core.json.JsonArray#JsonArray(io.vertx.core.buffer.Buffer)}.
 * 
 * 
 * The method may also accept the following parameters:
 * 

 * {@link WebSocketConnection}/{@link WebSocketClientConnection}; depending on the endpoint type
 * {@link HandshakeRequest}
 * {@link String} parameters annotated with {@link PathParam}
 * 
 */
@Retention(RUNTIME)
@Target(METHOD)
@Experimental("This API is experimental and may change in the future")
public @interface OnBinaryMessage {

    /**
     * Broadcasting is only supported for server endpoints annotated with {@link WebSocket}.
     *
     * @return {@code true} if all the connected clients should receive the objects returned by the annotated method
     * @see WebSocketConnection#broadcast()
     */
    public boolean broadcast() default false;

    /**
     * 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 {@link #outputCodec()} returns a non-default
     * value.
     */
    @SuppressWarnings("rawtypes")
    Class codec() default BinaryMessageCodec.class;

    /**
     * The codec used for output messages.
     * 
     * By default, the same codec as for the input message is used.
     */
    @SuppressWarnings("rawtypes")
    Class outputCodec() default BinaryMessageCodec.class;

}