|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.ObjectRateMonitor
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:
RateMonitor
assumes that the default joscar implementations
of RateInfoCmd
and RateChange
are passed to its packet
listeners. If you have provided custom SNAC command factories that use custom implementations of those SNAC
commands, you will need to call setRateClasses
and updateRateClass
on your own. (Note that this issue will not be a problem for
the great majority of joscar users, and if you don't know what it all means,
ignore it.) RateMonitor
's behavior is undefined if it is attached to a
SNAC processor that is already connected. That is, only create
RateMonitor
s for ClientSnacProcessor
s which are not
already connected. Also note that when a SNAC processor is disconnected
or detached, one should either throw out any rate monitors attached to it or
call reset()
for each. 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.
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, 50
ms, means that the rate
monitor will not decide that it is un-rate-limited until its rate is
50
ms above the server-specified "rate cleared average."
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 RateClassMonitor
s 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.
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 |
public static final java.lang.Object ERRTYPE_RATE_LISTENER
public static final int ERRORMARGIN_DEFAULT
Constructor Detail |
public RateMonitor(ClientSnacProcessor processor)
processor
- the SNAC processor whose rates should be monitoredMethod Detail |
public final void detach()
public final void reset()
public final ClientSnacProcessor getSnacProcessor()
public final void addListener(RateListener l)
l
- the listener to addpublic final void removeListener(RateListener l)
null
.)
l
- the listener to removepublic final void setRateClasses(RateClassInfo[] rateInfos)
rateInfos
- the list of rate class information blocks to usepublic void updateRateClass(int changeCode, RateClassInfo rateInfo)
changeCode
- the "change code" sent in the rate class change packetrateInfo
- the rate information block sent in the rate class change
packetpublic final void setErrorMargin(int errorMargin) throws java.lang.IllegalArgumentException
errorMargin
- a new error margin
java.lang.IllegalArgumentException
- if the given error margin is negativepublic final int getErrorMargin()
public final RateClassMonitor getMonitor(CmdType type)
null
unless no
rate information has yet been set or no default rate class was specified
by the server.
type
- the type of command whose associated rate class monitor is to
be returned
public final RateClassMonitor[] getMonitors()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |