"The basic issue is there isn't enough information in an incoming websocket message for the container to know where to route it if there are multiple methods where it may land."
Danny Coward, JSR-356 lead
In response to question on user mailing list
WebSocket Apps
Spring Framework 4 (part 1)
Rossen Stoyanchev
Part 1:
Comprehensive Intro to WebSocket
in Spring Framework 4.0
Part 2:
Building WebSocket Applications
The WebSocket Protocol
- RFC 6455 finalized in Dec-2011
- Two-way communication between browser and server
- Doesn't require multiple HTTP connections
- On the heels of long history
How Did We Get Here?
- 1996 - Java Applets/Netscape 2.0
- 1999/2000 - XMLHttpRequest
- 2003 - Macromedia/Adobe Flash
- 2006 - Comet (term by Alex Russel)
XHR long-polling, XHR streaming,
htmlfile ActiveXObject, Server-Sent Events, etc
How Did We Get Here?
- HTTP async support in Servlet 3.0
CallableandDeferredResult
controller return values in Spring MVC 3.2- Enables HTTP long-polling/streaming
How WebSocket Works
- HTTP used for initial handshake only
- Server responds with 101 "Switching Protocols"
- TCP connection used thereafter
- Exchange text (UTF-8) or binary messages
Practical Considerations
- Not supported in IE < 10
- Proxies may fail the upgrade or close the connection
- It's very low level (thin layer over TCP)
- Messaging architecture
Java WebSocket API
- JSR-356 finalized in May-2013
- Lots of debate, fast-paced schedule
- A convergance of implementations and APIs
complete re-writes across containers - Now better than ever to start using
Relation To the Servlet API
- WebSocket discussions started in Servlet 3.1 (JSR-340)
then moved into its own JSR - Designed to have no dependency on the Servlet API
- In practice it comes down to Servlet containers
- Servlet 3.1 exposes hook for upgrade mechanism
HttpServletRequest.upgrade
Server Availability
- Tomcat 8 (currently RC5) + backport to Tomcat 7.0.47
(existing Tomcat 7 WebSocket support removed) - Jetty 9 all-new, WebSocket API / impl
Jetty 9.1 (currently RC0) adds JSR-356 layer - Glassfish 4 with Tyrus WebSocket engine
- More on the way with Java EE 7
Example
import org.springframework.web.socket.*;
public class MyHandler extends TextWebSocketHandlerAdapter {
@Override
public void handleTextMessage(WebSocketSession session,
TextMessage message) throws Exception {
session.sendMessage(message);
}
}Basic Config
@Configuration
public class WsConfig implements WebSocketConfigurer {
}Basic Config
@Configuration
@EnableWebSocket
public class WsConfig implements WebSocketConfigurer {
}Basic Config
@Configuration
@EnableWebSocket
public class WsConfig implements WebSocketConfigurer {
@Override
public void registerWebSocketHandlers(
WebSocketHandlerRegistry registry) {
registry.addHandler(new MyHandler(), "/echo");
}
}Browser client
var ws = new WebSocket("wss://localhost:8080/myapp/echo");
ws.onopen = function () {
console.log("opened");
};
ws.onmessage = function (event) {
console.log('message: ' + event.data);
};
ws.onclose = function (event) {
console.log('closed:' + event.code);
};HandshakeInterceptor
- Access to HTTP request & response
before and after handshake - Can return
falsefrombeforeHandshake - Can also pass attributes to WebSocketSession
e.g.HttpSessionHandshakeInterceptor
Add Interceptor
@Configuration
@EnableWebSocket
public class WsConfig implements WebSocketConfigurer {
@Override
public void registerWebSocketHandlers(
WebSocketHandlerRegistry registry) {
registry.addHandler(echoHandler(), "/echo");
}
}Add Interceptor
@Configuration
@EnableWebSocket
public class WsConfig implements WebSocketConfigurer {
@Override
public void registerWebSocketHandlers(
WebSocketHandlerRegistry registry) {
registry.addHandler(echoHandler(), "/echo")
.addInterceptors(new MyHandshakeInterceptor());
}
}Per-Session Handler
- A new handler can be created for each new session
- Use
PerConnectionWebSocketHandler
and passWebSocketHandlertype to constructor - Singleton vs stateful handlers
- Instances have DI and lifecycle applied
Configure Per-Session Handler
@Configuration
@EnableWebSocket
public class WsConfig implements WebSocketConfigurer {
@Bean
public WebSocketHandler snakeHandler() {
return new PerConnectionWebSocketHandler(
SnakeWebSocketHandler.class);
}
}Configure Per-Session Handler
@Configuration
@EnableWebSocket
public class WsConfig implements WebSocketConfigurer {
@Bean
public WebSocketHandler snakeHandler() {
return new PerConnectionWebSocketHandler(
SnakeWebSocketHandler.class);
}
@Override
public void registerWebSocketHandlers(
WebSocketHandlerRegistry registry) {
registry.addHandler(snakeHandler(), "/snake");
}
}Deployment Notes
- Config doesn't use JSR-356 deployment mechanism
- HTTP handshakes served by
DispatcherServlet - Requires container-specific
RequestUpgradeStrategy
currently supported are Tomcat, Jetty, Glassfish - See WEBSOCKET_SPEC-211 (and vote!)
SockJS
- Transparent fallback options
- For where WebSocket isn't supported or is precluded
- Emulate WebSocket API as close as possible
- At least one streaming protocol per browser,
polling in old browsers or behind restrictive proxies
SockJS Protocol
- Specified in the form of a (readable) test suite
- Browser JavaScript client provided
- Wide range of server implementations available
- Now also in
spring-websocket
SockJS URL Scheme
GET /echo
GET /echo/info
POST /echo/<server>/<session>/<transport>
SockJsService
- Handles all requests at endpoint URL prefix
for example"/echo/**" - Determine transport to use from the URL
"/echo/{server}/{session}/xhr-polling" - Invoke
TransportHandler - Messages transparently delivered to/from
WebSocketHandler
Configure SockJS
@Configuration
@EnableWebSocket
public class WsConfig implements WebSocketConfigurer {
@Override
public void registerWebSocketHandlers(
WebSocketHandlerRegistry registry) {
registry.addHandler(myHandler(), "/echo");
}
}Configure SockJS
@Configuration
@EnableWebSocket
public class WsConfig implements WebSocketConfigurer {
@Override
public void registerWebSocketHandlers(
WebSocketHandlerRegistry registry) {
registry.addHandler(myHandler(), "/echo").withSockJS();
}
}WebSocket Handler
(same as before)
import org.springframework.web.socket.*;
public class MyHandler extends TextWebSocketHandlerAdapter {
@Override
public void handleTextMessage(WebSocketSession session,
TextMessage message) throws Exception {
session.sendMessage(message);
}
}Server Versions
- Spring's SockJS support will work on
any Servlet 3.0 container - Even where WebSocket not available yet
- Experimental Netty support
Detecting Client Disconnects
- No notification with Servlet 3 async support
when a client does away - See SERVLET_SPEC-44 (and vote!)
- However
SockJsServicesends periodic heartbeats
every 25 secs by default - Session cleaned up on failure to send message
Questions?
WebSocket Apps
Spring Framework 4 (part 2)
Rossen Stoyanchev
Non-Trivial Applications
- WebSocket is quite low level
- Thin layer above TCP
- A stream of messages rather than bytes
- Arguably not an application-level protocol like HTTP
Using a WebSocket API is a bit like
writing a custom Servlet application
Except WebSocket is even lower level
You'll likely have 1 WebSocket handler
for the whole application
Annotations can't help much either...
...not without making assumptions about
what's in a message!
"The subprotocol attribute of the handshake might serve as a useful place to attach this kind of message description/meta data, or some JSR356 specific headers in the handshake. Of course, the other issue is that the other end is often javascript, which would need to participate in some way in such a scheme."
"These are all things we'll likely look at in the next version."
From next reply on same thread
The Sub-protocol Attribute
- WebSocket defines the use of sub-protocols
i.e. higher-level protocols - ...but does not require it
- Either way apps are going to choose a message format
be it custom, standard, or framework-specific - The choice has implications for client and server
Furthermore..
- WebSocket implies a messaging architecture
- Completely different from HTTP/REST--
asynchronous, event-driven, reactive - Closer to traditional messaging (JMS, AMQP, etc)
- Still a web application though
Message Brokers an Option?
- It's possible to connect to RabbitMQ, ActiveMQ,
and others from a browser - Messaging is a hard problem
and brokers have worked on it for a long time - Traditionally used within enterprise
- Not over the web
We Need a Bit of Both Worlds
- Event-driven, messaging achitecture
- Ideally have option to incorporate message broker
- Yet remain close to the needs of web applications
Many Approaches Exist
The Spring Approach
- STOMP over WebSocket
- Ability to plug message broker for message broadcasting
- New
spring-messagingmodule - Core types from Spring Integration
Message,MessageChannel,MessageHandler, etc - Message processing annotations
@MessageMapping,@SubscribeEvent, etc
STOMP
- Simple messaging protocol
originally for use from scripting languages (Ruby, Python) - Widely supported
- Can be used over WebSocket (origingally over TCP)
- Frames modelled on HTTP
STOMP Frame
Client-to-Server Commands
SENDSUBSCRIBEUNSUBSCRIBE
Server-to-Client Commands
MESSAGEERRORRECEIPTACKNACK
"Destination" Header
- Opaque string, syntax left to server
- Typically path-like URIs (
"/queue/a","/topic/a") - Message brokers define semantics
Keep in mind:
A server cannot send unsolicited messages
client must subscribe first
Example
Client Sends Message
Example
Client Subscribes To Receive Messages
Example
Client Receives Message
STOMP over WebSocket
Spring Framework 4.0
- Trivial to configure
- Application becomes STOMP broker to clients
- Subscriptions automatically processed
via "simple" broker by default - Applications can handle messages via annotated methods
Basic Configuration
@Configuration
@EnableWebSocketMessageBroker
public class Config
implements WebSocketMessageBrokerConfigurer {
@Override
public void registerStompEndpoints(StompEndpointRegistry r){
}
@Override
public void configureMessageBroker(MessageBrokerConfigurer c){
}
}Basic Configuration
@Configuration
@EnableWebSocketMessageBroker
public class Config
implements WebSocketMessageBrokerConfigurer {
@Override
public void registerStompEndpoints(StompEndpointRegistry r){
r.addEndpoint("/stomp");
}
@Override
public void configureMessageBroker(MessageBrokerConfigurer c){
}
}Basic Configuration
@Configuration
@EnableWebSocketMessageBroker
public class Config
implements WebSocketMessageBrokerConfigurer{
@Override
public void registerStompEndpoints(StompEndpointRegistry r){
r.addEndpoint("/stomp");
}
@Override
public void configureMessageBroker(MessageBrokerConfigurer c){
c.enableSimpleBroker("/topic/");
}
}Basic Configuration
@Configuration
@EnableWebSocketMessageBroker
public class Config
implements WebSocketMessageBrokerConfigurer{
@Override
public void registerStompEndpoints(StompEndpointRegistry r){
r.addEndpoint("/stomp");
}
@Override
public void configureMessageBroker(MessageBrokerConfigurer c){
c.enableSimpleBroker("/topic/");
c.setApplicationDestinationPrefixes("/app");
}
}
Handle a Message
@Controller
public class GreetingController {
@MessageMapping("/greetings")
public void handle(String greeting) {
// ...
}
}@MessageMapping
- Supported on type- and method-level
- Ant-style patterns with URI variables
and@PathVariablearguments - Various methods arguments
@Header/@Headers,@Payload,Message,Principal
@MessageMapping
Return Values
- Return value converted and wrapped as message
- Broadcast by default to same destination but
with a default, configurable prefix"/topic" - Or choose precise destination(s) with
@SendTo
Send via Return Value
@Controller
public class GreetingController {
@MessageMapping("/greetings")
public String greet(String greeting) {
return "[" + getTimestamp() + "]: " + greeting;
}
}Send via Return Value
@Controller
public class GreetingController {
// A message is broadcast to "/topic/greetings"
@MessageMapping("/greetings")
public String greet(String greeting) {
return "[" + getTimestamp() + "]: " + greeting;
}
}Send to Different Destination
with @SendTo
@Controller
public class GreetingController {
@MessageMapping("/greetings")
@SendTo("/topic/wishes")
public String greet(String greeting) {
return "[" + getTimestamp() + "]: " + greeting;
}
}Send via SimpMessagingTemplate
@Controller
public class GreetingController {
@Autowired
private SimpMessagingTemplate template;
@RequestMapping(value="/greetings", method=POST)
public void greet(String greeting) {
String text = "[" + getTimeStamp() + "]:" + greeting;
this.template.convertAndSend("/topic/wishes", text);
}
}Handle Subscription
(Request-Reply Pattern)
@Controller
public class PortfolioController {
@SubscribeEvent("/positions")
public List<Position> getPositions(Principal p) {
Portfolio portfolio = ...
return portfolio.getPositions();
}
}Plug in Message Broker
- "Simple" broker great for getting started
- Supports only subset of STOMP (no acks, receipts)
- Relies on simple message sending loop
- Not suitable for clustering
Enable "Broker Relay"
@Configuration
@EnableWebSocketMessageBroker
public class Config
implements WebSocketMessageBrokerConfigurer{
@Override
public void configureMessageBroker(MessageBrokerConfigurer c){
}
}Enable "Broker Relay"
@Configuration
@EnableWebSocketMessageBroker
public class Config
implements WebSocketMessageBrokerConfigurer{
@Override
public void configureMessageBroker(MessageBrokerConfigurer c){
c.enableStompBrokerRelay("/queue/", "/topic/");
}
}Enable "Broker Relay"
@Configuration
@EnableWebSocketMessageBroker
public class Config
implements WebSocketMessageBrokerConfigurer{
@Override
public void configureMessageBroker(MessageBrokerConfigurer c){
c.enableStompBrokerRelay("/queue/", "/topic/");
c.setApplicationDestinationPrefixes("/app");
}
}
Authentication
- STOMP
CONNECTframe has authentication headers - Over WebSocket we can use HTTP
- Protect application as usual, e.g. Spring Security
- All messages enriched with "user" header
Destination "/user/**"
- Spring-supported destination
- Create uniquely named, user-specific queues
- Useful for receiving errors or any user-specific info
(trade confirmation, etc)
UserDestinationHandler
- Transforms
"/user/..."destinations - Removes prefix, appends unique id and resends message
- Client subscribes to
"/user/queue/abc"(without collision) - Can then send to
"/user/{username}/queue/abc"
Client Subscribes
To "/user/queue/..."
var socket = new SockJS('/myapp/portfolio');
var client = Stomp.over(socket);
client.connect('', '', function(frame) {
client.subscribe("/user/queue/trade-confirm",function(msg){
// ...
});
client.subscribe("/user/queue/errors",function(msg){
// ...
});
}Send Reply To User
@Controller
public class GreetingController {
@MessageMapping("/greetings")
public String greet(String greeting) {
return "[" + getTimestamp() + "]: " + greeting;
}
}Send Reply To User
@Controller
public class GreetingController {
@MessageMapping("/greetings")
@SendToUser
public String greet(String greeting) {
return "[" + getTimestamp() + "]: " + greeting;
}
}Send Reply To User
@Controller
public class GreetingController {
// Message sent to "/user/{username}/queue/greetings"
@MessageMapping("/greetings")
@SendToUser
public String greet(String greeting) {
return "[" + getTimestamp() + "]: " + greeting;
}
}Send Error To User
@Controller
public class GreetingController {
@MessageExceptionHandler
@SendToUser("/queue/errors")
public String handleException(IllegalStateException ex) {
return ex.getMessage();
}
}Send Message To User
via SimpMessagingTemplate
@Service
public class TradeService {
@Autowired
private SimpMessagingTemplate template;
public void executeTrade(Trade trade) {
String user = trade.getUser();
String dest = "/queue/trade-confirm";
TradeResult result = ...
this.template.convertAndSendToUser(user, dest, result);
}
}
Managing Inactive Queues
(with Full-Featured Broker)
- Check broker documentation
- For example RabbitMQ creates auto-delete queue
with destinations like"/exchange/amq.direct/a" - ActiveMQ has config options to purge inactive destinations