The FSM Tool comes with a sample application, "Hello World", as an example of how to create and extend a service with the tool.

To review the sample application, please explore the following:

What the sample state machine looks like

The FSM Tool sample state machine works like this:

"Hello World" state machine

FsmToolExampleStateMachineSbb

The "Hello World" state machine includes:

  • two states — startState and stopState

  • one endpoint — tcp

  • one input — hello, received through the endpoint tcp

  • one entry action — helloWorld, for stopState.

Note When the machine detects the hello input received on the tcp endpoint in state startState, it transitions to state stopState, whereupon it executes entry action helloWorld.

How the sample state machine is defined

You define FSM Tool state machines using a simple, easy-to-understand (and modify), text-based, domain-specific language (DSL). Below is the DSL definition for the Hello World example (FsmToolExampleStateMachineSbb.fsm):

fsm FsmToolExampleStateMachineSbb {

    description "{product-name} Example State Machine";

    endpoint tcp;

    initial state startState {
         description "Start state";
         transition if(tcp.hello) stopState;
    }
    final state stopState  {
         description "Stop state";
         entryaction helloWorld;
    }

    inputdictionary {
         tcp.hello {
              description "Hello event received.";
         }
    }

    actiondictionary {
         helloWorld {
              description "Say Hello World!";
         }
    }
}

Running the example

Below are instructions to build, deploy, and run the "Hello World" sample FSM Tool service.

Install and start the Rhino SDK

See Rhino (SDK) Getting Started Guide.

Build and deploy

First build and deploy the service, using the following commands:

cd ${fsmtool.home}/example
ant deploy-example-ra
ant deploy-helloworld

Run with telnet

Then run the service, using OpenCloud’s example RA (which uses a telnet connection to send lines of text as events to the service), as follows:

  1. Start a command window or shell.

  2. Enter telnet localhost 9999

  3. Type hello, and press Return.

What happens…​

When you press Return:

  1. The application wraps the text hello in a new ExampleRA MessageEvent event, and delivers it to FsmToolHelloWorldSbb.

  2. The Sbb receives the event in the onMessageEvent() event handler. The code in the event handler sets the hello input, associating the received event object with the input as data object. It then associates the SLEE ActivityContext on which the event was received with the tcp endpoint and finally triggers a run of the FSM execution algorithm.

    public void onMessageEvent(MessageEvent event, ActivityContextInterface aci) {

    // Use the input scheduler to raise the 'hello' input on the 'tcp' endpoint and associate
    // the event object with it
    getInputScheduler().raise(getInputs().tcp.hello, event);

    // Associate the aci with the 'tcp' endpoint
    getEndpoints().tcp.setAci(aci);

    // Execute the FSM logic
    execute();
}

  3. The state machine executes, transitioning to stopState and running the helloWorld action. The FSM logic maps the helloWorld action to the method helloWorldAction() which is implemented by the developer to return the "Hello World" text on the telnet connection.

    public void helloWorldAction(Inputs inputs, InputScheduler<FSMInput> inputScheduler,
                             Endpoints endpoints, Facilities facilities) {
        ...
        // The ACI stored using the endpoint setAci(ActivityContextInterface) method is accessed
        // in the action methods using getAci().
        ActivityContextInterface aci = endpoints.tcp.getAci();

        ConnectionActivity connection = (ConnectionActivity) aci.getActivity();
        try {
            connection.sendMessage("Received " + event + ". Hello World.");

        } catch (IOException e) {
            facilities.getTracer().warning("Sbb failed to send response", e);
            return;
        }
}

  4. You receive the "Hello World" text in the telnet connection

    Exit the telnet session (press Ctrl-], type exit and press Return).

Note
Digging deeper

The FSM Tool package includes:

  • full source code of the Hello World example: $\{fsmtool.home\}/example/src/helloworld/com/opencloud/slee/services/fsmtool/helloworld

  • the build scripts for the example: $\{fsmtool.home\}/example/build.xml

When you run the build-service task, it executes the FSM Tool Ant task, to generate an Sbb that implements the state machine definition — FsmToolExampleStateMachineSbb.java. The FsmToolExampleSbb class, which is the root Sbb of the service and extends the FsmToolExampleStateMachineSbb class, implements the event handler method, and provides the implementation for the helloWorld entry action in the helloWorldAction() method.

Extending the "Hello World" example

Now that you have successfully run the "Hello World" example you can extend the state-machine definition to implement more complex state-machine behaviour, as follows:

Extended "Hello World" state machine

FsmToolExampleStateMachineSbb-extended

Extending the example (to respond to subsequent events)

FSM Tool includes an extended "Hello World" example, in $\{fsmtool.home}/example/src/helloworldextended.

Installing the extended HelloWorld example

First build and deploy the service, using the following commands:

cd ${fsmtool.home}/example
ant deploy-example-ra
ant undeploy-helloworld
ant deploy-helloworldextended

Steps to extend from the HelloWorld service

Extend the helloworld example, by editing the FsmToolExampleStateMachineSbb.fsm file in your Java IDE, as follows:

1

Remove the final from the stopState declaration and then add a new transition*

...
    state stopState  {
         description "Stop state";
         entryaction helloWorld;
         transition if(tcp.hello) startState;
    }
    ...

2

Add a new entry action startingAgain to startState, and declare it in the output dictionary

...
    initial state startState {
         description "Start state";
         entryaction startingAgain;
         transition if(tcp.hello) stopState;
    }

    actiondictionary {
         helloWorld {
              description "Say Hello World!";
         }
         startingAgain {
              description "Starting again.";
         }
    }

3

(Re)build the file

ant build-helloworld

The Ant task will re-generate FsmToolExampleStateMachineSbb.java and try compiling the service, which will fail because FsmToolExampleSbb has not yet been updated to implement the new startingAgainAction() method in the actions interface implementation.

4

Implement the startingAgainAction() method in the actions interface implementation.

public void startingAgainAction(Inputs inputs,
                InputScheduler<FSMInput> inputScheduler, Endpoints endpoints,
                Facilities facilities) {

    // The tracer is provided via the facilities method argument
    facilities.getTracer().finest("Running Hello World Action");

    // Objects passed in the InputScheduler.raise(Input, Object) can be accessed
    // from the input using the getAssociatedObject() method
    MessageEvent event = (MessageEvent) inputs.tcp.hello.getAssociatedObject();

    // The ACI stored using the endpoint's setAci(ActivityContextInterface) method is accessed
    // in the action methods using getAci().
    ActivityContextInterface aci = endpoints.tcp.getAci();

    ConnectionActivity connection = (ConnectionActivity) aci.getActivity();
    try {
        connection.sendMessage("Received " + event + ". Starting Again.");
    } catch (IOException e) {
        facilities.getTracer().warning("Sbb failed to send response", e);
        return;
    }
}

5

Recompile and redeploy

ant undeploy-helloworld
ant deploy-helloworld

6

Run the extended example:

  1. Start a command window or shell.

  2. Run telnet localhost 9999

  3. Type hello, and press Return.
    (The application performs same transition as before.)

  4. Type hello, and press Return again.

What happens…​

As a result of your modifications:

  • The state machine executes, transitioning from stopState to startState, and executing the startingAgain action — which returns the text "Starting Again" on the telnet connection.

  • You receive "Starting Again" in the telnet connection.

  • If you keep on entering inputs, you will get alternating messages as the state machine transitions between the two states.

Exit the telnet session (press Ctrl-], type exit and press Return).

Generating Javadocs and diagrams

The FSM Tool supports the automatic generation of javadocs and state-machine diagrams.

Tip The diagrams for the basic and extended example page were automatically generated from their respective state machine definitions.

To generate state machine Javadocs and diagrams, run:

ant javadocs
Previous page Next page