Monitor connections from the server side
This topic has not yet been written. The content below is from the topic description.
A remoting server also has the capability to detect when a client is no longer available. This is done by establishing a lease with the remoting clients that connect to a server. 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. Server side activation. To turn on server side connection failure detection of remoting clients, it is necessary 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 Connector method public void setLeasePeriod(long leasePeriodValue); The second criterion is that an implementation of the org.jboss.remoting.ConnectionListener interface is added as a connection listener to the Connector, either via the method public void addConnectionListener(ConnectionListener listener) or through the use of the ServerInvoker.CONNECTION_LISTENER parameter (actual value "connectionListener") in the Connector's configuration map, XML configuration file, or ServerConfiguration POJO. If the ServerInvoker.CONNECTION_LISTENER parameter is used, the value can be either a JMX object name or the fully qualified name of a class that implements ConnectionListener and has a default constructor. 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. The actual lease window established on the server side is dynamic based the rate at which the client updates its lease. In particular, the lease window will always be set to lease period * 2 for any lease that does not have a lease update duration that is longer than 75% of the lease window (meaning if set lease period to 10 seconds and always update that lease in less then 7.5 seconds, the lease period will always remain 10 seconds). If the update duration is greater than 75% of the lease window, the lease window will be reset to the lease duration X 2 (meaning if set lease period to 10 seconds and update that lease in 8 seconds, the new lease window will be set to 16 seconds). Also, the lease will not immediately expire on the first lease timeout (meaning did not get an update within the lease window). It takes two consecutive timeouts before a lease will expire and a notification for client connection failure is fired. This essentially means that the time it will take before a connection listener is notified of a client connection failure will be at least 4 X lease period (no exceptions). Client side activation. By default, the client is not configured to do client leasing. To allow a client to do leasing, either set the parameter "leasing" to "true" in the InvokerLocator or set the parameter Client.ENABLE_LEASE (actual value "enableLease") to true in the InvokerLocator or in the Client configuration map. [The use of Client.ENABLE_LEASE is recommended.] This does not mean that client will lease for sure, but will indicate the client should call on the server to see if the server has activated leasing and get the leasing period suggested by the server. It is possible to override the suggested lease period by setting the parameter org.jboss.remoting.InvokerLocator.CLIENT_LEASE_PERIOD (actual value "lease_period") to a value greater than 0 and less than the value suggested by the server. Note. If the client and server are local, meaning running within the JVM, leasing (and thus connection notification) will not be activated, even if is configured to do so. If leasing is turned on within the client side, there is no API or configuration changes needed, unless want to override as mentioned previously. 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 that 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. From the server side, there are two ways in which to disable leasing (i.e. turn leasing off). The first is to call: public void removeConnectionListener(ConnectionListener listener) and remove all the registered ConnectionListeners. Once the last one has been removed, leasing will be disabled and all the current leasing sessions will be terminated. The other way is to call: public void setLeasePeriod(long leasePeriodValue) and pass a value less than zero. This will disable leasing, preventing any new leases to be established but will allow current leasing sessions to continue. The following parameter is relevant to leasing configuration on the server side: org.jboss.remoting.ServerInvoker.CLIENT_LEASE_PERIOD (actual value "clientLeasePeriod") - specifies the timeout period used by the server to determine if a PING is late. The default value is "5000", which indicates that leasing will be activated if an org.jboss.remoting.ConnectionListener is registered with the server. 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: org.jboss.remoting.Client.ENABLE_LEASE (actual value "enableLease") - if set to "true", will lead org.jboss.remoting.Client to attempt to set up a lease with the server, if leasing is activated on the server. org.jboss.remoting.InvokerLocator.CLIENT_LEASE (actual value "leasing") - if set to "true" in the InvokerLocator, will lead org.jboss.remoting.Client to attempt to set up a lease with the server, if leasing is activated on the server. It is suggested that this parameter be avoided, in favor of Client.ENABLE_LEASE. org.jboss.remoting.InvokerLocator.CLIENT_LEASE_PERIOD (actual value "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. org.jboss.remoting.LeasePinger.LEASE_PINGER_TIMEOUT (actual value "leasePingerTimeout") - specifies the per invocation timeout value use by LeasePinger when it sends PING messages. In the absence of a configured value, the timeout value used by the Client that created the LeasePinger will be used. For examples of how to use server side connection listeners, reference org.jboss.test.remoting.lease.LeaseTestServer and org.jboss.test.remoting.lease.LeaseTestClient.