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.