WebSockets - Errai

ErraiBus has support for WebSocket-based communication. When WebSockets are enabled, capable web browsers will attempt to upgrade their COMET-based communication with the server-side bus to use a WebSocket channel.

There are two different ways the bus can enable WebSockets. The first uses a sideband server, which is a small, lightweight server which runs on a different port from the application server. The second is native JBoss AS 7-based integration.

Configuring the sideband server

Activating the sideband server is as simple as adding the following to the ErraiService.properties file:

errai.bus.enable_web_socket_server=true

The default port for the sideband server is 8085. You can change this by specifying a port with the errai.bus.web_socket_port property in the ErraiService.properties file.

Deploying with JBoss AS 7

It is currently necessary use the native connector in JBoss AS for WebSockets to work. So the first step is to configure your JBoss AS instance to use the native connector by changing the domain/configuration/domain.xml file, and change the line:

<subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="false">

to:

<subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="true">

You will then need to configure the servlet in your application's web.xml which will provide WebSocket upgrade support within AS7.

Add the following to the web.xml:

<context-param>
  <param-name>websockets-enabled</param-name>
  <param-value>true</param-value>
</context-param>

<context-param>
  <param-name>websocket-path-element</param-name>
  <param-value>in.erraiBusWS</param-value>
</context-param>

This will tell the bus to enable web sockets support. The websocket-path-element specified the path element within a URL which the client bus should request in order to negotiate a websocket connection. For instance, specifying in.erraiBusWS as we have in the snippit above, will result in attempted negotiation at http://<your_server>:<your_port>/<context_path>/in.erraiBusWS. For this to have any meaningful result, we must add a servlet mapping that will match this pattern:

<servlet>
  <servlet-name>ErraiWSServlet</servlet-name>
  <servlet-class>org.jboss.errai.bus.server.servlet.JBossAS7WebSocketServlet</servlet-class>
  <init-param>
    <param-name>service-locator</param-name>
    <param-value>org.jboss.errai.cdi.server.CDIServiceLocator</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
  <servlet-name>ErraiWSServlet</servlet-name>
  <url-pattern>*.erraiBusWS</url-pattern>
</servlet-mapping>

Do not remove the regular ErraiBus servlet mappings!

When configuring ErraiBus to use WebSockets on JBoss AS, you do not remove the existing servlet mappings for the bus. The WebSocket servlet is in addition to your current bus servlet. This is because ErraiBus always negotiates WebSocket sessions over the COMET channel.