net.kano.joscar.ratelim
Class RateMonitor

java.lang.Object
  extended byRateMonitor

public class RateMonitor
extends java.lang.Object

Keeps track of the current "rate" on a SNAC connection. See RateClassInfo for details on the algorithm used.

To use a rate monitor, one could use code such as:

RateMonitor monitor = new RateMonitor(snacProcessor);
 
The rate monitor will attach itself to the given SNAC processor and compute the rate for each rate class without any further effort. A few notes: Rate monitors can themselves be monitored via rate listeners, which listen for rate-related events. If any calls to these listeners' listener methods produces an error, the FLAP processor underneath a given rate monitor's attached SNAC processor will be notified of the error with its handleException method. The type of the error will be ERRTYPE_RATE_LISTENER, and the info/reason object will be the RateListener whose listener method threw the exception.

Rate monitors have a concept of an "error margin" to allow for error when computing whether or not a rate class is rate-limited. This value defaults to ERRORMARGIN_DEFAULT, or 100 ms as of this writing. A value of 100 ms is very conservative value, as the largest recorded deviation from the actual average is less than 5 ms. The value of the error margin indicates how much error is allowed, in milliseconds, between the actual rate and the computed rate. The effect of setting this to, say, 50ms, means that the rate monitor will not decide that it is un-rate-limited until its rate is 50ms above the server-specified "rate cleared average."

Once rate class information has been received from the server, a RateClassMonitor is created for each rate class. For more information on what exactly a rate class is, see RateClassInfo. After the initial rate class information is received, rate classes are never added or removed, and the SNAC commands which each rate class contains cannot be changed, so it is safe to keep references to RateClassMonitors until new rate class information is received (as on a new connection). (You can be notified of rate class information's arrival by adding a rate listener.

RateMonitor logs to the Java Logging API namespace "net.kano.joscar.ratelim" on the levels Level.FINE and Level.FINER in order to, hopefully, ease the debugging rate-limiting-related applications. For information on how to access these logs, see the Java Logging API reference at the J2SE website.

Most of the interesting rate limiting information is provided by the child of this class, RateClassMonitor. To access rate information for IM's, one could use code such as the following:
CmdType cmd = new CmdType(IcbmCommand.FAMILY_ICBM,
        IcbmCommand.CMD_IM);
RateClassMonitor classMonitor = rateMonitor.getMonitor(type);
System.out.println("Current IM rate average: "
        + classMonitor.getCurrentAvg() + "ms");
 


Field Summary
static int ERRORMARGIN_DEFAULT
          A default rate average error margin.
static java.lang.Object ERRTYPE_RATE_LISTENER
          An error type indicating that an exception occurred when calling a rate listener method.
 
Constructor Summary
RateMonitor(ClientSnacProcessor processor)
          Creates a new rate monitor for the given SNAC processor.
 
Method Summary
 void addListener(RateListener l)
          Adds a listener for rate-monitor-related events.
 void detach()
          "Detaches" this rate monitor from the SNAC processor to which it is attached.
 int getErrorMargin()
          Returns this rate monitor's current error margin value.
 RateClassMonitor getMonitor(CmdType type)
          Returns the rate class monitor used to handle commands of the given type.
 RateClassMonitor[] getMonitors()
          Returns all of the rate class monitors currently being used.
 ClientSnacProcessor getSnacProcessor()
          Returns the SNAC processor which this rate monitor is monitoring.
 void removeListener(RateListener l)
          Removes the given listener from this rate monitor's listener list, if present.
 void reset()
          Resets this rate monitor to the state it was in when first created.
 void setErrorMargin(int errorMargin)
          Sets this rate monitor's error margin.
 void setRateClasses(RateClassInfo[] rateInfos)
          Clears all rate information present in this rate monitor and stores the given rate information.
 void updateRateClass(int changeCode, RateClassInfo rateInfo)
          Updates rate class information in this rate monitor with the given rate class information block.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ERRTYPE_RATE_LISTENER

public static final java.lang.Object ERRTYPE_RATE_LISTENER
An error type indicating that an exception occurred when calling a rate listener method. The error info object for an error of this type will be the listener that threw the exception.


ERRORMARGIN_DEFAULT

public static final int ERRORMARGIN_DEFAULT
A default rate average error margin.

See Also:
Constant Field Values
Constructor Detail

RateMonitor

public RateMonitor(ClientSnacProcessor processor)
Creates a new rate monitor for the given SNAC processor.

Parameters:
processor - the SNAC processor whose rates should be monitored
Method Detail

detach

public final void detach()
"Detaches" this rate monitor from the SNAC processor to which it is attached. This monitor will stop listening for events on the given processor.


reset

public final void reset()
Resets this rate monitor to the state it was in when first created. All rate class and all rate class monitors are discarded until new rate information is received after a call to this method.


getSnacProcessor

public final ClientSnacProcessor getSnacProcessor()
Returns the SNAC processor which this rate monitor is monitoring.

Returns:
this rate monitor's attached SNAC processor

addListener

public final void addListener(RateListener l)
Adds a listener for rate-monitor-related events.

Parameters:
l - the listener to add

removeListener

public final void removeListener(RateListener l)
Removes the given listener from this rate monitor's listener list, if present. (Note that the given listener value cannot be null.)

Parameters:
l - the listener to remove

setRateClasses

public final void setRateClasses(RateClassInfo[] rateInfos)
Clears all rate information present in this rate monitor and stores the given rate information. After a call to this method, the given rate information will be used in calculating the rate.

Note that calling this method is not normally necessary as rate class information is automatically set upon receiving the associated commands on the attached SNAC processor. See above for details.

Parameters:
rateInfos - the list of rate class information blocks to use

updateRateClass

public void updateRateClass(int changeCode,
                            RateClassInfo rateInfo)
Updates rate class information in this rate monitor with the given rate class information block. Note that calling this method is not normally necessary, as rate class information is automatically updated when the associated commands are received from the server. See above for details.

Parameters:
changeCode - the "change code" sent in the rate class change packet
rateInfo - the rate information block sent in the rate class change packet

setErrorMargin

public final void setErrorMargin(int errorMargin)
                          throws java.lang.IllegalArgumentException
Sets this rate monitor's error margin. See above for details on what this means.

Parameters:
errorMargin - a new error margin
Throws:
java.lang.IllegalArgumentException - if the given error margin is negative

getErrorMargin

public final int getErrorMargin()
Returns this rate monitor's current error margin value. See above for details on what this means.

Returns:
this rate monitor's error margin value

getMonitor

public final RateClassMonitor getMonitor(CmdType type)
Returns the rate class monitor used to handle commands of the given type. Note that the returned value will never be null unless no rate information has yet been set or no default rate class was specified by the server.

Parameters:
type - the type of command whose associated rate class monitor is to be returned
Returns:
the rate class monitor associated with the given command type

getMonitors

public final RateClassMonitor[] getMonitors()
Returns all of the rate class monitors currently being used.

Returns:
all of the rate class monitors in use in this rate monitor