Package jakarta.websocket

Annotation Interface 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:

1. 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 or Decoder.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 or Decoder.BinaryStream).
   • if the method is handling pong messages:
     • PongMessage for handling pong messages
2. and Zero to n String or Java primitive parameters annotated with the jakarta.websocket.server.PathParam annotation for server endpoints.
3. 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);
 }
 
 

For example:

 
 @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
 }
 
 

Developers should not continue to reference message objects of type Reader, ByteBuffer or InputStream after the annotated method has completed, since they may be recycled by the implementation.

Author:

dannycoward

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 no maximum has been configured.

Element Details

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 no maximum has been configured. 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.

Setting this attribute to a value larger than Integer#MAX_VALUE will trigger a DeploymentException unless the JVM supports Strings (for text messages) or ByteBuffers (for binary messages) larger than Integer#MAX_VALUE. Note that, as of Java 22, there are no plans for such support.

Returns:

the maximum size in bytes.

Default:

-1L