org.apache.river.fiddler

Interface FiddlerAdmin

All Superinterfaces:

DestroyAdmin, JoinAdmin

public interface FiddlerAdmin
extends JoinAdmin, DestroyAdmin

An administrative interface for the Fiddler implementation of the lookup discovery service (see Fiddler). The comments that follow describe Fiddler with respect to the following methods:

• setLeaseBound
• getLeaseBound
• setPersistenceSnapshotWeight
• getPersistenceSnapshotWeight
• setPersistenceSnapshotThreshold
• getPersistenceSnapshotThreshold

The intent of the information contained in this note is to clarify the use of these methods and the effect that use will have on the configuration of Fiddler. Note that the phrase lookup discovery service as used throughout this note refers to the Fiddler implementation of that service. While such a lookup discovery service is running, the following sort of state changes can occur:

• Clients register and un-register (cancel their lease) with the lookup discovery service
• Leases on the registrations created for a client by the lookup discovery service are granted, renewed, cancelled and expired
• Managed sets of groups, locators and lookup services associated with the client registrations are added, modified, and removed from the lookup discovery service

In order to make the lookup discovery service's state persistent across system crashes or network outages, each of the state changes described above are written to a file referred to as the service's log file. The service's log file records, over time, the incremental changes -- or deltas -- made to the lookup discovery service's state.

To prevent the log file from growing indefinitely, the lookup discovery service's complete state is intermittently written to another file referred to as the service's snapshot file. When a snapshot of the service's state is logged to the service's snapshot file, the service's log file is cleared, and the incremental logging of deltas begins anew. When the service is started for the first time, the initial period prior to the creation of the first snapshot is referred to as the system ramp-up period. This ramp-up period is the only time where a log file exists without a corresponding snapshot file.

When recovering the system's state after a crash or network outage (or after the lookup discovery service or its ActivationGroup has been un-registered and then re-registered through the Activation daemon), a "base state" is first recovered by retrieving and applying the contents of the snapshot file (if it exists). Then, if the log file has length greater than zero, its contents are retrieved and applied in order to incrementally recover the state changes that occurred from the point of the base state.

The criteria used by the lookup discovery service to determine exactly when to "take a snapshot" depends on the current size of the log file relative to the size that the snapshot file will be. Note that whereas, the size of the log file depends on the total number of changes to the lookup discovery service's state, the size of the snapshot file depends on the number of registrations that are currently active; that is, the more registrations that have been created and which have valid leases, the larger the snapshot. For example, if only 10 registrations are active, the snapshot file will be relatively small; but lease renewals may be regularly requested on some of those registrations. The regular lease renewals will result in a very large log file.

A balance must be maintained between how large the log file is allowed to get and how often a snapshot is taken; taking snapshots too often can slow down processing significantly. The lookup discovery service is initially configured with a threshold value and a weighting factor that are employed in a computation that determines when to take a snapshot. The methods specified by this interface provide ways to access and modify those values. Thus, based on a particular lookup discovery service's makeup, these methods can be used by that service's administrative client to "tune" performance with respect to logging the service's persistent state.

 The following comparison is made to determine when to take a snapshot:
 
   if (logSize >= W*snapshotSize) && (snapshotSize >= T) {
       take a snapshot;
   }
       where W = persistenceSnapshotWeight
             T = persistenceSnapshotThreshold
 

The first comparison is used to ensure that the log file does not grow too large. The second comparison ensures that snapshots are not taken too often.

Administrative clients of Fiddler should consider these relationships when using the methods specified by this interface to tune that service's persistence mechanism.

Author:

Sun Microsystems, Inc.

Method Summary

Modifier and Type	Method and Description
long	getLeaseBound() Retrieves the least upper bound applied to all lease durations granted by the lookup discovery service.
int	getPersistenceSnapshotThreshold() Retrieve the value of the size threshold of the snapshot; which is employed by the lookup discovery service in the test to determine whether or not to take a "snapshot" of the system state.
float	getPersistenceSnapshotWeight() Retrieve the weight factor applied by the lookup discovery service to the snapshot size during the test to determine whether or not to take a "snapshot" of the system state.
void	setLeaseBound(long newBound) Changes the least upper bound applied to all lease durations granted by the lookup discovery service.
void	setPersistenceSnapshotThreshold(int threshold) Change the value of the size threshold of the snapshot; which is employed by the lookup discovery service in the test to determine whether or not to take a "snapshot" of the system state.
void	setPersistenceSnapshotWeight(float weight) Change the weight factor applied by the lookup discovery service to the snapshot size during the test to determine whether or not to take a "snapshot" of the system state.

Methods inherited from interface net.jini.admin.JoinAdmin

addLookupAttributes, addLookupGroups, addLookupLocators, getLookupAttributes, getLookupGroups, getLookupLocators, modifyLookupAttributes, removeLookupGroups, removeLookupLocators, setLookupGroups, setLookupLocators

Methods inherited from interface org.apache.river.admin.DestroyAdmin

destroy

Method Detail

setLeaseBound

void setLeaseBound(long newBound)
            throws RemoteException

Changes the least upper bound applied to all lease durations granted by the lookup discovery service.

When a client registers with the lookup discovery service, it requests a desired duration for the lease that the lookup discovery service grants on the registration. As stated in the lookup discovery service specification, the actual duration granted is guaranteed to never be greater than the requested duration. But the Fiddler implementation of the lookup discovery service applies an additional restriction on the duration of the lease that is ultimately granted to the client: when determining the actual duration to grant, Fiddler applies a bound to the duration request. That is, whenever a client requests a lease duration that is greater than the value of this bound, the value of the actual duration assigned by Fiddler will not only be less than the requested value, it will also be less than or equal to the value of the bound.

The bound satisfies the definition of a least upper bound on the set of all possible granted durations because the durations granted by Fiddler can be arbitrarily close to the bound, but will never be greater than the bound.

Thus, this method is a mechanism for an entity with the appropriate privileges to administratively change the value of the least upper bound that will be applied by the Fiddler implementation of the lookup discovery service when determining the duration to assign to the lease on a requested registration.

Parameters:

newBound - long value representing the new least upper bound (in milliseconds) on the set of all possible lease durations that may be granted

Throws:

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service. When this exception does occur, the bound value may or may not have been changed successfully.

getLeaseBound

long getLeaseBound()
            throws RemoteException

Retrieves the least upper bound applied to all lease durations granted by the lookup discovery service.

Returns:

long value representing the current least upper bound (in milliseconds) on the set of all possible lease durations that may be granted

Throws:

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service.

setPersistenceSnapshotWeight

void setPersistenceSnapshotWeight(float weight)
                           throws RemoteException

Change the weight factor applied by the lookup discovery service to the snapshot size during the test to determine whether or not to take a "snapshot" of the system state.

Parameters:

weight - weight factor for snapshot size

Throws:

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service. When this exception does occur, the weight factor may or may not have been changed successfully.

getPersistenceSnapshotWeight

float getPersistenceSnapshotWeight()
                            throws RemoteException

Retrieve the weight factor applied by the lookup discovery service to the snapshot size during the test to determine whether or not to take a "snapshot" of the system state.

Returns:

float value corresponding to the weight factor for snapshot size

Throws:

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service.

setPersistenceSnapshotThreshold

void setPersistenceSnapshotThreshold(int threshold)
                              throws RemoteException

Change the value of the size threshold of the snapshot; which is employed by the lookup discovery service in the test to determine whether or not to take a "snapshot" of the system state.

Parameters:

threshold - size threshold for taking a snapshot

Throws:

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service. When this exception does occur, the threshold may or may not have been changed successfully.

getPersistenceSnapshotThreshold

int getPersistenceSnapshotThreshold()
                             throws RemoteException

Retrieve the value of the size threshold of the snapshot; which is employed by the lookup discovery service in the test to determine whether or not to take a "snapshot" of the system state.

Returns:

int value corresponding to the size threshold of the snapshot

Throws:

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service.