Test FSM - Sample Xholon App
What is it
This application tests and demonstrates the ability of Xholon to model and execute hierarchical finite state machines (FSM). Xholon FSMs are based on the Unified Modeling Language (UML 2) specification for State Machines. This FSM was modeled using the Magic Draw UML tool, exported to XML Metadata Interchange (XMI) format, converted to Xholon XML and Java files using a set of XSLT scripts, merged with several manually-produced Xholon Java files, and executed using the Xholon runtime framework.
The structure of this model is shown in the following two MagicDraw UML 2 diagrams. The first is a class diagram showing the structural classes in this system. FsmXholon contains the state machine, while TestHarness exercises the state machine by running the test scenarios. Instances of both of these classes are contained within TestFsmSystem. All three of these are subclasses of XholonClass. Partner is a port class that allows messages containing the SIG1, SIG2, and SIG3 signals to be sent.
The composite structure diagram specifies that TestHarness and FsmXholon are both Xholon pure active objects. Each has a port called P_PARTNER (of class Partner). These two ports connect to each other, allowing messages to be sent.
How to use it
Run the application:
- Run the Java application through the Xhn GUI (org.primordion.xholon.app.Xhn.java), and select File --> Open --> TestFsm --> TestFsm_xhn.xml.
- You should see a list of parameter settings, and then the following lines showing which hierarchical states are initially active.
StateA1 entry StateA:state_22 activeSubState is StateA1:state_50 Top:state_5 activeSubState is StateA:state_22 stateMachine_3 activeSubState is Top:state_5
Start the FSM:
- Expand the Controller node in the GUI tree.
- Press the Start node.
- You should see:
Harness StateA1 exit StateA1 trans SIG2 Choice y == 5 StateA from exit point to StateB Top:state_5 activeSubState is StateB:state_60 stateMachine_3 activeSubState is Top:state_5 StateB trans SIG2 Top:state_5 activeSubState is :finalState_61 stateMachine_3 activeSubState is Top:state_5
Things to notice
The Test FSM application implements the following features of the UML 2 State Machine formalism. Each line provides the name of the UML 2 feature, and the Xholon class name in angle brakets. See the InheritanceHierarchy, CompositeStructureHierarchy, and ClassDetails XML files.
- Behavior <Behavior>
- StateMachine <StateMachine>
- Region <Region>
- Vertex <Vertex>
- State <State>
- FinalState <FinalState>
- Pseudostate <Pseudostate>
- PseudostateKind: choice <PseudostateChoice>
- PseudostateKind: entryPoint <PseudostateEntryPoint>
- PseudostateKind: exitPoint <PseudostateExitPoint>
- PseudostateKind: initial <PseudostateInitial>
- PseudostateKind: terminate <PseudostateTerminate>
- Trigger <Trigger>
- Transition <Transition>
- transition effect activity <Activity>
- guard <Guard>
- entry activity <EntryActivity>
- exit activity <ExitActivity>
- connectionPoint <port name="cnpt">
The MagicDraw state machine diagram specifies the hierarchical states and transitions within the behavior of FsmXholon. Top, StateA, StateA1, StateA2, StateA3, and StateB are UML States. StateA1, StateA2, and StateA3 are hierarchically contained within StateA. Each state is contained within an invisible Region. There is a FinalState at the lower right hand corner of the diagram. The diagram includes the following kinds of Pseudostate: choice (diamond), entryPoint (circle), exitPoint (cirlce with X inside), initial (large filled circle), terminate (small filled circle inside larger circle). Arrows represent Transitions between States. Each Transition is labeled with the name of a received signal that acts as a Trigger (ex: SIG1), an optional Guard condition (ex: x< 10), and the name of an action (ex: sig1lt10). Several states include entry or exit activities.
Things to try
XhTestFsm.java runs one of five different scenarios. The default is scenario TEST_SCENARIO_4. Try one of the other four scenarios by changing the TestScenario parameter in TestFsm_xhn.xml. Enter a value between 1 and 5. Look at XhTestFsm.java to see what actions are taken in each test.
Extending the model
Create additional test scenarios in XhTestFsm.java.
If you are familiar with UML and with MagicDraw, make some changes to the UML model and regenerate the Xholon application.
Semi-automatic generation of a Xholon application from a UML model.
Xholon hierarchical finite state machines.
The performActivity(int activityId) and guardActivity(int activityId) methods in XhTestFsm were generated using a XSLT script from the MagicDraw model XMI file. The long integers used in the Java case statements are derived from MagicDraw-generated unique IDs. The same IDs appear in the ClassDetails XML file.
Credits and references
See additional information in _README.txt in the transform/MagicDraw folder.
Visit the OMG site to learn more about UML 2, and to view the current UML specification, Version 2.0, as a free download. This document is called the UML 2.0 Superstructure specification.
Visit the MagicDraw site. You might want to download a trial version of their UML tool, or their free model Reader. You can use either of these to load and view the TestFsm5.xml.zip MagicDraw model file in the transform/MagicDraw folder.