Add package-info, javadoc, and update package names

spring-websocket/src/main/java/org/springframework/sockjs/package-info.java

@@ -0,0 +1,7 @@
+
+/**
+ * Common abstractions and Spring configuration support for the SockJS protocol.
+ *
+ */
+package org.springframework.sockjs;
+

spring-websocket/src/main/java/org/springframework/sockjs/server/package-info.java

@@ -0,0 +1,7 @@
+
+/**
+ * Server-side SockJS abstractions and base classes.
+ *
+ */
+package org.springframework.sockjs.server;
+

spring-websocket/src/main/java/org/springframework/sockjs/server/support/SockJsServiceHandlerMapping.java

@@ -15,18 +15,28 @@
  */
 package org.springframework.sockjs.server.support;
 
+import java.io.IOException;
 import java.util.Arrays;
 import java.util.List;
 
+import javax.servlet.ServletException;
 import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
+import org.springframework.http.server.AsyncServletServerHttpRequest;
+import org.springframework.http.server.ServerHttpRequest;
+import org.springframework.http.server.ServerHttpResponse;
+import org.springframework.http.server.ServletServerHttpResponse;
 import org.springframework.sockjs.server.AbstractSockJsService;
+import org.springframework.web.HttpRequestHandler;
 import org.springframework.web.servlet.handler.AbstractHandlerMapping;
+import org.springframework.web.util.NestedServletException;
 
 /**
- * A Spring MVC HandlerMapping matching requests to SockJS services by prefix.
+ * A Spring MVC HandlerMapping for matching requests to a SockJS services based on the
+ * {@link AbstractSockJsService#getPrefix() prefix} property of each service.
  *
  * @author Rossen Stoyanchev
  * @since 4.0
@@ -56,7 +66,7 @@ public class SockJsServiceHandlerMapping extends AbstractHandlerMapping {
 					logger.debug("Matched to " + service);
 				}
 				String sockJsPath = lookupPath.substring(service.getPrefix().length());
-				return new SockJsServiceHttpRequestHandler(sockJsPath, service);
+				return new SockJsServiceHttpRequestHandler(service, sockJsPath);
 			}
 		}
 
@@ -67,4 +77,37 @@ public class SockJsServiceHandlerMapping extends AbstractHandlerMapping {
 		return null;
 	}
 
+
+	/**
+	 * {@link HttpRequestHandler} wrapping the invocation of the selected SockJS service.
+	 */
+	private static class SockJsServiceHttpRequestHandler implements HttpRequestHandler {
+
+		private final String sockJsPath;
+
+		private final AbstractSockJsService sockJsService;
+
+
+		public SockJsServiceHttpRequestHandler(AbstractSockJsService sockJsService, String sockJsPath) {
+			this.sockJsService = sockJsService;
+			this.sockJsPath = sockJsPath;
+		}
+
+		@Override
+		public void handleRequest(HttpServletRequest request, HttpServletResponse response)
+				throws ServletException, IOException {
+
+			ServerHttpRequest httpRequest = new AsyncServletServerHttpRequest(request, response);
+			ServerHttpResponse httpResponse = new ServletServerHttpResponse(response);
+
+			try {
+				this.sockJsService.handleRequest(httpRequest, httpResponse, this.sockJsPath);
+			}
+			catch (Exception ex) {
+				// TODO
+				throw new NestedServletException("SockJS service failure", ex);
+			}
+		}
+	}
+
 }

spring-websocket/src/main/java/org/springframework/sockjs/server/support/package-info.java

@@ -0,0 +1,9 @@
+
+/**
+ * Server-side SockJS classes including a
+ * {@link org.springframework.sockjs.server.support.DefaultSockJsService} implementation
+ * as well as a Spring MVC HandlerMapping mapping SockJS services to incoming requests.
+ *
+ */
+package org.springframework.sockjs.server.support;
+

spring-websocket/src/main/java/org/springframework/sockjs/server/transport/EndpointWebSocketTransportHandler.java

@@ -19,7 +19,7 @@ package org.springframework.sockjs.server.transport;
 import org.springframework.sockjs.server.SockJsConfiguration;
 import org.springframework.websocket.WebSocketHandler;
 import org.springframework.websocket.server.HandshakeHandler;
-import org.springframework.websocket.server.endpoint.EndpointHandshakeHandler;
+import org.springframework.websocket.server.endpoint.handshake.EndpointHandshakeHandler;
 
 
 /**

spring-websocket/src/main/java/org/springframework/sockjs/server/transport/package-info.java

@@ -0,0 +1,11 @@
+
+/**
+ * Server-side support for SockJS transports including
+ * {@link org.springframework.sockjs.server.TransportHandler} implementations
+ * for processing incoming requests and their
+ * {@link org.springframework.sockjs.SockJsSession} counterparts for
+ * sending messages over the various transports.
+ *
+ */
+package org.springframework.sockjs.server.transport;
+

spring-websocket/src/main/java/org/springframework/websocket/client/package-info.java

@@ -0,0 +1,7 @@
+
+/**
+ * Client-side support for WebSocket applications.
+ *
+ */
+package org.springframework.websocket.client;
+

spring-websocket/src/main/java/org/springframework/websocket/endpoint/StandardWebSocketSession.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package org.springframework.websocket.support;
+package org.springframework.websocket.endpoint;
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;

spring-websocket/src/main/java/org/springframework/websocket/endpoint/WebSocketHandlerEndpoint.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package org.springframework.websocket.support;
+package org.springframework.websocket.endpoint;
 
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;

spring-websocket/src/main/java/org/springframework/websocket/endpoint/package-info.java

@@ -0,0 +1,8 @@
+
+/**
+ * Classes for use with the standard Java WebSocket endpoints from both client and
+ * server code.
+ *
+ */
+package org.springframework.websocket.endpoint;
+

spring-websocket/src/main/java/org/springframework/websocket/package-info.java

@@ -0,0 +1,7 @@
+
+/**
+ * Common abstractions and Spring configuration support for WebSocket applications.
+ *
+ */
+package org.springframework.websocket;
+

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

@@ -38,8 +38,6 @@ import org.springframework.http.server.ServerHttpRequest;
 import org.springframework.http.server.ServerHttpResponse;
 import org.springframework.util.Assert;
 import org.springframework.util.StringUtils;
-import org.springframework.web.util.UriComponentsBuilder;
-import org.springframework.websocket.WebSocketHandler;
 
 
 /**
@@ -53,25 +51,25 @@ public abstract class AbstractHandshakeHandler implements HandshakeHandler, Bean
 
 	protected Log logger = LogFactory.getLog(getClass());
 
-	private final WebSocketHandler webSocketHandler;
+	private final Object webSocketHandler;
 
-	private final Class<? extends WebSocketHandler> handlerClass;
+	private final Class<?> webSocketHandlerClass;
 
 	private List<String> supportedProtocols;
 
 	private AutowireCapableBeanFactory beanFactory;
 
 
-	public AbstractHandshakeHandler(WebSocketHandler webSocketHandler) {
-		Assert.notNull(webSocketHandler, "webSocketHandler is required");
-		this.webSocketHandler = webSocketHandler;
-		this.handlerClass = null;
+	public AbstractHandshakeHandler(Object handler) {
+		Assert.notNull(handler, "webSocketHandler is required");
+		this.webSocketHandler = handler;
+		this.webSocketHandlerClass = null;
 	}
 
-	public AbstractHandshakeHandler(Class<? extends WebSocketHandler> handlerClass) {
+	public AbstractHandshakeHandler(Class<?> handlerClass) {
 		Assert.notNull((handlerClass), "handlerClass is required");
 		this.webSocketHandler = null;
-		this.handlerClass = handlerClass;
+		this.webSocketHandlerClass = handlerClass;
 	}
 
 	public void setSupportedProtocols(String... protocols) {
@@ -89,10 +87,10 @@ public abstract class AbstractHandshakeHandler implements HandshakeHandler, Bean
 		}
 	}
 
-	protected WebSocketHandler getWebSocketHandler() {
-		if (this.handlerClass != null) {
-			Assert.notNull(this.beanFactory, "BeanFactory is required for WebSocketHandler instance per request.");
-			return this.beanFactory.createBean(this.handlerClass);
+	protected Object getWebSocketHandler() {
+		if (this.webSocketHandlerClass != null) {
+			Assert.notNull(this.beanFactory, "BeanFactory is required for WebSocket handler instances per request.");
+			return this.beanFactory.createBean(this.webSocketHandlerClass);
 		}
 		else {
 			return this.webSocketHandler;

spring-websocket/src/main/java/org/springframework/websocket/server/HandshakeHandler.java

@@ -21,13 +21,13 @@ import org.springframework.http.server.ServerHttpResponse;
 
 
 /**
+ * Abstraction for integrating a WebSocket implementation some HTTP processing pipeline.
  *
  * @author Rossen Stoyanchev
  * @since 4.0
  */
 public interface HandshakeHandler {
 
-
 	boolean doHandshake(ServerHttpRequest request, ServerHttpResponse response) throws Exception;
 
 }

spring-websocket/src/main/java/org/springframework/websocket/server/endpoint/EndpointExporter.java

@@ -35,7 +35,7 @@ import org.springframework.util.ObjectUtils;
 
 /**
  * BeanPostProcessor that detects beans of type
- * {@link javax.websocket.server.ServerEndpointConfig} and registers the corresponding
+ * {@link javax.websocket.server.ServerEndpointConfig} and registers the provided
  * {@link javax.websocket.Endpoint} with a standard Java WebSocket runtime.
  *
  * <p>If the runtime is a Servlet container, use {@link ServletEndpointExporter}.

spring-websocket/src/main/java/org/springframework/websocket/server/endpoint/EndpointRegistration.java

@@ -36,7 +36,7 @@ import org.springframework.util.Assert;
 import org.springframework.util.ClassUtils;
 import org.springframework.web.context.ContextLoader;
 import org.springframework.web.context.WebApplicationContext;
-import org.springframework.websocket.support.WebSocketHandlerEndpoint;
+import org.springframework.websocket.endpoint.WebSocketHandlerEndpoint;
 
 
 /**

spring-websocket/src/main/java/org/springframework/websocket/server/endpoint/EndpointRequestUpgradeStrategy.java

@@ -23,7 +23,8 @@ import org.springframework.http.server.ServerHttpResponse;
 
 
 /**
- * A strategy for performing the runtime-specific parts of a WebSocket upgrade request.
+ * A strategy for performing the container-specific steps for upgrading an HTTP request
+ * as part of a WebSocket handshake.
  *
  * @author Rossen Stoyanchev
  * @since 4.0

spring-websocket/src/main/java/org/springframework/websocket/server/endpoint/ServletEndpointExporter.java

@@ -32,10 +32,8 @@ import org.springframework.web.context.ServletContextAware;
  */
 public class ServletEndpointExporter extends EndpointExporter implements ServletContextAware {
 
-	/**
-	 *
-	 */
 	private static final String SERVER_CONTAINER_ATTR_NAME = "javax.websocket.server.ServerContainer";
+
 	private ServletContext servletContext;
 
 

spring-websocket/src/main/java/org/springframework/websocket/server/endpoint/handshake/EndpointHandshakeHandler.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package org.springframework.websocket.server.endpoint;
+package org.springframework.websocket.server.endpoint.handshake;
 
 import javax.websocket.Endpoint;
 
@@ -23,13 +23,18 @@ import org.springframework.http.server.ServerHttpRequest;
 import org.springframework.http.server.ServerHttpResponse;
 import org.springframework.util.ClassUtils;
 import org.springframework.websocket.WebSocketHandler;
+import org.springframework.websocket.endpoint.WebSocketHandlerEndpoint;
 import org.springframework.websocket.server.AbstractHandshakeHandler;
 import org.springframework.websocket.server.HandshakeHandler;
-import org.springframework.websocket.support.WebSocketHandlerEndpoint;
+import org.springframework.websocket.server.endpoint.EndpointRequestUpgradeStrategy;
 
 
 /**
- * A {@link HandshakeHandler} for use with standard Java WebSocket.
+ * A {@link HandshakeHandler} for use with standard Java WebSocket runtimes. A
+ * container-specific {@link EndpointRequestUpgradeStrategy} is required since standard
+ * Java WebSocket currently does not provide any means of integrating a WebSocket
+ * handshake into an HTTP request processing pipeline. Currently available are
+ * implementations for Tomcat and Glassfish.
  *
  * @author Rossen Stoyanchev
  * @since 4.0
@@ -45,12 +50,17 @@ public class EndpointHandshakeHandler extends AbstractHandshakeHandler {
 	private final EndpointRequestUpgradeStrategy upgradeStrategy;
 
 
+	public EndpointHandshakeHandler(Endpoint endpoint) {
+		super(endpoint);
+		this.upgradeStrategy = createUpgradeStrategy();
+	}
+
 	public EndpointHandshakeHandler(WebSocketHandler webSocketHandler) {
 		super(webSocketHandler);
 		this.upgradeStrategy = createUpgradeStrategy();
 	}
 
-	public EndpointHandshakeHandler(Class<? extends WebSocketHandler> handlerClass) {
+	public EndpointHandshakeHandler(Class<?> handlerClass) {
 		super(handlerClass);
 		this.upgradeStrategy = createUpgradeStrategy();
 	}
@@ -85,7 +95,21 @@ public class EndpointHandshakeHandler extends AbstractHandshakeHandler {
 			throws Exception {
 
 		logger.debug("Upgrading HTTP request");
-		Endpoint endpoint = new WebSocketHandlerEndpoint(getWebSocketHandler());
+
+		Object webSocketHandler = getWebSocketHandler();
+
+		Endpoint endpoint;
+		if (webSocketHandler instanceof Endpoint) {
+			endpoint = (Endpoint) webSocketHandler;
+		}
+		else if (webSocketHandler instanceof WebSocketHandler) {
+			endpoint = new WebSocketHandlerEndpoint((WebSocketHandler) webSocketHandler);
+		}
+		else {
+			String className = webSocketHandler.getClass().getName();
+			throw new IllegalArgumentException("Unexpected WebSocket handler type: " + className);
+		}
+
 		this.upgradeStrategy.upgrade(request, response, protocol, endpoint);
 	}
 

spring-websocket/src/main/java/org/springframework/websocket/server/endpoint/handshake/GlassfishRequestUpgradeStrategy.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package org.springframework.websocket.server.endpoint.support;
+package org.springframework.websocket.server.endpoint.handshake;
 
 import java.lang.reflect.Constructor;
 import java.net.URI;
@@ -49,6 +49,8 @@ import org.springframework.websocket.server.endpoint.EndpointRegistration;
 import org.springframework.websocket.server.endpoint.EndpointRequestUpgradeStrategy;
 
 /**
+ * Glassfish support for upgrading an {@link HttpServletRequest} during a WebSocket
+ * handshake.
  *
  * @author Rossen Stoyanchev
  * @since 4.0

spring-websocket/src/main/java/org/springframework/websocket/server/endpoint/handshake/TomcatRequestUpgradeStrategy.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package org.springframework.websocket.server.endpoint.support;
+package org.springframework.websocket.server.endpoint.handshake;
 
 import java.lang.reflect.Method;
 import java.util.Collections;
@@ -36,6 +36,7 @@ import org.springframework.websocket.server.endpoint.EndpointRequestUpgradeStrat
 
 
 /**
+ * Tomcat support for upgrading an {@link HttpServletRequest} during a WebSocket handshake.
  *
  * @author Rossen Stoyanchev
  * @since 4.0

spring-websocket/src/main/java/org/springframework/websocket/server/endpoint/handshake/package-info.java

@@ -0,0 +1,8 @@
+
+/**
+ * WebSocket handshake support for use with standard Java WebSocket runtimes including
+ * container-specific strategies for upgrading the HttpServletRequest.
+ *
+ */
+package org.springframework.websocket.server.endpoint.handshake;
+

spring-websocket/src/main/java/org/springframework/websocket/server/endpoint/package-info.java

@@ -1,8 +1,13 @@
 
 /**
- *
- * Server-specific support for configuring and adapting standard Java WebSocket endpoint's.
- *
+ * Server classes for use with standard Java WebSocket endpoints including
+ * {@link org.springframework.websocket.server.endpoint.EndpointRegistration} and
+ * {@link org.springframework.websocket.server.endpoint.EndpointExporter} for
+ * registering type-based endpoints,
+ * {@link org.springframework.websocket.server.endpoint.SpringConfigurator} for
+ * instantiating annotated endpoints through Spring, and
+ * {@link org.springframework.websocket.server.endpoint.handshake.EndpointHandshakeHandler}
+ * for integrating endpoints into HTTP request processing.
  */
 package org.springframework.websocket.server.endpoint;
 

spring-websocket/src/main/java/org/springframework/websocket/server/package-info.java

@@ -0,0 +1,7 @@
+
+/**
+ * Server-side abstractions for WebSocket applications.
+ *
+ */
+package org.springframework.websocket.server;
+

spring-websocket/src/main/java/org/springframework/websocket/server/support/HandshakeHttpRequestHandler.java

@@ -5,7 +5,7 @@
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- *      http://www.apache.org/licenses/LICENSE-2.0
+ * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
@@ -13,7 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.springframework.sockjs.server.support;
+
+package org.springframework.websocket.server.support;
 
 import java.io.IOException;
 
@@ -21,45 +22,46 @@ import javax.servlet.ServletException;
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
-import org.springframework.http.server.AsyncServletServerHttpRequest;
 import org.springframework.http.server.ServerHttpRequest;
 import org.springframework.http.server.ServerHttpResponse;
+import org.springframework.http.server.ServletServerHttpRequest;
 import org.springframework.http.server.ServletServerHttpResponse;
-import org.springframework.sockjs.server.AbstractSockJsService;
+import org.springframework.util.Assert;
 import org.springframework.web.HttpRequestHandler;
 import org.springframework.web.util.NestedServletException;
+import org.springframework.websocket.server.HandshakeHandler;
+
 
 /**
- * A Spring MVC {@link HttpRequestHandler} wrapping the invocation of a SockJS service.
+ * A Spring MVC {@link HttpRequestHandler} wrapping the invocation of a WebSocket
+ * {@link HandshakeHandler};
  *
  * @author Rossen Stoyanchev
  * @since 4.0
  */
-public class SockJsServiceHttpRequestHandler implements HttpRequestHandler {
+public class HandshakeHttpRequestHandler implements HttpRequestHandler {
 
-	private final String sockJsPath;
-
-	private final AbstractSockJsService sockJsService;
+	private final HandshakeHandler handshakeHandler;
 
 
-	public SockJsServiceHttpRequestHandler(String sockJsPath, AbstractSockJsService sockJsService) {
-		this.sockJsService = sockJsService;
-		this.sockJsPath = sockJsPath;
+	public HandshakeHttpRequestHandler(HandshakeHandler handshakeHandler) {
+		Assert.notNull(handshakeHandler, "handshakeHandler is required");
+		this.handshakeHandler = handshakeHandler;
 	}
 
 	@Override
 	public void handleRequest(HttpServletRequest request, HttpServletResponse response)
 			throws ServletException, IOException {
 
-		ServerHttpRequest httpRequest = new AsyncServletServerHttpRequest(request, response);
+		ServerHttpRequest httpRequest = new ServletServerHttpRequest(request);
 		ServerHttpResponse httpResponse = new ServletServerHttpResponse(response);
 
 		try {
-			this.sockJsService.handleRequest(httpRequest, httpResponse, this.sockJsPath);
+			this.handshakeHandler.doHandshake(httpRequest, httpResponse);
 		}
-		catch (Exception ex) {
+		catch (Exception e) {
 			// TODO
-			throw new NestedServletException("SockJS service failure", ex);
+			throw new NestedServletException("HandshakeHandler failure", e);
 		}
 	}
 

spring-websocket/src/main/java/org/springframework/websocket/server/support/package-info.java

@@ -0,0 +1,7 @@
+
+/**
+ * Server-side support classes for WebSocket applications.
+ *
+ */
+package org.springframework.websocket.server.support;
+

spring-websocket/src/main/java/org/springframework/websocket/support/package-info.java

@@ -1,8 +0,0 @@
-
-/**
- *
- * Support for working with standard Java WebSocket Endpoint's.
- *
- */
-package org.springframework.websocket.support;
-