Wicket Native WebSockets

What ?

Since version 6.0 Wicket provides an experimental module that provides integration with WebSocket support in the web containers like Jetty and Tomcat.

Why ?

Martin Grigorov looked at Typesafe's Console and the support for WebSockets in Play Framework as a whole and I decided that it will be a good addition to WicketStuff HTML5 project. Later Martijn Dashorst suggested that such projects should be added to Apache Wicket as experimental modules and when they become more mature they can be promoted as production ready, or if they are not used/liked then they can be moved to WicketStuff project.

How it works ?

Each of the integrations provide a custom implementation of org.apache.wicket.protocol.http.WicketFilter that first checks whether the current web request needs to upgrade its protocol from HTTP to WebSocket. This is done by checking the request headers for the special header with name "Upgrade". If the request is an upgrade then the filter registers an endpoint for the web socket connection. Later this endpoint is used to read/write messages from/to the client.
All messages sent through the web socket connection are not intercepted by WicketFilter. This is how the web containers currently work.
When a client is connected it is being registered in a global (application scoped) registry using as a key the application, the client session and the id of the page that registered it. Later when the server needs to push a message it uses this registry to filter which clients need to receive the message.
When a message is received from the client Wicket uses the associated page id for the web connection and loads the Wicket Page as Ajax requests do, then it broadcasts a IWebSocketMessage (Wicket 1.5 Event system) to all its components so they can react on it.
The server-side can push plain text and binary messages to the client - pure web socket messages, but can also add components for re-render, prepend/append JavaScript as you do with AjaxRequestTarget.

How to use it ?

Maven dependency

Add dependency to either org.apache.wicket:wicket-native-websocket-jetty9, org.apache.wicket:wicket-native-websocket-jetty, or org.apache.wicket:wicket-native-websocket-tomcat.

Custom WicketFilter

Setup the custom WicketFilter implementation for the chosen web container in your web.xml.

For Jetty 9.0+ this is
<filter-class>org.apache.wicket.protocol.ws.jetty9.Jetty9WebSocketFilter</filter-class>

For Jetty 7.5+ - 8.x this is
<filter-class>org.apache.wicket.protocol.ws.jetty7.Jetty7WebSocketFilter</filter-class>

For Tomcat 7.0.27+:
<filter-class>org.apache.wicket.protocol.ws.tomcat7.Tomcat7WebSocketFilter</filter-class>

WebSocketBehavior

org.apache.wicket.protocol.ws.api.WebSocketBehavior is much like Ajax behaviors that you may know from earlier versions of Wicket.
Add WebSocketBehavior to the page that will use web socket communication:

public class MyPage extends WebPage {

  public MyPage()
  {
    add(new WebSocketBehavior() {
      @Override
      protected void onMessage(WebSocketRequestHandler handler, TextMessage message)
      {
      }
    });
  }
}

Use message.getText() to read the message sent by the client and use the passed handler.push(String) to push a text message to the connected client. Additionally you can use handler.add(Component...) to add Wicket components for re-render, handler#prependJavaScript(CharSequence) and handler#appendJavaScript(CharSequence) as you do with AjaxRequestTarget.

See the demo application at martin-g's GitHub. It is written with Scala and uses Akka which are not available at Maven central repository so it cannot be hosted at Apache Git servers.

Client side APIs

By adding a WebSocketBehavior to your component(s) Wicket will contribute wicket-websocket-jquery.js library which provides some helper functions to write your client side code. There is a default websocket connection per Wicket Page opened for you which you can use like Wicket.WebSocket.send('{msg: "my message"}').

If you need more WebSocket connections then you can do: var ws = new Wicket.WebSocket(); ws.send('message');

To close a connection: Wicket.WebSocket.close() or ws.close().

Wicket.WebSocket is a simple wrapper around the native window.WebSocket API which is used to intercept the calls and to fire special events (Wicket.Event PubSub).

If you don't need to listen for these events then you can just use the native JavaScript API (window.WebSocket).

A demo code can be seen in the Demo Application

Testing

The module provides org.apache.wicket.protocol.ws.util.tester.WebSocketTester which gives you the possibility to emulate sending and receiving messages without the need to run in a real web container, as WicketTester does this for HTTP requests.

Check WebSocketTesterTest for an example.

Differences with Wicket-Atmosphere module.

Wicket-Atmosphere provides integration with Atmosphere and let it handle the inconsistencies in WebSocket protocol support in different browsers and web containers. If either the browser or the web container do not support WebSockets then Atmosphere will downgrade (depending on the configuration) to either long-polling, streaming, server-side events, jsonp, ... to simulate the long running connection.

Wicket Native WebSocket uses only WebSocket connections, so it wont work for browsers and web containers which do not support WebSockets. There are no plans to add such support in future. Use it only if you really know that you will run your application in an environment that supports WebSockets.

Currently supported web containers are Jetty 7.5+ and Tomcat 7.0.27+.
Currently supported browsers are Google Chrome/Chromium, Firefox 11+, Safari 5.x (with Jetty), IE10.

FAQ

Request and session scoped beans do not work.

The Web Socket communication is not processed by Servlet Filters and Listeners and thus the Dependency Injection libraries have no chance to export the request and session beans.