## org.beepcore.beep.core
Class SessionImpl

    java.lang.Object
      org.beepcore.beep.core.SessionImpl

All Implemented Interfaces:
  Session

Direct Known Subclasses:
  TCPSession

public abstract class SessionImpl
extends java.lang.Object
implements Session

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

Fields inherited from interface org.beepcore.beep.core.Session
`SESSION_STATE_ABORTED, SESSION_STATE_ACTIVE, SESSION_STATE_CLOSE_PENDING, SESSION_STATE_CLOSED, SESSION_STATE_CLOSING, SESSION_STATE_GREETING_SENT, SESSION_STATE_INITIALIZED, SESSION_STATE_TUNING, SESSION_STATE_TUNING_PENDING`

Constructor Summary
`protected` `SessionImpl(ProfileRegistry registry, int firstChannel, SessionCredential localCred, SessionCredential peerCred, SessionTuningProperties tuning, java.lang.String serverName)` 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 void` `fireSessionReset(Session newSession)`
`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`.
`java.lang.String` `getServerName()`
`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 boolean` `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.util.Collection profiles, RequestHandler handler)` Sends a start channel request using the given list of profiles.
`Channel` `startChannel(StartChannelProfile profile, RequestHandler handler)` Sends a request to start a new Channel on this Session for the specified profile.
`Channel` `startChannel(java.lang.String profile)` Sends a request to start a new Channel on this Session for the specified profile.
`Channel` `startChannel(java.lang.String profile, boolean base64Encoding, java.lang.String data)` Sends a request to start a new Channel on this Session for the specified profile.
`Channel` `startChannel(java.lang.String profile, boolean base64Encoding, java.lang.String data, MessageListener listener)` Sends a request to start a new Channel on this Session for the specified profile.
`Channel` `startChannel(java.lang.String profile, MessageListener listener)` Sends a request to start a new Channel on this Session for the specified profile.
`Channel` `startChannel(java.lang.String profile, RequestHandler handler)` Sends a request to start a new Channel on this Session for 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.).
`java.lang.String` `toString()`
`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 currentSeq, int currentAvail)` 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, wait, wait, wait`

Constructor Detail

### SessionImpl

    protected SessionImpl(ProfileRegistry registry,
                          int firstChannel,
                          SessionCredential localCred,
                          SessionCredential peerCred,
                          SessionTuningProperties tuning,
                          java.lang.String serverName)
                   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` - The Profile Registry summarizing the profiles this Session will support
  `firstChannel` - used internally in the API, an indication of the ordinality of the channels this peer can start, odd, or even.
  `localCred` -
  `peerCred` -
  `tuning` -
  `serverName` -

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.

  Specified by:
    `addChannelListener` in interface `Session`
  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.

  Specified by:
    `addSessionListener` in interface `Session`
  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.

  Specified by:
    `close` in interface `Session`
  Throws:
    `BEEPException`

### getLocalCredential

    public SessionCredential getLocalCredential()

  Get the local `SessionCredential` for this session.

  Specified by:
    `getLocalCredential` in interface `Session`
  Returns:
    May return `null` if this session has not been authenticated

### getPeerCredential

    public SessionCredential getPeerCredential()

  Get our peer's `SessionCredential` for this session.

  Specified by:
    `getPeerCredential` in interface `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.

  Specified by:
    `getPeerSupportedProfiles` in interface `Session`

### getProfileRegistry

    public ProfileRegistry getProfileRegistry()

  Returns the `ProfileRegistry` for `Session`.

  Specified by:
    `getProfileRegistry` in interface `Session`
  Returns:
    A `ProfileRegistry`.
  See Also:
    `ProfileRegistry`

### getState

    public int getState()

  Returns the state of `Session`.

  Specified by:
    `getState` in interface `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.

  Specified by:
    `isInitiator` in interface `Session`

### 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.

  Specified by:
    `removeChannelListener` in interface `Session`
  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.

  Specified by:
    `removeSessionListener` in interface `Session`
  See Also:
    `addSessionListener(org.beepcore.beep.core.event.SessionListener)`

### startChannel

    public Channel startChannel(java.lang.String profile)
                         throws BEEPException,
                                BEEPError

  Description copied from interface: `Session`
  Sends a request to start a new Channel on this Session for the specified profile.

  Specified by:
    `startChannel` in interface `Session`
  Parameters:
    `profile` - The URI of the profile for the new Channel.
  Throws:
    `BEEPError` - Thrown if the remote peer is unable or refuses to start a new Channel for the requested profile.
    `BEEPException` - Thrown for errors other than those defined by the BEEP protocol (e.g. the Session is not in a state to create a new Channel).

### startChannel

    public Channel startChannel(java.lang.String profile,
                                MessageListener listener)
                         throws BEEPException,
                                BEEPError

  Description copied from interface: `Session`
  Sends a request to start a new Channel on this Session for the specified profile. This version of `startChannel` allows a `MessageListener` to be specified to be registered once the Channel is started. This is useful for profiles that are peer-to-peer in nature.

  Specified by:
    `startChannel` in interface `Session`
  Parameters:
    `profile` - The URI of the profile for the new Channel.
    `listener` - A `MessageListener` to receive MSG messages sent by the remote peer of this Session.
  Throws:
    `BEEPException` - Thrown for errors other than those defined by the BEEP protocol (e.g. the Session is not in a state to create a new Channel).
    `BEEPError` - Thrown if the remote peer is unable or refuses to start a new Channel for the requested profile.
  See Also:
    `MessageListener`

### startChannel

    public Channel startChannel(java.lang.String profile,
                                RequestHandler handler)
                         throws BEEPException,
                                BEEPError

  Description copied from interface: `Session`
  Sends a request to start a new Channel on this Session for the specified profile. This version of `startChannel` allows a `RequestHandler` to be specified to be registered once the Channel is started. This is useful for profiles that are peer-to-peer in nature.

  Specified by:
    `startChannel` in interface `Session`
  Parameters:
    `profile` - The URI of the profile for the new Channel.
    `handler` - A `RequestHandler` to receive MSG messages sent by the remote peer of this Session.
  Throws:
    `BEEPException` - Thrown for errors other than those defined by the BEEP protocol (e.g. the Session is not in a state to create a new Channel).
    `BEEPError` - Thrown if the remote peer is unable or refuses to start a new Channel for the requested profile.

### startChannel

    public Channel startChannel(java.lang.String profile,
                                boolean base64Encoding,
                                java.lang.String data)
                         throws BEEPException,
                                BEEPError

  Description copied from interface: `Session`
  Sends a request to start a new Channel on this Session for the specified profile. This version of `startChannel` allows a `MessageListener` to be specified to be registered once the Channel is started. This is useful for profiles that are peer-to-peer in nature.

  Specified by:
    `startChannel` in interface `Session`
  Parameters:
    `profile` - The URI of the profile for the new Channel.
    `base64Encoding` - Indicates whether or not `data` is base64 encoded. `data` must be base64 encoded if it is not valid XML CDATA.
    `data` - An initial request to be sent piggyback'd along with the request to start the Channel. This request can be at most 4K in size.
  Throws:
    `BEEPException` - Thrown for errors other than those defined by the BEEP protocol (e.g. the Session is not in a state to create a new Channel).
    `BEEPError` - Thrown if the remote peer is unable or refuses to start a new Channel for the requested profile.
  See Also:
    `MessageListener`

### startChannel

    public Channel startChannel(java.lang.String profile,
                                boolean base64Encoding,
                                java.lang.String data,
                                MessageListener listener)
                         throws BEEPException,
                                BEEPError

  Description copied from interface: `Session`
  Sends a request to start a new Channel on this Session for the specified profile. This version of `startChannel` allows a `MessageListener` to be specified to be registered once the Channel is started. This is useful for profiles that are peer-to-peer in nature.

  Specified by:
    `startChannel` in interface `Session`
  Parameters:
    `profile` - The URI of the profile for the new Channel.
    `base64Encoding` - Indicates whether or not `data` is base64 encoded. `data` must be base64 encoded if it is not valid XML CDATA.
    `data` - An initial request to be sent piggyback'd along with the request to start the Channel. This request can be at most 4K in size.
    `listener` - A `MessageListener` to receive MSG messages sent by the remote peer of this Session.
  Throws:
    `BEEPError` - Thrown if the remote peer is unable or refuses to start a new Channel for the requested profile.
    `BEEPException` - Thrown for errors other than those defined by the BEEP protocol (e.g. the Session is not in a state to create a new Channel).
  See Also:
    `MessageListener`

### startChannel

    public Channel startChannel(StartChannelProfile profile,
                                RequestHandler handler)
                         throws BEEPException,
                                BEEPError

  Description copied from interface: `Session`
  Sends a request to start a new Channel on this Session for the specified profile. This version of `startChannel` allows a `RequestHandler` to be specified to be registered once the Channel is started.

  Specified by:
    `startChannel` in interface `Session`
  Parameters:
    `profile` -
    `handler` - A `RequestHandler` to receive MSG messages sent by the remote peer of this Session.
  Throws:
    `BEEPError` - Thrown if the remote peer is unable or refuses to start a new Channel for the requested profile.
    `BEEPException` - Thrown for errors other than those defined by the BEEP protocol (e.g. the Session is not in a state to create a new Channel).

### startChannel

    public Channel startChannel(java.util.Collection profiles,
                                MessageListener listener)
                         throws BEEPException,
                                BEEPError

  Description copied from interface: `Session`
  Sends a start channel request using the given list of profiles.

  Specified by:
    `startChannel` in interface `Session`
  Parameters:
    `profiles` - A collection of `StartChannelProfile`(s).
    `listener` - A `MessageListener` to receive MSG messages sent by the remote peer of this Session.
  Throws:
    `BEEPError` - Thrown if the remote peer is unable or refuses to start a new Channel for the requested profile.
    `BEEPException` - Thrown for errors other than those defined by the BEEP protocol (e.g. the Session is not in a state to create a new Channel).
  See Also:
    `StartChannelProfile`, `MessageListener`

### startChannel

    public Channel startChannel(java.util.Collection profiles,
                                RequestHandler handler)
                         throws BEEPException,
                                BEEPError

  Description copied from interface: `Session`
  Sends a start channel request using the given list of profiles.

  Specified by:
    `startChannel` in interface `Session`
  Parameters:
    `profiles` - A collection of `StartChannelProfile`(s).
    `handler` - A `RequestHandler` to receive MSG messages sent by the remote peer of this Session.
  Throws:
    `BEEPException` - Thrown for errors other than those defined by the BEEP protocol (e.g. the Session is not in a state to create a new Channel).
    `BEEPError` - Thrown if the remote peer is unable or refuses to start a new Channel for the requested profile.
  See Also:
    `StartChannelProfile`, `RequestHandler`

### 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.).

  Specified by:
    `terminate` in interface `Session`
  Parameters:
    `reason` -

### toString

    public java.lang.String toString()

### 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.

  Throws:
    `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 boolean 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.
  Throws:
    `BEEPException`

### sendFrame

    protected abstract void sendFrame(Frame f)
                               throws BEEPException

  Implement this method to send frames and on the sub-classed transport.

  Parameters:
    `f` - BEEP frame to send.
  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()

  Specified by:
    `getTuningProperties` in interface `Session`

### getServerName

    public java.lang.String getServerName()

### updateMyReceiveBufferSize

    protected abstract boolean updateMyReceiveBufferSize(Channel channel,
                                                         long currentSeq,
                                                         int currentAvail)
                                                  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` -
    `currentSeq` -
    `currentAvail` -
  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`

### fireSessionReset

    protected void fireSessionReset(Session newSession)

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