Improve docs on STOMP / WebSocket frame max size

Issue: SPR-17514

Author: rstoyanchev

spring-websocket/src/main/java/org/springframework/web/socket/config/annotation/WebSocketTransportRegistration.java

@@ -47,20 +47,12 @@ public class WebSocketTransportRegistration {
 
 
 	/**
-	 * Configure the maximum size for an incoming sub-protocol message.
-	 * For example a STOMP message may be received as multiple WebSocket messages
-	 * or multiple HTTP POST requests when SockJS fallback options are in use.
-	 * <p>In theory a WebSocket message can be almost unlimited in size.
-	 * In practice WebSocket servers impose limits on incoming message size.
-	 * STOMP clients for example tend to split large messages around 16K
-	 * boundaries. Therefore a server must be able to buffer partial content
-	 * and decode when enough data is received. Use this property to configure
-	 * the max size of the buffer to use.
+	 * Configure the maximum size of an inbound sub-protocol message, such as
+	 * a STOMP frame which may be aggregated from multiple WebSocket messages.
 	 * <p>The default value is 64K (i.e. 64 * 1024).
-	 * <p><strong>NOTE</strong> that the current version 1.2 of the STOMP spec
-	 * does not specifically discuss how to send STOMP messages over WebSocket.
-	 * Version 2 of the spec will but in the mean time existing client libraries
-	 * have already established a practice that servers must handle.
+	 * <p><strong>Note:</strong> This is not the same as the size of an
+	 * individual WebSocket message which needs to be configured at the WebSocket
+	 * server level instead. See the reference documentation for details.
 	 */
 	public WebSocketTransportRegistration setMessageSizeLimit(int messageSizeLimit) {
 		this.messageSizeLimit = messageSizeLimit;

src/docs/asciidoc/web/websocket.adoc

@@ -1133,6 +1133,42 @@ application.
 
 
 
+[[websocket-stomp-server-config]]
+=== WebSocket Server
+
+To configure the underlying WebSocket server, the information in
+<<websocket-server-runtime-configuration>> applies. For Jetty, however you need to set
+the `HandshakeHandler` and `WebSocketPolicy` through the `StompEndpointRegistry`:
+
+====
+[source,java,indent=0]
+[subs="verbatim,quotes"]
+----
+	@Configuration
+	@EnableWebSocketMessageBroker
+	public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
+
+		@Override
+		public void registerStompEndpoints(StompEndpointRegistry registry) {
+			registry.addEndpoint("/portfolio").setHandshakeHandler(handshakeHandler());
+		}
+
+		@Bean
+		public DefaultHandshakeHandler handshakeHandler() {
+
+			WebSocketPolicy policy = new WebSocketPolicy(WebSocketBehavior.SERVER);
+			policy.setInputBufferSize(8192);
+			policy.setIdleTimeout(600000);
+
+			return new DefaultHandshakeHandler(
+					new JettyRequestUpgradeStrategy(new WebSocketServerFactory(policy)));
+		}
+	}
+----
+====
+
+
+
 [[websocket-stomp-message-flow]]
 === Flow of Messages