There has been a lot of discussion lately about WebSockets. WebSocket client API is part of HTML 5.
WebSocket wire protocol that handles the low-level handshaking, framing, and negotiation was just
released in 2012. WebSocket has been a multi year work in progress that just completed.

At this point (March 2012), only Chrome and FireFox support the official WebSocket wire protocol.
Safari supports it in the nightly build so it will likely be supported in the next version of
Safari, and Internet Explorer will support it in Explorer 10. JSR 356 was recently formed to
define a standard API for creating WebSocket applications. Also even if you have both a client
that works with WebSocket and a server which can handle WebSockets, you still need to be able
to work through firewalls. Most modern firewall software handles WebSockets, but not all. The
most reliable way to handle WebSockets is through a TLS connection (sometimes incorrectly known
as SSL).

You can use WebSocket from a browser like you can Ajax/REST. But when should use WebSockets and when
should you use Ajax/REST? Also, can you use WebSocket from other clients?

This tutorial is going to try to answer these questions. Its aim is to be a
compare, contrast and learn tutorial. In order to convey the information enough code is added to make
this tutorial go beyond the pointy hair boss description. To do this, we slowly build a chat client and server.

Let's do a quick code comparison of the JavaScript and Java involved in doing Ajax and WebSockets
to start off the discussion. To developers sometimes code examples are very demystifying.

This tutorial covers both the JavaScript client side and Java server side so it is complete.

The first part of this tutorial, we build a simple chat prototype. In the second part of this tutorial,
we build a scalable chat room which could handle thousands of users.

Now typically, you don't use XMLHttpRequest directly, instead you use jQuery or Prototype or
any number of other JavaScript frameworks. But to ease the explanation, and to aid in comparison
to WebSocket, let's start with raw JavaScript (later tutorials will use raw JavaScript, and
jQuery).

Quick Review of Ajax: sendChatMessageAjax (2) is JavaScript function that uses an
instance of XMLHttpRequest called ajax (1) to send an HTTP POST request
back to the server. Since this is JavaScript, and you don't want to block the user and JavaScript
does not support threads, then you must register a callback called
handleChatMessageAjaxResponse with the
ajax.onreadystatechange (XMLHttpRequest) (3).

Servlet that handles Ajax call

Now let's cover the Java side of the house. Again, there are many Java frameworks that add layers
between the Java backend and the HTML/JavaScript rendering to handle Ajax nicely. But for this
discussion, let's start with the simplest thing that will work, and in Java that is a Java
HttpServlet as follows:

This is fairly basic. Read the data (1), convert data into a String (2), send the data back to the
browser with "Hello from Server-side Ajax : " prepended to to it (3).

WebSocket simple example client and server

Now lets compare the above client and server to a WebSocket equivalent. Efforts are made to keep
this JavaScript really simple and easy to understand so it is easy to compare against the previous
Ajax example.

The following code listing is a simple JavaScript Ajax, HTML 5 example that sends a
"Hello WebSocket World?" message to our server.

Quick Run down of the WebSocket code: sendChatMessageWebSocket (2) is JavaScript
function that uses an instance of WebSocket called socket (1) to
start a WebSocket connection (HTTP upgrade) with the server. Since this is JavaScript, and you don't
want to block the user and JavaScript does not support threads, then you must register a callback
called handleChatMessageWebSocketResponse with the
socket.onmessage (WebSocket) (3).

Ok so they look very similar. Again, I am going to start with the similarities.
The differences are to come.

This is fairly basic. Read the data (1), convert data into a String (2), send the data back to the
browser with "Hello from Server-side Ajax : " prepended to it (3).

At this point, these are nearly identical. You can use WebSockets similar to how you should use
Ajax. No real learning curve for simple cases.

Some noticeable differences between WebSockets, and Ajax examples

The first difference between this and the Servlet version is that we are using a
WebSocketListener. The WebSocketListener is a Resin class as Java EE 6
does not have WebSocket support. Java EE 6 predates Websocket. The WebSocketListener
looks fairly similar to the Servlet API as much as possible by design.

Note that the current plan for Java EE 7 is to include WebSocket support.
Caucho Technology is and has been involved in several Java EE JSRs, and was heavily involved in the
IETF WebSocket draft.

From a programming perspective, so far, there is no real difference between the WebSocket version
and the Ajax/Servlet version. There is a little bit of handshaking that the Servlet has to do which
we will cover later, but essentially if this is all you wanted, then WebSocket looks a lot like
Ajax. Now since we are developing a chat example, eventually we will want to push messages from other
people who are in the chat session. This is where WebSockets is going to shine.

What is WebSockets again?

From a web developers viewpoint, WebSocket is a new browser feature for HTML 5 browsers.
This new feature enables richer user interactions. Both the browser and the server can send
asynchronous messages over a single TCP socket, without doing less scalable hacks like long polling
or comet.

The communication starts out like HTTP and then upgrades after a
HTTP handshake to bidirectional WebSockets. A WebSocket is a bidirectional message stream
between the client and the server.

While all modern browsers support some version of WebSocket as of March 2012 few application servers and web servers do.
In order for browsers to take advantage of WebSockets, you need to have an application server or web
server that can handle WebSockets.

There are several Java WebSocket implementations out in the wild. Resin WebSocket support is the most
mature and gets used by more high traffic sites. If you are not familiar with Resin Server, it is a scalable,
fast, mature Java EE certified application/web server. Its speed is faster than NginX and Apache HTTPD,
and it is more scalable.

All of Resin's cloud/clustering communication works on top of WebSocket.
Resin's WebSocket support predates most implementations. If you are serious about WebSockets
and Java, then Resin Server is an obvious contender. Also you can try out the Open Source version
for free.

Many Java WebSocket implementations do not allow stream access to WebSocket (Reader,
Writer, InputStream, OutputStream), and instead rely on
simple buffer constructs like String and byte[] or dump you
down into working directly with low level WebSocket frames (Frame API). Since WebSocket is a streaming,
framing wire protocol, naturally Resin Server supports streams. It is easy to for Java developers to
go from streams to byte[] and String as shown in the above examples.
Using byte[] and String are probably ok for some department level or
company level applications, but if for anything else you really need to use streams to maximize the
throughput and minimize contention.

Regarding a Frame oriented API, when you program with TCP/IP you never have an application developer
API that exposes TCP/IP packets bit mask fields, in the same way the WebSocket Frame is the wrong
level of abstraction for most developers. Resin's API is the right level of abstraction, i.e., streams like the Servlet API.
That said, we are always looking for feedback.

Now that we have the background in the why of the API, let's discuss how the streaming works.

WebSocket Streaming, Frames and Messaging

WebSocket is unlike Ajax/HTTP in that the WebSocket connection stays open and it is bidirectional.
This is perfect for a chat application or a near real time stock price app, etc.

WebSockets have two types of messages, binary (byte[]), and text (String). If your message is bigger
than a single Frame then it gets sent as chunks in multiple frames. For the sake of argument let's
say that a frame holds 1K bytes. If you are sending a JSON payload to the browser that is 4K then
you are sending 4 Frames. (Actual framing varies, this are example sizes for discussion.)

To begin a message you need to send a stream of WebSocket frames. To start the message you call
context.startTextMessage() (NEW 4). If your message does not fit into one frame,
then a another frame is created and marked that it continues the previous frame in the series using a
"continues" flag. In WebSockets the final frame in a message is marked with a "finished" flag.
This final frame is sent when you call close on the stream. This final frame says that you are done
sending the current binary or text message. The out.close (5) is your way to tell Resin's
WebSocket implementation that the message is done so go ahead and mark the current frame as finished
and then send that as the last frame. On the client end of the wire, WebSockets client implementation
will see that the it got the last frame. The JavaScript WebSocket client will only call
socket.onmessage (WebSocket) after it receives the Frame marked final. HTML 5 has the
luxury of handling whole message at a time because efficiency is not a concern for scalability like
it is on the server-side of the house.

Get all of that? That is ok if you don't. Just remember to call close, and then Resin WebSockets will
complete sending the message just like you would write output to a Servlet or write to a file.
WebSocket frames are a nice fit with the Java IO Stream and Reader/Writer APIs.

Again the JavaScript API for WebSocket only deals with buffers like String and
byte[] (these are String and ArrayBuffer or Blob in JavaScript speak). WebSocket is
a generally purpose framing/wire protocol so expect a lot of other uses outside of HTML 5.
Many other protocols spend a lot of time and effort
creating a framing protocol (AMQP, IIOP, RMI-JRMP, etc.). If you are developing a new protocol that
needs framing, you can just build your new protocol on top of WebSocket. Consider framing solved.

WebSockets are extensible, and you could build other protocol on top of it. You could for example
build a version of IIOP on top of WebSockets. Expect extensions for flow control, multiplexing,
and compression.

Protocol negotiation

HTTP upgrade was added to the HTTP specification to support changing to new versions of HTTP more flawlessly.

To use WebSockets which is a different wire protocol then HTTP, the client must do an HTTP upgrade, and
tell the server that it supports WebSockets. The Browser HTML 5 client sends a special HTTP GET that has
special headers. If the server supports WebSocket it sends an acknowledgement and then the conversation begins.

To register our ChatWebSocketListener you have to create a Servlet that handles this special
request as follows:

The above checks the subprotocol that the HTML 5 browser client expects via the Sec-WebSocket-Protocol
HTTP header (1). Then it creates and instance of the ChatWebSocketListener that we
covered earlier (2) and registers that with the WebSocketServletRequest (4) via the
startWebSocket method.

The client, HTML 5 Browser client, can request that the server use a specific subprotocol by including the
Sec-WebSocket-Protocol field in its handshake. The server responds with a comma delimited list of
of subprotocols. A subprotocol is basically the version of the wire format. It is an indication
of what kinds of marshaling you are doing. Let's say you worked at Caucho Technology Inc. Your
subprotocol could be called "chat.example.com". Subprotocols can be versioned in, e.g., "chat.example.com"
versus "v2.chat.example.com" are two different subprotocols.

The HTTP header handshake from the browser could look something like this:

Details about WebSocketContext and WebSocketListener

The WebSocketListener is the main area of focus for the server-side implementation.
It is similar in concept to a Java Servlet at first blush.
Unlike a Servlet, a WebSocketListener is a single-threaded handler for events and messages from the client.

The onReadText of WebSocketListener method will only get called by one thread
at a time whilst a HttpServlet.doGet method can be called by many threads.

The Reader, PrintWriter and WebSocketContext are not thread
safe and should only be accessed by one thread at a time. It is important that you only access
these from one thread at a time. This is similar to the normal Servlet programming as it also works with streams and reader/writers
which can only be accessed by one thread at a time.

The onReadText should not do anything that is going to block if you are trying to write
a scalable application. Blocking might be okay for department level or company level application.
For applications that support higher traffic and need higher throughput blocking on an
onReadText is not ok. Higher scaling application would need to use some sort of
queuing mechanisms, we will cover this in a later tutorial.

The big take away that I want you to get from this discussion is this: although the programming model
may look the same from Ajax/Servlet to WebSocket, it is very different. Ajax/REST is request/response.
WebSocket is messaging.

With WebSocket the connection stays open. It is expected that the server is calling the client at will.
It is common in WebSockets for the reading and writing to happen in different threads.

As was mentioned earlier, we are going to cover building a full HTML 5 chat client, but to whet your appetite
without going into crazy complexity, let's change the last example from a traditional Request/Response
to a full blown bidirectional connection. The HTML 5 client is sending messages on one end, while
the server is at the same time sending messages to the HTML 5 client.

In this example, we ask the server for a thread to fire off a chat message sender. The message sender
gets messages from a queue. It echoes the messages back. If it does not hear from the client in five
seconds, it starts nagging it with a "Are you there?" message. To do this, you do the following.

(THE EXAMPLE BELOW IS UNDER REVIEW BY PEERS. It may change.)

You change the client to connect as soon as the page loads as follows (full code listings will be at end of tutorial):

You are going to handle the WebSocketListener.onStart method to start up this new
message deliverer. WebSocketListener.onStart needs to schedule a task with the servers executor
(java.util.concurrent.Executor). The task will listen for items that the onReadText
puts on the queue.

Then change the WebSocketListener to create a BlockingQueue (1)
and @Inject a ThreadPoolExecutor (2).

Notice that the onReadText no longer handles the writing of message directly. Instead
it adds the text message to the queue (3).

The onStart method gets called as soon as WebSocket connection is established and ready
to receive messages (from either side). Change the onStart method to create the queue, then
execute a task (4) with the executor that handles the echoing of messages and the sending of our
nagging reminders.

The task (anonymous inner class instance of Runnable) checks to see if the connection
has been closed in a forever loop (6). The close flag is a volatile boolean
that is set by the ChatWebSocketListener.onDisconnect
which gets called when the connection is shut down. Each iteration of the loop, the task checks
to see if there are any more messages on the queue (7). If there is a message, then it echoes that message
back using the (context) WebSocketContext (8). Just to proove that we can send messages
without getting told to by the client, every five seconds we send "I have not heard from you in a while ",
"Are you stil there?", and "WAKE UP!!!!!!!!".

IMPORTANT: Note that only the runnable task's thread accesses the WebSocketContext.
Only one thread at a time can access a WebSocketContext so also note that the onReadText no longer accesses
the WebSocketContext like it did in the first example. WebSocketContext is not thread safe.
This is why only one thread can access it. In the first example the onReadText accessed it directly.
If it still did that, then this would be broke and we would have thread synchronization issues. If
the thread that was running onReadText and the thread that is running this task both wrote at
the same time, given the streaming nature of WebSockets and the need to sends frames in sequences,
bad things could happen.

Ok, we have introduced enough new concepts for WebSockets. I hope you can see the value in it, and understand
some key differences between Ajax and WebSockets as well as some clear similarities. Going through
the process of writing these tutorials has given us some insight into how to make the WebSocket API more
complete. We plan on updating these tutorials as we improve the API. In addition, the next installment
in this series is going to cover building a multi user chat system so stay tuned.

WebSocket Handler for Chat example prototype

Notice we subclass AbstractWebSocketListener instead of implement WebSocketListener.
The AbstractWebSocketListener implements WebSocketListener so you can ignore the
callback handler that you do not care about.