net.kano.joscar.rv
Interface RvSession


public interface RvSession

Represents a single "rendezvous session."

Briefly, every rendezvous command sent between two buddies contains a "session ID" which is used to group a set of commands logically. For example, consider a situation where Alice sends Bob a file send request, Bob sends an acceptance command back, and then halfway through getting the file Bob cancels the file transfer, sending a rejection command. Each of the request, acceptance, and rejection commands are rendezvous commands, and each command contains the same "session ID" as the initial file send request Alice sent.

These "sessions" are never formally created or ended on the OSCAR protocol level, but this author decided creating a class for it would be the best way to do it. Thus, to send a rendezvous using a RvProcessor, first one must create a new RvSession (see RvProcessor.createRvSession(java.lang.String)) and then send the RV commands through that.

You may ask why something so obviously functional and not prone to extension is an interface. I did this for two reasons: firstly, an RV session is a very abstract thing -- as I said earlier, sessions are never created or destroyed formally in the OSCAR protocol. Secondly, I did it to avoid what would otherwise be the tediously long type name RvProcessor.RvSession. Besides, RV sessions shouldn't necessarily be so deeply intertwined with RV processors as to force their association by using that type name.


Method Summary
 void addListener(RvSessionListener l)
          Adds a listener for incoming events on this session.
 RvProcessor getRvProcessor()
          Returns the RV processor on which this session resides.
 long getRvSessionId()
          Returns the RV session ID of this session.
 java.lang.String getScreenname()
          Returns the screenname of the user with whom this session exists.
 void removeListener(RvSessionListener l)
          Removes the given listener from this session's listener list.
 void sendResponse(int code)
          Sends the given RV response code to the user with whom this session exists.
 void sendRv(RvCommand command)
          Sends the given RV command to the user with whom this session exists, with an ICBM message ID of 0.
 void sendRv(RvCommand command, long icbmMessageId)
          Sends the given RV command to the user with whom this session exists, giving the outgoing RV ICBM the given message ID.
 

Method Detail

addListener

public void addListener(RvSessionListener l)
Adds a listener for incoming events on this session.

Parameters:
l - the listener to add

removeListener

public void removeListener(RvSessionListener l)
Removes the given listener from this session's listener list.

Parameters:
l - the listener to remove

getRvProcessor

public RvProcessor getRvProcessor()
Returns the RV processor on which this session resides.

Returns:
the RV processor on which this session resides.

getRvSessionId

public long getRvSessionId()
Returns the RV session ID of this session.

Returns:
this session's RV session ID

getScreenname

public java.lang.String getScreenname()
Returns the screenname of the user with whom this session exists.

Returns:
the screenname of the user with whom this session exists

sendRv

public void sendRv(RvCommand command)
Sends the given RV command to the user with whom this session exists, with an ICBM message ID of 0.

Note that calling this method will have no effect if the underlying RvProcessor is not currently attached to a SNAC connection. See RvProcessor.attachToSnacProcessor(net.kano.joscar.snac.ClientSnacProcessor) for details.

Parameters:
command - the RV command to send
See Also:
SendRvIcbm, sendRv(RvCommand, long)

sendRv

public void sendRv(RvCommand command,
                   long icbmMessageId)
Sends the given RV command to the user with whom this session exists, giving the outgoing RV ICBM the given message ID.

Note that calling this method will have no effect if the underlying RvProcessor is not currently attached to a SNAC connection. See RvProcessor.attachToSnacProcessor(net.kano.joscar.snac.ClientSnacProcessor) for details.

Parameters:
command - the RV command to send
icbmMessageId - an ICBM message ID for the outgoing RV ICBM
See Also:
SendRvIcbm, sendRv(RvCommand)

sendResponse

public void sendResponse(int code)
Sends the given RV response code to the user with whom this session exists. Note that calling this method will have no effect if the underlying RvProcessor is not currently attached to a SNAC connection. See RvProcessor.attachToSnacProcessor(net.kano.joscar.snac.ClientSnacProcessor) for details.

Parameters:
code - the RV response code to send
See Also:
RvResponse