Borland® C#BuilderTM Architect extends the development capabilities of C#Builder to cover model-driven development. This saves time coding business logic by automatically implementing part of a UML software model.
In this article I’ll outline how to create a simple model-driven application that uses DB2 ® for its storage. I assume that you’re familiar with the basic use of C#Builder – if not, take a look at some of the other articles in the developerWorks DB2 and Borland Zone for tips.
A trial version of C#Builder Architect is available from the Borland Web site, together with a patch for the first version which addresses some compilation issues.
The Unified Modeling Language, or UML, can be used as a way to represent objects in a system, their interrelations and the processes they perform. UML itself is very comprehensive, with many different types of diagrams that together are used to represent just about every aspect of an application.
C#Builder Architect uses two of the UML diagrams, the Class diagram and the Package diagram. These are the two basic diagram types that are used to represent classes.
How C#Builder Architect saves development time
C#Builder Architect includes a new form of C# project, the Borland ECO application. ECO, the Enterprise Core Objects framework, creates and stores .NET Framework classes from UML class and package diagrams. For example, a model for a simple HR application might look like this:
Figure 1. UML class diagram of simple HR application
This application is intended to keep a simple log of departments, their employees, and applicants for jobs in the departments.
UML class diagrams are designed to be straightforward to read. In this case, you have a superclass Person, with sub-classes Employee and Candidate that inherit the properties (or attributes) and methods (or operations) of Person. The Department class has one or more associated employees, and one or more associated candidates.
A 'traditional' application would need to maintain tables for each of these data items and enforce integrity rules. That might mean a large amount of program code to write and maintain.
Here, for instance, you might want to extract the job titles as a class of their own and define further associations between employees, candidates, and their jobs. With a traditional C# application, you’d need to rewrite much of the application to make this change. In a model-driven application system such as ECO, it’s easy to make the changes to the model and regenerate the application. The data can even be migrated to recognize the changes.
With C#Builder Architect, you design a ‘UML package’ to contain these core classes. This UML package is used in turn by the ‘EcoSpace’ to define and store objects in memory that are instances of these classes. The EcoSpace can contain ‘persistence handlers’ that can write the objects away to a DB2 database.
The end result is that there’s no need to define data tables and write code to maintain them. Instead, ECO uses an object-oriented approach, storing the objects in a DB2 database transparently.
In this article, I’ll use ECO to quickly design a complete application that maintains the four tables listed above. The end result won’t look particularly pretty, but it shows the powerful way that ECO can look after maintaining rather complex objects and their interrelations.
An ECO application is a special form of C# program with extra containers and classes that work with ECO. It can only be loaded and edited from within Borland C#Builder Architect.
To create the application, choose File | New | Other…, then select C# Projects and choose ECO Application from the list. Choose a project name (such as HRApp) and select OK.
The application looks like any other blank project created using C#Builder. However, if you look carefully, you’ll see that an extra component has been added to the default WinForm. I’ll cover the use of the reference handle rhRoot later when I talk about how to connect components on the form to objects in the database.
If you examine the Project Manager, you’ll see that there are three additional source code units that have been included:
CoreClasses.cs contains the class definitions
from the UML package used by the application. This unit of code is managed
automatically by C#Builder Architect and makes extensive use of C#
attributes. You shouldn’t need to edit this file directly.
EcoSpace.cs is where the classes defined in
CoreClasses.cs are turned into objects. The EcoSpace also contains the
persistence mapper that stores the objects away to a DB2 database. An
application can contain several EcoSpaces; classes can be divided among
them by using UML packages. The classes for an EcoSpace are stored into
the associated DB2 database.
EcoWinForm.cs is a specialized WinForm that
works directly with the objects on the EcoSpace. It’s instantiated in a
special way, as you’ll see later on.
To create the model, switch to Model View and expand the top-most leaf. You’ll see three further leaves at the next level:
Figure 2. Initial model view of a blank ECO Application
The gray 'folder' icon named CoreClassesPackage represents the logical (or domain) model for the application. This is where the UML definitions create classes. The Model View reads this from CoreClasses.cs.
The white ‘application’ icon named after your project represents the implementation of the model and is where the language-specific and operating-specific definitions are made. Each C# class in the application has a leaf under this icon, including the classes defined through the UML diagram and the classes defined automatically by C#Builder as part of the application. Note that for implementation, C#Builder automatically adds extra internal members to the class definitions for the ECO classes.
The third icon is a colored ‘model’ icon. This is used to open the UML diagram in the main IDE. Double-click on this, and for the blank application, at the top level you’ll see two packages in the UML diagram: CoreClassesPackage and the implementation package.
Figure 3: Initial overall UML diagram for a blank application
Double click in the diagram on CoreClassesPackage and you’ll go down one level to the UML designer for the application. Because you haven't defined any objects yet, this designer is blank.
Defining classes in the UML model
In the UML designer, you draw the model graphically. It will look like this:
Figure 4: The final version of the UML model
To create the Person class, click on the Class icon in the tool palette and draw a box on the design surface. A blank class named Class_1 is added; wait a few moments and you will be able to enter the class name Person.
Next add the properties; in UML, these are known as attributes. Right-click on the Person class and choose Add | Attribute. Enter Name: string to name the attribute and define it as the in-built String class. Click Enter; C#Builder automatically adds the "+" visibility operator.
Repeat the step for the other attributes; I suggest HomePhone:string and HomeEmail:string for now. One of the great advantages of ECO is that you can very easily add new attributes without having to rework the complete application - the data storage is even updated automatically.
With the Person class completed, add the Employee and Candidate classes in the same way. You’ll add their attributes in a moment.
These are sub-classes of the Person class; in English, employees and candidates are people, too. C#Builder lets us show this 'generalization' through the arrow tool on the tool palette. Use this tool to draw a line from the Employee class to the Person class to signify this relationship. Do the same for Candidate class.
Now you can add the extra attributes for the two new sub-classes. The Employee should have three more attributes, WorkPhone:string, WorkEmail:string, and JobTitle: string. Candidate has one extra attribute, JobSought:string. Because Employee and Candidate are sub-classes of Person, these attributes add to those that you’ve already defined for the Person class.
Next, you’ll add a fourth class, Department. This will be used to filter the employees and candidates for particular departments. Add attributes Name:string and Location:string. You can always add more later.
Defining associations between classes
The next step is to define UML associations between the employees, candidates and their department. Click on the Association icon on the Tool Palette and draw a line from the Candidate class to the Department class. C#Builder automatically creates the association, names it Association_1, and assigns a default multiplicity to each end.
What you’ve done here is to define a simple one-to-one relationship between objects of the two classes. The multiplicity '0..1' says that for a particular candidate there could be zero or one matching departments. Similarly, each department might have zero or one associated candidate.
This isn’t what you want. In practice, a department might have zero or many candidates - in other words a '0..*' multiplicity. You’ll simplify matters and assume that each candidate will have one, and only one, department to which they’ve applied for a job - in other words, a '1' multiplicity.
To fix this, click on the association, and use the Object Inspector to set the following properties. You’ll need to expand the End1 and End2 properties to this:
End1.Multiplicity: 0..* End1.Name: mightEmploy End2.Multiplcity: 1 End2.Name: mightWorkFor |
The end result should look like Figure 4 above.
The names of the association ends are important – they’re used as attributes in their own right.
Repeat these last steps for the association between employees and their departments. Set the properties for the association to be:
End1.Multiplicity: 0..* End1.Name: employs End2.Multiplicity: 1 End2.Name: worksFor |
Quite remarkably, that’s all you’ll need to do to set up the classes. From this point ECO will maintain the relationships and ensure that any objects that are created adhere to the associations - so, for instance, an Employee object ‘myEmployee’ will have a property ‘myEmployee.worksFor’ that is their Department object. Similarly, a Department object ‘selDepartment’ will have a property ‘selDepartment.mightEmploy’ that is a collection of Candidate objects.
But we’re getting ahead of ourselves. Let’s create the user interface so you can instantiate some of these objects.
Putting together a user interface
Before you create the user interface, it’s important to compile the application. If you look at the source code of CoreClasses.cs (switch to the Project Manager and double-click on the file) you’ll see the UML editor has created attributes (in square brackets) alongside the classes. These are used internally by ECO to read the model and generate the objects correctly.
In C#, attributes work through .NET reflection, which is the ability of a class to describe itself. The classes don’t exist until the application is compiled, so .NET reflection won’t work until you press Ctrl-F9 to build the application. (Note, early versions of C#Builder Architect would return an error at this point. You’ll want to download and install the latest updates from the Borland Web site to address this.
Compiling so that reflection works is necessary in a fair number of places throughout your work with C#Builder. It’s best to make it a habit, like saving a project: whenever you adjust the model, press Ctrl-F9 to compile.
The user interface that you’ll create for this application won’t look like anything special, but it will show how to work with the classes that we’ve created. You’ll start by adding three DataGrid components to the main WinForm of the application so we can enter departments and employees and see the overall list of people in our system. Then you’ll add an extra form to add and delete candidates.
Switch to the Project Manager and double-click on the WinForm.cs source file. The form designer that you saw at the start should be displayed with a blank form.
For an ECO Application, the WinForm works very much as it does for a regular Windows Form application. This is the form that’s displayed when the application is first loaded.
However, as you noticed, an extra component has already been placed on it: rhRoot, a ReferenceHandle. In ECO, reference handles are used to point to an object in a model in the application. Click on rhRoot and set the EcoSpaceType property to point to the entire EcoSpace:
Figure 5: Each WinForm in an ECO Application has a reference handle rhRoot
If you don’t see the EcoSpaceType value in the drop-down list, then it’s most likely that you haven't compiled the application. Press Ctrl-F9 and try again.
A real strength of ECO is that it’s very easy to use the objects that it defines. The key to this is the ExpressionHandle, which makes the objects in the model available as regular, ordinary, conventional .NET data sets. From there, they can be connected to any of the data-aware components just as if they were getting their data from ADO.NET. All the familiar programming techniques for working with data sets work with ECO ExpressionHandles, too.
Place an ExpressionHandle on the form, and set its properties as follows:
Name: ehDepartment RootHandle: rhRoot |
Click on the property editor next to Expression. Here’s where you can graphically build an expression for this handle using UML Object Constraint Language.
Figure 6: ECO includes an OCL expression editor
You want the Department objects, so double-click on Department on the right-hand pane. The method that returns a .NET collection is .allinstances, so double-click on that. The OCL parser at the bottom of the OCL expression editor confirms that the syntax is okay and that you’re returning a collection.
Now all you need to do is add a DataGrid to the form and hook up its DataSource property to point to ehDepartment. Do this, and you’ll see the columns for Name and Location are automatically added.
Next you want a way to create objects. Add a button and set
Name: btnAddDepartment Text: Add Dept |
Against the Click event handler, add the one line of code:
new Department(EcoSpace);
Run the application. Click the Add Dept button, and you’ll see a blank Department object appear in the grid. Enter some data, and click the button again to enter another department.
Figure 7: Simple UI
You’ve now done everything that you need to do to create and edit Department objects. However, once you close the application, any changes disappear into the ether. This is because the objects are all created in memory and aren’t stored to disk at any point.
As I’ve already discussed, the EcoSpace is the central part of the application where the objects are defined and stored. C#Builder Architect provides an EcoSpace designer that can include persistence mappers that store the objects into a relational database. IBM DB2 is a great choice for use as a persistence store.
One consideration to bear in mind is that ECO really needs to have its own database to store its objects. This is because there are several internal system tables that are used to control the objects alongside tables that contain the data. If you use the IBM DB2 administration tools to browse the data, you’ll see that there are additional fields in these tables, too, which are used internally.
Using the DB2 command prompt on the server, or using the Control Center, create a new database called ECOHR. Set up your client workstation to point to this database in the regular way, and add the database to the available databases in your C#Builder Data Explorer. (See this article for more information.)
The EcoSpace.cs source file has its own graphical editor that can be used to set up the persistence mapping for the objects to the database. First, use the Project Manager to switch to the EcoSpace.cs designer. Then drop a BdpConnection component on the workspace and use the Connection Editor at the bottom of the Object Inspector to point it to the database. This will be used to store the data away in the DB2 database, just as for a regular application that uses the Borland Data Provider. (For more information on the Borland Data Provider, click here.)
Then, choose the persistence mapper component. The one you’ll use, persistenceMapperBdp, maps to the Borland Data Provider. The two others in C#Builder Architect are persistenceMapperSql, used to connect directly to SQL Server through the ADO.NET SqlConnection component, and persistenceMapperXml, which uses an XML file for storage.
Select the persistenceMapperBdp component and drop it on the EcoSpace designer. Set the Connection property to be bdpConnection1, created in the previous step.
The next step is to set up the particular SQL dialect that the persistence mapper will use – in this case, the DB2 SQL. There’s a property editor that does this in one step, but to see what it does, first expand the SqlDatabaseConfig property in the Object Inspector. Then click on the DB2 Setup property editor. Notice the changes to the SqlDatabaseConfig properties.
Figure 8: Customizing the persistence mapper for DB2
You can adjust these parameters according to the needs of your application. Some will have a considerable impact on performance – for instance, the limit of 250 rows retrieved in a single SELECT statement in FetchBlockSize.
Finally, you need to set the PersistenceMapper property of the EcoSpace to point to the persistence mapper you just created. Click on the background and set the property to the persistenceMapperBdp1 component.
The EcoSpace designer has a small toolbar at the bottom-right that maintains the underlying database.
Figure 9: The EcoSpace toolbar is used to create and maintain the mapping to DB2 databases
Click on the icon at the far left. You’ll see a dialog asking you to confirm that the application has been recently compiled. This is an essential step at this point, because otherwise the database could be generated from an out-of-date model definition.
The Messages window is displayed at the bottom of the IDE. A message will appear if the database was generated; otherwise a diagnostic error will be shown.
Figure 10: ECO has its own output window in the Messages pane
Loading and saving objects from the database
The final stage that I’ll cover in this first article is to store the objects to the database. This needs a single method call.
So you can keep track of what’s happening, you’ll add a button to the form to save the EcoSpace objects. Go back to WinForm.cs and add a button at the bottom, setting the property Name to btnSave and Text to Save.
The Click handler for btnSave should read:
EcoSpace.UpdateDatabase()
That’s all that’s necessary: ECO will now automatically store the objects in the database when the button is clicked.
Figure 11: The application now stores objects in the database
Run the application, and enter a few rows. Click the Save button. Close the application and then run it again – you’ll see that ECO automatically restores the objects when the application loads.
You have control over the restoration of objects. If you scroll to the constructor for the WinForm, you’ll see that C#Builder has added code to automatically initialize the EcoSpace when the application loads. If you need to, you can add your own code here to set up the database connection before the EcoSpace is loaded – perhaps to authorize the user or log in to a database.
Because ECO handles all of the data storage internally, ECO applications are perfect for new developments where there isn’t any particular need to work with an existing set of data tables. In particular, development teams that are accustomed to using UML models as the blueprint for an application – rather than database schemas – should find ECO a very productive way to create applications.
ECO can use any relational database to persist objects, but it is especially well-suited to IBM DB2 UDB. The scalability and reliability of the database, together with its ability to run on a broad range of hardware, make it the perfect complement.
While you’ve created a fairly sophisticated model here, you’ve only given the user the ability to maintain one class of objects. In the next article, I’ll extend the user interface to control the additional classes and examine how these are manipulated in code.
- Before working with ECO, you’ll want to understand the basic
principles of C#Builder and how it works with databases. There’s a
great introduction to this in the developerWorks articles
here.
- You can also find some further information on how the ADO.NET
architecture differs from other Borland products
here.
- For more information on ECO, see the
Borland Web site.
- For more information on the UML modeling language that’s used in ECO,
see
www.omg.org/uml
and
www.rational.com/uml.
Jeremy McGee started writing applications using BASIC on the Commodore PET. He fondly remembers typesetting a book-length publication on an early Apple Mac with a refrigerator-sized laser printer attached. Since then he's variously been a DEC VAX sysadmin, a technical support engineer for Borland Paradox, and was part of the team that launched Borland Delphi in Europe. Jeremy now runs a consulting firm in Southampton, UK.
Comments (Undergoing maintenance)
Table of contents
- Introduction
- UML models
- How C#Builder Architect saves development time
- The ECO application
- Working with the Model View
- Defining classes in the UML model
- Defining associations between classes
- Putting together a user interface
- Storing the data
- Initializing the database
- Loading and saving objects from the database
- Conclusion and Next Steps
- Resources
- About the author
- Comments
Next steps from IBM
My developerWorks community
Tags
Use the slider bar to see more or fewer tags.
Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).
My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
