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:
    • if the method is 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.

  • 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 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 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