net.kano.joscar.snac
Class ClientSnacProcessor

java.lang.Object
  extended byAbstractSnacProcessor
      extended byClientSnacProcessor

public class ClientSnacProcessor
extends AbstractSnacProcessor

A client-side SNAC processor. In addition to the functionality provided by AbstractSnacProcessor, a ClientSnacProcessor provides a request-response system (see SnacRequest, sendSnac) with automatic request ID generation and management.

ClientSnacProcessor passes two additional (see AbstractSnacProcessor) types of exceptions thrown during SNAC processing to its attached FlapProcessor's error handlers using FlapProcessor's handleException method, which in turn causes the exceptions to be passed to your own error handlers. The extra error types used are ERRTYPE_SNAC_REQUEST_LISTENER and ERRTYPE_SNAC_RESPONSE_LISTENER. See individual documentation for each for further detail.

A ClientSnacProcessor intercepts incoming SNAC packets if they match the request ID of a previous outgoing request (see below for details). The process is as follows:
If the request ID matches that of a previous outgoing request,

And finally, a bit about SNAC requests. The OSCAR protocol and SNAC data structure are defined such that each individual SNAC packet has its own request ID, a four-byte integer (or any other way you want to represent it, actually). This combined with one other aspect of the protocol allows for interesting things to be done with regard to automated connection handling. That other aspect is that for any command sent to an OSCAR server, all direct responses to that command that are sent back to the client have the same request ID as the original request. This means that, for example, an application can request two user directory searches at once and display the results to each in separate windows, all based on their request ID. This also allows for more complicated things like determining network lag between an OSCAR server by matching up request ID's with packet send times. See SnacRequest for more information on how to utilize the request system.

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


Field Summary
static java.lang.Object ERRTYPE_SNAC_REQUEST_LISTENER
          An error type indicating that an exception was thrown while calling a SNAC request response listener to handle a response to a SNAC request or another request-related event.
static java.lang.Object ERRTYPE_SNAC_RESPONSE_LISTENER
          An error type indicating that an exception was thrown while calling a global SNAC response listener to handle a response to a SNAC request.
static long REQID_MAX
          The maximum request ID value before it wraps to REQID_MIN.
static long REQID_MIN
          The minimum request ID value.
static int REQUEST_TTL_DEFAULT
          The default SNAC request "time to live," in seconds.
 
Fields inherited from class AbstractSnacProcessor
ERRTYPE_SNAC_PACKET_LISTENER, ERRTYPE_SNAC_PACKET_PREPROCESSOR
 
Constructor Summary
ClientSnacProcessor(FlapProcessor processor)
          Creates a SNAC processor with no SNAC factories installed and the default request time-to-live, attached to the given FLAP processor.
 
Method Summary
 void addGlobalRequestListener(OutgoingSnacRequestListener l)
          Adds a global request listener to listen for outgoing SNAC requests sent on this connection.
 void addGlobalResponseListener(SnacResponseListener l)
          Adds a "global response listener" to listen for incoming SNAC request responses.
protected  boolean continueHandling(SnacPacketEvent event)
          Returns whether or not the given SNAC packet event should be passed to packet listeners.
 void detach()
          Detaches from the currently attached FLAP processor, if any.
 int getRequestTtl()
          Returns the current "time to live" for SNAC requests, in seconds.
 SnacQueueManager getSnacQueueManager()
          Returns this SNAC processor's current SNAC queue manager.
 boolean isPaused()
          Returns whether this SNAC processor is currently paused.
 void migrate(FlapProcessor processor)
          Attaches to the given FLAP processor without clearing any SNAC queues.
 void pause()
          Pauses this SNAC processor.
 void removeGlobalRequestListener(OutgoingSnacRequestListener l)
          Removes a global request listener from the list of listeners.
 void removeGlobalResponseListener(SnacResponseListener l)
          Removes a "global response listener" from the list of listeners.
 void sendSnac(SnacRequest request)
          Sends the given SnacRequest to the attached FLAP connection.
 void sendSnacImmediately(SnacRequest request)
          Sends the given SNAC request to the server, bypassing the SNAC request queue and any pausing status that may be present.
 void setRequestTtl(int requestTtl)
          Sets the "time to live" for SNAC requests, in seconds.
 void setSnacQueueManager(SnacQueueManager mgr)
          Sets this SNAC processor's SNAC queue manager.
 void unpause()
          Unpauses this SNAC processor if previously paused with a call to pause().
 void unsetSnacQueueManager(SnacQueueManager mgr)
          Calls setSnacQueueManager(null) if and only if the given mgr is the current SNAC queue manager.
 
Methods inherited from class AbstractSnacProcessor
addPacketListener, addPreprocessor, addVetoablePacketListener, getCmdFactoryMgr, getFlapProcessor, isAttached, removePacketListener, removePreprocessor, removeVetoablePacketListener, sendSnac
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ERRTYPE_SNAC_REQUEST_LISTENER

public static final java.lang.Object ERRTYPE_SNAC_REQUEST_LISTENER
An error type indicating that an exception was thrown while calling a SNAC request response listener to handle a response to a SNAC request or another request-related event. In this case, the extra error information (the value returned by getReason()) will be the SnacRequest whose listener threw the exception.


ERRTYPE_SNAC_RESPONSE_LISTENER

public static final java.lang.Object ERRTYPE_SNAC_RESPONSE_LISTENER
An error type indicating that an exception was thrown while calling a global SNAC response listener to handle a response to a SNAC request. In this case, the extra error information (the value returned by getReason()) will be the SnacResponseListener that threw the exception.


REQUEST_TTL_DEFAULT

public static final int REQUEST_TTL_DEFAULT
The default SNAC request "time to live," in seconds.

See Also:
setRequestTtl(int), Constant Field Values

REQID_MIN

public static final long REQID_MIN
The minimum request ID value.

See Also:
Constant Field Values

REQID_MAX

public static final long REQID_MAX
The maximum request ID value before it wraps to REQID_MIN.

See Also:
Constant Field Values
Constructor Detail

ClientSnacProcessor

public ClientSnacProcessor(FlapProcessor processor)
Creates a SNAC processor with no SNAC factories installed and the default request time-to-live, attached to the given FLAP processor.

Parameters:
processor - the FLAP processor to attach to
Method Detail

pause

public final void pause()
Pauses this SNAC processor. A paused SNAC processor does not send any SNAC commands to the server until a call to unpause(). Note that if this method is called while the processor is already paused, no action will be taken. Note that SNAC commands can still be sent while the processor is paused; however, they will not be sent to the server until unpausing.

See Also:
unpause(), isPaused(), PauseCmd

unpause

public final void unpause()
Unpauses this SNAC processor if previously paused with a call to pause(). SNAC commands sent during the paused period will begin to be sent to the server (depending on the implementation of the queue manager).

See Also:
pause(), isPaused(), ResumeCmd

isPaused

public final boolean isPaused()
Returns whether this SNAC processor is currently paused.

Returns:
whether this SNAC processor is currently paused
See Also:
pause()

migrate

public final void migrate(FlapProcessor processor)
Attaches to the given FLAP processor without clearing any SNAC queues. Effectively "moves" this SNAC connection transparently to the given processor. Note that if this processor is paused, a call to migrate will not unpause it. Unpausing must be done explicitly with a call to unpause().

Overrides:
migrate in class AbstractSnacProcessor
Parameters:
processor - a new FLAP processor to use for this SNAC connection
See Also:
MigrationNotice

addGlobalRequestListener

public final void addGlobalRequestListener(OutgoingSnacRequestListener l)
Adds a global request listener to listen for outgoing SNAC requests sent on this connection. The given listener will be used as if it had been manually added to each outgoing request.

Parameters:
l - the listener to add

removeGlobalRequestListener

public final void removeGlobalRequestListener(OutgoingSnacRequestListener l)
Removes a global request listener from the list of listeners.

Parameters:
l - the listener to remove

addGlobalResponseListener

public final void addGlobalResponseListener(SnacResponseListener l)
Adds a "global response listener" to listen for incoming SNAC request responses. The given listener will be notified of any incoming responses to previously sent outgoing SNAC requests. See above for details on when global response listeners' event handling methods are called.

Parameters:
l - the listener to add

removeGlobalResponseListener

public final void removeGlobalResponseListener(SnacResponseListener l)
Removes a "global response listener" from the list of listeners.

Parameters:
l - the listener to remove

setSnacQueueManager

public final void setSnacQueueManager(SnacQueueManager mgr)
Sets this SNAC processor's SNAC queue manager. A SNAC queue manager has almost complete control over when individual SNAC commands are actually sent to the server. If mgr is null, as is the default value, all SNACs will be sent to the server immediately (the queue manager will be set to an ImmediateSnacQueueManager)

Parameters:
mgr - the new SNAC queue manager, or null to send all SNACs immediately

unsetSnacQueueManager

public final void unsetSnacQueueManager(SnacQueueManager mgr)
Calls setSnacQueueManager(null) if and only if the given mgr is the current SNAC queue manager. If the given SNAC queue manager is not the current SNAC queue manager, no change takes place.

Parameters:
mgr - the SNAC queue manager to unset, if set

getSnacQueueManager

public final SnacQueueManager getSnacQueueManager()
Returns this SNAC processor's current SNAC queue manager. Note that this value will never be null, even after an explicit call to setSnacQueueManager(null). See that method's documentation for details.

Returns:
this SNAC processor's current SNAC queue manager

setRequestTtl

public void setRequestTtl(int requestTtl)
Sets the "time to live" for SNAC requests, in seconds. After roughly this amount of time, SNAC requests will be removed from the request list, and any future responses will be processed as if they were normal SnacPackets and not responses to requests.

Note that this value must be at least zero. A value of zero enables several special cases to use less memory and CPU time involved in sending SNAC requests. A value of zero also means that SNAC requests' listeners will never be called with responses, as request ID's are not stored at all. Additionally, with a value of zero, SNAC requests' listeners will never be called with timeout events, as all requests will "time out" immediately.

Parameters:
requestTtl - the new "time to live" for SNAC requests, in seconds

getRequestTtl

public int getRequestTtl()
Returns the current "time to live" for SNAC requests, in seconds.

Returns:
the current SNAC request "time to live"

sendSnac

public final void sendSnac(SnacRequest request)
Sends the given SnacRequest to the attached FLAP connection. It may not immediately be sent in future releases due to possible features such as rate limiting prevention.

Parameters:
request - the SNAC request to send

sendSnacImmediately

public final void sendSnacImmediately(SnacRequest request)
Sends the given SNAC request to the server, bypassing the SNAC request queue and any pausing status that may be present. Note that using this method for normal SNAC command sending is not recommended for the reasons above.

Parameters:
request - the request to send
See Also:
setSnacQueueManager(net.kano.joscar.snac.SnacQueueManager)

detach

public final void detach()
Detaches from the currently attached FLAP processor, if any. This method effectively resets this SNAC processor, causing any information about the current connection such as queued SNAC commands or SNAC request ID's to be discarded. This method is thus not useful for migrating. Note that this processor will be unpaused if it is currently paused.

Overrides:
detach in class AbstractSnacProcessor
See Also:
migrate(net.kano.joscar.flap.FlapProcessor)

continueHandling

protected final boolean continueHandling(SnacPacketEvent event)
Description copied from class: AbstractSnacProcessor
Returns whether or not the given SNAC packet event should be passed to packet listeners. Note that when this method is called, preprocessors have already been invoked. (Note that the default implementation always returns true.)

Overrides:
continueHandling in class AbstractSnacProcessor
Parameters:
event - the event
Returns:
whether or not the given SNAC packet event should be passed to vetoable and normal packet listeners