JavaWebSockets

WebSockets

Using WebSockets instead of Comet sockets

A Comet socket is a kind of hack allowing to send live events to the web browser. Also it supports only one way communication from the server to the client. Top push events to the server the Web browser can make Ajax requests.

Modern Web browser support natively two way live communication via WebSockets.

WebSocket is a web technology providing for bi-directional, full-duplex communications channels, over a single Transmission Control Protocol (TCP) socket. The WebSocket API is being standardized by the W3C, and the WebSocket protocol has been standardized by the IETF as RFC 6455.

WebSocket is designed to be implemented in web browsers and web servers, but it can be used by any client or server application. Because ordinary TCP connections to port numbers other than 80 are frequently blocked by administrators outside of home environments, it can be used as a way to circumvent these restrictions and provide similar functionality with some additional protocol overhead while multiplexing several WebSocket services over a single TCP port. Additionally, it serves a purpose for web applications that require real-time bi-directional communication. Before the implementation of WebSocket, such bi-directional communication was only possible using comet channels; however, a comet is not trivial to implement reliably, and due to the TCP Handshake and HTTP header overhead, it may be inefficient for small messages. The WebSocket protocol aims to solve these problems without compromising security assumptions of the web.

http://en.wikipedia.org/wiki/WebSocket

Handling WebSockets

Until now we were using a simple action methid to handle standard HTTP requests and sending back standard HTTP result. But WebSockets are a totally different beast and can't be handled via standard actions.

So to handle a WebSocket your method must return a WebSocket instead of an Result:

public static WebSocket<String> index() {
  return new WebSocket<String>() {
      
    // Called when the Websocket Handshake is done.
    public void onReady(WebSocket.In<String> in, WebSocket.Out<String> out) {
      
      // For each event received on the socket,
      in.onMessage(new Callback<String>() {
         public void invoke(String event) {
             
           // Log events to the console
           println(event);  
             
         } 
      });
      
      // When the socket is closed.
      in.onClose(new Callback0() {
         public void invoke() {
             
           println("Disconnected")
             
         }
      });
      
      // Send a single 'Hello!' message
      out.write("Hello!");
      
    }
    
  }
}

A WebSocket has access to the request headers (from the HTTP request which initiate the WebSocket connection) allowing you to retrieve standard headers and session data. But it doesn't have access to any request body, nor to the HTTP response.

When the WebSocket is ready you get both in and out channel.

It this example we print each message to console. And we send a single Hello! message.

Tip: You can test websocket on http://websocket.org/echo.html. Just set ws://localhost:9000 as location.

Let's write another example that discard totally the input data and that close the socket just after sending the Hello! message:

public static WebSocket<String> index() {
  return new WebSocket<String>() {
      
    public void onReady(WebSocket.In<String> in, WebSocket.Out<String> out) {
      out.write("Hello!");
      out.close()
    }
    
  }
}

Next: The template engine