Fixes #13915 - You can not have both Frame and Text handler in 12.1.x Jetty websocket. (#13917)

* Updated migration guide.
* Updated annotation javadocs.

Signed-off-by: Simone Bordet <[email protected]>

Author: sbordet

documentation/jetty/modules/programming-guide/pages/migration/12.0-to-12.1.adoc

@@ -132,3 +132,13 @@ If the generation of the server response overflows `HttpConfiguration.responseHe
 If the generation overflows also `HttpConfiguration.maxResponseHeaderSize`, a `500` error response is generated.
 
 In Jetty 12.1.x and HTTP/2 `HttpConfiguration.maxResponseHeaderSize` is used for the link:https://datatracker.ietf.org/doc/html/rfc9113#SETTINGS_MAX_HEADER_LIST_SIZE[`MAX_HEADER_LIST_SIZE`] setting, while in HTTP/3 is used for the link:https://datatracker.ietf.org/doc/html/rfc9114#SETTINGS_MAX_FIELD_SECTION_SIZE[`MAX_FIELD_SECTION_SIZE`] setting.
+
+[[api-changes-websocket]]
+=== `WebSocket`
+
+In Jetty 12.0.x, it was possible to use the Jetty WebSocket annotations to have, in the same WebSocket EndPoint, a method annotated with `@OnWebSocketFrame` and one annotated with `@OnWebSocketMessage`, `@OnWebSocketPing` or `@OnWebSocketPong`.
+However, this was causing issues, discussed in link:https://github.com/jetty/jetty.project/pull/12342[#12342].
+
+In Jetty 12.1.x if the annotation `@OnWebSocketFrame` is present, then there cannot be methods annotated with `@OnWebSocketMessage`, `@OnWebSocketPing` or `@OnWebSocketPong`.
+
+Furthermore, in Jetty 12.1.x the signature of methods annotated with `@OnWebSocketFrame` now requires a `Callback` parameter.

jetty-core/jetty-websocket/jetty-websocket-jetty-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketClose.java

@@ -21,13 +21,11 @@
 
 /**
  * <p>Annotation for methods to receive WebSocket close events.</p>
- * <p>Acceptable method patterns:</p>
+ * <p>Acceptable method signatures:</p>
  * <ol>
- * <li>{@code public void <methodName>(int statusCode, String reason)}</li>
- * <li>{@code public void <methodName>(Session session, int statusCode, String reason)}</li>
- * <li>{@code public void <methodName>(int statusCode, String reason, Callback callback)}</li>
  * <li>{@code public void <methodName>(Session session, int statusCode, String reason, Callback callback)}</li>
  * </ol>
+ * <p>None of the parameters are mandatory, and you can specify any combination of parameters.</p>
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)

jetty-core/jetty-websocket/jetty-websocket-jetty-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketError.java

@@ -21,11 +21,11 @@
 
 /**
  * <p>Annotation for methods to receive WebSocket errors.</p>
- * <p>Acceptable method patterns:</p>
+ * <p>Acceptable method signatures:</p>
  * <ol>
- * <li>{@code public void <methodName>(Throwable cause)}</li>
- * <li>{@code public void <methodName>(Session session, Throwable cause)}</li>
+ * <li>{@code public void <methodName>(Session session, *Throwable cause)}</li>
  * </ol>
+ * <p>The {@code *} before the parameter type means that the parameter is mandatory.</p>
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)

jetty-core/jetty-websocket/jetty-websocket-jetty-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketFrame.java

@@ -23,11 +23,11 @@
 
 /**
  * <p>Annotation for methods to receive WebSocket frame events.</p>
- * <p>Acceptable method patterns:</p>
+ * <p>Acceptable method signatures:</p>
  * <ol>
- * <li>{@code public void <methodName>(Frame frame)}</li>
- * <li>{@code public void <methodName>(Session session, Frame frame)}</li>
+ * <li>{@code public void <methodName>(Session session, *Frame frame, *Callback callback)}</li>
  * </ol>
+ * <p>The {@code *} before the parameter type means that the parameter is mandatory.</p>
  *
  * @see Frame
  */

jetty-core/jetty-websocket/jetty-websocket-jetty-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketMessage.java

@@ -23,42 +23,38 @@
 
 /**
  * <p>Annotation for methods to receive BINARY or TEXT WebSocket events.</p>
- * <p>Acceptable method patterns:</p>
- * <u>Text Message Versions</u>
+ * <p>Acceptable method signatures for text messages:</p>
  * <ol>
- * <li>{@code public void methodName(String text)}</li>
- * <li>{@code public void methodName(Session session, String text)}</li>
- * <li>{@code public void methodName(Reader reader)}</li>
- * <li>{@code public void methodName(Session session, Reader reader)}</li>
+ * <li>{@code public void methodName(Session session, *String text)}</li>
+ * <li>{@code public void methodName(Session session, *Reader reader)}</li>
  * </ol>
+ * <p>The {@code *} before the parameter type means that the parameter is mandatory.</p>
  * <p>NOTE</p>
  * <p>Method that takes a {@link Reader} must have
  * {@link WebSocket#autoDemand()} set to {@code true}.</p>
  * <p>NOTE</p>
  * <p>The {@link Reader} argument will always use the UTF-8 charset,
  * (as dictated by RFC 6455). If you need to use a different charset,
  * you must use BINARY messages.</p>
- * <u>Binary Message Versions</u>
+ * <p>Acceptable method signatures for binary messages:</p>
  * <ol>
- * <li>{@code public void methodName(ByteBuffer message, Callback callback)}</li>
- * <li>{@code public void methodName(Session session, ByteBuffer message, Callback callback)}</li>
- * <li>{@code public void methodName(InputStream stream)}</li>
- * <li>{@code public void methodName(Session session, InputStream stream)}</li>
+ * <li>{@code public void methodName(Session session, *ByteBuffer message, *Callback callback)}</li>
+ * <li>{@code public void methodName(Session session, *InputStream stream)}</li>
  * </ol>
+ * <p>The {@code *} before the parameter type means that the parameter is mandatory.</p>
  * <p>NOTE</p>
  * <p>Method that takes a {@link InputStream} must have
  * {@link WebSocket#autoDemand()} set to {@code true}.</p>
- * <u>Partial Message Variations</u>
- * <p>These are used to receive individual frames (and therefore partial
+ * <p>Partial messages are used to receive individual frames (and therefore partial
  * messages) without aggregating the frames into a complete WebSocket message.
  * A {@code boolean} parameter is supplied to indicate whether the frame is
  * the last segment of data of the message.</p>
+ * <p>Acceptable method signatures for partial messages:</p>
  * <ol>
- * <li>{@code public void methodName(ByteBuffer payload, boolean last, Callback callback)}</li>
- * <li>{@code public void methodName(Session session, ByteBuffer payload, boolean last, Callback callback)}</li>
- * <li>{@code public void methodName(String payload, boolean last)}</li>
- * <li>{@code public void methodName(Session session, String payload, boolean last)}</li>
+ * <li>{@code public void methodName(Session session, *String payload, *boolean last)}</li>
+ * <li>{@code public void methodName(Session session, *ByteBuffer payload, *boolean last, *Callback callback)}</li>
  * </ol>
+ * <p>The {@code *} before the parameter type means that the parameter is mandatory.</p>
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)

jetty-core/jetty-websocket/jetty-websocket-jetty-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketOpen.java

@@ -21,10 +21,11 @@
 
 /**
  * <p>Annotation for methods to receive WebSocket connect events.</p>
- * <p>Acceptable method patterns:</p>
+ * <p>Acceptable method signatures:</p>
  * <ol>
- * <li>{@code public void <methodName>(Session session)}</li>
+ * <li>{@code public void <methodName>(*Session session)}</li>
  * </ol>
+ * <p>The {@code *} before the parameter type means that the parameter is mandatory.</p>
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)

jetty-core/jetty-websocket/jetty-websocket-jetty-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketPing.java

@@ -21,11 +21,11 @@
 
 /**
  * <p>Annotation for methods to receive WebSocket PING events.</p>
- * <p>Acceptable method patterns:</p>
+ * <p>Acceptable method signatures:</p>
  * <ol>
- * <li>{@code public void <methodName>(ByteBuffer payload)}</li>
- * <li>{@code public void <methodName>(Session session, ByteBuffer payload)}</li>
+ * <li>{@code public void <methodName>(Session session, *ByteBuffer payload)}</li>
  * </ol>
+ * <p>The {@code *} before the parameter type means that the parameter is mandatory.</p>
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)

jetty-core/jetty-websocket/jetty-websocket-jetty-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketPong.java

@@ -21,11 +21,11 @@
 
 /**
  * <p>Annotation for methods to receive WebSocket PONG events.</p>
- * <p>Acceptable method patterns:</p>
+ * <p>Acceptable method signatures:</p>
  * <ol>
- * <li>{@code public void <methodName>(ByteBuffer payload)}</li>
- * <li>{@code public void <methodName>(Session session, ByteBuffer payload)}</li>
+ * <li>{@code public void <methodName>(Session session, *ByteBuffer payload)}</li>
  * </ol>
+ * <p>The {@code *} before the parameter type means that the parameter is mandatory.</p>
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)