Saturday, February 14, 2015

WebSockets with Grizzly on Apache Felix (OSGi)

Since July 2014, I have been in contact with OSGi and Java technologies. With a Microsoft background on my past, this technology is kind a new to me and I'm still settling on this new Java oriented world (jars/bundles, maven, nexus repositories, eclipse and other). Too bad that the receptivity to languages like C# and web technologies like ASP.NET are not very good with this Java Mafia folks that I'm working here at my university.

OSGi technology is a set of specifications that defines a dynamic component system for Java. These specifications reduce software complexity by providing a modular architecture for large-scale distributed systems as well as small, embedded applications.

On a recent project of mine that I'm currently working on, I use Apache Felix. Apache Felix is a community effort to implement the OSGi Framework and Service platform and other interesting OSGi-related technologies under the Apache license.

This project is somewhat related with my MSc Thesis, an envolves among other things realtime communication. The main goal of the system is to acquired realtime data from multiple remote endpoints distributed physically through multiple facilities, these endpoints are also known as remote agents.

The remote agents were designed to be thin clients, therefore and by principle, all the complex logic of this system relies on the central system. The central system is responsible for knowing what information must be gathered from building devices through this remote agents, and to send them instructions informing what they should do.

To accomplish this, some concerns arise:
  • Who starts the connection?
  • What type of connection is required? Is polling enough or are web sockets preferable?
  • Assuming the network middleware to gather data from building devices already exists and is based on an OSGi infrastructure using Apache Felix, how can we extend this existing system?
Since there is a need to acquire realtime data, and all the configuration are sent from the central system to the remote agents. These remote agents must be receptive to establish a connection with an external system. Therefore, the central system starts the connection negotiation. To address the need for realtime data, Web Sockets will be used. 

The objective resides in sending a batch of commands to configure the remote agents for the data that must be gathered. After the configuration procedure, the agent sends data continuously from the building devices to the main server, see Fig. 1.

Fig 1: Central System controls multiple agents to gather realtime
data from multiple buildings.

To solve this problem, I proposed to solve a simpler problem related with this, which consists in implementing an extension to this network middleware, that is able to accept web socket connections. Once established, these web sockets would send from the remote agents to the central system a predefined message ("hello world") every 5 seconds. This simpler solution will then enable us to solve a more complex problem (remember Divide and Conquer).

After researching a bit, I found Project Grizzly. Grizzly’s goal is to help developers to build scalable and robust servers using Java™ NIO API as well as offering extended framework components: Web Framework (HTTP/S), WebSocket, Comet, and more!

From my colleagues experiences, OSGi can be both heaven and hell when not approached properly, so since Grizzly comes with an OSGi HTTP Service implementation (including WebSockets), this seemed a great solution to start with!

Digging some internet tutorials, most outdate and featuring bugs, I came up with an working example which I am glade to be able to share with the community.

First this is a maven project, therefore we need to add Grizzly HTTP Service as a dependency. My pom.xml file is listed bellow:

    <description>Remote Agent</description>

Next we will need to create 2 classes. The HelloWorldApplication Class, responsible for accepting connection requests and determine if a WebSocket should be create or not. The second class is the HelloWorldSocket Class, this class represents the WebSocket and contains the programming logic inherent to the HelloWorldSocket—a program that sends "Hello World" messages every 5 seconds, not very cleaver in my personal opinion, but forms the base for a more complex logic like the one discussed above.

The HelloWorldApplication Class is listed bellow:

package automationmiddleware.plugins.remoteagent;

import org.glassfish.grizzly.http.HttpRequestPacket;
import org.glassfish.grizzly.websockets.ProtocolHandler;
import org.glassfish.grizzly.websockets.WebSocket;
import org.glassfish.grizzly.websockets.WebSocketApplication;
import org.glassfish.grizzly.websockets.WebSocketListener;

 * HelloWorldApplication Class, accepts websocket connections for a given endpoint.
 * @author João Pinho
public class HelloWorldApplication extends
        WebSocketApplication {
    public boolean isApplicationRequest(HttpRequestPacket request) {
        return request.getRequestURI().endsWith("/helloworld");

    public WebSocket createSocket(ProtocolHandler handler,
                                  HttpRequestPacket requestPacket,
                                  WebSocketListener... listeners) {
        return new HelloWorldSocket(handler, requestPacket, listeners);

The HelloWorldSocket Class is also listed bellow:

package automationmiddleware.plugins.remoteagent;

import org.glassfish.grizzly.http.HttpRequestPacket;
import org.glassfish.grizzly.websockets.DataFrame;
import org.glassfish.grizzly.websockets.DefaultWebSocket;
import org.glassfish.grizzly.websockets.ProtocolHandler;
import org.glassfish.grizzly.websockets.WebSocketListener;

 * HelloWorldSocket Class.
 * @author João Pinho
public class HelloWorldSocket extends DefaultWebSocket implements Runnable {
    private static final int TIMEOUT = 5000;

    public HelloWorldSocket(ProtocolHandler protocolHandler,
                            HttpRequestPacket request,
                            WebSocketListener[] listeners) {
        super(protocolHandler, request, listeners);

    private Thread handlerThread;
    private boolean connected = false;

    public void onConnect() {
        handlerThread = new Thread(this);
        connected = true;

    public void run() {
        while (connected) {
            try {
            } catch (Exception e) {
            send("hello world!");

    public void onClose(DataFrame frame) {
        connected = false;

Since our program needs to run within an OSGi bundle (aka, JAR) we need to create an Activator Class. An activator class has two methods a method Start called by Apache Felix to start your bundle and a method Stop, called by Felix when your bundle is stopped.

The Activator Class in the example looks like this:

package automationmiddleware.plugins.remoteagent;


import org.glassfish.grizzly.http.server.HttpServer;
import org.glassfish.grizzly.http.server.NetworkListener;
import org.glassfish.grizzly.websockets.WebSocketAddOn;
import org.glassfish.grizzly.websockets.WebSocketEngine;
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.service.log.LogService;


 * Remote Agent bundle starts a self-hosted web server listening on a predefined
 * port accepting for websocket connections.
 * @author João Pinho
public final class Activator
        implements BundleActivator {

    private static final String HELLOWORLDAPP = "/helloworld";
    private static final String CONTEXT_PATH = "/remoteagent";
    private static final int SERVER_PORT = 9000;
    private static HttpServer server;
    private static HelloWorldApplication helloApp;

    public void start(BundleContext context) throws Exception {
        new Logger().log(LogService.LOG_INFO, "[Remote Agent] started!");

    public void stop(BundleContext context) throws Exception {
        new Logger().log(LogService.LOG_INFO, "[Remote Agent] stopped!");

    private static void runServer() {
        server = HttpServer.createSimpleServer(CONTEXT_PATH, SERVER_PORT);
        final WebSocketAddOn addon = new WebSocketAddOn();
        new Logger().log(LogService.LOG_INFO, "[Remote Agent] server started on port " + SERVER_PORT + ".");

        for (NetworkListener listener : server.getListeners()) {

        helloApp = new HelloWorldApplication();
        WebSocketEngine.getEngine().register(CONTEXT_PATH, HELLOWORLDAPP, helloApp);

        try {
        } catch (IOException e) {

        new Logger().log(LogService.LOG_INFO, "[Remote Agent] server accepting connection to "
                                              + CONTEXT_PATH + HELLOWORLDAPP + ".");

    private static void stopServer() {
        if (server != null) {

After this we need to deploy our code. Unfortunately I faced some problems:
  1. After dropping my bundle (JAR) into Felix "/bundles" folder, I started felix and I got a collision of HTTP ports. For some reason Apache Felix Web Console and Grizzly HTTP Server were both trying to listen on port 9193 (which is configured in the Felix config file "/config/").

    The problem was that Felix Web Console bundle was trying to start Jetty HTTP Server on the port defined in this Felix property org.osgi.service.http.port.

    I was intrigued why Felix Web Console needed Jetty Server in first place, shouldn't it run on some isolated mode? To solve this I when to Maven Central, searched for felix-webconsole latests version and I downloaded its JAR together with its dependencies and put them all in a folder called "webconsole" inside "bundles" directory of Apache Felix.

    This solved it, and I managed to get Felix Web Console working side by side with Grizzly. Don't ask me how did I remember such solution, I think it had something to do with God intervention... Just popped into my head! Further study on this can be found at this StackOverflow answer.
  2. When resolving my bundle, Felix trowed this exception "Unresolved constraint in bundle org.glassfish.grizzly.osgi.grizzly-httpservice-bundle [13]: Unable to resolve 13.0: missing requirement [13.0] osgi.wiring.package; (osgi.wiring.package=sun.misc))".

    The little bastard was "sun.misc", this bundle was preventing grizzly bundle from loading. To solve this you need to change your Felix with this:

After this, my bundle started successfully.

Update: After talking to my colleagues about this, they warn me to the fact that this is just an workaround. Doing this will expose all bundles to this package, which by them selves may dependent on different version of sun.misc, which can cause "General Error" exceptions later on! Most probably when shipping to production, according to Murphy's law. To do it by the book as recommended here, please read my next post!

To test it I did a very simple web page example, the code is listed bellow:

 <script type="text/javascript" src=""></script>
 <script type="text/javascript">
  var wsUri = 'ws://localhost:9000/remoteagent/helloworld';
  websocket = new WebSocket(wsUri);
  websocket.onopen = function(event) {
   if (console)
    console.log('connection oppened.');
  websocket.onclose = function(event) {
   if (console)
    console.log('connection closed.');
  websocket.onerror = function(event) {
   if (console)
    console.log('connection error.');
  websocket.onmessage = function(event) {
   $('#container').append('<div>msg:' + + '</div>');
 <div id="container"></div>

And thats it! If you are trying to replicate this example and you faced some problems, please feel free to contact me. Hope you like this. Stay tuned!