Updated compatibility statements in RequestUpgradeStrategy javadocs

Author: jhoeller

spring-websocket/src/main/java/org/springframework/web/socket/server/jetty/JettyRequestUpgradeStrategy.java

@@ -56,8 +56,8 @@
 import org.springframework.web.socket.server.RequestUpgradeStrategy;
 
 /**
- * {@link RequestUpgradeStrategy} for use with Jetty 9. Based on Jetty's internal
- * {@code org.eclipse.jetty.websocket.server.WebSocketHandler} class.
+ * A {@link RequestUpgradeStrategy} for use with Jetty 9.0-9.3. Based on Jetty's
+ * internal {@code org.eclipse.jetty.websocket.server.WebSocketHandler} class.
  *
  * @author Phillip Webb
  * @author Rossen Stoyanchev
@@ -83,17 +83,17 @@ public class JettyRequestUpgradeStrategy implements RequestUpgradeStrategy, Life
 
 
 	/**
-	 * Default constructor that creates {@link WebSocketServerFactory} through its default
-	 * constructor thus using a default {@link WebSocketPolicy}.
+	 * Default constructor that creates {@link WebSocketServerFactory} through
+	 * its default constructor thus using a default {@link WebSocketPolicy}.
 	 */
 	public JettyRequestUpgradeStrategy() {
 		this(new WebSocketServerFactory());
 	}
 
 	/**
-	 * A constructor accepting a {@link WebSocketServerFactory}. This may be useful for
-	 * modifying the factory's {@link WebSocketPolicy} via
-	 * {@link WebSocketServerFactory#getPolicy()}.
+	 * A constructor accepting a {@link WebSocketServerFactory}.
+	 * This may be useful for modifying the factory's {@link WebSocketPolicy}
+	 * via {@link WebSocketServerFactory#getPolicy()}.
 	 */
 	public JettyRequestUpgradeStrategy(WebSocketServerFactory factory) {
 		Assert.notNull(factory, "WebSocketServerFactory must not be null");
@@ -199,7 +199,7 @@ public void upgrade(ServerHttpRequest request, ServerHttpResponse response,
 		}
 		catch (IOException ex) {
 			throw new HandshakeFailureException(
-					"Response update failed during upgrade to WebSocket, uri=" + request.getURI(), ex);
+					"Response update failed during upgrade to WebSocket: " + request.getURI(), ex);
 		}
 		finally {
 			wsContainerHolder.remove();

spring-websocket/src/main/java/org/springframework/web/socket/server/standard/AbstractTyrusRequestUpgradeStrategy.java

@@ -54,9 +54,10 @@
 import org.springframework.web.socket.server.HandshakeFailureException;
 
 /**
- * An base class for WebSocket servers using Tyrus.
+ * A base class for {@code RequestUpgradeStrategy} implementations on top of
+ * JSR-356 based servers which include Tyrus as their WebSocket engine.
  *
- * <p>Works with Tyrus 1.3.5 (WebLogic 12.1.3) and Tyrus 1.7 (GlassFish 4.0.1).
+ * <p>Works with Tyrus 1.3.5 (WebLogic 12.1.3) and Tyrus 1.7+ (GlassFish 4.1.x).
  *
  * @author Rossen Stoyanchev
  * @since 4.1

spring-websocket/src/main/java/org/springframework/web/socket/server/standard/GlassFishRequestUpgradeStrategy.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -34,7 +34,7 @@
 import org.springframework.web.socket.server.HandshakeFailureException;
 
 /**
- * A WebSocket {@code RequestUpgradeStrategy} for GlassFish 4.0.1 and beyond.
+ * A WebSocket {@code RequestUpgradeStrategy} for Oracle's GlassFish 4.1 and higher.
  *
  * @author Rossen Stoyanchev
  * @author Juergen Hoeller

spring-websocket/src/main/java/org/springframework/web/socket/server/standard/TomcatRequestUpgradeStrategy.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -34,8 +34,10 @@
 import org.springframework.web.socket.server.HandshakeFailureException;
 
 /**
- * Tomcat support for upgrading an {@link HttpServletRequest} during a WebSocket handshake.
- * To modify properties of the underlying {@link javax.websocket.server.ServerContainer}
+ * A WebSocket {@code RequestUpgradeStrategy} for Apache Tomcat. Compatible with
+ * all versions of Tomcat that support JSR-356, i.e. Tomcat 7.0.47+ and higher.
+ *
+ * <p>To modify properties of the underlying {@link javax.websocket.server.ServerContainer}
  * you can use {@link ServletServerContainerFactoryBean} in XML configuration or,
  * when using Java configuration, access the container instance through the
  * "javax.websocket.server.ServerContainer" ServletContext attribute.
@@ -59,7 +61,7 @@ public void upgradeInternal(ServerHttpRequest request, ServerHttpResponse respon
 		HttpServletResponse servletResponse = getHttpServletResponse(response);
 
 		StringBuffer requestUrl = servletRequest.getRequestURL();
-		String path = servletRequest.getRequestURI(); // shouldn't matter
+		String path = servletRequest.getRequestURI();  // shouldn't matter
 		Map<String, String> pathParams = Collections.<String, String> emptyMap();
 
 		ServerEndpointRegistration endpointConfig = new ServerEndpointRegistration(path, endpoint);
@@ -71,11 +73,11 @@ public void upgradeInternal(ServerHttpRequest request, ServerHttpResponse respon
 		}
 		catch (ServletException ex) {
 			throw new HandshakeFailureException(
-					"Servlet request failed to upgrade to WebSocket, uri=" + requestUrl, ex);
+					"Servlet request failed to upgrade to WebSocket: " + requestUrl, ex);
 		}
 		catch (IOException ex) {
 			throw new HandshakeFailureException(
-					"Response update failed during upgrade to WebSocket, uri=" + requestUrl, ex);
+					"Response update failed during upgrade to WebSocket: " + requestUrl, ex);
 		}
 	}
 

spring-websocket/src/main/java/org/springframework/web/socket/server/standard/UndertowRequestUpgradeStrategy.java

@@ -59,8 +59,8 @@
 import org.springframework.web.socket.server.HandshakeFailureException;
 
 /**
- * A {@link org.springframework.web.socket.server.RequestUpgradeStrategy} for use
- * with WildFly and its underlying Undertow web server.
+ * A WebSocket {@code RequestUpgradeStrategy} for use with WildFly and its
+ * underlying Undertow web server. Also compatible with embedded Undertow usage.
  *
  * <p>Compatible with Undertow 1.0 to 1.3 - as included in WildFly 8.x, 9 and 10.
  *

spring-websocket/src/main/java/org/springframework/web/socket/server/standard/WebLogicRequestUpgradeStrategy.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -42,7 +42,7 @@
 import org.springframework.web.socket.server.HandshakeFailureException;
 
 /**
- * A WebSocket {@code RequestUpgradeStrategy} for WebLogic 12.1.3.
+ * A WebSocket {@code RequestUpgradeStrategy} for Oracle's WebLogic 12.1.3 and higher.
  *
  * @author Rossen Stoyanchev
  * @since 4.1

spring-websocket/src/main/java/org/springframework/web/socket/server/support/AbstractHandshakeHandler.java

@@ -46,19 +46,26 @@
 import org.springframework.web.socket.server.RequestUpgradeStrategy;
 
 /**
- * A base class to use for {@link HandshakeHandler} implementations.
- * Performs initial validation of the WebSocket handshake request -- possibly rejecting it
- * through the appropriate HTTP status code -- while also allowing sub-classes to override
+ * A base class for {@link HandshakeHandler} implementations, independent from the Servlet API.
+ *
+ * <p>Performs initial validation of the WebSocket handshake request - possibly rejecting it
+ * through the appropriate HTTP status code - while also allowing its subclasses to override
  * various parts of the negotiation process (e.g. origin validation, sub-protocol negotiation,
  * extensions negotiation, etc).
  *
  * <p>If the negotiation succeeds, the actual upgrade is delegated to a server-specific
- * {@link RequestUpgradeStrategy}, which will update
+ * {@link org.springframework.web.socket.server.RequestUpgradeStrategy}, which will update
  * the response as necessary and initialize the WebSocket. Currently supported servers are
- * Tomcat 7 and 8, Jetty 9, and GlassFish 4.
+ * Jetty 9.0-9.3, Tomcat 7.0.47+ and 8.x, Undertow 1.0-1.3, GlassFish 4.1+, WebLogic 12.1.3+.
  *
  * @author Rossen Stoyanchev
- * @since 4.0
+ * @author Juergen Hoeller
+ * @since 4.2
+ * @see org.springframework.web.socket.server.jetty.JettyRequestUpgradeStrategy
+ * @see org.springframework.web.socket.server.standard.TomcatRequestUpgradeStrategy
+ * @see org.springframework.web.socket.server.standard.UndertowRequestUpgradeStrategy
+ * @see org.springframework.web.socket.server.standard.GlassFishRequestUpgradeStrategy
+ * @see org.springframework.web.socket.server.standard.WebLogicRequestUpgradeStrategy
  */
 public abstract class AbstractHandshakeHandler implements HandshakeHandler, Lifecycle {
 
@@ -137,6 +144,7 @@ else if (websphereWsPresent) {
 		else {
 			throw new IllegalStateException("No suitable default RequestUpgradeStrategy found");
 		}
+
 		try {
 			Class<?> clazz = ClassUtils.forName(className, classLoader);
 			return (RequestUpgradeStrategy) clazz.newInstance();
@@ -258,7 +266,7 @@ public final boolean doHandshake(ServerHttpRequest request, ServerHttpResponse r
 		}
 		catch (IOException ex) {
 			throw new HandshakeFailureException(
-					"Response update failed during upgrade to WebSocket, uri=" + request.getURI(), ex);
+					"Response update failed during upgrade to WebSocket: " + request.getURI(), ex);
 		}
 
 		String subProtocol = selectProtocol(headers.getSecWebSocketProtocol(), wsHandler);
@@ -392,8 +400,7 @@ protected List<WebSocketExtension> filterRequestedExtensions(ServerHttpRequest r
 	 * in the process of being established. The default implementation calls
 	 * {@link ServerHttpRequest#getPrincipal()}
 	 * <p>Subclasses can provide custom logic for associating a user with a session,
-	 * for example for assigning a name to anonymous users (i.e. not fully
-	 * authenticated).
+	 * for example for assigning a name to anonymous users (i.e. not fully authenticated).
 	 * @param request the handshake request
 	 * @param wsHandler the WebSocket handler that will handle messages
 	 * @param attributes handshake attributes to pass to the WebSocket session

spring-websocket/src/main/java/org/springframework/web/socket/server/support/DefaultHandshakeHandler.java

@@ -22,18 +22,12 @@
 import org.springframework.web.socket.server.RequestUpgradeStrategy;
 
 /**
- * A default {@link org.springframework.web.socket.server.HandshakeHandler} implementation.
- * Performs initial validation of the WebSocket handshake request -- possibly rejecting it
- * through the appropriate HTTP status code -- while also allowing sub-classes to override
- * various parts of the negotiation process (e.g. origin validation, sub-protocol negotiation,
- * extensions negotiation, etc).
- *
- * <p>If the negotiation succeeds, the actual upgrade is delegated to a server-specific
- * {@link org.springframework.web.socket.server.RequestUpgradeStrategy}, which will update
- * the response as necessary and initialize the WebSocket. Currently supported servers are
- * Tomcat 7 and 8, Jetty 9, and GlassFish 4.
+ * A default {@link org.springframework.web.socket.server.HandshakeHandler} implementation,
+ * extending {@link AbstractHandshakeHandler} with Servlet-specific initialization support.
+ * See {@link AbstractHandshakeHandler}'s javadoc for details on supported servers etc.
  *
  * @author Rossen Stoyanchev
+ * @author Juergen Hoeller
  * @since 4.0
  */
 public class DefaultHandshakeHandler extends AbstractHandshakeHandler implements ServletContextAware {