menu

• abstract : Writing a simple ECO application: the UML model, the in memory objects and the GUI presentation. We also will show how to evaluate OCL expressions
  
• key words : ECO - Enterprise Core Objects - UML - EcoSpace - OCL - Object Constraint Language - ExpressionHandle - UML class diagram
  
• software used : Windows XP Home, Delphi 2006
  
• hardware used : Pentium 2.800Mhz, 512 M memory, 140 G hard disc
  
• scope : Delphi 2006, Turbo Delphi for .Net
  
• level : Delphi developer
  
• plan :
  
  • ECO modeling and coding
    
  • An Invoicing example
    
  • Handling Related Classes
    
  • OCL: the Object Constraint Language
    
  • Download the Sources
    
  • ECO documentation
    

---

1 - ECO modeling and coding

ECO is a Delphi modeling tool: the developer draws the model of his application, and the ECO framework builds an in-memory structure of this model using objects. This representation is used to implement the model in order to add a visual interface to our application (Forms, Buttons etc) and transfer the data to disc (.XML files or Sql Database).

The overall objective is to let the developer work at a high model level, letting the ECO machinery take care of many of the low-level coding tasks (writing Sql requests, synchronizing the visual GUI with the Tables, handling master / detail navigation etc).

This tutorial will present how to write a simple, application with ECO.

---

2 - An Invoicing example

2.1 - The Goal

We will build a tiny invoicing application with INVOICEs and ITEMs. Each ITEM corresponds to a PART, which can be either manufactured by our company, or purchased outside.

This corresponds to the following diagram:

In this paper, we are only going to use the invoice / item CLASSEs:

2.2 - The ECO architecture

Building and ECO application involves 2 basic steps

• create the UML model for this application
  
• generate the Delphi code corresponding to this model, and write some code
  

This can be represented by the following figure:

and

• we draw the UML Class diagram using any kind of UML editor (Rational Rose, Model Maker, Together)
  
• this "picture" is converted into a code structure. This is the EcoSpace which contains:
  • the classes from the UML Class diagram (in the UMLRt, which is the Run Time representation of the diagram)
    
  • the objects which are instances of those UML Classes which will contain the values of our Database
    
• we can access those EcoSpace objects (for creation, reading, writing) using EcoHandles. Those handles are used for displaying the values in GUI controls
  

2.3 - Create the UML model

To create the ECO model, we will start an ECO project. This can be done using the Delphi Wizard. So let's start a new Windows Forms ECO application:

2.4 - Building the Model

Let's create the basic UML model with the 3 CLASSes.

The diagrams are created on the modeling surface, which must be displayed:

To create the diagram for our INVOICE CLASS

A this stage, compile the project, in order to synchronize the model (the UML drawings) with the EcoSpace (the object representation of those drawings). So: This compilation is required, since the Delphi IDE will use the in-memory representation of the UML drawing. So compiling is often required, as well as clicking on the "Regenerate Eco Source Code" - like icons a the top of the model view notebook.

You may look at the PACKAGE_1UNIT.PAS, which now contains 2 more definitions

• the c_invoice CLASS
  
• a Ic_invoiceList INTERFACE which is used to represent the list of invoices (the in-memory representation of our future disc data content)
  

Note that

• compiling from time to time seems to be a good idea. The p_01_invoicingEcoSpace design surface even reminds you to compile each time you load the project in the Delphi IDE.
  

2.5 - Adding Invoices

To add invoices, we have to call a c_invoice CONSTRUCTOR and initialize the attributes:

• one of the c_invoice CONSTRUCTORs uses the tWinForm.EcoSpace as its parameter. This allows the object to be added to the invoice list contained in the EcoSpace
  
• the c_invoice CLASS contains the m_customer and m_invoice_number members which can be used to initialize the object
  

Therefore

2.6 - Saving the Result in an .XML file

To save the objects to disc, we can place them in .XML files or into some Sql Database. To avoid mixing ADO .Net components in our tutorial, we chose to use the more simple .XML files.

Persisting the data in an .XML file only requires a PersistencMapperXML component which takes all data objects contained in the EcoSpace and saves it to (or reads it from) an .XML file.

That's quite easy:

Once the .XML file has been created, the data will automatically be loaded in the EcoSpace at each run. This is similar to the tClientDataSet briefcase saving. Of course, if you remove the file name from the PersistentMapper, this will not happen.

From an architectural point of view, we have the following (partial) diagram:

and:

• our tWinForm contains an EcoSpace attribute
  
• the EcoSpace CLASS contains a PersistenceMapper attribute
  
• there is a whole hierarchy of persistence mappers. We used the .XML mapper, but we could have chosen a PersistencMapperBDP, or PersistenceMapperSqlServer
  

At this stage, I would suggest that you start looking into the Help. Clicking F1 and navigating to the ECO Framework, you will find all the Assemblies involved (partial view):

image

The main Assemblies are:

• Borland.ECO.UmlRt where all the CLASSES and INTERFACES for the in-memory object representation of the UML graphic are located
  
• Borland.ECO.ObjectRepresentation which contains all the objects containing our data (the values of our invoices)
  
• Borland.ECO.Services, for all the ECO services. We will not present them in detail, but they are at the heart of the ECO machinery
  
• Borland.ECO.Handles, which contains our EcoSpace, as well as the ReferenceHandle and ExpressionHandle that we will use shortly to display the objects in a DataGrid
  
• Borland.ECO.Persistence for all disc handling
  

2.7 - Displaying the invoices

We will now display the values of our invoices in a TextBox.

To list the in-memory invoices, we need to use an ExpressionHandle. The handles are a way to read or write the EcoSpace elements. Handles can return values, objects or object lists. What will be returned depends on the ExpressionHandle.Expression, and this Expression is written in some special language called OCL (Object Constraint Language). In our case, we want all the invoice objects, and the OCL expression is

ExpressionHandles can be chained: we can reach a list of objects using a first expression, and add a chain another ExpressionHandle to do some filtering, for instance.

The ExpressionHandle chains must have a starting point, which is specified in the ExpressionHandle.RootHandle property.

In our case we will use the rhRoot Handle. And we must initialize the rhRoot.EcoSpaceType property with the Tp_01_invoicingEcoSpace.

So :

Note that

• OCL might be case sensitive (it seems Bold was, maybe ECO I, ECO II and ECO III are not)
  

To put those handles into perspective, here is a (partial) UML Class diagram:

and:

• we start the access chain with a ReferenceHandle. This handle is used to reach into the EcoSpace. Usually we use the rhRoot handle which was generated by the Wizard. We simply must check that this rhRoot has been initialized with some EcoSpace, and that has been done after the first project compilation by setting the rhRoot.EcoSpaceType to p_01_invoicingEcoSpace.Tp_01_invoicingEcoSpacepoint

• we use an ExpressionHandle linked to this ReferenceHandle

• now the ExpressionHandle has two basic functionalities :
  
  • it allows us to write an OCL Expression, which will yield in the ExpressionHandle.Element some iElement descendent. In our case an iObjectList.

    We cannot directly display an iElement. It lives in the outer EcoSpace there, some kind of Walhalla filled with thunder and lightning. So we first have to cast it using iElement.AsObject. More seriously, it seems that the EcoSpace has a fragmented representation of our c_invoice CLASS, and AsObject brings all the parts back together, yielding a nice tObject with all the attributes and methods. And since we know that this object is a c_invoice, we cast it into a c_invoice and can then use the c_invoice.m_customer members.

  • the ExpressionHandles are mainly used as visual control DataSource, since ExpressionHandles implement the iBindingList INTERFACE. This will be presented below
    

2.8 - Implementing ToString

If we want a general display of our classes, we can implement the VIRTUAL ToString FUNCTION in our CLASS.

To do so

2.9 - Deleting an invoice

To remove an invoice from the invoice list, we mark it as "deleted". The next saving to the persistent media will physically remove this invoice when UpdateDataBase is called (by removing it in the new .XML file version, or by generating an DELETE Sql request).

Here is an example which deletes the second invoice (index 1):

Note that

• you should NOT remove the object with Free or Destroy, since the in-memory list will no longer contain any information about this object, and it will not be deleted from the disc files (.XML or Sql Database)
  
• the Delete method is part of the iObject (see the UML diagram above). To call this method, we first must cast the c_invoice object into an iObject object, and this casting is available in c_invoice (as represented in the UML diagram above)
  

2.10 - Display in a DataGrid

Instead of manually dumping the invoices values in a TextBox, we can display them in visual controls, using the Windows Forms binding mechanism (see the Ado .Net tutorial for more details about binding).

Here is how to display the invoices in a DataGrid:

Note that

• in usual ECO applications, you will go directly from the UML diagram to the DataGrid, without the creation and listing steps. All that is required is
  • some kind of PersistentMapper to get the data
    
  • an initialized rhRoot
    
  • an ExpressionHandle with the relevant OCL Expression
    
  • and, of course, a DataGrid
    

You can change the values in the DataGrid, but cannot insert new invoices. To do so, you must first create the c_invoice object, and you can then set the values in the DataGrid. Here is an example:

The DataGrid can be used to navigate the invoice list. If we want to perform some action on the current invoice, we must find a way to find which invoice is the selected invoice in the DataGrid.

This can be achieved using a Windows Forms CurrencyManager-like component (see the Ado .Net tutorial for more details about the CurrencyManager).

Therefore:

---

3 - Handling Related Classes

3.1 - Master Detail relation

We want to add invoice items: each invoice contains several items with price and quantity.

This is done using the following steps

• we add a new c_item class to the UML class diagram
  
• we add an association between the c_invoice and the c_item classes. We must specify on both ends of this association
  • the multiplicity (1 on the c_invoice side, 1..* on the c_item side, meaning that any item MUST belong to a single invoice, and any invoice has at least 1 item, possibly many more)
    
  • the name of the association end.
    
    • on the c_item end, we chose has_item, which can be read from left to right "a invoice has_item the items'
      
    • on the c_invoice end we chose from_invoice, which means "an item comes from_invoice an invoice"
      
  The class diagram looks like this:
  image

• now the important part: we want to add an invoice with 2 items
  
  • we create the my_c_invoice object, as explained above
    my_c_invoice:= c_invoice.Create(EcoSpace);
    my_c_invoice.m_customer:= 'Miller';
    my_c_invoice.m_invoice_number:= 1234;
    

  • for each item
    
    • we create the item
      my_c_item:= c_item.Create(EcoSpace);
      my_c_item.m_price:= 765.33;
      my_c_item.m_quantity:= 18;
      

    • we add this item to the invoice's item list:
      my_c_invoice.has_item.Add(m_c_item);

      This is the crux: we use the has_item relation-end name as a COLLECTION of c_item objects

      We could also have worked the other way around, by specifying to which c_invoice the newly created c_item belongs:

      m_c_item.from_invoice:= my_c_invoice;
      
      

Note that

• this use of the relation end names is called OCL navigation
  
• we did not include any key in the c_invoice table. There is an underlying key, but is is automatically managed by the ECO framework
  
• using the my_c_invoice.has_item collection is similar to a tObjectList nested inside each c_invoice. But OCL navigation is more general then simple containerpart relations
  

3.2 - Add the invoice_items

So let's implement this relation in our code.

You may use the previous project, but for this presentation, we will start a new project. Here are the steps to create the invoices part (everything here has been explained above):

We will now add the c_item CLASS:

If you look at the c_invoice CLASS (in PACKAGE_1UNIT.PAS) you will notice that the CLASS now contains a has_item PROPERTY (the code has been heavily changed):

Here is how to add a couple of items to our first invoice:

To check that the invoices and the items are correctly linked, we can display them in a TextBox

Using the same technique, we added a couple of items to the other invoices (the "create_items_" Button which is in the .ZIP sources).

To add the item DataGrid display, we follow those steps:

Note that

• we could not impose the attribute order in the c_item UML class diagram. We first chose (m_price, m_quantity) and then tried to change it to (m_quantity, m_price) but could'nt succeed
  
• for the (m_price, m_quantity) first trial, the invoice_grid had a last "has_item" column in the invoice_datagrid. After trying to switch to (m_quantity, m_price) we have a first "from_invoice" column.
  By the same token, we could not increase the size of the invoice_datagrid last column width. There must be a way to do those things, but since this is not the most important part, we
  

In a way similar to how we deleted an invoice, we can add some items to the current invoice using the CurrencyManagerHandle component

---

4 - OCL: the Object Constraint Language

4.1 - OCL for navigation and for modeling

OCL at the start was created to impose pre and post-conditions, similar to the pre and post-condition that the Eiffel language introduced to implement "Design by Contract". For a bank withdraw() method, you require that at the start of the method, just after BEGIN, the balance should be greater then the amount taken out, and after the withdrawal, just before the END of the method, the balance must be equal to the starting amount less the amount taken out. It basically is an expression language allowing to specify in a non procedural way how the methods of our CLASSes are changing the state of our system. In other words specifying the behaviour of the model. Since the methods of one CLASS often uses other CLASSes, OCL also formalized navigation, allowing for instance to specify that the total of the c_item amounts of a c_invoice should be greater than 100ƒhƒ‹:

In our projects above, we already used OCL expressions to navigate the model. For instance, to be able to visualize the invoice collection in a DataGrid, we used:

my_c_expression_handle.Expression:= 'c_invoice.AllInstances';

We now are going to investigate some other OCL expressions.

4.2 - Evaluating OCL expression by Code

So lets start with the expression that we already used, c_invoice.AllInstances. This expression computes the list of all c_invoice objects. The result of this computation is some kind of list. To be more accurate, it is an iObjectList.

To compute this list we call the EcoSpace.OclService.Evaluate function, which returns the iObjectList:

This iObjectList has a Count and an Item property. Each Item[nnn] is an iElement. So to display it we have to cast it back into our Delphi object world, using AsObject:

Since our objects (c_invoice and c_item) implement the ToString FUNCTION, we will see the values displayed.

This is how we implemented this evaluation

Here is an UML Class diagram of this evaluation:

and:

• our tWinForm contains the EcoSpace attribute, this EcoSpace containing the OclService member
  
• the OclService.Evaluate returns one of the iElement descendents
  

4.3 - Evaluating different iElement expressions

How do we know that the type of the AllInstances is iObjectList ? Well OCL expressions compute values in the EcoSpace world. The object kinds in this outer world are all descendents of iElement, and the iElement CLASS has a ContentType enumeration, which tells us which descendent of iElement should be used. So while spelunking in this EcoSpace world, we used the following FUNCTION which displays the iElement descendent that should be used

Here is the function (which is in the downloadable .ZIP):

Note that

• since ContentType is defined in the Borland.Eco.ObjectRepresentation Namespace, we also had to move this USES from the IMPLEMENTATION to the INTERFACE level
  

To be able to display other iElement descendent expression, we then implemented the other evaluation methods. Here are all our OCL expression evaluation and display methods:

At the start of the method we also display the expression string (this is not shown here)

4.4 - OCL expression gallore

4.4.1 - Class member collection

We can request to evaluate the values of the members of a CLASS. For instance, to get the list of all customer names, we can use:

The result of this expression is a collection, with the iElementCollection TYPE. So we called:

4.4.2 - OCL operators

OCL contains some predefined functions, like Size. We can call this on any iObjectList or iElementCollection values. To avoid some conflict with any CLASS attribute which could be named "Size", OCL decided to use the "->" symbol to specify a FUNCTION call, like this:

The result of Size is an iPrimitive Integer value, so we called:

Also not that those functions are called "operators" (like UML methods)

4.4.3 - ForAll

To check that some condition is true for all members of a list, we can call the ForAll function:

The result of Size is an iPrimitive Boolean value, so we called:

4.4.4 - Select and Self

The Select FUNCTION allows us to extract a list of iElements from a list:

The result of Size is an iObjectList, so we called:

We used this Select to specify a single c_invoice object. All OCL expressions are evaluated in some context. In our case, we used the global EcoSpace context. But if some expression is in the context of one object (say the invoice object of Mr Miller) we could use the Self OCL specifier. Like this:

4.4.5 - Navigating to a related object

To navigate to another object, we use the relation end names. For instance, to display the items of some invoice:

And to display the iObjectList values:

The result of Size is an iObjectList, so we called:

s
Checking the OCL expression

To make sure that our OCL expression is correct, we can use the OCL Editor. This is accessible from the ExpressionHandle.Expression property in the Object Inspector.

So:

---

5 - Comments on this ECO III with Delphi 2006 tutorial

5.1 - What's Next ?

Among the many things that were not presented, we can list

• the use of Sql Database persistence. Since we already presented many papers about ADO .Net, the connection should be easy. However, ECO has also some specific parts for handling transactions and tweaking the generated Sql requests
  
• the uses of ASP .Net Web pages, and Web Services. There are published papers in this area (see the references)
  
• the creation of "derived attributes", which in Delphi language means calculated fields
  
• the creation of "ECO Variables", which are the equivalent in OCL world of the parameters in parametrized Sql requests
  
• the creation of custom OCL operations (adding new OCL function, in addition to Size etc)
  
• using OCL constraints at the UML model level
  
• the possibility to execute the UML state diagram, and in ECO III to use an Action Language (wich can change the state of the objects, whereas OCL only evaluates expressions, without side effects)
  

5.2 - OCL for modeling

My primary motivation to look at the ECO framework was to try the OCL language.

To be able to code at a more abstract level than Pascal code, UML (or any other modeling language) looks like a very good choice for structural modeling (Class diagram). On the behavioral side, things get more complicated.

First of all you have two schools:

• one trying to work at the UML model level only, and the framework will blindly generate the Pascal code. The same jump from model to Pascal as from Pascal to Assembler. This is the MDA approach, with Action Languages, implemented by Kennedy Carter, PathFinder or xtUML and MELLOR at Bridgepoint. Quite heavy machinery, with many marketing enthusiatic presentations, and very few real life examples, if any. In addition these models generate the code from State Diagrams, since those frameworks are anchored in the telecom world (the phone is "on hook", "ringing", etc)

• one trying to use the UML model as a starting point, this model being used to generate some stub code that the developer has to fine tune. This is the "round trip" approach.
  In this area you find both generation from State Diagram or from Activity Diagram (or Object Diagrams). The Activity Diagram approach focuses more on chunks of work, than state. This is obviously more in line with business thinking ("process the order", "manufacture the product" etc), and somehow gave birth to the Workflow models.
  

At the end of this ECO trial, we now know how to use some specification language at the UML model level, like OCL, to navigate the different Classes of the model, and this was our main target at this point. And ECO is the only implementation we have, with State Diagram execution and Action Language.

---

6 - Download the Sources

Here are the source code files:

• 01_invoicing.zip: the project with the single c_invoice CLASS (36 K)
  
• 02_invoicing_relation.zip: the project with 2 CLASSes linked with a relation (37 K)
  
• 03_invoicing_ocl.zip: the project with the OCL evaluation examples (44 K)
  

The .ZIP file(s) contain:

• the main program (.DPR, .DOF, .RES), the main form (.PAS, .DFM), and any other auxiliary form
  
• any .TXT for parameters, samples, test data
  
• all units (.PAS) for units
  

Those .ZIP

• are self-contained: you will not need any other product (unless expressly mentioned).
  
• for Delphi 6 projects, can be used from any folder (the pathes are RELATIVE)
  
• will not modify your PC in any way beyond the path where you placed the .ZIP (no registry changes, no path creation etc).
  

To use the .ZIP:

• create or select any folder of your choice
  
• unzip the downloaded file
  
• using Delphi, compile and execute
  

To remove the .ZIP simply delete the folder.

The Pascal code uses the Alsacian notation, which prefixes identifier by program area: K_onstant, T_ype, G_lobal, L_ocal, P_arametre, F_unction, C_lasse etc. This notation is presented in the Alsacian Notation paper.

As usual:

• please tell us at fcolibri@felix-colibri.com if you found some errors, mistakes, bugs, broken links or had some problem downloading the file. Resulting corrections will be helpful for other readers
  
• we welcome any comment, criticism, enhancement, other sources or reference suggestion. Just send an e-mail to fcolibri@felix-colibri.com.
  
• or more simply, enter your (anonymous or with your e-mail if you want an answer) comments below and clic the "send" button
  Name :

  E-mail :

  Comments * :

• and if you liked this article, talk about this site to your fellow developpers, add a link to your links page ou mention our articles in your blog or newsgroup posts when relevant. That's the way we operate: the more traffic and Google references we get, the more articles we will write.
  

---

7 - ECO documentation

We are not overhelmed with documentation, but here is what I found:

• the basic tutorials are those from Anthony RICHARDSON
  
  • first the Bold tutorials (the ancestor of ECO)
    
  • Creating your first ECO application
    
  • Working with Associations
    
  • Using ECO II with Databases
    
• there are a couple of slides (use Google to find the links)
  
  • Jason VOKES, Gerard VAN DER POL (marketing slides)
    
  • Peter MORRIS, did some presentations, and also has a blog (see below)
    
  • Tim JARVIS
    
• some blogs will keep you up to date
  
  • Holger FLICK
    
  • Malcolm GROVES
    
• there is a book:
  
  • Alois SCHMID who wrote a book in german, which seems to have been translated in English
    
• Peter MORRIS has several interesting places:
  
  • the site myecospace.net contains documents on ECO
    
  • you will also find his blog here
    
• there is a Eco Community page on the CodeGear site
  
• also there is a Wiki page at CogeGear with very nice tutorials on some detailed points of ECO II or ECO III. Exactly what a Borland tutorial should have looked like in the first place (but for the whole framework, not for some specific points only)
  
• ECO Wikia a wiki about ECO. And there are other Wiki pages about ECO
  
• projects
  
  • Delphi_Unleashing_enterprise_models_with_Delphi_8_Architect_for_.NET.pdf" - by Christoph FLOURY - A Whitepaper with a Project Mangement example, and the most complete Class diagram about the ECO Framework
    
  • BLOGGING WITH DELPHI is a 4 part paper from Bob SWART explaining how to build a blog application with ECO and ASP.Net
    
  • Real life complexity with ECOII by Hans KARLSEN, is a time keeping application
    
• using Tamaracka to search the Eco newsgroup, you will find many ECO questions, and, what is very nice, is that the ECO developer often directly answer to the questions
  

Overall, I feel a little bit disapointed that ECO changed so often, and that the official documentation (manuals or Help) are so thin. But all those resources should get you started in this brave new ECO world.

---

8 - The author

Felix John COLIBRI works at the Pascal Institute. Starting with Pascal in 1979, he then became involved with Object Oriented Programming, Delphi, Sql, Tcp/Ip, Html, UML. Currently, he is mainly active in the area of custom software development (new projects, maintenance, audits, BDE migration, Delphi Xe_n migrations, refactoring), Delphi Consulting and Delph training. His web site features tutorials, technical papers about programming with full downloadable source code, and the description and calendar of forthcoming Delphi, FireBird, Tcp/IP, Web Services, OOP / UML, Design Patterns, Unit Testing training sessions.

+ articles_with_sources
+ database
+ interbase
– firebird_trans_simulator
+ sql_server
+ bdp
– db_refactoring
– sql_parser
– sql_to_html
– sniffing_interbase
– dbx4_programming
– blackfishsql
– rave_pdf_intraweb
– rave_reports_tutorial
– rave_reports_video
– embarcadero_er/studio
+ firedac
– bde_unidac_migration
+ web_internet_sockets
+ oop_components
+ uml_design_patterns
+ debug_and_test
+ graphic
+ controls
+ colibri_utilities
+ colibri_helpers
+ delphi
+ firemonkey
+ compilers

+ delphi_training

+ delphi_developments

+ sweet_home

– download_zip_sources

+ links