net.kano.joscar.ratelim
Class RateLimitingQueueMgr

java.lang.Object
  RateLimitingQueueMgr

All Implemented Interfaces:

SnacQueueManager

public class RateLimitingQueueMgr

extends java.lang.Object

implements SnacQueueManager

A SNAC queue manager which uses a RateMonitor to determine when to send SNAC commands to avoid becoming rate-limited.

Note that a RateLimitingQueueMgr creates its own RateMonitor for each SNAC processor to which it is added. This behavior has several noteworthy implications:

• As per the RateMonitor documentation, RateMonitors should not be attached to SNAC processors which are already connected. Thus, a RateLimitingQueueMgr should not be set as the SNAC queue manager for a SNAC processor which has already connected.
• To avoid calculating the rate more than once, it is not recommended to create one's own RateMonitor for SNAC processors which use a RateLimitingQueueMgr for a SNAC queue manager. To retrieve the RateMonitor used by the RateLimitingQueueMgr for a given SNAC processor, simply use code such as the following:
  
  RateMonitor mon = rateLimitingQueueMgr.getQueueMgr(snacProcessor).getRateMonitor()

One may also wish to note that each instance of RateLimitingQueueMgr starts its own thread to manage the queue. It may be desirable to add a single rate limiting queue manager to every SNAC processor, or to split them up by giving each logical OSCAR connection (that is, each screenname) its own instance, or to give each SNAC processor its own. At the time of this writing, the threading / queue management code is not optimal, and it may consume a rather large amount of CPU when added to too many SNAC processors. In buzzword terms, it may not scale well. Thus, for now, it may be recommended to give each SNAC processor its own individual RateLimitingQueueMgr.

A RateLimitingQueueMgr delegates most actual functionality to a set of "child" ConnectionQueueMgrs. See getQueueMgr and getQueueMgrs for information on how to use these after assigning the RateLimitingQueueMgr to a SNAC processor.

See Also:

RateMonitor

Constructor Summary

RateLimitingQueueMgr()

Method Summary

void	attached(ClientSnacProcessor processor) Called when this SNAC queue manager has been set as the SNAC queue manager for the given processor.
void	clearQueue(ClientSnacProcessor processor) Clears all pending (queued) SNAC commands in this SNAC manager for the given SNAC processor.
void	detached(ClientSnacProcessor processor) Called when this SNAC queue manager has been removed from being the SNAC queue manager for the given processor.
ConnectionQueueMgr	getQueueMgr(ClientSnacProcessor processor) Returns the single-SNAC-processor queue manager for the given SNAC processor.
ConnectionQueueMgr[]	getQueueMgrs() Returns a list of all SNAC processor queue managers currently being used.
void	pause(ClientSnacProcessor processor) A method called to indicate that the queue should be paused until a call to unpause(net.kano.joscar.snac.ClientSnacProcessor).
void	queueSnac(ClientSnacProcessor processor, SnacRequest request) Enqueues the given SNAC request for the given SNAC processor.
void	unpause(ClientSnacProcessor processor) A method called to indicate that the queue for the given SNAC processor can once again send SNACs.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RateLimitingQueueMgr

public RateLimitingQueueMgr()

Method Detail

getQueueMgrs

public final ConnectionQueueMgr[] getQueueMgrs()

Returns a list of all SNAC processor queue managers currently being used. One ConnectionQueueMgr exists for each SNAC processor for which this RateLimitingQueueMgr is set.

Returns:

a list of all single-SNAC-processor queue managers currently in use

getQueueMgr

public final ConnectionQueueMgr getQueueMgr(ClientSnacProcessor processor)

Returns the single-SNAC-processor queue manager for the given SNAC processor. Note that if this RateLimitingQueueMgr is not set as the given SNAC processor's queue manager this method will return null.

Parameters:

processor - a SNAC processor

Returns:

the SNAC processor queue manager in use for the given SNAC processor, or null if none is in use for the given SNAC processor

attached

public void attached(ClientSnacProcessor processor)

Description copied from interface: SnacQueueManager

Called when this SNAC queue manager has been set as the SNAC queue manager for the given processor. This will always be the first method called in this queue manager for the given SNAC processor.

Specified by:

attached in interface SnacQueueManager

Parameters:

processor - the SNAC processor for which this manager has been set

detached

public void detached(ClientSnacProcessor processor)

Description copied from interface: SnacQueueManager

Called when this SNAC queue manager has been removed from being the SNAC queue manager for the given processor. This method will always be the last method called in this queue manager for the given SNAC processor unless this manager is re-set as the given processor's queue manager, in which case the next method to be called for the given processor will always be attached.

Specified by:

detached in interface SnacQueueManager

Parameters:

processor - the SNAC processor for which this manager has been set

queueSnac

public void queueSnac(ClientSnacProcessor processor,
                      SnacRequest request)

Description copied from interface: SnacQueueManager

Enqueues the given SNAC request for the given SNAC processor. This method can just as easily send the given request immediately (via sendSnac) as it can enqueue it to be sent later. Note that the given request will not be sent at all until it is sent from this SNAC queue manager using sendSnac. It is not recommended that a request be modified before it is sent.

Specified by:

queueSnac in interface SnacQueueManager

Parameters:

processor - the SNAC processor on which the given request was created and on which it is to be sent

request - the request being enqueued

clearQueue

public void clearQueue(ClientSnacProcessor processor)

Description copied from interface: SnacQueueManager

Clears all pending (queued) SNAC commands in this SNAC manager for the given SNAC processor. This is normally only called when the given SNAC processor has been disconnected. Note that a call to this method implies a call to SnacQueueManager.unpause(net.kano.joscar.snac.ClientSnacProcessor) for the given SNAC processor as well, although no queued SNACs should be sent (as they might be with an actual call to unpause}.

Specified by:

clearQueue in interface SnacQueueManager

Parameters:

processor - the SNAC processor for which pending SNACs should be erased

pause

public void pause(ClientSnacProcessor processor)

Description copied from interface: SnacQueueManager

A method called to indicate that the queue should be paused until a call to SnacQueueManager.unpause(net.kano.joscar.snac.ClientSnacProcessor). This method will never be called for a given ClientSnacProcessor twice without a call to unpause in between; that is, it will never be called twice in a row. Note that calls to SnacQueueManager.queueSnac(net.kano.joscar.snac.ClientSnacProcessor, net.kano.joscar.snac.SnacRequest) can and probably will be made before a call to SnacQueueManager.unpause(net.kano.joscar.snac.ClientSnacProcessor); that is, the queue must still accept the queueing of SNAC commands while it is paused.

Note that this will be the first method called for a given SNAC processor if this queue manager is added to the processor while the processor is paused.

Specified by:

pause in interface SnacQueueManager

Parameters:

processor - the SNAC processor on which to pause

unpause

public void unpause(ClientSnacProcessor processor)

Description copied from interface: SnacQueueManager

A method called to indicate that the queue for the given SNAC processor can once again send SNACs. This method will only be called after a call to SnacQueueManager.pause(net.kano.joscar.snac.ClientSnacProcessor), and will never be called twice for a SNAC processor without a call to SnacQueueManager.pause(net.kano.joscar.snac.ClientSnacProcessor) in between; that is, essentially, it will never be called twice in a row for a given SNAC processor.

Specified by:

unpause in interface SnacQueueManager

Parameters:

processor - the SNAC processor on which to pause