SSF.OS
Class ProtocolSession

java.lang.Object
  |
  +--SSF.OS.ProtocolSession

All Implemented Interfaces:

com.renesys.raceway.DML.Configurable

Direct Known Subclasses:

Advertiser, AppSession, BGPCrasher, BGPKiller, BGPSession, BogusAdvertiser, DDoSSession, DDoSSessionRand, httpClient, httpServer, httpServer_WM, ICMP, IP, MacroscopicModelConfigurator, NIC, OSPF, ProbeSession, RadixTreeRoutingTable, socketMaster, sOSPF, tcpClient, tcpClientSession, tcpServer, tcpSession, tcpSessionMaster, tcpSocket, udpSession, udpSessionMaster, udpStreamClient, udpStreamServer, udpStreamSession

public abstract class ProtocolSession

extends java.lang.Object

implements com.renesys.raceway.DML.Configurable

Base class for Protocol implementations. Specifies default mechanisms for how to behave when configured, when opened by another ProtocolSession, when a ProtocolMessage is pushed to this protocol by another ProtocolSession, and so forth. Subclasses may extend these behaviors with their own specific behaviors.
Since release 1.4: Provides uniform support for protocol monitoring by classes implementing interface SSF.OS.ProtocolMonitor. A derived ProtocolSession with monitoring enabled will call monitorReceive, monitorSend, monitorDrop when it receives, sends or drops a message, respectively. A ProtocolMonitor can be added/removed and enabled/disabled at runtime.

Field Summary

java.lang.String	name Symbolic name of the protocol this session implements
java.lang.String	use Protocol class name to instantiate to make this session

Constructor Summary

ProtocolSession()

Method Summary

void	close(ProtocolSession S) Called by a neighboring session to close (unconfigure) this session.
void	closed(ProtocolSession S) Called by a neighboring session to confirm to this session that a close operation has succeeded, and that this session is now successfully unconfigured from the caller session.
void	config(com.renesys.raceway.DML.Configuration cfg) Configure this ProtocolSession.
java.lang.String	debugIdentifier() Returns a standardized prefix string "time, NHI address, protocol_name" for diagnostic messages from this protocol.
ProtocolGraph	inGraph() Return a handle to the protocol graph within which this session is currently configured, or NULL if it stands alone.
void	init() Initialization routine, called by the ProtocolGraph after instantiation.
void	open(ProtocolSession S, java.lang.Object request) Called by a neighboring session to open this session.
void	opened(ProtocolSession S) Called by a neighboring session to confirm to this session that an open operation has succeeded, and that this session is now successfully configured over/under the caller session.
abstract boolean	push(ProtocolMessage message, ProtocolSession fromSession) Routine to call when a message is being sent to ("pushed into") this ProtocolSession by another ProtocolSession.
boolean	pushAfterDelay(ProtocolMessage message, ProtocolSession fromSession, double seconds) Push the message into this protocol session after the specified number of ticks of CPU time have been consumed.
protected void	pushAfterDelayFailed(ProtocolException pex) Method called back when pushAfterDelay has failed.
void	setGraph(ProtocolGraph G) Set the protocol graph in which this session is configured.
java.lang.String	version() "Type" string identifying the version of this protocol.

Methods inherited from class java.lang.Object

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

Field Detail

name

public java.lang.String name

Symbolic name of the protocol this session implements

use

public java.lang.String use

Protocol class name to instantiate to make this session

Constructor Detail

ProtocolSession

public ProtocolSession()

Method Detail

init

public void init()
          throws ProtocolException

Initialization routine, called by the ProtocolGraph after instantiation. The order of initialization of a set of protocols is unspecified, so other methods (like open()) may be called before init(). Resources (like connection tables) that may be needed by open() should therefore be created in the ProtocolSession constructor.

ProtocolException

push

public abstract boolean push(ProtocolMessage message,
                             ProtocolSession fromSession)
                      throws ProtocolException

Routine to call when a message is being sent to ("pushed into") this ProtocolSession by another ProtocolSession. The pusher sends a reference to itself in the second argument. This push happens immediately, without any simulation time elapsing, regardless of other activities taking place in the ProtocolGraph.

If you desire "safe" interaction with other CPU activities, even though your push() consumes no measurable/modelable CPU cycles, define the "cpudelay true" attribute for the ProtocolGraph and use pushAfterDelay(message,fromSession,0.0). This will guarantee proper ordering; that is, the framework will wait until the CPU is free before proceeding with the requested push().

ProtocolException

pushAfterDelay

public boolean pushAfterDelay(ProtocolMessage message,
                              ProtocolSession fromSession,
                              double seconds)
                       throws ProtocolException

Push the message into this protocol session after the specified number of ticks of CPU time have been consumed. The protocol session contends with other system behavior to get the attention of the CPU associated with the ProtocolGraph, so the actual time between the pushAfterDelay request and the actual message push may be longer than requested. For example, pushAfterDelay(msg,from,0.) may actually cause some time to elapse before the push takes place, because we will wait for the CPU to become free, even though the requested delay is zero.

ProtocolException

pushAfterDelayFailed

protected void pushAfterDelayFailed(ProtocolException pex)

Method called back when pushAfterDelay has failed. The existence of this method is unfortunate, but neither the boolean value from push() nor the ability to throw a ProtocolException are available from within the long-distance callback. This should be a rare condition (almost an assertion failure) because of our shared-resource delay model. The failure branch of the continuation used to model the delay is never called back. If the underlying push() throws a ProtocolException, pushAfterDelayFailed will be called; that's presumably a nonrecoverable error anyway resulting from protocol stack misconfiguration.

config

public void config(com.renesys.raceway.DML.Configuration cfg)
            throws com.renesys.raceway.DML.configException

Configure this ProtocolSession.

Specified by:

config in interface com.renesys.raceway.DML.Configurable

com.renesys.raceway.DML.configException

version

public java.lang.String version()

"Type" string identifying the version of this protocol.

inGraph

public ProtocolGraph inGraph()

Return a handle to the protocol graph within which this session is currently configured, or NULL if it stands alone. A standalone session is a temporary aberration during construction, which will be corrected when the session opens or is opened by a session within an existing protocol graph.

setGraph

public void setGraph(ProtocolGraph G)
              throws ProtocolException

Set the protocol graph in which this session is configured.

Throws:

ProtocolException - if the session is already configured in a protocol graph

open

public void open(ProtocolSession S,
                 java.lang.Object request)
          throws ProtocolException

Called by a neighboring session to open this session. Default semantics are to immediately respond with a confirming callback to opened() on the calling session. Session subclasses can override this behavior to implement delayed open (e.g., open-enable).

Throws:

ProtocolException - if neither the opening session nor the opened session are contained within a valid protocol graph, or if they are already contained within different protocol graphs, or if the opening session could not be added to the list of open sessions, perhaps because the max session count has been exceeded

opened

public void opened(ProtocolSession S)
            throws ProtocolException

Called by a neighboring session to confirm to this session that an open operation has succeeded, and that this session is now successfully configured over/under the caller session.

Throws:

ProtocolException - if the opened session could not be added to the list of open sessions, perhaps because the max session count has been exceeded

close

public void close(ProtocolSession S)
           throws ProtocolException

Called by a neighboring session to close (unconfigure) this session. Default semantics are to immediately respond with a confirming call to closed() on the neighboring session. Session subclasses can override this behavior to implement delayed close.

Throws:

ProtocolException - if the closing session could not be removed from the list of open sessions

closed

public void closed(ProtocolSession S)
            throws ProtocolException

Called by a neighboring session to confirm to this session that a close operation has succeeded, and that this session is now successfully unconfigured from the caller session.

Throws:

ProtocolException - if the closed session could not be removed from the list of open sessions

debugIdentifier

public java.lang.String debugIdentifier()

Returns a standardized prefix string "time, NHI address, protocol_name" for diagnostic messages from this protocol.