Annotation Type OnMessage
-
@Retention(RUNTIME) @Target(METHOD) public @interface OnMessage
This method level annotation can be used to make a Java method receive incoming web socket messages. Each websocket endpoint may only have one message handling method for each of the native websocket message formats: text, binary and pong. Methods using this annotation are allowed to have parameters of types described below, otherwise the container will generate an error at deployment time.The allowed parameters are:
- Exactly one of any of the following choices
- if the method is handling text messages:
String
to receive the whole message- Java primitive or class equivalent to receive the whole message converted to that type
- String and boolean pair to receive the message in parts
Reader
to receive the whole message as a blocking stream- any object parameter for which the endpoint has a text decoder (
Decoder.Text
orDecoder.TextStream
).
- if the method is handling binary messages:
- byte[] or
ByteBuffer
to receive the whole message - byte[] and boolean pair, or
ByteBuffer
and boolean pair to receive the message in parts InputStream
to receive the whole message as a blocking stream- any object parameter for which the endpoint has a binary decoder (
Decoder.Binary
orDecoder.BinaryStream
).
- byte[] or
- if the method is handling pong messages:
PongMessage
for handling pong messages
- if the method is handling text messages:
- and Zero to n String or Java primitive parameters annotated with the
jakarta.websocket.server.PathParam
annotation for server endpoints. - and an optional
Session
parameter
The parameters may be listed in any order.
The method may have a non-void return type, in which case the web socket runtime must interpret this as a web socket message to return to the peer. The allowed data types for this return type, other than void, are String, ByteBuffer, byte[], any Java primitive or class equivalent, and anything for which there is an encoder. If the method uses a Java primitive as a return value, the implementation must construct the text message to send using the standard Java string representation of the Java primitive unless there developer provided encoder for the type configured for this endpoint, in which case that encoder must be used. If the method uses a class equivalent of a Java primitive as a return value, the implementation must construct the text message from the Java primitive equivalent as described above.
Developers should note that if developer closes the session during the invocation of a method with a return type, the method will complete but the return value will not be delivered to the remote endpoint. The send failure will be passed back into the endpoint's error handling method.
For example:
@OnMessage public void processGreeting(String message, Session session) { System.out.println("Greeting received:" + message); }
@OnMessage public void processUpload(byte[] b, boolean last, Session session) { // process partial data here, which check on last to see if these is more on the way }
Reader
,ByteBuffer
orInputStream
after the annotated method has completed, since they may be recycled by the implementation.- Author:
- dannycoward
- Exactly one of any of the following choices
-
-
Optional Element Summary
Optional Elements Modifier and Type Optional Element Description long
maxMessageSize
Specifies the maximum size of message in bytes that the method this annotates will be able to process, or -1 to indicate that there is no maximum.
-
-
-
Element Detail
-
maxMessageSize
long maxMessageSize
Specifies the maximum size of message in bytes that the method this annotates will be able to process, or -1 to indicate that there is no maximum. The default is -1. This attribute only applies when the annotation is used to process whole messages, not to those methods that process messages in parts or use a stream or reader parameter to handle the incoming message. If the incoming whole message exceeds this limit, then the implementation generates an error and closes the connection using the reason that the message was too big.- Returns:
- the maximum size in bytes.
- Default:
- -1L
-
-