Arjan Tijms - The Definitive Guide to JSF in Java EE 8: Building Web Applications with JavaServer Faces

The JSR- WebSocket specification does not officially support programmatic initialization of the socket end point during runtime. So we cannot initialize it by simply declaring in the view and wait until a JSF page referencing it is being opened for the first time. We really need to initialize it explicitly during deployment time. We could do that by default, but having an unused WebSocket end point open forever is not really nice if its never used by the web application. So we cannot avoid having a context parameter to explicitly initialize it during deployment time.

If you prefer programmatic initialization over declarative initialization, then you can always use ServletContext#setInitParameter() in a ServletContainerInitializer of your web fragment library as follows:

Note that it is not possible to perform this task in a ServletContextListener as JSF will actually register the WebSocket end point in its own ServletContainerInitializer implementation which always runs before any ServletContextListener .

Once the WebSocket end point is enabled and successfully initialized during deployment, it will listen for WebSocket handshake requests on the URL (uniform resource locator) pattern /javax.faces.push/* . The first path element will represent the WebSocket channel name.

Coming back to officially, some WebSocket implementations do, however, support programmatic initialization, such as the one provided by Undertow , which is in turn used in WildFly. Unfortunately, the spec doesnt say so, and there may be WebSocket implementations that simply do not support programmatic initialization, such as Tyrus as used in Payara.

The WebSocket container will, by default, listen for handshake requests on the same port as the application server is listening for HTTP requests. You can optionally change the port with another web.xml context parameter,

or programmatically in a ServletContainerInitializer :

In your JSF page , just declare the tag along with the required channel attribute representing the channel name and the optional onmessage attribute representing a reference to a JavaScript function.

The JavaScript function will be invoked with three arguments.

1. message : the push message as JSON object.

2. channel : the WebSocket channel name. This may be useful in case you intend to have a global listener, or want to manually control the close of the WebSocket.

3. event : the original MessageEvent object. This may be useful in case you intend to inspect it in the JavaScript function.

On the WAR side, you can inject the PushContext via the @Push annotation in any web artifact that supports CDI injection. This can be a simple CDI managed bean, but it can also be a @WebServlet , @WebFilter or @WebListener .

The PushContext variable name test must match the channel name declared in the JSF page. In case you cannot match the variable name with the channel name, you can always specify the channel name in the optional channel attribute of the @Push annotation.

Once the submit() method of the bean shown before is invoked by some JSF command component, even in a different JSF page, the push message Hello World! will be sent to all opened sockets on the very same channel name, application wide.