org.beepcore.beep.core
Class Session

java.lang.Object
  |
  +--org.beepcore.beep.core.Session
Direct Known Subclasses:
TCPSession

public abstract class Session
extends java.lang.Object

This class encapsulates the notion of a BEEP Session (a relationship between BEEP peers).

The implementor should sub-class Session's abstract methods for a given transport. It's principal function is to sit on whatever network or referential 'connection' exists between the BEEP peers, read and write BEEP frames and deliver them to or receive them from the associated Channel.

See Also:
Channel

Field Summary
static int SESSION_STATE_ABORTED
           
static int SESSION_STATE_ACTIVE
           
static int SESSION_STATE_CLOSE_PENDING
           
static int SESSION_STATE_CLOSED
           
static int SESSION_STATE_CLOSING
           
static int SESSION_STATE_GREETING_SENT
           
static int SESSION_STATE_INITIALIZED
           
static int SESSION_STATE_TUNING
           
static int SESSION_STATE_TUNING_PENDING
           
 
Constructor Summary
protected Session(ProfileRegistry registry, int firstChannel, SessionCredential localCred, SessionCredential peerCred, SessionTuningProperties tuning)
          Default Session Constructor.
 
Method Summary
 void addChannelListener(org.beepcore.beep.core.event.ChannelListener l)
          adds the listener from the list of listeners to be notified of future events.
 void addSessionListener(org.beepcore.beep.core.event.SessionListener l)
          adds the listener from the list of listeners to be notified of future events.
 void close()
          Closes the Session gracefully.
protected  Frame createFrame(byte[] header, int headerLength)
          This method is intended for use by tranport specific Sessions to create a new Frame object representing a BEEP MSG, RPY, ERR, or NUL frames.
protected abstract  void disableIO()
          Method disableIO
protected abstract  void enableIO()
          Method enableIO
protected  int getChannelAvailableWindow(int channel)
          Returns the channel's available window size.
protected  java.lang.String getChannelNumberAsString(Channel channel)
          Get the channel number as a String
 SessionCredential getLocalCredential()
          Get the local SessionCredential for this session.
protected abstract  int getMaxFrameSize()
          Returns the maximum frame size that a channel should send for this session.
 SessionCredential getPeerCredential()
          Get our peer's SessionCredential for this session.
 java.util.Collection getPeerSupportedProfiles()
          Returns the profiles sent by the remote peer in the greeting.
 ProfileRegistry getProfileRegistry()
          Returns the ProfileRegistry for Session.
 int getState()
          Returns the state of Session.
 SessionTuningProperties getTuningProperties()
           
protected  void init()
          Initializes the Session.
 boolean isInitiator()
          Indicates whehter or not this session is in the initiator role.
protected  void postFrame(Frame f)
          Method postFrame
 void removeChannelListener(org.beepcore.beep.core.event.ChannelListener l)
          Removes the listener from the list of listeners to be notified of future events.
 void removeSessionListener(org.beepcore.beep.core.event.SessionListener l)
          Removes the listener from the list of listeners to be notified of future events.
protected abstract  Session reset(SessionCredential localCred, SessionCredential peerCred, SessionTuningProperties tuning, ProfileRegistry registry, java.lang.Object argument)
          This method is used by a tuning profile to reset the session after the tuning is complete.
protected abstract  void sendFrame(Frame f)
          Implement this method to send frames and on the sub-classed transport.
protected  void setLocalCredential(SessionCredential cred)
          Method setLocalCredential
protected  void setPeerCredential(SessionCredential cred)
          Method setPeerCredential
protected  void setTuningProperties(SessionTuningProperties tuning)
          sets the tuning properties for this session
 Channel startChannel(java.util.Collection profiles, MessageListener listener)
          Sends a start channel request using the given list of profiles.
 Channel startChannel(java.lang.String profile)
          Sends a start channel request using the specified profile.
 Channel startChannel(java.lang.String profile, boolean base64Encoding, java.lang.String data, MessageListener listener)
          Sends a start channel request using the specified profile.
 Channel startChannel(java.lang.String profile, MessageListener listener)
          Sends a start channel request using the specified profile.
 void terminate(java.lang.String reason)
          This method is used to terminate the session when there is an non-recoverable error in the BEEP protocol (framing error, etc.).
protected  void tuningInit()
          A reentrant version of init() that doesn't block the first I/O thread waiting on a greeting when it should die and go away.
protected abstract  boolean updateMyReceiveBufferSize(Channel channel, long previouslySeq, long currentSeq, int previouslyUsed, int currentlyUsed, int bufferSize)
          This method is designed to allow for flow control across the multiplexed connection we have.
protected  void updatePeerReceiveBufferSize(int channelNum, long lastSeq, int size)
          Method updatePeerReceiveBufferSize
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SESSION_STATE_INITIALIZED

public static final int SESSION_STATE_INITIALIZED
See Also:
Constant Field Values

SESSION_STATE_GREETING_SENT

public static final int SESSION_STATE_GREETING_SENT
See Also:
Constant Field Values

SESSION_STATE_ACTIVE

public static final int SESSION_STATE_ACTIVE
See Also:
Constant Field Values

SESSION_STATE_TUNING_PENDING

public static final int SESSION_STATE_TUNING_PENDING
See Also:
Constant Field Values

SESSION_STATE_TUNING

public static final int SESSION_STATE_TUNING
See Also:
Constant Field Values

SESSION_STATE_CLOSE_PENDING

public static final int SESSION_STATE_CLOSE_PENDING
See Also:
Constant Field Values

SESSION_STATE_CLOSING

public static final int SESSION_STATE_CLOSING
See Also:
Constant Field Values

SESSION_STATE_CLOSED

public static final int SESSION_STATE_CLOSED
See Also:
Constant Field Values

SESSION_STATE_ABORTED

public static final int SESSION_STATE_ABORTED
See Also:
Constant Field Values
Constructor Detail

Session

protected Session(ProfileRegistry registry,
                  int firstChannel,
                  SessionCredential localCred,
                  SessionCredential peerCred,
                  SessionTuningProperties tuning)
           throws BEEPException
Default Session Constructor. A relationship between peers - a session - consists of a set of profiles they share in common, and an ordinality (to prevent new channel collision) so that the initiator starts odd channels and the listener starts channels with even numbers.

Parameters:
registry -
firstChannel - used internally in the API, an indication of the ordinality of the channels this peer can start, odd, or even.
Method Detail

init

protected void init()
             throws BEEPException
Initializes the Session. Initializes Channel Zero and its listener. Sends a greeting and waits for corresponding greeting.

Throws:
BEEPException

tuningInit

protected void tuningInit()
                   throws BEEPException
A reentrant version of init() that doesn't block the first I/O thread waiting on a greeting when it should die and go away.

Throws:
BEEPException

addChannelListener

public void addChannelListener(org.beepcore.beep.core.event.ChannelListener l)
adds the listener from the list of listeners to be notified of future events.

See Also:
removeChannelListener(org.beepcore.beep.core.event.ChannelListener)

addSessionListener

public void addSessionListener(org.beepcore.beep.core.event.SessionListener l)
adds the listener from the list of listeners to be notified of future events.

See Also:
removeSessionListener(org.beepcore.beep.core.event.SessionListener)

close

public void close()
           throws BEEPException
Closes the Session gracefully. The profiles for the open channels on the session may veto the close request.

Throws:
BEEPException

getLocalCredential

public SessionCredential getLocalCredential()
Get the local SessionCredential for this session.

Returns:
May return null if this session has not been authenticated

getPeerCredential

public SessionCredential getPeerCredential()
Get our peer's SessionCredential for this session.

Returns:
May return null if this session has not been authenticated

getPeerSupportedProfiles

public java.util.Collection getPeerSupportedProfiles()
Returns the profiles sent by the remote peer in the greeting.


getProfileRegistry

public ProfileRegistry getProfileRegistry()
Returns the ProfileRegistry for Session.

Returns:
A ProfileRegistry.
See Also:
ProfileRegistry

getState

public int getState()
Returns the state of Session.

Returns:
Session state (see the Constants in this class).

isInitiator

public boolean isInitiator()
Indicates whehter or not this session is in the initiator role.


removeChannelListener

public void removeChannelListener(org.beepcore.beep.core.event.ChannelListener l)
Removes the listener from the list of listeners to be notified of future events. Note that the listener will be notified of events which have already happened and are in the process of being dispatched.

See Also:
addChannelListener(org.beepcore.beep.core.event.ChannelListener)

removeSessionListener

public void removeSessionListener(org.beepcore.beep.core.event.SessionListener l)
Removes the listener from the list of listeners to be notified of future events. Note that the listener will be notified of events which have already happened and are in the process of being dispatched.

See Also:
addSessionListener(org.beepcore.beep.core.event.SessionListener)

startChannel

public Channel startChannel(java.lang.String profile)
                     throws BEEPException,
                            BEEPError
Sends a start channel request using the specified profile.

Parameters:
profile - The uri of the profile for the channel you wish to start.
Returns:
A Channel for the specified profile.
Throws:
BEEPError - Thrown if an error occurs in the under lying transport.
BEEPException - Thrown if any of the parameters are invalid, or if the profile is unavailable on this Session.

startChannel

public Channel startChannel(java.lang.String profile,
                            MessageListener listener)
                     throws BEEPException,
                            BEEPError
Sends a start channel request using the specified profile.

Parameters:
profile - The uri of the profile for the channel you wish to start.
listener - An implementation of MessageListener that is to receive message callbacks for this channel. It can be null, but don't expect to be called back.
Returns:
A Channel for the specified profile.
Throws:
BEEPError - Thrown if an error occurs in the under lying transport.
BEEPException - Thrown if any of the parameters are invalid, or if the profile is unavailable on this Session.
See Also:
MessageListener

startChannel

public Channel startChannel(java.lang.String profile,
                            boolean base64Encoding,
                            java.lang.String data,
                            MessageListener listener)
                     throws BEEPException,
                            BEEPError
Sends a start channel request using the specified profile.

Parameters:
profile - The uri of the profile for the channel you wish to start.
base64Encoding - Indicates whether or not the data is base64 encoded.
data - The associated data or initial element for the profile of the channel you wish to start.
listener - An implementation of MessageListener that is to receive message callbacks for this channel. It can be null, but don't expect to be called back.
Returns:
A Channel for the specified profile.
Throws:
BEEPError - Thrown if an error occurs in the under lying transport.
BEEPException - Thrown if any of the parameters are invalid, or if the profile is unavailable on this Session.
See Also:
MessageListener

startChannel

public Channel startChannel(java.util.Collection profiles,
                            MessageListener listener)
                     throws BEEPException,
                            BEEPError
Sends a start channel request using the given list of profiles.

Parameters:
profiles - A collection of StartChannelProfile(s).
listener - An implementation of MessageListener that is to receive message callbacks for this channel. It can be null, but don't expect to be called back.
Returns:
a started channel for the profile selected by the listener
Throws:
BEEPError - Thrown if an error occurs in the under lying transport.
BEEPException - Thrown if any of the parameters are invalid, or if the profile is unavailable on this Session.
See Also:
StartChannelProfile, MessageListener

terminate

public void terminate(java.lang.String reason)
This method is used to terminate the session when there is an non-recoverable error in the BEEP protocol (framing error, etc.).

Parameters:
reason -

createFrame

protected Frame createFrame(byte[] header,
                            int headerLength)
                     throws BEEPException
This method is intended for use by tranport specific Sessions to create a new Frame object representing a BEEP MSG, RPY, ERR, or NUL frames.

Returns:
a Frame for the specified values
Throws:
BEEPException

disableIO

protected abstract void disableIO()
Method disableIO


enableIO

protected abstract void enableIO()
Method enableIO


getChannelAvailableWindow

protected int getChannelAvailableWindow(int channel)
                                 throws BEEPException
Returns the channel's available window size.

BEEPException

getChannelNumberAsString

protected java.lang.String getChannelNumberAsString(Channel channel)
Get the channel number as a String

Parameters:
channel -

getMaxFrameSize

protected abstract int getMaxFrameSize()
                                throws BEEPException
Returns the maximum frame size that a channel should send for this session.

Throws:
BEEPException

postFrame

protected void postFrame(Frame f)
                  throws BEEPException
Method postFrame

Parameters:
f -
Throws:
BEEPException

reset

protected abstract Session reset(SessionCredential localCred,
                                 SessionCredential peerCred,
                                 SessionTuningProperties tuning,
                                 ProfileRegistry registry,
                                 java.lang.Object argument)
                          throws BEEPException
This method is used by a tuning profile to reset the session after the tuning is complete.

Returns:
A new Session with the tuning complete.
BEEPException

sendFrame

protected abstract void sendFrame(Frame f)
                           throws BEEPException
Implement this method to send frames and on the sub-classed transport.

Throws:
BEEPException

setLocalCredential

protected void setLocalCredential(SessionCredential cred)
Method setLocalCredential

Parameters:
cred -

setPeerCredential

protected void setPeerCredential(SessionCredential cred)
Method setPeerCredential

Parameters:
cred -

setTuningProperties

protected void setTuningProperties(SessionTuningProperties tuning)
sets the tuning properties for this session

Parameters:
tuning -
See Also:
SessionTuningProperties

getTuningProperties

public SessionTuningProperties getTuningProperties()

updateMyReceiveBufferSize

protected abstract boolean updateMyReceiveBufferSize(Channel channel,
                                                     long previouslySeq,
                                                     long currentSeq,
                                                     int previouslyUsed,
                                                     int currentlyUsed,
                                                     int bufferSize)
                                              throws BEEPException
This method is designed to allow for flow control across the multiplexed connection we have.

The idea is to throttle data being sent over this session to be manageable per Channel, so that a given Channel doesn't take up all the bandwidth.

This method restricts the bufferSize, per the beep spec, to be at most two-thirds of the socket's receiveBufferSize. If a size is requested beyond that, an exception is thrown.

Parameters:
channel -
previouslySeq -
currentSeq -
previouslyUsed -
currentlyUsed -
bufferSize -
Returns:
true if the Receive Buffer Size was updated
Throws:
throws - BEEPException if a specified buffer size is larger than what's available on the Socket.
BEEPException

updatePeerReceiveBufferSize

protected void updatePeerReceiveBufferSize(int channelNum,
                                           long lastSeq,
                                           int size)
                                    throws BEEPException
Method updatePeerReceiveBufferSize

Parameters:
channelNum -
lastSeq -
size -
Throws:
BEEPException


Copyright ? 2001 Invisible Worlds, Inc. All Rights Reserved.