Define Websocket Server Endpoints using Liferay Websocket Whiteboard

JSR 356 is the Java API for Websocket. It defines the standard way to create Websocket client and server endpoits in Java. In this blog we are going to describe how you can register websocket server endpoints in a OSGi container using Liferay Websocket Whiteboard. 

What is Liferay Websocket Whiteboard?

The Liferay Websocket Whiteboard is a simple module which allows you to define new Websocket server endpoints as regular OSGi services.

How do you register a Websocket server endpoint with Liferay Websocket Whiteboard?

Include dependencies

First of all you will need to add the Liferay Websocket Whiteboard dependency to your project.

For now we have not published the dependencies in our nexus, so you need to create the needed jars from the source code (run gradle install in the websocket folder).

In the near future, once we publish the artifacts to our public Nexus repo, you will just need to add the dependencies in your build file, as shown below:

com.liferay:com.liferay.websocket.whiteboard:1.0.0
com.liferay:com.liferay.websocket.whiteboard.spifly.fragment:1.0.0

Configure your Liferay OSGi Container

Configure your NonLiferay OSGi Container

If you are going to register your server endpoint in a standalone OSGi Container, you will need to register a javax.servlet.ServletContext service with the property websocket.active set to true.

Here you can see an example of how to register a ServletContext service with the property websocket.active set to TRUE:

Dictionary<String, Object> servletContextProps = new Hashtable<String, Object>();
servletContextProps.put("websocket.active", Boolean.TRUE);

bundleContext.registerService(ServletContext.class, servletContext, servletContextProps);

Define server endpoints

Now your are ready to create your first Websocket server endpoint. For now we don't support the Annotation-Driven Approach version, only the Interface-Driven Approach is supported.

If you want to  create a websocket Server endpoint you only need to register a OSGi Service for javax.websocket.Endpoint.class with the following properties:

org.osgi.htto.websocket.endpoint.path: required, the path for the websocket.

Here you can see an example of how to register a server Endpoint service using Declarative Services:

@Component(
    immediate = true,
    property = {"org.osgi.http.websocket.endpoint.path=/echo"},
    service = Endpoint.class
)
public class EchoWebSocketEndpoint extends Endpoint {
    @Override
    public void onOpen(final Session session, EndpointConfig endpointConfig) {
        session.addMessageHandler(
            new MessageHandler.Whole<String>() {
                @Override
                public void onMessage(String text) {
                    try {
                        RemoteEndpoint.Basic remoteEndpoint =
                            session.getBasicRemote();
                        remoteEndpoint.sendText(text);
                    }
                    catch (IOException ioe) {
                        throw new RuntimeException(ioe);
                    }
                }
            });
    }
}

See also

JSR 356

Websocket server endpoints