It is possible to register a listener with the remoting client to receive callbacks when a connection failure to a remoting server is detected, even when the client is idle.
The only requirement is to implement the org.jboss.remoting.ConnectionListener interface, which has only one method:
public void handleConnectionException(Throwable throwable, Client client)
Then call the addConnectionListener(ConnectionListener listener) method on the Client class and pass your listener instance. Can also call addConnectionListener(ConnectionListener listener, int pingPeriod) if want to specify how frequently wish to ping server.
Currently, the Client will use the org.jboss.remoting.ConnectionValidator class to handle the detection of connection failures. This is done by pinging the server periodically (defaults to every 2 seconds). If there is a failure during this ping, the exception and the Client will be passed to the listener.
A remoting server also has the capability to detect when a client is no longer available. This is done by estabilishing a lease with the remoting clients that connect to a server.
To turn on server side connection failure detection of remoting clients, will need to satisfy two criteria. The first is that the client lease period is set and is a value greater than 0. The value is represented in milliseconds. The client lease period can be set by either the 'clientLeasePeriod' attribute within the Connector configuration or by calling the:
public void setLeasePeriod(long leasePeriodValue)
method within Connector. The second criterion is that an implementation of the org.jboss.remoting.ConnectionListener interface is added as a connection listener to the Connector, via the method:
public void addConnectionListener(ConnectionListener listener)
Note, there is no way to set the connection listener via xml based configuration for the Connector. Once both criteria are met, the remoting server will turn on client leasing.
The ConnectionListener will be notified of both client failures and client disconnects via the handleConnectionException() method. If the client failed, meaning its lease was not renewed within configured time period, the first parameter to the handleConnectionException() method will be null. If the client disconnected in a regular manner, the first parameter to the handleConnectionException() method will be of type ClientDisconnectedException (which indicates a normal termination). Note, the client's lease will be renewed on the server with any and every invocation made on the server from the client, whether it be a normal invocation or a ping from the client internally.
One the client side, there is no API or configuration changes needed. When the client initially connects to the server, it will check to see if client leasing is turned on by the server. If it is, it will internally start pinging periodically to the server to maintain the lease. When the client disconnects, it will internally send message to the server to stop monitoring lease for this client. Therefore, it is IMPORTANT that disconnect is called on the client when done using it. Otherwise, the client will continue to make its ping call on the server to keep its lease current.
The client can also provide extra metadata the will be communicated to the connection listener in case of failure by supplying a metadata Map to the Client constructor. This map will be included in the Client instance passed to the connection listener (via the handleConnectionException() method) via the Client's getConfiguration() method.
For examples of how to use server side connection listeners, reference org.jboss.test.remoting.lease.LeaseTestServer and org.jboss.test.remoting.lease.LeaseTestClient.