Polish SockJS exception handling and javadoc

See javadoc in SockJsService for details.

Also remove ReadOnlyMultiValueMap, CollectionUtils has a method for
that already.

spring-web/src/main/java/org/springframework/http/server/ServletServerHttpRequest.java

@@ -44,9 +44,9 @@
 import org.springframework.http.HttpMethod;
 import org.springframework.http.MediaType;
 import org.springframework.util.Assert;
+import org.springframework.util.CollectionUtils;
 import org.springframework.util.LinkedMultiValueMap;
 import org.springframework.util.MultiValueMap;
-import org.springframework.util.ReadOnlyMultiValueMap;
 
 /**
  * {@link ServerHttpRequest} implementation that is based on a {@link HttpServletRequest}.
@@ -184,7 +184,7 @@ public MultiValueMap<String, String> getQueryParams() {
 					}
 				}
 			}
-			this.queryParams = new ReadOnlyMultiValueMap<String, String>(result);
+			this.queryParams = CollectionUtils.unmodifiableMultiValueMap(result);
 		}
 		return this.queryParams;
 	}

spring-websocket/src/main/java/org/springframework/web/socket/sockjs/SockJsProcessingException.java → spring-websocket/src/main/java/org/springframework/web/socket/sockjs/SockJsException.java

@@ -19,29 +19,24 @@
 import org.springframework.core.NestedRuntimeException;
 
 /**
- * Raised when SockJS request handling fails.
+ * Base class for exceptions raised while processing SockJS HTTP requests.
  *
  * @author Rossen Stoyanchev
  * @since 4.0
  */
 @SuppressWarnings("serial")
-public class SockJsProcessingException extends NestedRuntimeException {
+public class SockJsException extends NestedRuntimeException {
 
 	private final String sessionId;
 
 
-	public SockJsProcessingException(String msg, Throwable cause, String sessionId) {
-		super(msg, cause);
+	public SockJsException(String message, String sessionId, Throwable cause) {
+		super(message, cause);
 		this.sessionId = sessionId;
 	}
 
 	public String getSockJsSessionId() {
 		return this.sessionId;
 	}
 
-	@Override
-	public String getMessage() {
-		return "Transport error for SockJS session id=" + this.sessionId + ", " + super.getMessage();
-	}
-
 }

spring-websocket/src/main/java/org/springframework/web/socket/sockjs/SockJsMessageDeliveryException.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2002-2013 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.
+ * You may obtain a copy of the License at
+ *
+ * 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,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.web.socket.sockjs;
+
+import java.util.List;
+
+
+/**
+ * An exception thrown when a message frame was successfully received over an HTTP POST
+ * and parsed but one or more of the messages it contained could not be delivered to the
+ * WebSocketHandler either because the handler failed or because the connection got
+ * closed.
+ * <p>
+ * The SockJS session is not automatically closed after this exception.
+ *
+ * @author Rossen Stoyanchev
+ * @since 4.0
+ */
+@SuppressWarnings("serial")
+public class SockJsMessageDeliveryException extends SockJsException {
+
+	private final List<String> undeliveredMessages;
+
+
+	public SockJsMessageDeliveryException(String sessionId, List<String> undeliveredMessages, Throwable cause) {
+		super("Failed to deliver message(s) " + undeliveredMessages + " for session " + sessionId, sessionId, cause);
+		this.undeliveredMessages = undeliveredMessages;
+	}
+
+	public List<String> getUndeliveredMessages() {
+		return this.undeliveredMessages;
+	}
+
+}

spring-websocket/src/main/java/org/springframework/web/socket/sockjs/SockJsService.java

@@ -16,14 +16,24 @@
 
 package org.springframework.web.socket.sockjs;
 
-import java.io.IOException;
-
 import org.springframework.http.server.ServerHttpRequest;
 import org.springframework.http.server.ServerHttpResponse;
 import org.springframework.web.socket.WebSocketHandler;
+import org.springframework.web.socket.support.ExceptionWebSocketHandlerDecorator;
 
 /**
- * A service for processing SockJS HTTP requests.
+ * The main entry point for processing HTTP requests from SockJS clients.
+ * <p>
+ * In a Servlet 3+ container, {@link SockJsHttpRequestHandler} can be used to invoke this
+ * service. The processing servlet, as well as all filters involved, must have
+ * asynchronous support enabled through the ServletContext API or by adding an
+ * {@code <async-support>true</async-support>} element to servlet and filter declarations
+ * in web.xml.
+ * <p>
+ * The service can be integrated into any HTTP request handling mechanism (e.g. plain
+ * Servlet, Spring MVC, or other). It is expected that it will be mapped, as expected
+ * by the SockJS protocol, to a specific prefix (e.g. "/echo") including all sub-URLs
+ * (i.e. Ant path pattern "/echo/**").
  *
  * @author Rossen Stoyanchev
  * @since 4.0
@@ -34,16 +44,27 @@ public interface SockJsService {
 
 
 	/**
-	 * Process a SockJS request.
+	 * Process a SockJS HTTP request.
+	 * <p>
+	 * See the "Base URL", "Static URLs", and "Session URLs" sections of the <a
+	 * href="http://sockjs.github.io/sockjs-protocol/sockjs-protocol-0.3.3.html">SockJS
+	 * protocol</a> for details on the types of URLs expected.
 	 *
 	 * @param request the current request
 	 * @param response the current response
-	 * @param handler the handler to process messages with
+	 * @param handler the handler that will exchange messages with the SockJS client
 	 *
-	 * @throws IOException raised if writing the to response of the current request fails
-	 * @throws SockJsProcessingException
+	 * @throws SockJsException raised when request processing fails; generally, failed
+	 *         attempts to send messages to clients automatically close the SockJS session
+	 *         and raise {@link SockJsTransportFailureException}; failed attempts to read
+	 *         messages from clients do not automatically close the session and may result
+	 *         in {@link SockJsMessageDeliveryException} or {@link SockJsException};
+	 *         exceptions from the WebSocketHandler can be handled internally or through
+	 *         {@link ExceptionWebSocketHandlerDecorator} or some alternative decorator.
+	 *         The former is automatically added when using
+	 *         {@link SockJsHttpRequestHandler}.
 	 */
 	void handleRequest(ServerHttpRequest request, ServerHttpResponse response, WebSocketHandler handler)
-			throws IOException, SockJsProcessingException;
+			throws SockJsException;
 
 }

spring-websocket/src/main/java/org/springframework/web/socket/sockjs/SockJsTransportFailureException.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2002-2013 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.
+ * You may obtain a copy of the License at
+ *
+ * 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,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.web.socket.sockjs;
+
+
+/**
+ * Indicates a serious failure that occurred in the SockJS implementation as opposed to in
+ * user code (e.g. IOException while writing to the response). When this exception is
+ * raised, the SockJS session is typically closed.
+ *
+ * @author Rossen Stoyanchev
+ * @since 4.0
+ */
+@SuppressWarnings("serial")
+public class SockJsTransportFailureException extends SockJsException {
+
+
+	public SockJsTransportFailureException(String message, String sessionId, Throwable cause) {
+		super(message, sessionId, cause);
+	}
+
+}