SLEE Freephone FSM Service for IN and IMS

What is the FSM Tool?

OpenCloud's FSM Tool is a lightweight service-creation tool designed to simplify service creation for the Rhino SLEE.

What does it do?

It powers the design, specification, implementation, testing, and documentation of JAIN SLEE Service Building Blocks (SBBs).

How does it help developers?

From the developer's perspective, the tool ensures that the specification and implementation artifacts remain completely accurate and synchronized throughout the development and maintenance life cycle of each component.

The SBB developer creates the specification of a finite state machine (FSM), which specifies states, inputs, transitions, and actions. The FSM Tool interprets the specification and generates the state machine as a base SBB. The developer then creates another SBB class to extend the base SBB. This extension class sets state machine inputs and implements actions.

For more information, please read the FSM Tool documentation.

Migrating the Freephone service to use FSM Tool

The previous version of the SLEE Freephone service had three SBBs: one to implement service logic (number translating, charging, and so on), and two for signaling protocol communication (SIP and CAP). The SBBs communicated through the local interfaces.

Since each SBB has its own state and logic, the FSM Tool considers each as an independent process unit. This means the SBB developer can use the FSM Tool to generate a state machine for each SBB, as illustrated below. (The developer implements communication between the SBBs as normal.)

Class diagram with generated state machines.

See the details that follow for the sample FSM Tool-generated CAP base SBB specification and diagram and the developer's extension.

Sample specification

Below is an example of the finite state machine (FSM) specification, which the FSM Tool will read to generate the Freephone service's CAP SBB. It includes:

• definitions of four states: OPEN, CONNECTING, ANSWERED, and DISCONNECTED, each with input and output (actions and transitions to other states)
• an inputdictionary that defines inputs to the state machine
• an outputdictionary that defines actions to perform (based on the inputs).

fsm CapFreePhoneStateMachine {
    initial state OPEN {
        description "An OpenRequest has been received";
        inputaction if(open) checkOpenRequest;        
        transition if(connect) CONNECTING;
        transition if(reject) DISCONNECTED; 
    }    
    state CONNECTING {
        description "Waiting to perform next operation";
        inputaction if (eventReport) checkEventReport;        
        transition if (answer) ANSWERED;
        transition if (unsuccessful) DISCONNECTED;
    }    
    state ANSWERED {
        description "Call was answered";
        inputaction if (eventReport) checkEventReport;        
        transition if (disconnect) DISCONNECTED;
    }    
    final state DISCONNECTED {
        description "End state";        
        exitaction tearDown;
    }

    inputdictionary {
        open {
            description "OpenRequest received";
        }        
        connect {
            description "Call Connected";
        }        
        reject {
            description "Call Rejected";
        }
        answer {
            description "Call Answered";
        }        
        disconnect {
            description "Call Disconnected";
        }
        unsuccessful {
            description "Call unsuccessful";
        }        
        eventReport {
            description "EventReport Received";
        }
    }
    outputdictionary {
        checkOpenRequest {
            description "check the Open Request";
        }        
        checkEventReport {
            description "check the BCSM Event Report Received";
        }        
        tearDown {
            description "tear down call";
        }
    }
}

FSM Tool also lets you configure conditional and unconditional actions and transitions in a specification.

Generating the FSM Diagram

After writing the specification, you can use the FSM Tool to generate a diagram of the finite state machine (FSM), by executing an [Ant task]. Below is a diagram FSM Tool generated for the Freephone service's CAP SBB.

FSM Tool-generated FSM diagram

Extending the FSM Tool-generated CAP SBB

In migrating the Freephone service, the SBB developer must implement an SBB class that extends the SBB state machine that FSM Tool generates.

Setting inputs

As the minimum, the SBB class must map or set inputs in the state machine. For example, the OPEN state expects the DialogOpenRequestEvent input to execute an action. This SBB sets the input on the Open Request event handler:

public void onOpenRequest(DialogOpenRequestEvent openRequest, ActivityContextInterface aci, EventContext ec)
{
    setInitialEventContext(ec);
    receivedInput(Input.open, openRequest, aci);
}

While a fine-grained state machine specification maps each received event to an input, developers may also choose a higher abstraction of the state machine, implementing some logic without relying on the state machine. In this implementation, the InitialDP request will be processed within the OPEN state, an alternative would be to have an additional state to receive the initial detection point as a separate input.

Implementing actions

The state machine evaluates the input and performs actions — if any — defined in the specification. In this example, the specification instructs the interpreter to perform the action checkOpenRequest, defined as a method by the extension SBB.

The following example shows a method implementation that represents an action for the state machine to execute.

public int checkOpenRequestAction(Object event, ActivityContextInterface aci) throws Exception
{
    if (getTracer().isFinestEnabled())
        getTracer().finest("Received: " + event);
     
    Dialog dialog = ((DialogOpenRequestEvent) event).getDialog();
    try
    {
        dialog.acceptDialog();
        // Handle IDP component
        processInitialDPRequest(aci);
    } 
    catch (ProtocolException pe)
    {
        getTracer().severe("Failed to process request", pe);
    }
    return 0;
}

The implementation of the action will set either the connect or reject input, depending on the outcome of evaluating the call. Since the OPEN state defines transactions based on those inputs, upon setting the inputs connect or reject, the state machine transitions to the state CONNECTING or DISCONNECTED, respectively.

Cleaner, clearer, forward-thinking development and maintenance

The FSM Tool reads the specification of a state machine and auto-generates a class that implements the interpreter of that state machine. The developer then extends the state machine class to map or set inputs and implement actions.

In essence, the separation of the state machine management from the service logic implementation creates cleaner service implementations, that are easier to understand. This is a powerful programming approach that simplifies the implementation and maintenance of an SBB.

The development and migration of a service with the FSM Tool is a straightforward process. It lets the developer specify the service as a fined-grain machine (when working with protocol-handling SBBs), or set up an incremental development process.

Review source code For a complete understanding of how this example works, please review the source code for this version of the SLEE Freephone service.