net.kano.joscar.rv
Class RvProcessor

java.lang.Object
  RvProcessor

public class RvProcessor

extends java.lang.Object

Provides an easy interface for creating and manipulating "rendezvous sessions" as well as sending and receiving individual rendezvous commands nested in RV ICBM's.

This class manages rendezvous "sessions" as follows. Every rendezvous command contains a unique session ID. For example, if you attempt to send a file to someone, and that person rejects the file transfer, each of those commands will (normally) contain the same session ID, as they pertain to the same "session": the file transfer you initiated. This class recognizes such sessions and creates appropriate RvSession instances for each new rendezvous session created. It is certainly possible to use rendezvous sessions without using a RvProcessor, but this class attempts to make session management and RvCommand generation simpler and somewhat transparent to the developer.

This class will generate exceptions in the attached SNAC processor's attached FLAP processor's exception handler should any exceptions occur when running callbacks or RV command factory methods.

Exception type	Meaning	Reason object
ERRTYPE_RV_CMD_GEN	This type indicates that an exception was thrown when attempting to convert an incoming RV ICBM to a RvCommand using a RvCommandFactory's genRvCommand method.	The reason object in this case will be the RecvRvIcbm whose attempted processing caused the given exception.
ERRTYPE_RV_LISTENER	This type indicates that an exception was thrown when calling a method of a RvProcessorListener.	The reason object in this case will be the RvProcessorListener which threw the exception.
ERRTYPE_RV_SESSION_LISTENER	This type indicates that an exception was thrown when calling a method of a RvSessionListener attached to a specific RvSession.	The reason object in this case is the RvSessionListener that threw the exception.

When attached to a ClientSnacProcessor, an instance of this class will intercept all RecvRvIcbms and all RvResponses. After attaching an RV processor to a given SNAC processor, that SNAC processor's packet listeners will no longer receive packet events for either of these two commands (until detaching the RV processor).

Note that if an RvProcessor is not attached to a SNAC processor, all attempts at sending rendezvous commands and responses (via RvSession.sendRv(net.kano.joscar.snaccmd.icbm.RvCommand) and RvSession.sendResponse(int) will be quietly ignored.

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

Field Summary

static java.lang.Object	ERRTYPE_RV_CMD_GEN A FLAP exception handler error type indicating that an exception was thrown when generating a RvCommand with an attached RvCommandFactory.
static java.lang.Object	ERRTYPE_RV_LISTENER A FLAP exception handler error type indicating that an exception was thrown when calling a method of an attached RvProcessorListener.
static java.lang.Object	ERRTYPE_RV_SESSION_LISTENER A FLAP exception handler error type indicating that an exception was thrown when calling a method of an RvSessionListener attached to an RvSession.

Constructor Summary

RvProcessor()
Creates a RV processor which is not attached to any SNAC processor and which contains no RvCommand factories or new session listeners.

RvProcessor(ClientSnacProcessor snacProcessor)
Creates a RV processor attached to the given SNAC processor and which contains no RvCommand factories or new session listeners.

Method Summary

void	addListener(RvProcessorListener l) Adds the given RV processor listener to this processor's listener list.
void	attachToSnacProcessor(ClientSnacProcessor snacProcessor) "Attaches" this RV processor to the given SNAC processor.
RvSession	createRvSession(java.lang.String sn) Creates a new "outgoing" rendezvous session with the given user and a new unique session ID.
RvSession	createRvSession(java.lang.String sn, long sessionID) Creates a new "outgoing" rendezvous session with the given user and the given session ID.
void	detach() "Detaches" this RV processor from the currently attached SNAC processor, if any.
RvCommandFactory	getRegisteredRvCmdFactory(CapabilityBlock cap) Returns the RvCommand factory that is registered for the given capability (rendezvous type).
ClientSnacProcessor	getSnacProcessor() Returns the SNAC processor to which this RV processor is currently attached, or null if none is attached.
void	registerRvCmdFactory(CapabilityBlock cap, RvCommandFactory factory) Registers the given RvCommand factory for the given capability (that is, RV type).
void	registerRvCmdFactory(RvCommandFactory factory) Registers a new RvCommand factory with this RvProcessor.
void	removeListener(RvProcessorListener l) Removes the given RV processor from this processor's listener list, if present.
void	unregisterRvCmdFactory(CapabilityBlock cap, RvCommandFactory factory) Unregisters the given RV command factory for the given RV type (capability).
void	unregisterRvCmdFactory(RvCommandFactory factory) Unregisters the given RV command factory for all RV types for which it is currently registered.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ERRTYPE_RV_CMD_GEN

public static final java.lang.Object ERRTYPE_RV_CMD_GEN

A FLAP exception handler error type indicating that an exception was thrown when generating a RvCommand with an attached RvCommandFactory. See above for details.

ERRTYPE_RV_LISTENER

public static final java.lang.Object ERRTYPE_RV_LISTENER

A FLAP exception handler error type indicating that an exception was thrown when calling a method of an attached RvProcessorListener. See above for details.

ERRTYPE_RV_SESSION_LISTENER

public static final java.lang.Object ERRTYPE_RV_SESSION_LISTENER

A FLAP exception handler error type indicating that an exception was thrown when calling a method of an RvSessionListener attached to an RvSession. See above for details.

Constructor Detail

RvProcessor

public RvProcessor()

Creates a RV processor which is not attached to any SNAC processor and which contains no RvCommand factories or new session listeners.

RvProcessor

public RvProcessor(ClientSnacProcessor snacProcessor)

Creates a RV processor attached to the given SNAC processor and which contains no RvCommand factories or new session listeners.

Parameters:

snacProcessor - the SNAC processor to which to attach

See Also:

attachToSnacProcessor(net.kano.joscar.snac.ClientSnacProcessor)

Method Detail

getSnacProcessor

public final ClientSnacProcessor getSnacProcessor()

Returns the SNAC processor to which this RV processor is currently attached, or null if none is attached.

Returns:

the SNAC processor to which this RV processor is currently attached

attachToSnacProcessor

public final void attachToSnacProcessor(ClientSnacProcessor snacProcessor)

"Attaches" this RV processor to the given SNAC processor. See above for details on attaching. Note that calling this method implies a call to detach(); that is, an RV processor cannot be attached to more than one SNAC processor.

Parameters:

snacProcessor - the SNAC processor to which this RV processor should attach

See Also:

detach()

detach

public final void detach()

"Detaches" this RV processor from the currently attached SNAC processor, if any. This RV processor will stop intercepting packet events from the currently attached processor and sending rendezvous commands will be disabled until a new SNAC processor is attached.

addListener

public final void addListener(RvProcessorListener l)

Adds the given RV processor listener to this processor's listener list.

Parameters:

l - the RV processor listener to add

removeListener

public final void removeListener(RvProcessorListener l)

Removes the given RV processor from this processor's listener list, if present.

Parameters:

l - the listener to remove

registerRvCmdFactory

public final void registerRvCmdFactory(RvCommandFactory factory)

Registers a new RvCommand factory with this RvProcessor. The given factory will be used to generate RvCommands for incoming rendezvouses of the types specified in its supported capabilities.

Parameters:

factory - the RV command factory to register

registerRvCmdFactory

public final void registerRvCmdFactory(CapabilityBlock cap,
                                       RvCommandFactory factory)

Registers the given RvCommand factory for the given capability (that is, RV type). The given factory will be used to generate RvCommands from incoming RV packets of the given type (capability). Note that if cap is null, the given factory will be used as a "fallback" factory, being used to generate commands whose types (capabilities) have no associated factory.

Parameters:

cap - the "type" or "capability" for which the given factory should be used, or null to handle all types for which a factory is not explicitly defined

factory - the RV command factory to use for the given rendezvous type

getRegisteredRvCmdFactory

public final RvCommandFactory getRegisteredRvCmdFactory(CapabilityBlock cap)

Returns the RvCommand factory that is registered for the given capability (rendezvous type). If cap is null, the "fallback factory" is returned. See above for details.

Note that even if a "fallback factory" is set, null will be returned if no factory is explicitly registered for the given type (unless, of course, cap is null, as stated above).

Parameters:

cap - the capability (rendezvous type) whose registered RV command factory should be returned, or null to return the "fallback factory"

Returns:

the RvCommandFactory registered for the given RV type, or null if no factory is registered for that type

unregisterRvCmdFactory

public final void unregisterRvCmdFactory(RvCommandFactory factory)

Unregisters the given RV command factory for all RV types for which it is currently registered.

Parameters:

factory - the RV command factory to fully unregister

unregisterRvCmdFactory

public final void unregisterRvCmdFactory(CapabilityBlock cap,
                                         RvCommandFactory factory)

Unregisters the given RV command factory for the given RV type (capability). If the given factory is not registered for the given RV type, no change will take place. If cap is null, the given factory is unregistered as the "fallback factory" (if, of course, it is currently the fallback factory). See above for details.

Parameters:

cap - the RV type for which the given factory should be unregistered

factory - the factory that should be unregistered from the given RV type

createRvSession

public final RvSession createRvSession(java.lang.String sn)

Creates a new "outgoing" rendezvous session with the given user and a new unique session ID. The session is only "outgoing" in that it was created locally, and the first command will probably be outgoing. Note that when this method is called a new NewRvSessionEvent of type TYPE_OUTGOING will be fired.

Parameters:

sn - the screenname of the user with whom to create a new session

Returns:

a new RvSession with the given user

createRvSession

public final RvSession createRvSession(java.lang.String sn,
                                       long sessionID)

Creates a new "outgoing" rendezvous session with the given user and the given session ID. The session is only "outgoing" in that it was created locally, and the first command will probably be outgoing. Note that when this method is called a new NewRvSessionEvent of type TYPE_OUTGOING will be fired.

Parameters:

sn - the screenname of the user with whom to create a new session

sessionID - a session ID number to use for the created session

Returns:

a new RvSession with the given user