net.kano.joscar.snac
Interface SnacQueueManager

All Known Implementing Classes:

ImmediateSnacQueueManager, RateLimitingQueueMgr

public interface SnacQueueManager

An interface for managing a "SNAC queue," which controls when individual SNAC commands are sent on a ClientSnacProcessor. Such a system is useful for, for example, implementing an automatic rate limiting mechanism.

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

Method Detail

attached

public void attached(ClientSnacProcessor processor)

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.

Parameters:

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

detached

public void detached(ClientSnacProcessor processor)

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.

Parameters:

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

pause

public 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). 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 queueSnac(net.kano.joscar.snac.ClientSnacProcessor, net.kano.joscar.snac.SnacRequest) can and probably will be made before a call to 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.

Parameters:

processor - the SNAC processor on which to pause

unpause

public void unpause(ClientSnacProcessor processor)

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 pause(net.kano.joscar.snac.ClientSnacProcessor), and will never be called twice for a SNAC processor without a call to 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.

Parameters:

processor - the SNAC processor on which to pause

queueSnac

public void queueSnac(ClientSnacProcessor processor,
                      SnacRequest request)

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.

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)

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

Parameters:

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