Getting Started with WebSocket APIs in Java

Friday Sep 4th 2015 by Manoj Debnath

Familiarize yourself with a few necessary background details before rushing into WebSocket implementation in a Web application.

Real-time Web application was realized with circumvention until the advent of WebSocket. The hacks were Polling, Long Polling, and Streaming to achieve a similar effect, but they were beset with great difficulty. WebSocket basically is a protocol that provides full duplex (two-way) communication over TCP connection, standardized by IETF as RFC 6455 in 2011. In Java EE7, JSR 356 provides the necessary APIs to implement it in a client/server application. It is, however, not a replacement of the HTTP request/response model; rather, it compliments the tech with an added advantage of real time support. It leverages existing full duplex communication of HTTP in the context of existing infrastructure. The difference is that, once the connection is established, the server responds without the intervention of the client. The article provides a few necessary background details before rushing into WebSocket implementation in a Web application.

WebSocket in a Nutshell...

WebSocket is a leveraged technology of HTTP protocol, designed to work over HTTP proxies and intermediaries over port 80 (for regular WebSocket connection) and 443 (for WebSocket connections tunneled over Transport Layer Security). Most importantly, if we take an isolated view of only reducing unnecessary header traffic, WebSocket has a significant improvement over a comet solution. Refer to HTML5 Web Sockets: A Quantum Leap in Scalability for the Web for more details. An HTTP header has a huge payload. In a regular client server model, this payload is transmitted each time a communication is established. In a WebSocket client server model, the communication grossly occurs in two parts: once while sending a handshake request and another during data transfer. For example:

  • To establish a WebSocket connection, the client opens a connection and sends an opening handshake request to the server in the form of an HTTP upgraded header (HTTP version 1.1+) along with a bunch of necessary and optional header fields. The client than waits for the response from the server.
  • Upon receiving the handshake request, the server parses the request header to obtain necessary information. This information is used to frame the handshake response in the form of another HTTP header. If the handshake is successful, the server opens the connection to accept incoming data.
  • Because the client had been waiting for the server's response, upon receiving it, it confirms the handshake and a constant connection is established for message transmission.
  • Data transmission occurs by using a sequence of frames. To maintain transmission security, every frame is masked by the client before sending it. The server, upon receiving data, checks whether the frames were masked or not. Any unmasked frame detected by the server results in closing the connection immediately by sending a protocol error frame to the client with status code 1002. The reverse situation occurs when the server is sending a frame to the client. It is unmasked. As a result, when the client discovers a masked frame, it also signals to close the connection to the server.
  • The connection remains open for communication until explicitly closed. During the open phase, the client/server can send/receive messages at will.

Thus, the overhead of sending and receiving an HTTP header at each request/response is reduced to the bare minimum throughout the communication. The HTTP header exchange between the client and server occurs only during the handshake phase. Once the handshake is successful, the server sends another HTTP header to inform the change of protocol to the WebSocket. The connection is now open for data transmission. And, in between, no HTTP header exchange occurs. This has a significant impact on the data transmission throughput, with improved latency in the entire message exchange history in client server communication. This glimpse gives us an idea why WebSocket is suitable for a real-time Web application.

WebSocket URI

There is nothing very significant about the URI format, especially from the programming point of view. If you are familiar with client/server programming, it's simple to understand and is reasonably straightforward. Yet, there is no harm to get a feel of it. The WebSocket URI follows the ABNF (Augmented Backus-Naur Form) syntax pattern (RFC 5234) and is of the form:

  • ws-URI:WebSocket URI connects to port 80 by default

    Figure 1: Standard WebSocket connection

  • wss-URI:Secure WebSocket URI component connects to port 443 by default

    Figure 2: Secure WebSocket connection

WebSocket in Java EE7

The Java API for WebSocket is a part enlisted in EE7 with JSR 356. Any Java EE7 compliant application server will be shipped with WebSocket protocol support. This enables WebSocket integration a de facto feature on both server side as well as a client side Java application. In fact, there is a very little difference between the client and server APIs, though JSR 356 defines a subset of the client API of the full stack WebSocket APIs in EE7. WebSocket is a new and evolving protocol. A lot of improvement willould be seen in coming years. Because every implementation of WebSocket adheres to JSR 356, developers can write WebSocket-based applications independent of any changes made to the underlying socket implementation.

Lifecycle Events

A Socket can be imagined as a two-way pipe connected between nodes (client and server), where one end of the pipe is attached to a HTML5-compliant browser and the other end to a Web server. WebSocket protocol enables continuous flow of communication without any need to reload the new page in the browser to reflect information changes received from the server, similar to that with AJAX. The events for WebSocket communication are as follows.

Figure 3: Establishing communication through a socket

  1. Client initiates connection by sending a HTTP handshake request.
  2. Server sends back HTTP handshake response.
  3. Symmetrical connection established (pipeline established).
  4. Send and receive messages.
  5. Anyone (client or the server) closes the connection.

There are two types of programming models supported by EE7 in implementing WebSocket. These are defined in the following sections.

Annotation Based

Any POJOs can interact with the WebSocket life cycle events using appropriate annotation. There are annotations for every event of the life cycle. Following is a rudimentary code snippet to show how an annotation-based POJO interacts with WebSocket life cycle events.

import javax.websocket.OnClose;
import javax.websocket.OnError;
import javax.websocket.OnMessage;
import javax.websocket.OnOpen;
import javax.websocket.Session;
import javax.websocket.server.ServerEndpoint;

public class MyWebSocketServer {

   public void open(Session session) { }

   public void close(Session session) { }

   public void error(Throwable error) { }

   public void message(String message,
      Session session) { }

Interface Based

Implement an Endpoint abstract class and the POJO is compliant to interact with the cycle events of WebSocket.

import javax.websocket.CloseReason;
import javax.websocket.Endpoint;
import javax.websocket.EndpointConfig;
import javax.websocket.Session;

public class MyWebsocketServer extends Endpoint{

   public void onOpen(Session session,
      EndpointConfig config) {

   public void onClose(Session session,
      CloseReason closeReason){
   public void onError(Session session,
      Throwable thr){


WebSocket is perfectly suitable for applications that require one-to-one pairing between the client and the server along with minimum response latency. Therefore, the class of application WebSocket is perfectly suited where not only real-time response is crucial but also require a dedicated channel for frequent message exchanges. So, it is a waste to establish pairing in every Web application. But, in cases where it is unnecessary to establish a permanent connection yet the client side does not have to reload the page to reflect changes received from server side, AJAX can do the magic.


Mobile Site | Full Site
Copyright 2017 © QuinStreet Inc. All Rights Reserved