Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.jini.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.

Method Summary
`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 com.sun.jini.admin.DestroyAdmin
`destroy`

Method Detail

### setLeaseBound

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved