WebSocket Overview

Tutorial Description

Files in this tutorial

WebSocket Servlet

WebSocket handshake - starting the connection

To upgrade a HTTP socket to WebSocket, the ServletRequest is cast to a WebSocketServletRequest (implemented by Resin), and then websockets is started with a startWebSocket call.

(The WebSocketServletRequest API is temporary until the next Servlet specification integrates the startWebSocket method directly.)

import com.caucho.servlet.WebSocketServletRequest;
import com.caucho.servlet.WebSocketListener;

...
public class MyServlet extends HttpServlet {

  public void service(HttpServletRequest req, HttpServletResponse res)
    throws IOException, ServletException
  {
    String protocol = req.getHeader("Sec-WebSocket-Protocol");

    WebSocketListener listener;

    if ("my-protocol".equals(protocol)) {
      listener = new MyListener();
      
      res.setHeader("Sec-WebSocket-Protocol", "my-protocol");
    }
    else {
      res.sendError(404);
      return;
    }
    
    WebSocketServletRequest wsReq = (WebSocketServletRequest) req;

    wsReq.startWebSocket(listener);
  }
}

WebSocketContext - sending messages

The WebSocketContext is used to send messages. Applications will need to synchronize on the WebSocketContext when sending messages, because WebSockets is designed for multithreaded applications, and because the WebSocketContext is not thread safe.

A message stream starts with startTextMessage or startBinaryMessage and is then used like a normal PrintWriter or OutputStream. Closing the stream finishes the message. A new message cannot be started until the first message is completed by calling close().

public void sendHello(WebSocketContext webSocket)
  throws IOException
{  
  PrintWriter out = webSocket.startTextMessage();
  out.println("hello");
  out.println("world");
  out.close();
}

WebSocketListener - receiving messages

The WebSocketListener is the heart of the server-side implementation of websockets. It is a single-threaded listener for client events.

When a new packet is available, Resin will call the onRead method, expecting the listener to read data from the client. While the onRead is processing, Resin will not call onRead again until the first one has completed processing.

In this example, the handler reads a WebSocket text packet and sends a response.

The Reader and PrintWriter from the WebSocketContext are not thread safe, so it's important for the server to synchronize writes so packets don't get jumbled up.

package example;

import com.caucho.websocket.WebSocketContext;
import com.caucho.websocket.AbstractWebSocketListener;

public class EchoHandler extends AbstractWebSocketListener
{
  ...

  @Override
  public void onReadText(WebSocketContext context, Reader is)
    throws IOException
  {
    PrintWriter out = context.startTextMessage();

    int ch;

    while ((ch = is.read()) >= 0) {
      out.print((char) ch);
    }

    out.close();
    is.close();
  }
}

WebSocketListener

Resin's WebSocketListener is the primary interface for receiving messages. The listener serializes messages: following messages will be blocked until the callback finishes processing the current one. Since only a single message is read at a time, the listener is single-threaded like a servlet.

The onStart callback is called when the initial handshake completes, letting the server send messages without waiting for a client response.

onClose is called when the peer gracefully closes the connection. In other words, an expected close.

onDisconnect is called when the socket is shut down. So a graceful close will have onClose followed by onDisconnect, while a dropped connection will only have an onDisconnect.

package com.caucho.servlet;

public interface WebSocketListener
{
  public void onStart(WebSocketContext context)
    throws IOException;

  public void onReadBinary(WebSocketContext context, InputStream is)
    throws IOException;

  public void onReadText(WebSocketContext context, Reader is)
    throws IOException;

  public void onClose(WebSocketContext context)
    throws IOException;

  public void onDisconnect(WebSocketContext context)
    throws IOException;

  public void onTimeout(WebSocketContext context)
    throws IOException;
}

WebSocketContext

The WebSocket context gives access to the WebSocket streams, as well as allowing setting of the socket timeout, and closing the connection.

package com.caucho.servlet;

public interface WebSocketContext
{
  public OutputStream startBinaryMessage() throws IOException;

  public PrintWriter startTextMessage() throws IOException;

  public void setTimeout(long timeout);

  public long getTimeout();

  public void close();
  
  public void disconnect();
}

WebSocket JavaScript

Connecting to the WebSocket in JavaScript

<?php
  $url = "ws://localhost:8080/example/websocket";
?>

<script language='javascript'>

function onopen(event) { ... }
function onmessage(event) { ... }
function onclose(event) { ... }

ws = new WebSocket("<?= $url ?>");
wsopen.ws = ws;
ws.onopen = wsopen;
ws.onmessage = wsmessage;
ws.onclose = wsclose;

</script>

Receiving WebSocket data in JavaScript

<script language='javascript'>

function wsmessage(event)
{
  data = event.data;

  alert("Received: [" + data + "]");
}

</script>

Sending WebSocket data in JavaScript

<script language='javascript'>

function wsopen(event)
{
  ws = this.ws;

  ws.send("my-message");
}

ws = new WebSocket(...);
wsopen.ws = ws;
ws.onopen = wsopen;

</script>

Application Protocols

JMTP (JSON Message Transport Protocol)

An example of a general protocol is JMTP (JSON Message Transport Protocol), which defines unidirectional and RPC messages routed to destination services, something like a simpler XMPP or SOA.

The JMTP protocol has 5 messages:

• "message" - unidirectional message
• "message_error" - optional error response for a message
• "query" - request portion of a bidirectional query
• "result" - response for a bidirectional query
• "query_error" - error for a query

Each JMTP message has the following components:

• "to" and "from" address, which looks like a mail address "hello-service@example.com"
• a type "com.foo.HelloMessage"
• a JSON payload "{'value', 15}"

The "to" and "from" allow a service or actor-oriented architecture, where the server routes messages to simple encapsulated services.

The type is used for object-oriented messaging and extensibility. A simple actor/service can implement a subset of messages and a full actor/service can implement more messages. The object-oriented messaging lets a system grow and upgrade as the application requirement evolve.

Each JMTP message is a single WebSocket text message where each component of the message is a separate line, allowing for easy parsing an debugging.

The "message" is a unidirectional message. The receiving end can process it or even ignore it. Although the receiver can return an error message, there is no requirement to do so.

message
to@example.com
from@browser
com.example.HelloMessage
{"value", 15}

The "query" is a request-response request with a numeric query identifier, to allow requests to be matched up with responses. The receiver must return a "response" or a "queryError" with a matching query-id, because the sender will the waiting. Since there's no requirement of ordering, several queries can be processing at the same time.

query
service@example.com
client@browser
com.example.HelloQuery
15
{"search", "greeting"}

The "result" is a response to a query request with the matching numeric query identifier. Since there's no requirement of ordering, several queries can be processing at the same time.

result
client@browser
service@example.com
com.example.HelloResult
15
{"greeting", "hello"}

The "query_error" is an error response to a query request with the matching numeric query identifier. The receiver must always return either a "response" or a "query_error", even if it does not understand the query, because the sender will be waiting for a response.

The "query_error" returns the original "query" request, plus a JSON map with the error information.

query_error
client@browser
service@example.com
com.example.HelloQuery
15
{"greeting", "hello"}
{"group":"internal-server-error","text":"my-error","type":"cancel"}

WebSocket Protocol Overview

Handshake

GET /test HTTP/1.1
Upgrade: WebSocket
Connection: Upgrade
Sec-WebSocket-Extensions: sample-extension
Sec-WebSocket-Origin: http://example.com
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Protocol: my-protocol
Sec-WebSocket-Version: 6
Host: localhost
Content-Length: 0

...

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Server: Resin/1.1
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: my-protocol
Content-Length: 0
Date: Fri, 08 May 1998 09:51:31 GMT

...

WebSocket frames

After the WebSocket connection is established, all messages are encoded in lightweight packets. While the spec defines a text message and a binary message format, browsers use the text packet exclusively. (Resin's HMTP uses the binary packet format.)

Each packet has a small frame header, giving the type and the length, and allowing for fragmentation for large messages.

x84 x0c hello, world

x85 x06 hello!