JSF 2.3 - Explicitly open/close a websocket channel

Before you read this post I recommend you to read:

WebSocket integration by Arjan Tijms

JSF 2.3 - The WebSocket Quickstart under Payara
JSF 2.3 - Conditionally open/close a websocket channel
JSF 2.3 - Firing one-time push when the web socket channel has been opened
JSF 2.3 - Multiple File Upload with HTML 5, AJAX and upload progress bar via web sockets

In this post, you will see how to explicitly open/close a channel. By default, a channel is automatically open when we start the application, but this is not always the desired behavior. As a consequence, first we need to instruct JSF to not open our channel automatically, and for this we set the optional channel attribute to false. This attribute can be a javax.el.ValueExpression that must be evaluated to boolean, and by default it is set to true.

<f:websocket channel="clock" connected="false" onmessage="socketListener" />

This attribute is re-evaluated on every AJAX request, but since we have set it to false, our channel will never be connected. This give us the freedom to open/close the channel explicitly via JavaScript functions:

jsf.push.open("channelName") - explicitly open a channel

jsf.push.close("channelName") - explicitly close a channel

Since these are JavaScript functions they can be invoked exactly as any other JavaScript function. For example, you can invoke them from a snippet of JavaScript, or from the onclick event of a button, as below:

<h:form>   

 <h:commandButton value="Open channel" onclick="jsf.push.open('clock')">

  <f:ajax />

 </h:commandButton>

 <h:commandButton value="Close channel" onclick="jsf.push.close('clock')">

  <f:ajax />

 </h:commandButton>

 <h:commandButton value="Clock" action="#{pushBean.clockAction()}">

  <f:ajax />

 </h:commandButton>

</h:form>

Moreover, we may want to be informed when the channel is open/close. For this, we can attach two special JavaScript listeners, as follows:

<f:websocket channel="clock" connected="false"

             onopen="websocketOpenListener"

             onclose="websocketCloseListener"

             onmessage="socketListener" />   

The optional onopen and onclose attributes are javax.el.ValueExpression that must be evaluated to String. These Strings represents the JavaScript listener functions that are invoked when the web socket is opened/closed. The JavaScript listener corresponding to onopen will receive a single argument represented by the channel name. The JavaScript listener corresponding to onclose will be invoked with three arguments: the close reason code, the channel name and the raw CloseEvent itself. Since this function is invoked on errors also, it is a good practice to have it around. Below, you can see two dummy implementation of our listeners:

function websocketOpenListener(channel) {

 alert("Channel " + channel + " was successfully open!");

}

function websocketCloseListener(code, channel, event) {

 if (code == -1) {

     // Web sockets not supported by client.

     alert("Web sockets not supported by client");

 } else if (code == 1000) {

     // Normal close (as result of expired session or view).

     alert("The channel " + channel + " was successfully closed");

 } else {

     // Abnormal close reason (as result of an error).

     alert("The channel " + channel + " was abnormally closed");

 }

}

Now, the interface will look like in figure below:

Explicitly open the channel

Use the opened channel

Explicitly close the channel

When you run the application, you can notice that the Clock button will not "work" until the channel is opened, and will not "work" after the channel is closed. This means that you are controlling the channel status explicitly via Open channel and Close channel buttons.

The complete application is available here.