Creating a Chat Application using Java EE 7, Websockets and GlassFish 4

Java EE 7 is out now and so I was curious to play around with the new specifications and APIs from in this technology stack.

That’s why I didn’t hesitate to add yet another websocket-chat tutorial to the existing ones on the internet in favour of gathering some experience with this technology and a possible integration using a GlassFish 4 server, the new Java API for JSON Processing for data serialization combined with custom websocket encoders/decoders and finally adding some Bootstrap and jQuery on the client side.

Figure 1. The final chat application.

Prerequisites

We need the following stuff to build and run the following application:

Creating the new Project

You should simply use the Java EE 7 WebappArchetype here so that your final pom.xml could look similar to this one (shortened):

<properties>
	<endorsed.dir>${project.build.directory}/endorsed</endorsed.dir>
	<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<dependencies>
	<dependency>
		<groupId>javax</groupId>
		<artifactId>javaee-api</artifactId>
		<version>7.0</version>
		<scope>provided</scope>
	</dependency>
</dependencies>

<build>
	<plugins>
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-compiler-plugin</artifactId>
			<version>3.1</version>
			<configuration>
				<source>1.7</source>
				<target>1.7</target>
				<compilerArguments>
					<endorseddirs>${endorsed.dir}</endorseddirs>
				</compilerArguments>
			</configuration>
		</plugin>
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-war-plugin</artifactId>
			<version>2.3</version>
			<configuration>
				<failOnMissingWebXml>false</failOnMissingWebXml>
			</configuration>
		</plugin>
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-dependency-plugin</artifactId>
			<version>2.6</version>
			[..]
		</plugin>
	</plugins>
</build>

Maven Embedded GlassFish Plugin

Adding the following snippet allows us to quickly download and start up a full GlassFish 4 instance with our application deployed by running one simple Maven goal.

Big thanks @resah for pointing out at one issue that got me initially (EMBEDDED_GLASSFISH-142) but is no problem if you’re using the following plugin configuration

<plugin>
	<groupId>org.glassfish.embedded</groupId>
	<artifactId>maven-embedded-glassfish-plugin</artifactId>
	<version>4.0</version>
	<configuration>
		<goalPrefix>embedded-glassfish</goalPrefix>
		<app>${basedir}/target/${project.artifactId}-${project.version}.war</app>
		<autoDelete>true</autoDelete>
		<port>8080</port>
		<name>${project.artifactId}</name>
		<contextRoot>hascode</contextRoot>
	</configuration>
	<executions>
		<execution>
			<goals>
				<goal>deploy</goal>
			</goals>
		</execution>
	</executions>
</plugin>

Afterwards we’re able to startup the application server by running the following command:

mvn embedded-glassfish:run

The Websocket Endpoint

This is our endpoint implementation. Some short facts here about the implementation.

@ServerEndpoint defines a new endpoint – the value specifies the URL path and allows PathParams as we’re used know from JAX-RS.
So value=”/chat/{room}” allows the client to open a websocket connection to an URL like ws://<IP>:<PORT>/<CONTEXT_PATH>/chat/room .. e.g. ws://0.0.0.0:8080/hascode/chat/java
The value in curly braces may be injected as a path parameter in the lifecycle callback methods in the endpoint using javax.websocket.server.PathParam
In addition to the URL schema, we’re specifying an encoder and a decoder class. We need this because we’re using a custom DTO object to pass our chat data between server and client
When a client opens the first connection to the server, he passes the chat-room he wants to enter as a path-parameter and we’re storing this value in the user properties map using session.getUserProperties()..
Now when a chat participant posts a new message over the tcp connection to the server, we’re iterating over all open session, and each session that is assigned to the room the session/message is bound to, receives the decoded and re-encoded message
If we wanted to send a simple text or binary message we could have used session.getBasicRemote().sendBinary() or session.getBasicRemote().sendText()…

package com.hascode.tutorial;

import java.io.IOException;
import java.util.logging.Level;
import java.util.logging.Logger;

import javax.websocket.EncodeException;
import javax.websocket.OnMessage;
import javax.websocket.OnOpen;
import javax.websocket.Session;
import javax.websocket.server.PathParam;
import javax.websocket.server.ServerEndpoint;

@ServerEndpoint(value = "/chat/{room}", encoders = ChatMessageEncoder.class, decoders = ChatMessageDecoder.class)
public class ChatEndpoint {
	private final Logger log = Logger.getLogger(getClass().getName());

	@OnOpen
	public void open(final Session session, @PathParam("room") final String room) {
		log.info("session openend and bound to room: " + room);
		session.getUserProperties().put("room", room);
	}

	@OnMessage
	public void onMessage(final Session session, final ChatMessage chatMessage) {
		String room = (String) session.getUserProperties().get("room");
		try {
			for (Session s : session.getOpenSessions()) {
				if (s.isOpen()
						&& room.equals(s.getUserProperties().get("room"))) {
					s.getBasicRemote().sendObject(chatMessage);
				}
			}
		} catch (IOException | EncodeException e) {
			log.log(Level.WARNING, "onMessage failed", e);
		}
	}
}

ChatMessage Data-Transfer-Object

This is the DTO we’re using to transfer the chat data bidirectional over the TCP connection.

package com.hascode.tutorial;

import java.util.Date;

public class ChatMessage {
	private String message;
	private String sender;
	private Date received;

	// getter, setter, toString omitted..
}

Converting ChatMessages

These are the encoder and the decoder implementations that are referenced in the @ServerEndpoint properties and that allow us to convert incoming or outgoing data between ChatMessages and the JSON format.

Decoder Implementation

The following decoder converts incoming chat message strings to out ChatMessage POJO.

We’re using the new Java API for JSON Processing (JSR353) here to pass data from the JSON format to the ChatMessage.

The willDecode() method allows us to specify if our decoder is able to handle the incoming data .. in our case this is always true ;)

package com.hascode.tutorial;

import java.io.StringReader;
import java.util.Date;

import javax.json.Json;
import javax.json.JsonObject;
import javax.websocket.DecodeException;
import javax.websocket.Decoder;
import javax.websocket.EndpointConfig;

public class ChatMessageDecoder implements Decoder.Text<ChatMessage> {
	@Override
	public void init(final EndpointConfig config) {
	}

	@Override
	public void destroy() {
	}

	@Override
	public ChatMessage decode(final String textMessage) throws DecodeException {
		ChatMessage chatMessage = new ChatMessage();
		JsonObject obj = Json.createReader(new StringReader(textMessage))
				.readObject();
		chatMessage.setMessage(obj.getString("message"));
		chatMessage.setSender(obj.getString("sender"));
		chatMessage.setReceived(new Date());
		return chatMessage;
	}

	@Override
	public boolean willDecode(final String s) {
		return true;
	}
}

Encoder Implementation

This encoder does the opposite – converting a ChatMessage to a JSON string again using the Java API for JSON Processing and its shiny new JSON builder.

package com.hascode.tutorial;

import javax.json.Json;
import javax.websocket.EncodeException;
import javax.websocket.Encoder;
import javax.websocket.EndpointConfig;

public class ChatMessageEncoder implements Encoder.Text<ChatMessage> {
	@Override
	public void init(final EndpointConfig config) {
	}

	@Override
	public void destroy() {
	}

	@Override
	public String encode(final ChatMessage chatMessage) throws EncodeException {
		return Json.createObjectBuilder()
				.add("message", chatMessage.getMessage())
				.add("sender", chatMessage.getSender())
				.add("received", chatMessage.getReceived().toString()).build()
				.toString();
	}
}

Bootstrap, Javascript .. the Client Side of Life…

Finally we’re adding the following index.html to the src/main/webapp directory (shortened, please feel free to have a look a the tutorial sources for the full code)

There are only three interesting API calls that we should remember here – the rest of the javascript adds some functions to the user interface etc …

A websocket URL follows this schema: _ws://IP:PORT/CONTEXT_PATH/ENDPOINT_URL e.g ws://0.0.0.0:8080/hascode/chat/java
A new websocket connection is created using the native WebSocket object e.g. var wsocket = new WebSocket(‘ws://0.0.0.0:8080/hascode/chat/java’);
Registering a callback function to receive incoming messages from the server goes like this: wsocket.onmessage = yourCallbackFunction;
Sending a message to the server is done by wsocket.send() .. pass a string, binary data .. whatever you like ..
Closing a connection is simply done by wsocket.close()
There is a lot of useful information that I did not add to this tutorial from keepalive-pings to the handshake protocol and other features .. one good starting point for detailed information about websockets might be IETF RFC 6455

<!DOCTYPE html>
<html lang="en">
<head>
[..]
<script>
	var wsocket;
	var serviceLocation = "ws://0.0.0.0:8080/hascode/chat/";
	var $nickName;
	var $message;
	var $chatWindow;
	var room = '';

	function onMessageReceived(evt) {
		//var msg = eval('(' + evt.data + ')');
		var msg = JSON.parse(evt.data); // native API
		var $messageLine = $('<tr><td class="received">' + msg.received
				+ '</td><td class="user label label-info">' + msg.sender
				+ '</td><td class="message badge">' + msg.message
				+ '</td></tr>');
		$chatWindow.append($messageLine);
	}
	function sendMessage() {
		var msg = '{"message":"' + $message.val() + '", "sender":"'
				+ $nickName.val() + '", "received":""}';
		wsocket.send(msg);
		$message.val('').focus();
	}

	function connectToChatserver() {
		room = $('#chatroom option:selected').val();
		wsocket = new WebSocket(serviceLocation + room);
		wsocket.onmessage = onMessageReceived;
	}

	function leaveRoom() {
		wsocket.close();
		$chatWindow.empty();
		$('.chat-wrapper').hide();
		$('.chat-signin').show();
		$nickName.focus();
	}

	$(document).ready(function() {
		$nickName = $('#nickname');
		$message = $('#message');
		$chatWindow = $('#response');
		$('.chat-wrapper').hide();
		$nickName.focus();

		$('#enterRoom').click(function(evt) {
			evt.preventDefault();
			connectToChatserver();
			$('.chat-wrapper h2').text('Chat # '+$nickName.val() + "@" + room);
			$('.chat-signin').hide();
			$('.chat-wrapper').show();
			$message.focus();
		});
		$('#do-chat').submit(function(evt) {
			evt.preventDefault();
			sendMessage()
		});

		$('#leave-room').click(function(){
			leaveRoom();
		});
	});
</script>
</head>

<body>

	<div class="container chat-signin">
		<form class="form-signin">
			<h2 class="form-signin-heading">Chat sign in</h2>
			<label for="nickname">Nickname</label> <input type="text"
				class="input-block-level" placeholder="Nickname" id="nickname">
			<div class="btn-group">
				<label for="chatroom">Chatroom</label> <select size="1"
					id="chatroom">
					<option>arduino</option>
					<option>java</option>
					<option>groovy</option>
					<option>scala</option>
				</select>
			</div>
			<button class="btn btn-large btn-primary" type="submit"
				id="enterRoom">Sign in</button>
		</form>
	</div>
	<!-- /container -->

	<div class="container chat-wrapper">
		<form id="do-chat">
			<h2 class="alert alert-success"></h2>
			<table id="response" class="table table-bordered"></table>
			<fieldset>
				<legend>Enter your message..</legend>
				<div class="controls">
					<input type="text" class="input-block-level" placeholder="Your message..." id="message" style="height:60px"/>
					<input type="submit" class="btn btn-large btn-block btn-primary"
						value="Send message" />
					<button class="btn btn-large btn-block" type="button" id="leave-room">Leave
						room</button>
				</div>
			</fieldset>
		</form>
	</div>
</body>
</html>

Build, Deploy, Run…

Now we’re ready to build and deploy our application. If you’re using the embedded-glassfish-plugin your simply need to run

mvn package embedded-glassfish:run

Alternatively upload the application to your GlassFish instance and use hascode as context path (or modify the path in the index.html according to your context path!).

Finally you should be able to load the chat application at the following URL: http://localhost:8080/hascode and it should look similar to this screenshot:

Figure 2. The final chat application.

Screencast

This is our chat in action – I’ve used two browser instances – one Chrome, one Firefox here to simulate two chat participants: Screencast on YouTube.

Tutorial Sources

Please feel free to download the tutorial sources from my GitHub repository, fork it there or clone it using Git:

git clone https://github.com/hascode/javaee7-websocket-chat.git

Direct Download

For those of you who do not want to build the application by themselves, I’ve added the war file as a direct download here:

https://github.com/hascode/javaee7-websocket-chat/downloads/javaee7-websocket-chat-1.0.0.war

Slides

I’ve added the following presentation on my slideshare account:

Creating a Java EE 7 Websocket Chat Application from Micha Kops

Client Implementation in Java

Please feel free to have a look at my article "Creating different Websocket Chat Clients in Java" for a client implementation in Java.

Resources

Websocket Chat Articles

I have written other tutorials about websocket server and client implementations, please feel to read further:

Article Updates

2018-06-01: Embedded YouTube video removed (GDPR/DSGVO).
2016-10-29: Link to Go implementation of websocket chat added.
2014-11-09: Article about websocket client implementation in Java linked.

Prerequisites#

Creating the new Project#

Maven Embedded GlassFish Plugin#

The Websocket Endpoint#

ChatMessage Data-Transfer-Object#

Converting ChatMessages#

Decoder Implementation#

Encoder Implementation#

Bootstrap, Javascript .. the Client Side of Life…#

Build, Deploy, Run…#

Screencast#

Tutorial Sources#

Direct Download#

Slides#

Client Implementation in Java#

Resources#

Websocket Chat Articles#

Article Updates#