ICEBERG v1 Documentation: State Machine Engines

Extensible State Machine Implementation

The operations on IAP and Call Agent are modeled by generic (not specific to any access networks or devices) call processing state machines. The communication between IAP and Call Agent uses either UDP messages or Ninja vSpace cluster communication APIs which uses either UDP or TCP. The challenges of implementing the state machine-driven entities are to adapt to the evolution of the state machine design, and to allow dynamic customization of the state machines. Our strategy is to separate the generic state machine operation from specific state machine instance. All state machine executions start with some initial state, then event handling, and advance the state, and so on. We implemented State Machine Engine for this generic state machine operation. The "fuel" to the state machine engine include state specification, event specification, and the event handler implementation for each state-event pair. State machine engine implementation stays the same, but different "fuels" can be fed to the it to carry out different state machine operations. This way, state machine design change or customization is only a matter of supplying different "fuels". This is especially important for various IAP implementations, where event handlers are different for different access network or service endpoints. Details on this topic can be found here.

IAP and Call Agent Implementation

The state machine engines for IAP (iceberg1/nvsme/StateMachineEngine.java) and Call Agent (iceberg1/sme/StateMachineEngineWorker.java) are implemented slightly differently because Call Agent state machines run on Ninja vSpace, and must conform with Ninja vSpace event-driven programming model and API.

The IAP state machine fuel is specified as in iceberg1/smSpec/iap.sms, and the Call Agent state machine fuel is specified in iceberg1/smSpec/ca.sms (see here for pictures of the state machines). These files specifies the initial and terminal states, events to be handled at each state as well as initial events that arrive at the state machine. One can also specify the timeout value in milliseconds, as well as the name of the timeout event.

State machine engines take some configuration files which include the path of the state machine specification file (e.g., iap.sms or ca.sms). When state machine engines receive "first events" (e.g., the "IncomingCall" and "OutgoingCall"), state machine instances (see iceberg1/sme/StateMachineInstance.java, and iceberg1/nvsme/StateMachineInstance.java) are spawn. In other words, there can be a number of simultaneous state machine instances handling different requests at the same time.

Call Agent state machine is run as a Ninja vSpace worker as specified in example Ninja vSpace configuration files in iceberg1/vspacecfg. IAPs are run as separate Java applications. Example of IAP configuration files can be found in iceberg1/nvsme/ (e.g., demo-helenjw1.cfg).

Creating new IAPs

If you want to add new IAPs, it is only a matter of customizing generic IAP event handlers. iceberg1/iap/generic contains the generic IAP handlers. Your own IAP handler implementation can be done by creating a new directory with your IAP name. The handler templates can be automatically generated by the code generation tool iceberg1/codegen/codegen.tcl for your convenience. The script takes the code generation configuration file as argument. Please follow configuration example of iceberg1/codegen/cfg/vat_iap to create your new IAPs.