Package io.quarkus.websockets.next

Annotation Interface OnError

@Retention(RUNTIME)
@Target(METHOD)
public @interface OnError

WebSocket and 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 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 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 "error" parameter, i.e. a parameter that is assignable from Throwable. The method may also accept the following parameters:

• WebSocketConnection/WebSocketClientConnection; depending on the endpoint type
• HandshakeRequest
• String parameters annotated with 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 WebSocket/WebSocketClient endpoint. Such a method may not accept PathParam paremeters. If a global error handler accepts WebSocketConnection then it's only applied to server-side errors. If a global error handler accepts WebSocketClientConnection then it's only applied to client-side errors. Error handlers declared on an endpoint take precedence over the global error handlers.