io.quarkus.websockets.next.OnError 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 are invoked when an error
 * occurs.
 * 
 * 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. 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.
 *
 * 
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 "error" parameter, i.e. a parameter that is assignable from {@link java.lang.Throwable}.
 * 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}
 * 
 * 
 *
 * 
Global error handlers
 *
 * 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
 * handler accepts {@link WebSocketClientConnection} then it's only applied to client-side errors.
 *
 * Error handlers declared on an endpoint take precedence over the global error handlers.
 */
@Retention(RUNTIME)
@Target(METHOD)
@Experimental("This API is experimental and may change in the future")
public @interface OnError {

}