ECO State Machines

By: Gerard van.der.Pol

Abstract: Enterprise Core Objects (ECO) is a powerful application framework that provides both a design and runtime environment. The current version of ECO adds the State Machine diagram to model the behavior of classes.

Enterprise Core Objects (ECO) is a powerful application framework that provides both a design and runtime environment. The framework itself is very flexible, easy to extend and provides a large set of application services. Amongst the services the ECO framework provides is the persistence service, which handles the mapping of object attributes, storage, and retrieval in a relational database. Within the architecture of the framework the ECO space has a central role. Before Enterprise Core Objects (ECO) III, the current version of ECO that is part of Borland Developer Studio 2006, the UML Class diagram was the only diagram used in ECO to visually design (or develop) your model. ECO III adds the State Machine diagram to model the behavior of classes.

State Machines in a nutshell

Your model can be defined in one or many ECO packages. With all the information (classes, attributes, operations, associations, constraints, etc) specified in your model the ECO framework can execute your model during the lifetime of the application. At runtime the ECO space manages the lifecycle of the objects created during the lifetime of the application. These objects are instances of the classes defined in your model. The values of the attributes of an object at a certain moment present a specific condition of that object during its lifecycle. Such a specific condition is called a state, and we can add a label to such a state to identify it. An event can cause an object to move from one state into another, this is called a state transition. The UML term used for the event is trigger. In ECO a trigger is defined as a method of the class. You can set the “Is Trigger” property to turn a method into a trigger. This should sound very familiar to the Delphi developer. Every Delphi developer has been introduced to the concept of event driven programming. For example, a control on a form can trigger an event. The event can then result in an object to transition from one state into another.

What is the benefit of using State Machine diagrams?

Looking at the description above, you might ask yourself, what’s new? Well, what is really useful about a State Machine diagram is that you can get a visual map that specifies the flow from state to state. The advantages of this map is that it is much easier to read than getting this info from your code. It includes all the business logic and it is easy to adapt to changes. To get an idea what a State machine diagram looks like, let’s look at an example of the State Machine diagram, in this case showing the state of an order.

Hide image
Click to see full-sized image

Figure 1: Order State Machine diagram.

The diagram shows the following items:

  1. Initial state;
  2. The Pending, Denied, Approved and Referred state;
  3. State transitions with a trigger, guard and effect;
  4. Example of state transition with a guard defined.

All UML State Machines must have one initial state. This initial state points to the State that is the actual initial state of the Object, in this example the “Pending” state. So the order starts in the pending state and can transition to either the denied, referred or approved state. We also see that business rules are defined. The transition into the approved state (from the pending state) is only possible if the condition (total of the order is less than 500) is true. This is called a guard. Besides a guard you can also define an effect for a transition. Similar, you can define entry and exit actions for states. ECO uses the Object Constraint Language to capture the business logic. You will agree that it is quite easy to understand what is going on.

Let’s see what is needed to develop this example with ECO.

Step by step example

  1. Create a new ECO WinForms project
    (File->New->Other->Delphi for .NET project).

    Enter the name of the application and the directory for the project files.
    In this example the application is called EcoOrderApp.

    Hide image

    Figure 2: New ECO WinForms Application wizard

    After the wizard has finished, it will have created a form, an ECO space and an ECO package. Look at the Project Manager for the files that have been generated.
  2. Since we are focusing on state machines in this article, we will start with the eco package to define the order class. Select the model view and open the tree.

    Hide image
    model view
    Figure 3: Model view

    The default ECO package created is called Package_1. Rename this to “OrderPackage”. You can select the node and right click to rename the node. Do the same for the Package_1Unit, rename this to “uOrderPackage”.
  3. Next, we will switch to the design surface for our ECO package to define the order class. Select the ECO package node and select Open diagram or double click on the node. Now we can really start with specifying the business logic.
    Add an ECO class and name this “Order”. Add the following attributes to the order class: Description (string), Units (integer) and Price (price).
  4. Add another attribute called Total (integer). Set the derived property for this attribute to true, using the Object Inspector, and specify the following OCL expression, “units * price”.
    This is a so-called derived attribute that is needed later when specifying the guards for the triggers. Look again at the state machine earlier in the article to remind you of the business logic. Maybe it is good moment to refresh our memory, since in the next steps we are going to add the triggers to the class.
  5. When you look at the example state machine, you see that the following triggers are used; they are Approve, Deny and Refer. Select the class and add the three triggers (the shortcut key to add a trigger is Ctrl-T). The end result looks like this.

    Hide image
    order class
    Figure 4: Order class
  6. It’s time to look at the state machine. Right-click the class and add an ECO State Machine. A new diagram is created with the name of the class (order). Using the tool palette add the State and Transition elements needed to the diagram and create a similar setup as defined in the image shown in Figure 1. After adding a transition between two states, you can specify the trigger property using the Object Inspector. All the triggers defined on the class are available for selection, as shown in Figure 5.

    Hide image
    trigger property
    Figure 5: Object Inspector
  7. The last step is to define the guards for the transition between the state “pending” and “approved” and the transition between the state “referred” and “approved”. As you can see in Figure 5, the Object Inspector also shows the guard property when you select the transition. As mentioned before, the guard is specified as an OCL expression, so the property editor used is the OCL editor as you can see in Figure 6.

    Hide image

    Figure 6: OCL Expression Editor
  8. The diagram itself also has properties; you will notice the State attribute. This property connects the diagram to the order class. Switch back to the class diagram and notice that the order class has a new attribute with the same name and that is marked as a State attribute in the Object Inspector. If you want you can change the name of this attribute from the default State_1 to something like OrderState.

After defining our business logic we switch to the ECO space. The toolbar at the bottom of the ECO space designer has a button to specify what ECO packages will be used by the application. Keep in mind that ECO uses the .NET reflection technology a lot, both at design and runtime. So when developing an ECO application it is a good idea to compile your project at specific intervals. This provides the most up to date information to the ECO designers.

Hide image

Figure 7: ECO Space UML Packages selection dialog

We will not use a persistence storage in this example. Look at some of the other articles on the Borland Developer Network for the steps to connect your ECO application to a database and specify the object relational mapping.

The fastest way to prototype

So what is the fastest way to explore our business logic? When developing ECO applications, you will find that the ECO debugger is also really useful if you want test your ECO package. Move to the Winform that has been added to your project and drop a button on the form. Select the button and navigate to the EcoAction on EcoGlobalActions property in the Object Inspector. Select the Showdebugger value from the dropdown list. The caption of the button will reflect this. For those that have already explored ECO, you are probably ready to add an Expressionhandle and specify the ECOspacetype property of the Referencehandle. It seems that we do not need to do this. The debugger already has a handle to our ECO space, as we will see when running the example. Now press F9 to run our example application. Once the form is shown, click on the button to activate the ECO debugger. The result will look similar to Figure 8.

Hide image
Click to see full-sized image
Figure 8: ECO Debugger

Now start to explore your application using the debugger, take the time to get used to the debugger, as I mentioned before, it is a very useful piece of functionality. In order to quickly test our state machine, select the Order class and double click on it. This will enable the Add button. Click on Add to create an instance of the order class.

Hide image
Click to see full-sized image
Figure 9: ECO Debugger

The debugger is also equipped with ECO Autoforms so we can open the Autoform by double clicking on the created row, as shown in Figure 10. The form will show the properties of the object, the current state defined with the triggers to transition to another state.

Hide image

Figure 10: ECO AutoForm for Order class

When a guard of the possible transitions is false, the corresponding button is disabled. Look again at the definition of the guards in the state machine diagram. To test this, change the units to 10 and the price to 50. The total of the order is now 500; which means we can no longer transition into the approved state, as shown in Figure 11.

Hide image

Figure 11: ECO AutoForm for Order class


Although the example presented is very simple, you can see that state machines will enable you to raise the level of abstraction. State Machines are a very powerful extension to the ECO application framework. In future articles I will explore more advanced topics of using State Machines.

Server Response from: ETNASC04