net.kano.joscar.snac
Class SnacRequest

java.lang.Object
  extended bySnacRequest

public class SnacRequest
extends java.lang.Object

Encapsulates a single outgoing SNAC request and its corresponding incoming responses. See ClientSnacProcessor for details on the request system. The general procedure for using a SnacRequest is to create a SnacRequest containing the outgoing request you want to send to the server; adding one or more listeners for future responses; and sending the request over a SNAC connection with a ClientSnacProcessor's sendSnac method. Your SnacRequestListener (or SnacRequestAdapter) is notified when the request is sent, when it receives a response, and when it "times out."

When a request "times out," it is removed from its parent ClientSnacProcessor's request list. (This is done mainly for memory conservation reasons.) If a response to the request is received after it has "timed out," it will be processed as a normal SNAC packet and not as a response to an outgoing request. The default time after which a request "times out" is, as of this writing, ten minutes, allowing a great deal of time for any response to be received. That "time to live" can be increased, however (or decreased), with ClientSnacProcessor's setRequestTtl method.

Note that a SnacRequest will pass any exceptions thrown during the processing of a SNAC-request-related event to the FlapProcessor on which the events were received via its handleException method, which will then pass it to any of your registered exception handlers. The exception type will be ERRTYPE_SNAC_RESPONSE_LISTENER; see its documentation for details.

SnacRequest logs to the Java Logging API namespace "net.kano.joscar.snac" on the level Level.FINER in order to, hopefully, ease the debugging of SNAC request processing code.


Field Summary
static java.lang.Object ERRTYPE_SNAC_RESPONSE_LISTENER
          An error type indicating that an exception was thrown during the processing of a SNAC request listener.
 
Constructor Summary
SnacRequest(SnacCommand command, SnacRequestListener listener)
          Creates a new SnacRequest for the given command and adds the given event listener to its listener list.
 
Method Summary
 void addListener(SnacRequestListener l)
          Adds a listener for responses and other events related to this request.
 SnacCommand getCommand()
          Returns the SnacCommand that comprises the actual outgoing "request" to the OSCAR server.
 SnacResponseEvent[] getResponses()
          Returns the responses received thus far to this request.
 long getSentTime()
          Returns the time at which this request was sent.
 boolean hasListeners()
          Returns true if there are currently listeners listening for events related to this request.
 boolean isStoringResponses()
          Returns whether this request object is currently set to store responses received for this request.
 void removeListener(SnacRequestListener l)
          Removes an event listener from this request's event listener list.
 void setStoringResponses(boolean storingResponses)
          Sets whether to store responses to this request in this object.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ERRTYPE_SNAC_RESPONSE_LISTENER

public static final java.lang.Object ERRTYPE_SNAC_RESPONSE_LISTENER
An error type indicating that an exception was thrown during the processing of a SNAC request listener. In this case, the "reason" (the value returned by getReason()) will be the SnacRequestListener which threw the exception.

Constructor Detail

SnacRequest

public SnacRequest(SnacCommand command,
                   SnacRequestListener listener)
Creates a new SnacRequest for the given command and adds the given event listener to its listener list.

Parameters:
command - the outgoing SNAC command that comprises the outgoing "request" to the server
listener - a listener for responses and other events related to this request, or null to ignore responses
Method Detail

addListener

public final void addListener(SnacRequestListener l)
Adds a listener for responses and other events related to this request.

Parameters:
l - the listener to add

removeListener

public final void removeListener(SnacRequestListener l)
Removes an event listener from this request's event listener list.

Parameters:
l - the listener to remove

hasListeners

public final boolean hasListeners()
Returns true if there are currently listeners listening for events related to this request. Returns false if there are no listeners associated with this request.

Returns:
whether there are listeners associated with this request

getCommand

public final SnacCommand getCommand()
Returns the SnacCommand that comprises the actual outgoing "request" to the OSCAR server.

Returns:
the outgoing SnacCommand associated with this request

isStoringResponses

public boolean isStoringResponses()
Returns whether this request object is currently set to store responses received for this request. This value defaults to false.

Returns:
whether responses to this request are being stored
See Also:
getResponses()

setStoringResponses

public void setStoringResponses(boolean storingResponses)
Sets whether to store responses to this request in this object. Defaults to false.

Parameters:
storingResponses - whether to store responses to this request.
See Also:
getResponses()

getSentTime

public final long getSentTime()
Returns the time at which this request was sent. The value returned is in the format returned by System.currentTimeMillis, or milliseconds since the unix epoch.

Returns:
the time at which this request was sent

getResponses

public final SnacResponseEvent[] getResponses()
Returns the responses received thus far to this request. Will always be empty unless setStoringResponses(true) has been called on this object.

Returns:
the responses received thus far for this request
See Also:
setStoringResponses(boolean)

toString

public java.lang.String toString()