Session (BEEP Core API)

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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