Re-work solution

api/client/src/main/java/jakarta/websocket/OnMessage.java

@@ -120,30 +120,11 @@
      * 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.
      * <p>
-     * This attribute is ignored unless {@link #maxMessageBufferSize()} returns {@code -1}.
-     * <p>
-     * This attribute should not be set to a value larger than {@code Integer#MAX_VALUE}.
+     * Setting this attribute to a value larger than {@code Integer#MAX_VALUE} will trigger a
+     * {@code DeploymentException} unless the JVM supports Strings (for text messages) or ByteBuffers (for binary
+     * messages) larger than {@code Integer#MAX_VALUE}. Note that, as of Java 22, there are no plans for such support.
      *
      * @return the maximum size in bytes.
-     *
-     * @deprecated Use {@link #maxMessageBufferSize()}
      */
-    @Deprecated
     public long maxMessageSize() default -1;
-
-    /**
-     * 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.
-     * <p>
-     * If this attribute returns {@code -1}, the container will fall-back to the deprecated {@link #maxMessageSize()}.
-     * If that attribute is larger than {@code Integer#MAX_VALUE} then the value of {@code Integer#MAX_VALUE} will be
-     * used and the container may log a warning regarding the invalid configuration.
-     *
-     * @return the maximum size in bytes.
-     */
-    public int maxMessageBufferSize() default -1;
-
 }

spec/src/main/asciidoc/WebSocket.adoc

@@ -1053,21 +1053,6 @@ WebSocket implementation must not deploy such an endpoint and must raise
 a deployment error if an attempt is made to deploy such an annotated
 endpoint [WSC-4.7-4].
 
-[[maxmessagebuffersize]]
-==== maxMessageBufferSize
-
-The maxMessageBufferSize attribute allows the developer to specify the
-maximum size of message in bytes that the method it annotates will be
-able to process, or `-1` to indicate that no maximum has been
-configured. The default is `-1`.
-
-If this attribute returns `-1` then the deprecated `maxMessageSize`
-attribute will be used instead.
-
-If an incoming message exceeds the maximum message size, the
-implementation must formally close the connection with a close code of
-`1009` (Too Big) [WSC-4.7.1-1].
-
 [[maxmessagesize]]
 ==== maxMessageSize
 
@@ -1076,11 +1061,12 @@ size of message in bytes that the method it annotates will be able to
 process, or `-1` to indicate that no maximum has been configured. The
 default is `-1`.
 
-This attribute is ignored unless `maxMessageBufferSize()` returns `-1`.
-
-This attribute should not be set to a value larger than
-`Integer#MAX_VALUE`.
-
+Setting this attribute to a value larger than `Integer.MAX_VALUE` will
+trigger a `DeploymentException` unless the JVM supports ``String``s
+(for text messages) or ``ByteBuffer``s (for binary messages) larger than
+`Integer.MAX_VALUE`. Note that, as of Java 22, there are no plans for
+such support.
+
 If an incoming message exceeds the maximum message size, the
 implementation must formally close the connection with a close code of
 `1009` (Too Big) [WSC-4.7.1-1].
@@ -1540,10 +1526,8 @@ Clarify the responsibilities for sending ping messages.
 Add the `getSession()` method to `SendResult`.
 
 * https://github.com/jakartaee/websocket/issues/274[Issue 274]
-Deprecate `@OnMessage.maxMessageSize` as it is inconsistent with
-`Session.setMaxTextMessageBufferSize` and
-`Session.setMaxBinaryMessageBufferSize`
-and add `@OnMessage.maxMessageBufferSize` as a replacement.
+Clarify the behaviour if `@OnMessage.maxMessageSize` it is set to a
+value larger than `Integer.MAX_VALUE`.
 
 === Changes Between 2.1 and 2.0