Add SockJsMessageCodec

A SockJS message frame is an array of JSON-encoded messages and before
this change the use of the Jackson 2 library was hard-coded.

A Jackson 2 and Jackson 1.x implementations are provided and
automatically used if those libraries are present on the classpath.

Issue: SPR-10800

Author: rstoyanchev

build.gradle

@@ -507,7 +507,8 @@ project("spring-websocket") {
 		}
 		optional("org.eclipse.jetty.websocket:websocket-server:9.0.4.v20130625")
 		optional("org.eclipse.jetty.websocket:websocket-client:9.0.4.v20130625")
-		optional("com.fasterxml.jackson.core:jackson-databind:2.2.0") // required for SockJS support currently
+		optional("com.fasterxml.jackson.core:jackson-databind:2.2.0")
+		optional("org.codehaus.jackson:jackson-mapper-asl:1.9.12")
 	}
 
 	repositories {

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

@@ -46,17 +46,19 @@
 import org.springframework.web.socket.WebSocketHandler;
 
 /**
- * An abstract class for {@link SockJsService} implementations. Provides configuration
- * support, SockJS path resolution, and processing for static SockJS requests (e.g.
- * "/info", "/iframe.html", etc). Sub-classes are responsible for handling transport
- * requests.
- *
- * <p>It is expected that this service is mapped correctly to one or more prefixes such as
- * "/echo" including all sub-URLs (e.g. "/echo/**"). A SockJS service itself is generally
- * unaware of request mapping details but nevertheless must be able to extract the SockJS
- * path, which is the portion of the request path following the prefix. In most cases,
- * this class can auto-detect the SockJS path but you can also explicitly configure the
- * list of valid prefixes with {@link #setValidSockJsPrefixes(String...)}.
+ * An abstract base class for {@link SockJsService} implementations that provides SockJS
+ * path resolution and handling of static SockJS requests (e.g. "/info", "/iframe.html",
+ * etc). Transport-specific requests are left as abstract methods.
+ * <p>
+ * This 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 correctly to a
+ * prefix (e.g. "/echo") and will also handle all sub-URLs (i.e. "/echo/**").
+ * <p>
+ * The service itself is unaware of the underlying mapping mechanism but nevertheless must
+ * be able to extract the SockJS path, i.e. the portion of the request path following the
+ * prefix. In most cases, this class can auto-detect the SockJS path but it is also
+ * possible to configure explicitly the prefixes via
+ * {@link #setValidSockJsPrefixes(String...)}.
  *
  * @author Rossen Stoyanchev
  * @since 4.0

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

@@ -73,13 +73,13 @@ public abstract class AbstractSockJsSession implements ConfigurableWebSocketSess
 	 * @param config the sockJS configuration
 	 * @param webSocketHandler the recipient of SockJS messages
 	 */
-	public AbstractSockJsSession(String sessionId, SockJsConfiguration config,
-			WebSocketHandler webSocketHandler) {
-		Assert.notNull(sessionId, "sessionId must not be null");
-		Assert.notNull(webSocketHandler, "webSocketHandler must not be null");
+	public AbstractSockJsSession(String sessionId, SockJsConfiguration config, WebSocketHandler webSocketHandler) {
+		Assert.notNull(sessionId, "sessionId is required");
+		Assert.notNull(config, "sockJsConfig is required");
+		Assert.notNull(webSocketHandler, "webSocketHandler is required");
 		this.id = sessionId;
-		this.handler = webSocketHandler;
 		this.sockJsConfig = config;
+		this.handler = webSocketHandler;
 	}
 
 	@Override

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

@@ -38,7 +38,7 @@ public interface SockJsConfiguration {
 	 *
 	 * <p>The default value is 128K (i.e. 128 * 1024).
 	 */
-	public int getStreamBytesLimit();
+	int getStreamBytesLimit();
 
 	/**
 	 * The amount of time in milliseconds when the server has not sent any
@@ -47,11 +47,17 @@ public interface SockJsConfiguration {
 	 *
 	 * <p>The default value is 25,000 (25 seconds).
 	 */
-	public long getHeartbeatTime();
+	long getHeartbeatTime();
 
 	/**
 	 * A scheduler instance to use for scheduling heart-beat messages.
 	 */
-	public TaskScheduler getTaskScheduler();
+	TaskScheduler getTaskScheduler();
+
+	/**
+	 * The codec to use for encoding and decoding SockJS messages.
+	 * @exception IllegalStateException if no {@link SockJsMessageCodec} is available
+	 */
+	SockJsMessageCodec getMessageCodecRequired();
 
 }

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

@@ -20,8 +20,6 @@
 
 import org.springframework.util.Assert;
 
-import com.fasterxml.jackson.core.io.JsonStringEncoder;
-
 /**
  * Represents a SockJS frames. Provides methods for access to commonly used message
  * frames.
@@ -31,42 +29,43 @@
  */
 public class SockJsFrame {
 
-	private static final SockJsFrame OPEN_FRAME = new SockJsFrame("o");
+	private static final SockJsFrame openFrame = new SockJsFrame("o");
 
-	private static final SockJsFrame HEARTBEAT_FRAME = new SockJsFrame("h");
+	private static final SockJsFrame heartbeatFrame = new SockJsFrame("h");
 
-	private static final SockJsFrame CLOSE_GO_AWAY_FRAME = closeFrame(3000, "Go away!");
+	private static final SockJsFrame closeGoAwayFrame = closeFrame(3000, "Go away!");
 
-	private static final SockJsFrame CLOSE_ANOTHER_CONNECTION_OPEN = closeFrame(2010, "Another connection still open");
+	private static final SockJsFrame closeAnotherConnectionOpenFrame = closeFrame(2010, "Another connection still open");
 
 
 	private final String content;
 
 
 	private SockJsFrame(String content) {
-		Assert.notNull("content must not be null");
+		Assert.notNull("content is required");
 		this.content = content;
 	}
 
 
 	public static SockJsFrame openFrame() {
-		return OPEN_FRAME;
+		return openFrame;
 	}
 
 	public static SockJsFrame heartbeatFrame() {
-		return HEARTBEAT_FRAME;
+		return heartbeatFrame;
 	}
 
-	public static SockJsFrame messageFrame(String... messages) {
-		return new MessageFrame(messages);
+	public static SockJsFrame messageFrame(SockJsMessageCodec codec, String... messages) {
+		String encoded = codec.encode(messages);
+		return new SockJsFrame(encoded);
 	}
 
 	public static SockJsFrame closeFrameGoAway() {
-		return CLOSE_GO_AWAY_FRAME;
+		return closeGoAwayFrame;
 	}
 
 	public static SockJsFrame closeFrameAnotherConnectionOpen() {
-		return CLOSE_ANOTHER_CONNECTION_OPEN;
+		return closeAnotherConnectionOpenFrame;
 	}
 
 	public static SockJsFrame closeFrame(int code, String reason) {
@@ -82,35 +81,6 @@ public byte[] getContentBytes() {
 		return this.content.getBytes(Charset.forName("UTF-8"));
 	}
 
-	/**
-	 * See "JSON Unicode Encoding" section of SockJS protocol.
-	 */
-	public static String escapeCharacters(char[] characters) {
-		StringBuilder result = new StringBuilder();
-		for (char c : characters) {
-			if (isSockJsEscapeCharacter(c)) {
-				result.append('\\').append('u');
-				String hex = Integer.toHexString(c).toLowerCase();
-				for (int i = 0; i < (4 - hex.length()); i++) {
-					result.append('0');
-				}
-				result.append(hex);
-			}
-			else {
-				result.append(c);
-			}
-		}
-		return result.toString();
-	}
-
-	// See `escapable_by_server` var in SockJS protocol (under "JSON Unicode Encoding")
-
-	private static boolean isSockJsEscapeCharacter(char ch) {
-		return (ch >= '\u0000' && ch <= '\u001F') || (ch >= '\u200C' && ch <= '\u200F')
-				|| (ch >= '\u2028' && ch <= '\u202F') || (ch >= '\u2060' && ch <= '\u206F')
-				|| (ch >= '\uFFF0' && ch <= '\uFFFF') || (ch >= '\uD800' && ch <= '\uDFFF');
-	}
-
 	@Override
 	public String toString() {
 		String result = this.content;
@@ -137,31 +107,6 @@ public boolean equals(Object other) {
 	}
 
 
-	private static class MessageFrame extends SockJsFrame {
-
-		public MessageFrame(String... messages) {
-			super(prepareContent(messages));
-		}
-
-		public static String prepareContent(String... messages) {
-			Assert.notNull(messages, "messages must not be null");
-			StringBuilder sb = new StringBuilder();
-			sb.append("a[");
-			for (int i=0; i < messages.length; i++) {
-				sb.append('"');
-				// TODO: dependency on Jackson
-				char[] quotedChars = JsonStringEncoder.getInstance().quoteAsString(messages[i]);
-				sb.append(escapeCharacters(quotedChars));
-				sb.append('"');
-	            if (i < messages.length - 1) {
-	                sb.append(',');
-	            }
-			}
-			sb.append(']');
-			return sb.toString();
-		}
-	}
-
 	public interface FrameFormat {
 
 		SockJsFrame format(SockJsFrame frame);

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

@@ -0,0 +1,66 @@
+/*
+ * 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.io.IOException;
+import java.io.InputStream;
+
+
+/**
+ * A contract for encoding and decoding of messages to and from a SockJS message frame,
+ * which is essentially an array of JSON-encoded messages. For example:
+ *
+ * <pre>
+ * a["message1","message2"]
+ * </pre>
+ *
+ * @author Rossen Stoyanchev
+ * @since 4.0
+ */
+public interface SockJsMessageCodec {
+
+
+	/**
+	 * Encode the given messages as a SockJS message frame. Aside from applying standard
+	 * JSON quoting to each message, there are some additional JSON Unicode escaping
+	 * rules. See the "JSON Unicode Encoding" section of SockJS protocol (i.e. the
+	 * protocol test suite).
+	 *
+	 * @param messages the messages to encode
+	 * @return the content for a SockJS message frame, never {@code null}
+	 */
+	String encode(String[] messages);
+
+	/**
+	 * Decode the given SockJS message frame.
+	 *
+	 * @param content the SockJS message frame
+	 * @return an array of messages or {@code null}
+	 * @throws IOException if the content could not be parsed
+	 */
+	String[] decode(String content) throws IOException;
+
+	/**
+	 * Decode the given SockJS message frame.
+	 *
+	 * @param content the SockJS message frame
+	 * @return an array of messages or {@code null}
+	 * @throws IOException if the content could not be parsed
+	 */
+	String[] decodeInputStream(InputStream content) throws IOException;
+
+}

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

@@ -36,6 +36,8 @@ public interface TransportHandler {
 
 	TransportType getTransportType();
 
+	void setSockJsConfiguration(SockJsConfiguration sockJsConfig);
+
 	void handleRequest(ServerHttpRequest request, ServerHttpResponse response,
 			WebSocketHandler handler, AbstractSockJsSession session) throws TransportErrorException;
 

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

@@ -0,0 +1,86 @@
+/*
+ * 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.support;
+
+import org.springframework.util.Assert;
+import org.springframework.web.socket.sockjs.SockJsMessageCodec;
+
+
+/**
+ * An base class for SockJS message codec that provides an implementation of
+ * {@link #encode(String[])}.
+ *
+ * @author Rossen Stoyanchev
+ * @since 4.0
+ */
+public abstract class AbstractSockJsMessageCodec implements SockJsMessageCodec {
+
+
+	@Override
+	public String encode(String[] messages) {
+		Assert.notNull(messages, "messages must not be null");
+		StringBuilder sb = new StringBuilder();
+		sb.append("a[");
+		for (int i=0; i < messages.length; i++) {
+			sb.append('"');
+			char[] quotedChars = applyJsonQuoting(messages[i]);
+			sb.append(escapeSockJsSpecialChars(quotedChars));
+			sb.append('"');
+            if (i < messages.length - 1) {
+                sb.append(',');
+            }
+		}
+		sb.append(']');
+		return sb.toString();
+	}
+
+	/**
+	 * Apply standard JSON string quoting (see http://www.json.org/).
+	 */
+	protected abstract char[] applyJsonQuoting(String content);
+
+	/**
+	 * See "JSON Unicode Encoding" section of SockJS protocol.
+	 */
+	private String escapeSockJsSpecialChars(char[] characters) {
+		StringBuilder result = new StringBuilder();
+		for (char c : characters) {
+			if (isSockJsSpecialChar(c)) {
+				result.append('\\').append('u');
+				String hex = Integer.toHexString(c).toLowerCase();
+				for (int i = 0; i < (4 - hex.length()); i++) {
+					result.append('0');
+				}
+				result.append(hex);
+			}
+			else {
+				result.append(c);
+			}
+		}
+		return result.toString();
+	}
+
+	/**
+	 * See `escapable_by_server` variable in the SockJS protocol test suite.
+	 */
+	private boolean isSockJsSpecialChar(char ch) {
+		return (ch >= '\u0000' && ch <= '\u001F') || (ch >= '\u200C' && ch <= '\u200F')
+				|| (ch >= '\u2028' && ch <= '\u202F') || (ch >= '\u2060' && ch <= '\u206F')
+				|| (ch >= '\uFFF0' && ch <= '\uFFFF') || (ch >= '\uD800' && ch <= '\uDFFF');
+	}
+
+}