net.kano.joscar.flap
Class FlapProcessor

java.lang.Object
  extended byConnProcessor
      extended byFlapProcessor

public class FlapProcessor
extends ConnProcessor

Represents a FLAP connection that manages an outgoing FLAP queue as well as parsing and processing incoming FLAP packets. A FlapProcessor can be attached to any pair of input and output streams, allowing one to read and write FLAP commands to almost any source and destination. For an easier way to use the most common source and destination, a TCP socket, see ClientFlapConn.

FlapProcessor uses the Java Logging API namespace "net.kano.joscar.flap", logging various events at the levels Level.CONFIG, Level.FINE, and Level.FINER, in order to, hopefully, ease the debugging of FLAP-related applications. For more information on how to log such events, consult the Java Logging API reference at the J2SE website.

Note that upon receipt of a FLAP packet, an event is passed to each of the registered vetoable listeners first, halting immediately if a listener says to halt processing. If a vetoable listener has not halted processing, an event is next passed to each of the registered non-vetoable (that is, normal FlapPacketListener) listeners.

Note that a new instance of FlapProcessor does not come with any FLAP command factory installed! You are advised to install an instance of DefaultFlapCmdFactory (or your own custom factory).

See Also:
ClientFlapConn

Constructor Summary
FlapProcessor()
          Creates a FLAP processor with the default FLAP command factory and not yet attached to an input or output stream.
FlapProcessor(java.net.Socket socket)
          Creates a FLAP processor with the default FLAP command factory and attaches it to the given socket.
 
Method Summary
 void addExceptionHandler(FlapExceptionHandler handler)
          Adds an exception handler for FLAP-related exceptions.
 void addPacketListener(FlapPacketListener listener)
          Adds a FLAP packet listener to this FLAP processor.
 void addVetoablePacketListener(VetoableFlapPacketListener listener)
          Adds a "vetoable packet listener."
 void handleException(java.lang.Object type, java.lang.Throwable t)
          Processes the given exception with the given error type.
 void handleException(java.lang.Object type, java.lang.Throwable t, java.lang.Object info)
          Processes the given exception with the given error type and error detail info.
 boolean readNextFlap()
          Reads and processes a single FLAP packet from the attached input stream.
 void removeExceptionHandler(FlapExceptionHandler handler)
          Removes an exception handler from this FLAP processor.
 void removePacketListener(FlapPacketListener listener)
          Removes a FLAP packet listener from this FLAP processor.
 void removeVetoablePacketListener(VetoableFlapPacketListener listener)
          Removes the given vetoable packet listener from this FLAP processor's list of vetoable packet listeners.
 void runFlapLoop()
          A utility method to read FLAP packets indefinitely (that is, until the end of the stream is reached or an I/O error occurs).
 void sendFlap(FlapCommand command)
          Sends the given FLAP command on this FLAP processor's attached output stream.
 void setFlapCmdFactory(FlapCommandFactory factory)
          Sets the FLAP command factory to use for generating FlapCommands from FLAP packets.
 
Methods inherited from class ConnProcessor
attachToInput, attachToOutput, attachToSocket, detach, getInputStream, getOutputStream, isAttached
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FlapProcessor

public FlapProcessor()
Creates a FLAP processor with the default FLAP command factory and not yet attached to an input or output stream.


FlapProcessor

public FlapProcessor(java.net.Socket socket)
              throws java.io.IOException
Creates a FLAP processor with the default FLAP command factory and attaches it to the given socket.

Note that this does not begin any sort of loop or FLAP connection; you still need to do this yourself (see readNextFlap() and runFlapLoop().

Parameters:
socket - the connected socket to which this FLAP processor should be attached
Throws:
java.io.IOException - if an I/O exception occurs while attaching to the socket
See Also:
ConnProcessor.attachToSocket(java.net.Socket)
Method Detail

addVetoablePacketListener

public final void addVetoablePacketListener(VetoableFlapPacketListener listener)
Adds a "vetoable packet listener." A vetoable packet listener has the ability to halt the processing of a given FLAP.

Parameters:
listener - the listener to add

removeVetoablePacketListener

public final void removeVetoablePacketListener(VetoableFlapPacketListener listener)
Removes the given vetoable packet listener from this FLAP processor's list of vetoable packet listeners.

Parameters:
listener - the listener to remove

addPacketListener

public final void addPacketListener(FlapPacketListener listener)
Adds a FLAP packet listener to this FLAP processor.

Parameters:
listener - the listener to add

removePacketListener

public final void removePacketListener(FlapPacketListener listener)
Removes a FLAP packet listener from this FLAP processor.

Parameters:
listener - the listener to remove

addExceptionHandler

public final void addExceptionHandler(FlapExceptionHandler handler)
Adds an exception handler for FLAP-related exceptions.

Parameters:
handler - the handler to add

removeExceptionHandler

public final void removeExceptionHandler(FlapExceptionHandler handler)
Removes an exception handler from this FLAP processor.

Parameters:
handler - the handler to remove

setFlapCmdFactory

public final void setFlapCmdFactory(FlapCommandFactory factory)
Sets the FLAP command factory to use for generating FlapCommands from FLAP packets. This can be null, disabling the generation of FlapCommands.

Parameters:
factory - the new factory to use, or null to disable the generation of FlapCommands on this connection

handleException

public final void handleException(java.lang.Object type,
                                  java.lang.Throwable t)
Processes the given exception with the given error type. This exception will be passed to all registered exception handlers. Calling this method is equivalent to calling handleException(type, t, null).

Parameters:
type - an object representing the type or source of the given exception
t - the exception that was thrown
See Also:
addExceptionHandler(net.kano.joscar.flap.FlapExceptionHandler)

handleException

public final void handleException(java.lang.Object type,
                                  java.lang.Throwable t,
                                  java.lang.Object info)
Processes the given exception with the given error type and error detail info. This exception will be passed to all registered exception handlers.

Parameters:
type - an object representing the type or source of the given exception
t - the exception that was thrown
info - an object containing extra information or details on this exception and/or what caused it

sendFlap

public final void sendFlap(FlapCommand command)
Sends the given FLAP command on this FLAP processor's attached output stream. Note that if this processor is not currently attached to an output stream or socket, this method will return silently.

Parameters:
command - the command to send

runFlapLoop

public final void runFlapLoop()
                       throws java.io.IOException
A utility method to read FLAP packets indefinitely (that is, until the end of the stream is reached or an I/O error occurs).

Throws:
java.io.IOException - if an I/O error occurs

readNextFlap

public final boolean readNextFlap()
                           throws java.io.IOException
Reads and processes a single FLAP packet from the attached input stream. If this method returns false, it is safe to assume that the connection died.

Returns:
true if a packet was successfully read; false otherwise
Throws:
java.io.IOException - if an I/O error occurs