Remoting has two mechanisms for monitoring the health of established connections, which inform listeners on the client and server sides when a possible connection failure has been detected. Currently, only JBoss Messaging uses these facilities. Note that JBoss Messaging establishes connections programmatically, so some unused declarative configuration options are omitted from this discussion.
A remoting server has the capability to detect when a client is no longer available. This is done by establishing an org.jboss.remoting.Lease on the server side, managed by a ServerInvoker. On the client side, an org.jboss.remoting.LeasePinger periodically sends PING messages to the server, and on the server side an org.jboss.remoting.Lease informs registered listeners if the PING doesn't arrive within the specified timeout period. A LeasePinger is created by a RemoteClientInvoker and it sends PINGS to a particular Lease. That LeasePinger/Lease pair defines, for purposes of connection monitoring in Remoting, the abstract concept of a connection.
The following parameter is relevant to leasing configuration on the server side:
clientLeasePeriod - specifies the timeout period used by the server to determine if a PING is late. The default value is "5000". This is also the suggested lease period returned by the server when the client inquires if leasing is activated.
The following parameters are relevant to leasing configuration on the client side:
lease_period - if set to a value greater than 0 and less than the suggested lease period returned by the server, will be used to determine the time between PING messages sent by LeasePinger. This parameter is not used by JBoss Messaging.
leasePingerTimeout - specifies the per invocation timeout value use by LeasePinger when it sends PING messages. This parameter is not used by JBoss Messaging.
The actual lease window established on the server side is initially set to twice the clientLeasePeriod value, but it can expand dynamically to adjust to actual network conditions. As long as PINGs arrive within 75% of the lease window, the window will remain unchanged. However, if a PING arrives at between 75% and 100% of the lease window, the lease window will be expanded to twice the time since the previous PING. For example, if the current lease window is 20 seconds, and if a PING arrives 17 seconds after the previous PING, the lease window will be set to 34 seconds.
On the client side, an org.jboss.remoting.ConnectionValidator periodically sends a PING message to the server and reports a failure if the response does not arrive within a specified timeout period. The PING is sent on one thread, and another thread determines if the response arrives in time. Separating these two activities allows Remoting to detect a failure regardless of the cause of the failure.
A ConnectionValidator is created by a call to one of the overloaded Client.addConnectionListener() methods, and since multiple Clients may share a RemoteClientInvoker, multiple ConnectionValidators may be associated with a particular Remoting connection.
The following parameters are supported by ConnectionValidator:
validatorPingPeriod - specifies the time, in milliseconds, that elapses between the sending of PING messages to the server. The default value is 2000.
validatorPingTimeout - specifies the time, in milliseconds, allowed for arrival of a response to a PING message. The default value is 1000.
failureDisconnectTimeout - if the parameter "stopLeaseOnFailure" (see Interactions between client side and server side connection monitoring) is set to "true", then "failureDisconnectTimeout" determines the disconnect timeout value to be used by org.jboss.remoting.LeasePinger in shutting down. In particular, if "failureDisconnectTimeout" is set to "0", then LeasePinger will avoid any network i/o.
NOTE. The default values of "validatorPingPeriod" and "validatorPingTimeout" have often been found in practice to be too small, increasing the likelihood of spurious connection failures.
NOTE. It is important to set "validatorPingPeriod" to a value greater than the value of "validatorPingTimeout". Doing so gives the ConnectionValidator a chance to notify all ConnectionListeners, which might result in shutting down the connection, before the next PING is sent.
As of Remoting version 2.4, the client side and server side connection monitoring mechanisms can be, and by default are, more closely related, in two ways.
If the parameter stopLeaseOnFailure is set to true, then, upon detecting a connection failure, ConnectionValidator will stop the LeasePinger, if any, pinging a lease on the same connection. The default value is "true".
Note that by default, a LeasePinger has no identity, so if it is replaced by another LeasePinger that pings the same Lease, the connection remains unchanged. Suppose that leasing is enabled and that a RemoteClientInvoker stops and is replaced by a new RemoteClientInvoker with a new LeasePinger. If the replacement occurs quickly, the server side Lease may never miss a PING, in which case there is no evidence that anything changed on the client side. That is, the connection is still alive, as far as the server is concerned. That semantics might be perfectly acceptable for some applications, but other applications might interpret the same events as a connection failure followed by a new connection. In particular, JBoss Messaging needs the latter semantics.
As of release 2.5.2, an important concept related to connection monitoring, client connection identity, is available. Remoting can be configured to treat a connection as being defined by a LeasePinger/Lease pair in which the LeasePinger has an identity. More specifically, when configured to do so by setting the parameter useClientConnectionIdentity to "true", Remoting identifies a connection with a LeasePinger/Lease pair in which the Lease expects PINGs to arrive from a particular LeasePinger.
A Client participates in a connection when it is connected by way of the new method
public void connect(ConnectionListener listener, Map metadata) throws Exception;
This method serves to connect the Client to the server by way of a new or existing RemoteClientInvoker, and it also registers the new ConnectionValidator with the RemoteClientInvoker's LeasePinger. Subsequently, if any ConnectionValidator registered with that LeasePinger detects a connection failure, it will (if "stopLeaseOnFailure" is "true") stop the LeasePinger, and the LeasePinger will cause each registered ConnectionValidator to notify each of its registered ConnectionListeners of the connection failure. Once the LeasePinger has been shut down and all of the notifications have been made, the connection anchored by the LeasePinger is defunct, and the associated Clients should be disconnected by a call to Client.disconnect(). If such a Client is reconnected by a call to Client.connect(), it will be associated with a new LeasePinger and, therefore, a new connection.
As of release 2.5.3.SP2, Remoting also supports the concept of server connection identity. Suppose that a ServerInvoker managing a Lease stops and is replaced by a new ServerInvoker and Lease. If the replacement occurs between PINGs from a ConnectionValidator, there is no evidence that the server has been replaced. Again, that semantics might be appropriate for some applications, but JBoss Messaging needs a semantics in which the original connection is considered to have been destroyed and replaced. If the parameter useServerConnectionIdentity is set to "true", then, when a ServerInvoker responds to a PING from a ConnectionValidator, it returns a token of its unique identity. If the identity has changed, then ConnectionValidator considers the connection to have been broken and it notifies all registered listeners.