This blog has published a few blogs on using JSR 356 Reference Implementation (Tyrus) as its integrated in GlassFish 4 promoted builds.

• TOTD #183: Getting Started with WebSocket in GlassFish
• TOTD #184: Logging WebSocket Frames using Chrome Developer Tools, Net-internals and Wireshark
• TOTD #185: Processing Text and Binary (Blob, ArrayBuffer, ArrayBufferView) Payload in WebSocket
• TOTD #186: Custom Text and Binary Payloads using WebSocket
  

One of the typical usecase for WebSocket is online collaborative games. This Tip Of The Day (TOTD) explains a sample that can be used to build such games easily.

The application is a collaborative whiteboard where different shapes can be drawn in multiple colors. The shapes drawn on one browser are automatically drawn on all other peer browsers that are connected to the same endpoint. The shape, color, and coordinates of the image are transfered using a JSON structure. A browser may opt-out of sharing the figures. Alternatively any browser can send a snapshot of their existing whiteboard to all other browsers. Take a look at this video to understand how the application work and the underlying code.



The complete sample code can be downloaded here.

The code behind the application is also explained below.

The web page (index.jsp) has a HTML5 Canvas as shown:

<canvas id="myCanvas" width="150" height="150" style="border:1px solid #000000;"></canvas>

And some radio buttons to choose the color and shape. By default, the shape, color, and coordinates of any figure drawn on the canvas are put in a JSON structure and sent as a message to the WebSocket endpoint. The JSON structure looks like:

{
 "shape": "square",
 "color": "#FF0000",
 "coords": {
 "x": 31.59999942779541,
 "y": 49.91999053955078
 }
} 

The endpoint definition looks like:

@WebSocketEndpoint(value = "websocket",
encoders = {FigureDecoderEncoder.class},
decoders = {FigureDecoderEncoder.class})
public class Whiteboard {

As you can see, the endpoint has decoder and encoder registered that decodes JSON to a Figure (a POJO class) and vice versa respectively. The decode method looks like:

public Figure decode(String string) throws DecodeException {
 try {
 JSONObject jsonObject = new JSONObject(string);
 return new Figure(jsonObject);
 } catch (JSONException ex) {
 throw new DecodeException("Error parsing JSON", ex.getMessage(), ex.fillInStackTrace());
 }
}

And the encode method looks like:

public String encode(Figure figure) throws EncodeException {
 return figure.getJson().toString();
}

FigureDecoderEncoder implements both decoder and encoder functionality but thats purely for convenience. But the recommended design pattern is to keep them in separate classes. In certain cases, you may even need only one of them.

On the client-side, the Canvas is initialized as:

var canvas = document.getElementById("myCanvas");
var context = canvas.getContext("2d");
canvas.addEventListener("click", defineImage, false);

The defineImage method constructs the JSON structure as shown above and sends it to the endpoint using websocket.send().

An instant snapshot of the canvas is sent using binary transfer with WebSocket. The WebSocket is initialized as:

var wsUri = "ws://localhost:8080/whiteboard/websocket";
var websocket = new WebSocket(wsUri);
websocket.binaryType = "arraybuffer";

The important part is to set the binaryType property of WebSocket to arraybuffer. This ensures that any binary transfers using WebSocket are done using ArrayBuffer as the default type seem to be blob. The actual binary data transfer is done using the following:

var image = context.getImageData(0, 0, canvas.width, canvas.height);
var buffer = new ArrayBuffer(image.data.length);
var bytes = new Uint8Array(buffer);
for (var i=0; i<bytes.length; i++) {
 bytes[i] = image.data[i];
}
websocket.send(bytes);

This comprehensive sample shows the following features of JSR 356 API:

• Annotation-driven endpoints
• Send/receive text and binary payload in WebSocket
  
• Encoders/decoders for custom text payload

In addition, it also shows how images can be captured and drawn using HTML5 Canvas in a JSP.

How could this be turned in to an online game ? Imagine drawing a Tic-tac-toe board on the canvas with two players playing and others watching. Then you can build access rights and controls within the application itself. Instead of sending a snapshot of the canvas on demand, a new peer joining the game could be automatically transferred the current state as well. Do you want to build this game ?

I built a similar game a few years ago. Do somebody want to rewrite the game using WebSocket APIs ? :-)

Many thanks to Jitu and Akshay for helping through the WebSocket internals!

Here are some references for you:

• JSR 356: Java API for WebSocket - Specification (Early Draft) and Implementation (already integrated in GlassFish 4 promoted builds)

Subsequent blogs will discuss the following topics (not necessary in that order) ...

• Error handling
• Interface-driven WebSocket endpoint
• Java client API
• Client and Server configuration
• Security
• Subprotocols
• Extensions
  
• Other topics from the API