Connection Management

Connection Management

ICEfaces provides the following advanced connection management features:

Asynchronous Heartbeating
Managing Connection Status
Managing Redirection

Asynchronous Heartbeating

When configured for asynchronous communications mode (default), ICEfaces employs an asynchronous connection management scheme to provide robust asynchronous communications capability. Asynchronous connection management provides the following key capabilities:

Asynchronous connection health monitoring via a configurable heartbeat mechanism. The asynchronous heartbeat mechanism monitors the health of the Asynchronous connection and also prevents network infrastucture from terminating an otherwise idle connection, possibly resulting in lost or delayed asynchronous updates to the browser.
Transparent asynchronous connection recovery. In the event that an asynchronous connection is lost, the ICEfaces bridge will automatically attempt to recover the connection in a manner transparent to the application.

Note: When debugging, heartbeating can be toggled on and off from the client browser using the following keyboard sequence: CTR+SHIFT+. (that is, press the Control and Shift keys and then type a period (".")).

ICEfaces can optionally be used in a standard synchronous connection mode that does not require monitoring and maintaining continuous connections to the server. Instead, it creates a connection for each user-initiated request, just as with any non-ICEfaces web-application. For details, see Asynchronous vs. Synchronous Updates.

Asynchronous heartbeat is configured in the application web.xml file using the context parameters in the code examples below, where heartbeatInterval defines the time in milliseconds between heartbeat messages. The default value is 50000 (50 seconds).
<context-param>
 
		<param-name>com.icesoft.faces.heartbeatInterval</param-name>
 
		<param-value>50000</param-value>
 
</context-param>
 

 
In the following code example, heartbeatTimeout defines how long, in milliseconds, that the heartbeat monitor will wait for a response prior to timing out. If a heartbeat times out, the connection will be placed in a "caution" state while the bridge attempts to recover the connection. The default value is 30000 (30 seconds).
<context-param>
 
		<param-name>com.icesoft.faces.heartbeatTimeout</param-name>
 
		<param-value>30000</param-value>
 
</context-param>
 

 
The following code example defines heartbeatRetries, which specifies the number of consecutive timed-out heartbeats allowed before the connection is considered failed and reported to the user as "disconnected" . The default value is 3.
<context-param>
 
		<param-name>com.icesoft.faces.heartbeatRetries</param-name>
 
		<param-value>3</param-value>
 
</context-param>
 

 
The blockingConnectionTimeout parameter specifies how long, in milliseconds, an idle asynchronous blocking connection should be held open before being released for a new blocking connection. Normally, the blocking connection is closed and re-opened with every communication to the browser, such as user interaction or a heartbeat ping. The purpose of this setting is to remove the possibility of threads being held blocked for a long duration on a "dead" or completely inactive client connection (for example, if contact with the browser is lost). This value should be longer than the heartbeat interval to avoid unnecessary network traffic (unblocking and blocking without any updates available). The default value is 90000 (90 seconds).
<context-param>
 
		<param-name>com.icesoft.faces.blockingConnectionTimeout</param-name>
 
		<param-value>90000</param-value>
 
</context-param>
 

 
The connectionTimeout parameter defines how long, in milliseconds, that the bridge will wait for a response from the server for a user-initiated request before declaring the connection lost. The default value is 60000 (60 seconds).
<context-param>
 
		<param-name>com.icesoft.faces.connectionTimeout</param-name>
 
		<param-value>60000</param-value>
 
</context-param>
 
Managing Connection Status

Heartbeating actively monitors the asynchronous connection state and reports the connection health as one of the following states:

Inactive - The connection is alive and there is no pending activity.
Active - The connection is alive and there is a request pending.
Caution - The connection heartbeat latency has exceeded the configured threshold and that asynchronous updates from the server may not be received in a timely manner.
Disconnected - The connection has been lost, due either to network or application error, such as session expiry, etc.

The Caution state occurs if heartbeats go missing, but retries are in progress. If the retries fail, the connection state will transition to Disconnected, and if a retry succeeds, the connection state will return to Inactive.

The outputConnectionStatus component in the ICEfaces Component Suite supports all four states, so applications can incorporate visual indicators for connection status to end-users. If the outputConnectionStatus component is not present on a page and a Disconnected state occurs, ICEfaces displays a modal dialog on the page indicating the error state as shown in Figure 14.

Figure 14 Connection State Error

By default, if the outputConnectionStatus component is present on the page, it will indicate the connection lost status itself and will not display the modal error dialog. If you would like to display the modal error dialog even when the outputConnectionStatus component is being used, you may specify this using the showPopupOnDisconnect attribute on the outputConnectionStatus component.

The JavaScript Ajax bridge also supports a set of callback APIs for common connection management events that can be used to implement custom status indicators and reactions, etc. to events. See Bridge Connection Status Events for details.

Managing Redirection

Redirect on Connection Lost

When a connection is lost, ICEFaces can be configured to redirect the browser to a custom error page. This feature can be turned on application-wide using the ICEfaces context parameter, com.icesoft.faces.connectionLostRedirectURI.
<context-param>
 
		<param-name>com.icesoft.faces.connectionLostRedirectURI</param-name>
 
		<param-value>...custom error page URL....</param-value>
 
</context-param>
 
If not specified, the default `Connection Lost' overlay will be rendered or if the status component is present, the `Connection Lost' icon.

Redirect on Session Expiry

When a user session expires, ICEFaces can be configured to redirect the browser to a specific page. This feature can be turned on application-wide using the ICEfaces context parameter, com.icesoft.faces.sessionExpiredRedirectURI.
<context-param> 
 
		<param-name>com.icesoft.faces.sessionExpiredRedirectURI</param-name> 
 
		<param-value>...custom page URL....</param-value> 
 
</context-param> 
 

 
If not specified, the default `Session Expired' overlay will be rendered or if the ice:outputConnectionStatus component is present, the `Session Expired' icon.

Note: An ice:outputConnectionStatus component must be present on the page for the connectionLostRedirectURI parameter to function as expected.

Note: The automatic redirection features are only supported when ICEfaces is used in asynchronous communications mode (default).