net.kano.joscar.snac
Class AbstractSnacProcessor

java.lang.Object
  extended byAbstractSnacProcessor
Direct Known Subclasses:
ClientSnacProcessor, ServerSnacProcessor

public abstract class AbstractSnacProcessor
extends java.lang.Object

Provides an easy interface to listening for incoming SNAC packets as well as sending SNAC commands over a FLAP connection. An AbstractSnacProcessor provides a system for "preprocessing" SNAC's before they are formally handled and processed and a system for listening for incoming packets (and optionally "vetoing" their further processing).

AbstractSnacProcessor passes two 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 error types used are ERRTYPE_SNAC_PACKET_PREPROCESSOR and ERRTYPE_SNAC_PACKET_LISTENER. See individual documentation for each for further detail.

It may also be of interest to note that AbstractSnacProcessor attaches a vetoable packet listener to any attached FlapProcessor, effectively removing any incoming SNAC packet from the FlapProcessor's event queue. In practice this means that if you attach a SNAC processor to a FlapProcessor on which you are listening for FLAP packets, your packet listener will not be called when a channel-2 packet (SNAC packet) is received on that FlapProcessor. Instead, it will be processed as a SnacPacket and passed to any listeners on the SNAC processor.

Upon receipt of a SNAC packet, the packet is processed in the following order:

  1. It is passed through all registered SNAC preprocessors
  2. A SnacCommand is generated (see below)
  3. An event is passed to the subclass, like ClientSnacProcessor or ServerSnacProcessor; see the subclasses' documentation for details
  4. An event is passed to each of the registered vetoable packet listeners, halting immediately if a listener says to
  5. If no vetoable listener has halted processing, an event is next passed to all registered non-vetoable (that is, normal SnacPacketListener) packet listeners.
The process of generating a SnacCommand from a SnacPacket is as such:
  1. First, a suitable SnacCmdFactory must be found
    1. If a factory is registered for the exact command type (SNAC family and command ("subtype")) of the received packet, then that factory is used
    2. Otherwise, if a factory is registered for the entire SNAC family of the received packet (via registerSnacFactory(new CmdType(family), factory), for example), that factory is used
    3. Otherwise, if a factory is registered for all commands (via registerSnacFactory(CmdType.CMDTYPE_ALL, factory), for example), then that factory is used
    4. Otherwise, if a default SNAC factory list is set and not null, the above three steps are repeated for the factories registered by the default factory list
  2. If a factory has been found, a SnacCommand is generated with a call to the factory's genSnacCommand method
The above system allows one to customize the SnacCommands passed to your packet listeners, in order to, for example, process an extra field in a certain command that has been added to the protocol since this library's release. This can be done by registering your own SNAC command factories with the appropriate command types (see CmdFactoryMgr and getCmdFactoryMgr).

AbstractSnacProcessor 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_PACKET_LISTENER
          An error type indicating that an exception was thrown while calling a registered SNAC packet listener or vetoable packet listener to handle an incoming SNAC packet.
static java.lang.Object ERRTYPE_SNAC_PACKET_PREPROCESSOR
          An error type indicating that an exception was thrown while calling a registered SNAC preprocessor to process an incoming SNAC packet.
 
Constructor Summary
protected AbstractSnacProcessor(FlapProcessor flapProcessor)
          Creates a new SNAC processor attached to the given FLAP processor.
 
Method Summary
 void addPacketListener(SnacPacketListener l)
          Adds a packet listener to listen for incoming SNAC packets.
 void addPreprocessor(SnacPreprocessor p)
          Adds a SNAC preprocessor to the list of preprocessors.
 void addVetoablePacketListener(VetoableSnacPacketListener l)
          Adds a vetoable packet listener to this SNAC processor.
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 current FLAP processor without clearing any queued SNAC requests.
 CmdFactoryMgr getCmdFactoryMgr()
          Returns this SNAC processor's SNAC command factory manager.
 FlapProcessor getFlapProcessor()
          Returns the FLAP processor to which this SNAC processor is attached.
 boolean isAttached()
          Returns whether this SNAC processor is attached to its FLAP processor.
protected  void migrate(FlapProcessor processor)
          "Reattaches" or "migrates" to the given FLAP processor.
 void removePacketListener(SnacPacketListener l)
          Removes a packet listener from the list of listeners.
 void removePreprocessor(SnacPreprocessor p)
          Removes a SNAC preprocessor from the list of SNAC preprocessors.
 void removeVetoablePacketListener(VetoableSnacPacketListener l)
          Removes a vetoable packet listener from the list of listeners.
protected  void sendSnac(long reqid, SnacCommand cmd)
          Sends the given SNAC command with the given SNAC request ID over the currently attached FLAP processor.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ERRTYPE_SNAC_PACKET_PREPROCESSOR

public static final java.lang.Object ERRTYPE_SNAC_PACKET_PREPROCESSOR
An error type indicating that an exception was thrown while calling a registered SNAC preprocessor to process an incoming SNAC packet. In this case, the extra error information (the value returned by getReason()) will be the SnacPreprocessor that threw the exception.


ERRTYPE_SNAC_PACKET_LISTENER

public static final java.lang.Object ERRTYPE_SNAC_PACKET_LISTENER
An error type indicating that an exception was thrown while calling a registered SNAC packet listener or vetoable packet listener to handle an incoming SNAC packet. In this case, the extra error information (the value returned by getReason()) will be the VetoableFlapPacketListener or FlapPacketListener from whence the exception was thrown.

Constructor Detail

AbstractSnacProcessor

protected AbstractSnacProcessor(FlapProcessor flapProcessor)
Creates a new SNAC processor attached to the given FLAP processor.

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

migrate

protected void migrate(FlapProcessor processor)
"Reattaches" or "migrates" to the given FLAP processor. This method intends to leave the "old" FLAP processor as it was before this SNAC processor attached to it, and to leave this SNAC processor as if it had originally been attached to the given processor.

Parameters:
processor - the FLAP processor to which to migrate

getFlapProcessor

public final FlapProcessor getFlapProcessor()
Returns the FLAP processor to which this SNAC processor is attached.

Returns:
this SNAC processor's FLAP processor

isAttached

public final boolean isAttached()
Returns whether this SNAC processor is attached to its FLAP processor. (An attached SNAC processor handles SNAC FLAP packets.)

Returns:
whether this SNAC processor is attached to its FLAP processor
See Also:
detach()

detach

public void detach()
Detaches from the current FLAP processor without clearing any queued SNAC requests.


addPacketListener

public final void addPacketListener(SnacPacketListener l)
Adds a packet listener to listen for incoming SNAC packets.

Parameters:
l - the listener to add

removePacketListener

public final void removePacketListener(SnacPacketListener l)
Removes a packet listener from the list of listeners.

Parameters:
l - the listener to remove

addVetoablePacketListener

public final void addVetoablePacketListener(VetoableSnacPacketListener l)
Adds a vetoable packet listener to this SNAC processor. A vetoable SNAC packet listener has the ability to halt the processing of a given packet upon its receipt.

Parameters:
l - the listener to add.

removeVetoablePacketListener

public final void removeVetoablePacketListener(VetoableSnacPacketListener l)
Removes a vetoable packet listener from the list of listeners.

Parameters:
l - the listener to remove

addPreprocessor

public final void addPreprocessor(SnacPreprocessor p)
Adds a SNAC preprocessor to the list of preprocessors. Preprocessors are the first listeners called when a SNAC packet arrives, and are allowed to modify the contents of a packet.

Parameters:
p - the preprocessor to add

removePreprocessor

public final void removePreprocessor(SnacPreprocessor p)
Removes a SNAC preprocessor from the list of SNAC preprocessors.

Parameters:
p - the preprocessor to remove

getCmdFactoryMgr

public final CmdFactoryMgr getCmdFactoryMgr()
Returns this SNAC processor's SNAC command factory manager.

Returns:
this SNAC processor's SNAC command factory manager

continueHandling

protected boolean continueHandling(SnacPacketEvent event)
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.)

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

sendSnac

protected final void sendSnac(long reqid,
                              SnacCommand cmd)
Sends the given SNAC command with the given SNAC request ID over the currently attached FLAP processor.

Parameters:
reqid - the request ID of the SNAC packet to send
cmd - the SNAC command to use in generating the SNAC packet