Intro to WebSocket with
Spring Framework 4.0
Rossen Stoyanchev
About this talk
- Introduces WebSocket and Spring Framework support
- Separate talk on actually-
"Building WebSocket Browser Apps with Spring" - https://github.com/rstoyanchev/
s2gx2013-websocket-browser-apps-with-spring
WebSocket
"mechanism for browser-based applications...
two-way communication with servers...
does not rely on multiple HTTP connections"
- RFC 6455, The WebSocket Protocol
Excitement is justified
given long history of Ajax/Comet
However expectations have come
ahead of experience
A Few (False) Expectations
- It's standard, it's supported everywhere
- It's a replacement for Ajax/Comet (maybe even REST)
- I know web apps, how different can this be?
- I will program to a WebSocket API
Reality Check
- Not supported in IE < 10
- There are issues with proxies
- Not a replacement for REST
- A socket is very low level to work on
- Event-driven, messaging architecture
WebSockets
"Toto, I've a feeling we're not in REST land any more"
Last year's talk
Available on YouTube
- Broad, pragmatic introduction
- A survey of the land
- Some key (open-ended) questions defined
Key Takeaways from Last Year
- The need for fallback options will persist
- Integrating into a real application not yet trivial
- "Pure" WebSocket apps in the wild unlikely
- Questions remain around usage patterns
A Quick Definition
What is WebSocket?
- A layer on TCP
- Full-duplex, stateful connection
- Stream of messages (rather than bytes)
- HTTP used for the initial handshake
HANDSHAKE REQUEST
GET /mychat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Protocol: chat
Sec-WebSocket-Version: 13
Origin: http://example.com
HANDSHAKE RESPONSE
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
Sec-WebSocket-Protocol: chat
then exchange messages on the socket...
Typical API Lifecycle Events
open- session establishedmessage- new messages receivederror- transport errorclose- session closed- Symmetrical on the client and server sides
WebSocket Frame
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-------+-+-------------+-------------------------------+
|F|R|R|R| opcode|M| Payload len | Extended payload length |
|I|S|S|S| (4) |A| (7) | (16/64) |
|N|V|V|V| |S| | (if payload len==126/127) |
| |1|2|3| |K| | |
+-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - +
| Extended payload length continued, if payload len == 127 |
+ - - - - - - - - - - - - - - - +-------------------------------+
| |Masking-key, if MASK set to 1 |
+-------------------------------+-------------------------------+
| Masking-key (continued) | Payload Data |
+-------------------------------- - - - - - - - - - - - - - - - +
: Payload Data continued ... :
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
| Payload Data continued ... |
+---------------------------------------------------------------+
What kind of payload?
- Text messages encoded as UTF-8
- Binary messages
- Control frames: close, ping, pong
- Continuation frames
Message vs Frame
- A message can be broken into fragments
- Protocol implementation deals with fragments
- Applications mainly work with messages
- Good to know if tracing TCP traffic
Runtime Support
The Java API for WebSocket
- Several Servlet containers pre-date JSR-356
- Jetty 7/8, Tomcat 7, GlassFish 3.x
- Much debate on JSR-356 EG
- All-new WebSocket implementations
Relationship to Servlet Spec
- JSR-356 has no dependency on Servlet spec
- Nevertheless built for and by Servlet containers
- Servlet 3.1 provides a hook for upgrading:
HttpServletRequest.upgrade(Class<?>) - SCI scan used also in Servlet containers
Servlet Container Versions
- Tomcat 8 (currently RC1)-
expect RC2 soon and also backport to Tomcat 7 - Jetty 9 already has native WebSocket API-
Jetty 9.1 will addJSR-356 - Glassfish 4 with Tyrus WebSocket engine
- More containers to follow
The JSR-356 API
- Two main options
- Extend abstract class
Endpoint, or - Use annotated endpoints via
@ServerEndpoint,@ClientEndpoint
Server-Side Deployment
(JSR-356)
- Also two main options
- Servlet container scan for annotated endpoints
- Programmatic deployment at startup
viaWebSocketContainer
JSR-356 in Spring Apps
- Create endpoints through Spring container
ServerEndpointExporterdeploys beans of typeServerEndpointRegistrationSpringConfiguratorcan be referenced
via@ServerEndpointattribute- Check Javadoc of these classes
JSR-356 Limitations
- No fallback options (no IE)
- No sub-protocol support, hard to build real apps
- No way to handle HTTP and WebSocket requests
from one place (i.e. "front controller" pattern) - Resembles application framework
rather than remain flexible for frameworks to build on
Why Frameworks Matter?
- If you maintain one WebSocket per client
- i.e. one pipeline for all messages
- You end up with single
@ServerEndpointper application - This is too rudimentary
- Much like Servlet vs Web framework
"Using annotations and things is clearly in the vein of Spring and Hibernate and other popular Java libraries. When trying to build on top of it, though, I find myself wishing for an API more like Jetty 8, where I can just implement some interfaces and build my own abstractions on top of WebSocket."
Comment on jetty-users mailing list
Spring WebSocket API
Spring's own WebSocket API
- Abstraction over WebSocket runtimes
- Including JSR-356 containers
- But not limited to it-
Jetty 9 native API, Netty (experimental) - Supports transparent fallback options
based on SockJS protocol - New
spring-websocketmodule
Example
public class EchoHandler extends TextWebSocketHandlerAdapter {
@Override
public void handleTextMessage(WebSocketSession session,
TextMessage message) throws Exception {
session.sendMessage(message);
}
}Java config
@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {
@Override
public void registerWebSocketHandlers(
WebSocketHandlerRegistry registry) {
registry.addHandler(new EchoHandler(), "/echo");
}
}HandshakeInterceptor
- Access to HTTP request & response
before and after handshake - Can preclude handshake
- Can pass "handshake" attributes to
WebSocketSession - Example
HttpSessionHandshakeInterceptor
WebSocketHandlerDecorator
- Transparent decoration
ExceptionWebSocketHandlerDecoratorLoggingWebSocketHandlerDecorator- The above applied by default
PerConnectionWebSocketHandler
@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {
// ...
@Bean
public WebSocketHandler snakeHandler() {
Class<?> clazz = SnakeWebSocketHandler.class;
return new PerConnectionWebSocketHandler(clazz);
}
}Note on URL Mapping
- Spring does not use JSR-356 deployment mechanism
- Enables mapping
WebSocketHandlerin Spring MVC - Requires container-specific
RequestUpgradeStrategy - Currently supported are Tomcat, Jetty, Glassfish
- WEBSOCKET_SPEC-211 (exercise vote)
Client-Side API
- Programmatic handshake via
WebSocketClient - Returns
ListenableFuture<WebSocketSession> - Also available is declarative style (can auto-start)
ConnectionManagerSupportand sub-classeses
Example
@Configuration
static class ClientConfig {
@Bean
public WebSocketConnectionManager connectionManager() {
String url = "ws://example.com:8080/echo";
WebSocketHandler handler = new EchoWebSocketHandler();
WebSocketClient client = new StandardWebSocketClient();
WebSocketConnectionManager manager =
new WebSocketConnectionManager(client, handler, url);
manager.setAutoStartup(true);
return manager;
}
}SockJS Support
SockJS in a Nutshell
- Emulate WebSocket API as close as possible
- At least one streaming protocol per major browser
- Cross-domain and cookie support
- Polling in old browsers, hosts behind restrictive proxies
- No Flash inside
SockJS Transports by Browser
Configure SockJS
@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {
@Override
public void registerWebSocketHandlers(
WebSocketHandlerRegistry registry) {
WebSocketHandler echoHandler = new EchoHandler();
registry.addHandler(echoHandler, "/echo").withSockJS();
}
}WebSocketHandler
(remains unchanged)
public class EchoHandler extends TextWebSocketHandlerAdapter {
@Override
public void handleTextMessage(WebSocketSession session,
TextMessage message) throws Exception {
session.sendMessage(message);
}
}SockJS client
var ws = new SockJS("ws://localhost:8080/echo");
ws.onopen = function (event) {
// ...
};
ws.onmessage = function (event) {
// ...
};
ws.onclose = function (event) {
// ...
};
The SockJS Protocol
- Defines URL scheme
- Provided in the form of a readable test suite
- Wide support across languages
The SockJS URL Scheme
GET /echo
GET /echo/info
POST /echo/<server>/<session>/<transport>
Example SockJS Requests
GET /echo/info
POST /echo/375/5rzpg08l/xhr_streaming
POST /echo/375/5rzpg08l/xhr_send
POST /echo/375/5rzpg08l/xhr_send
Runtime Support
- Any Servlet 3.0 container
- Even without WebSocket support!
- No hard dependency on Servlet API
- Experimental Netty support
Client Disconnects
- Servlet 3 containers don't detect clients going away
SockJsServicehowever sends periodic heartbeats- A failure to send a message closes the session
- Check SERVLET_SPEC-44 (vote please)
and also related discussion
Beyond "Hello World"
- WebSocket and SockJS are important foundations
- We haven't discussed usage patterns
- Come to my next session:
"Building WebSocket Browser Apps with Spring"