A Java Client for a WebSockets API

1. Introduction

HTTP (Hypertext Transfer Protocol) is a stateless request-response protocol. Its simple design makes it very scalable but unsuitable and inefficient for highly interactive real-time web applications because of the amount of overhead that needs to be transmitted along with every request/response.

Since HTTP is synchronous and real-time applications need to be asynchronous, any solutions like polling or long polling (Comet) tend to be complicated and inefficient.

To solve the above-specified problem, we need a standards-based, bi-directional and full-duplex protocol which could be used by both servers and clients, and this led to the introduction of JSR 356 API – in this article, we’ll show an example usage of it.

2. Setup

Let’s include the Spring WebSocket dependencies to our project:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-websocket</artifactId>
    <version>4.3.9.RELEASE</version>
 </dependency>
 <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-messaging</artifactId>
    <version>4.3.9.RELEASE</version>
 </dependency>

We can always get the latest versions of the dependencies from Maven Central for spring-websocket and spring-messaging.

3. STOMP

Stream Text-Oriented Messaging Protocol (STOMP) is a simple, interoperable wire format that allows client and servers to communicate with almost all the message brokers. It is an alternative to AMQP (Advanced Message Queuing Protocol) and JMS (Java Messaging Service).

STOMP defines a protocol for client/server to communicate using messaging semantics. The semantics are on top of the WebSockets and defines frames that are mapped onto WebSockets frames.

Using STOMP gives us the flexibility to develop clients and servers in different programming languages. In this current example, we will use STOMP for messaging between client and server.

4. WebSocket Server

You can read more about building WebSocket servers in this article.

5. WebSocket Client

To communicate with the WebSocket server, the client has to initiate the WebSocket connection by sending an HTTP request to a server with an Upgrade header set properly:

GET ws://websocket.example.com/ HTTP/1.1
Origin: http://example.com
Connection: Upgrade
Host: websocket.example.com
Upgrade: websocket

Please note that the WebSocket URLs use ws and wss schemes, the former one signifies secure WebSockets.

The server responds back by sending the Upgrade header in the response if WebSockets support is enabled.

HTTP/1.1 101 WebSocket Protocol Handshake
Date: Wed, 16 Oct 2013 10:07:34 GMT
Connection: Upgrade
Upgrade: WebSocket

Once this process (also known as WebSocket handshake) is completed, the initial HTTP connection is replaced by WebSocket connection on top of same TCP/IP connection after which either parties can share data.

This client-side connection is initiated by WebSocketStompClient instance.

5.1. The WebSocketStompClient

As described in section 3, we first need to establish a WebSocket connection, and this is done using WebSocketClient class.

The WebSocketClient can be configured using:

• StandardWebSocketClient provided by any JSR-356 implementation like Tyrus
• JettyWebSocketClient provided by Jetty 9+ native WebSocket API
• Any implementation of Spring’s WebSocketClient

We will use StandardWebSocketClient, an implementation of WebSocketClient in our example:

WebSocketClient client = new StandardWebSocketClient();

WebSocketStompClient stompClient = new WebSocketStompClient(client);
stompClient.setMessageConverter(new MappingJackson2MessageConverter());

StompSessionHandler sessionHandler = new MyStompSessionHandler();
stompClient.connect(URL, sessionHandler);

new Scanner(System.in).nextLine(); // Don't close immediately.

By default, WebSocketStompClient supports SimpleMessageConverter. Since we are dealing with JSON messages, we set the message converter to MappingJackson2MessageConverter so as to convert the JSON payload to object.

While connecting to an endpoint, we pass an instance of StompSessionHandler, which handles the events like afterConnected and handleFrame.

If our server has SockJs support, then we can modify the client to use SockJsClient instead of StandardWebSocketClient.

5.2. The StompSessionHandler

We can use a StompSession to subscribe to a WebSocket topic. This can be done by creating an instance of StompSessionHandlerAdapter which in turn implements the StompSessionHandler.

A StompSessionHandler provides lifecycle events for a STOMP session. The events include a callback when the session is established and notifications in case of failures.

As soon as the WebSocket client connects to the endpoint, the StompSessionHandler is notified and the afterConnected() method is called where we use the StompSession to subscribe to the topic:

@Override
public void afterConnected(
  StompSession session, StompHeaders connectedHeaders) {
    session.subscribe("/topic/messages", this);
    session.send("/app/chat", getSampleMessage());
}
@Override
public void handleFrame(StompHeaders headers, Object payload) {
    Message msg = (Message) payload;
    logger.info("Received : " + msg.getText()+ " from : " + msg.getFrom());
}

Make sure that the WebSoket server is running and running the client, the message will be displayed on the console:

INFO o.b.w.client.MyStompSessionHandler - New session established : 53b993eb-7ad6-4470-dd80-c4cfdab7f2ba
INFO o.b.w.client.MyStompSessionHandler - Subscribed to /topic/messages
INFO o.b.w.client.MyStompSessionHandler - Message sent to websocket server
INFO o.b.w.client.MyStompSessionHandler - Received : Howdy!! from : Nicky

6. Conclusion

In this quick tutorial, we have implemented a Spring-based WebSocket client.

The complete implementation could be found over on GitHub.