Malcolm Groves: ECO

ECO III at ADUG Sydney

Wed, 18 Jan 2006 00:48:47 GMT

I'll be showing off some of the new features of ECO III at tonight's ADUG (Australian Delphi User Group) Sydney meeting.

It's essentially a repeat of my Borcon US session. Borland will be providing the pizza and drinks, so come along if you can.

ECO is Child's Play

Wed, 26 Oct 2005 05:39:09 GMT

I saw the rough recordings of this awhile back, but I just watched it again now that it's been posted on BDN.

I thought I was getting reasonably good at explaining this ECO thing, but I bow to the master (mistress?)

http://bdn.borland.com/article/0,1410,33331,00.html

Centillex ECOAccess

Wed, 28 Sep 2005 23:20:42 GMT

One of the things I've added to my "Things to tinker with when I get time" list is this ECO add-on from Thailand:

Centillex EcoAccess is a free library to enable declarative data access services for Borland ECO. It provides flexibilities to declare methods for querying or accessing ECO objects via OCL expression.

OK, so that meant bugger all to me as well when I read it, but looking at the code in the tutorials on the site, it makes a bit more sense.

Still not sure if I'd use it or not, but their use of attributes has got me curious. Worth a couple of hours playing with it to see, I think.

This one's going straight into the pool room

Mon, 26 Sep 2005 03:46:28 GMT

I spoke with Matthew Overington, a journalist in Australia, a little while back about Model Driven Development in general, and ECO in particular. The resulting article showed up on BuilderAU back in August.

I wouldn't normally post links to sites that have linked to an article I'm in, but I'm so tickled by this one, I just had to post. The article has been referenced on the Healthy Hair website, specifically on the Hair Loss blog (Who knew there was a blog about hair loss? Why wasn't I told?).

Now the less kind amongst you who know what I look like, will no doubt be able to construct some terribly amusing reason why I'd be on this site. Oh, how we'd laugh! Sorry to spoil it for you, but you'd be wrong. There were no photos in the article. Ha!

My mum will be so proud. I'm not even upset that they messed up the quote. This one's going straight into the pool room.

Real life complexity with ECOII. Part 1

Mon, 19 Sep 2005 00:35:05 GMT

Hans Karlsen has published the first in a series of articles covering his use of ECO II to deal with more real world complexity. Good stuff, especially if you've been wondering about Nestings.

ECO : Autoforms and Form Factories

Mon, 29 Aug 2005 00:32:46 GMT

I've been in New Zealand this week doing some Borland Developer Day's events. Mornings we've been focusing on ECO, afternoons we've been focusing on the new MDA features in the next version of Together.

Anyway, during the ECO session in Wellington, I was talking about the AutoForms capabilities, and how you could register your own AutoForms for specific types. This is a really useful feature, as you can use the default AutoForm during early parts of your development, so that you can focus on getting the model developed, and then when ready, you can create custom forms to be used to view and edit your objects. Registering them with the AutoForm service means that you don't have to change any of the code in your app that display's your AutoForm, it will automatically use the new form you have registered.

After the session, one of the guys in the audience who'd been using ECO for awhile came up to me asked how to do this. To be honest, I thought I'd already blogged about this. Apparently not, so I had a few hours to kill in the Qantas lounge in Christchurch while I waited for my flight home, so I thought I'd write something up. You can grab the sample code here.

A few things first. If you haven't seen the default AutoForm capabilities, download the source for this project and open it in Delphi 2005 Architect. Bring up Winform1, and note that I've set the ECOAutoForm property on the grdAllPeople DataGrid to True. Now I can simply double-click on a row in my grid, and an autoform will be created. This is probably the simplest way to get ECO to display an AutoForm for an object.

NB: If you can't see an ECOAutoForm property in the DataGrid's on your form, you probably need to add an ECOAutoFormExtender component to the form. This will insert some ECO-specific properties into the DataGrid.

Also click on Button3, which is the button labeled "Show Autoform" next to the upper grid. I've also set it to display an AutoForm for the currently selected Person in the grid. I've enabled this by setting it's ECOListAction property to ShowAutoForm, and setting its BindingContext to my grdAllPeople grid, and its RootHandle property to the ExpressionHandle holding the collection of Person objects, in this case, ehAllPeople. This is probably the second simplest way to display an AutoForm for an object.

If you want to display an autoform for an ECO object via some other method (e.g., via a context menu, etc), then the following code (Which is also in the Click event of Button4 in the sample project) will achieve the desired result:

procedure TWinForm1.Button4_Click(sender: System.Object; e: System.EventArgs);
var
autoContainer: IAutoContainer;
begin
if Assigned(cmhSelectedAppointment.Element) then
begin
    autoContainer := AutoContainerService.Instance.CreateContainer(
                       cmhSelectedAppointment.Element,
                       AutoContainerArgs.Create(EcoSpace,
                                                False,
                                                AutoContainerMemberVisibility.AllMembers,
                                                ContainerReusage.NeverReuse));
    if Assigned(autoContainer) then
    Form(autoContainer).Show;
end;
end;

Firstly, we're checking that an Appointment object has been selected in our grid, by seeing if the Element attribute of our CurrencyManagerHandle is assigned. Then, we're using the AutoContainerService's CreateContainer method to get back a reference to an IAutoContainer for the selected Appointment. Lastly, provided we got back a reference, we're casting it as a Form and calling show to display it.

Running the project should show that clicking the button to invoke this code has the same result as double clicking in the grid.

Personally any time I want to display a form in my ECO apps, I use this code. Yes, it's longer than just creating an instance of a custom form and assigning the ECOSpace and the ECO object you want to edit. However, bear with me for a minute and hopefully you'll see the advantage.

Open the fAppointmentAutoForm unit and have a look at the TAppointmentForm it contains. I designed this form like I would design any other ECO Winforms. File | New | Other...ECO Enabled Windows Form, drop my controls down. set the ReferenceHandle's ECOSpaceType and StaticValueTypeName properties, set up my databinding, etc. To convert this form into an ECO AutoForm, I have to do a few things:

1. Extend your form class so that it implements the IAutoContainer interface. You'll need to add the Borland.Eco.AutoContainers and the Borland.Eco.ObjectRepresentation namespaces to your interface uses clause. Use Ctrl-Space from within your class declaration to declare the BuildControls, HookUpGUI and set_ECOSpace methods, and extend the declaration of your EcoSpace property so that has a setter method (the aforementioned set_EcoSpace).

2. Ctrl-Shift-C from inside the form classes declaration to stub out the implementations of these new methods. The code within them looks like the following:

procedure TAppointmentForm.set_EcoSpace(value: EcoSpace);
begin
if value <> FEcoSpace then
FEcoSpace := value;
end;

procedure TAppointmentForm.HookUpGUI(ecoSpace: EcoSpace; element: IElement);
begin
FEcoSpace := ecoSpace;
RHRoot.EcoSpace := self.EcoSpace;
RHRoot.SetElement(element);
end;

procedure TAppointmentForm.BuildControls(element: IElement;
autoContainerArgs: AutoContainerArgs);
begin
// don't need to do anything, unless you intend writing a generic
// autoform
end;

Most of these should be fairly self explanatory. The BuildControls method is empty, however if you wanted to dynamically create controls on your AutoForm, this is where you'd do it.

3. So, now our AutoForm is complete, however we need to register it with the AutoFormService. To do ths, we define a simple Factory class. In the same unit, you'll see this under my form declaration. Its delcaration looks like this:

AppointmentAutoContainerFactory = class(System.Object, IAutoContainerFactory)
public
function get_AutoContainer: IAutoContainer;
function Matches(modelElement: IModelElement): Boolean;
end;

Its implementation looks like this:

function AppointmentAutoContainerFactory.get_AutoContainer: IAutoContainer;
begin
Result := TAppointmentForm.Create(nil);
end;

function AppointmentAutoContainerFactory.Matches(modelElement: IModelElement): Boolean;
begin
Result := modelElement.Name.Equals(Appointment.ClassName);
end;

You may need to add the Borland.Eco.UmlRt namespace to your Interface uses clause. The get_AutoContainer method is where we actually create an instance of our form. The Matches method will be called by the ECO Framework, passing in a reference to the model element for which it is trying to create an AutoForm. Your job in this method is to decide if your form will handle this class, in this case I'm checking whether it represents an Appointment, and if so returning true.

4. Lastly, I need to register my Factory with the AutoForm service, by adding the following code to the initialization section of the unit:

initialization
AutoContainerService.Instance.AddFactory(AppointmentAutoContainerFactory.Create);
finalization

That's it. Now when you run your app, you should notice that when you request an autoform for an Appointment object you'll get back our new form. This is regardless of how you request it (i.e.. double clicking in your grid, using the ECOListAction on your button, using the AutoForm code, ECOSpaceDebugger etc). You don't need to change any of your forms, you can make the change in one place and the rest of your app will follow. Way cool!

In the sample code, the initialization section code is commented out, so you can easily see the before and after effect.

24 hours of Delphi

Tue, 12 Jul 2005 23:07:56 GMT

So, we're getting close to the 24 hours of Delphi online radio thingy (yes, I think that's the official name). The schedule is up here.

I'm going to be on at midnight PST, and then again at 11pm PST (which thankfully is a much more civilised 5pm and 4pm respectively where I am), but I'll be sticking my head in whenever I can. I'll also be making an effort to be online for the ECO bits, which are:

3:00 am PST with Jan
3:45 am PST with Jonas
10:00 am PST with Daniel
7:00 pm pST with Randy
10:00pm with Tim and Dick

Hmm and Brian Long is always good value, and Marco, and..., OK, looks like I'm not going to get much work done for the next 24 hours.

OCL : subSequence

Mon, 04 Jul 2005 00:43:17 GMT

I think I've mentioend before that I've been working on an internal website using ASP.NET and ECO II. Partly because replacing the current site (based on static HTML) is going to make my life a lot easier, but also as I kinda miss coding as a day job, and of course if you want to really learn a new technology like ECO, there's no substitute for actually building and deploying an app into production.

Anyway, one of the things I wanted to do was to display summary lists of items on the main page of the site. You know, recently posted items, important upcoming dates, last 10 posts to the SE mailing list, etc. Most of this is easy, OCL like the following will pull out all Items in reverse order (ie. most newest to oldest).

Item.allInstances->orderdescending(ModifiedTime)

Problem is, I don't want to display all Items, only the most recent items, say, the last 10. Enter the subSequence operator:

Item.allInstances->orderdescending(ModifiedTime)->subSequence(1,10)

With this, I have a list of 10 Items, starting at position 1 in my list of Items ordered by ModifiedTime. Perfect!

ECOSpaceDebugger

Wed, 08 Jun 2005 11:04:43 GMT

ECO lets you move from building your model to executing and interacting with that model incredibly quickly. The model-aware framework with its databinding support, autoforms capabilities, etc mean you can build UI's that let you play with your model faster than any other tool.

However, ungrateful bugger that I am, I'm now spoiled and "incredibly quickly" just isn't fast enough anymore. What I want is a way to create my model, and without setting up anything, I want to be able to interact with it. Or more often, change my model, and test out my changes immediately, without adding the necesary UI bits until I know that it works how I want it to work.

Well, lurking away in a dark corner of the ECO Framework is something that gets me very close to that. The ECOSpace Debugger gives you a UI that lets you, amongst other things:

create, edit and delete instances of objects in your model
bring up autoforms for an object
set Checkpoints, then undu and redo changes
start, commit and rollback object transactions

At the moment you still need to write the code to invoke the ECOSpace Debugger, but it's only a couple of lines, so that's still pretty amazing.

Here's the steps to try it out:

Create a new Winforms ECO app
Define a few classes and associations in your model
Add the Borland.ECO.Diagnostics namespace to your mainform's uses clause.
Drop a button on your mainform, and in the Click event add the following code:

EcoSpaceDebugger.Create(EcoSpace).Show;

That's it! Run your app, click the button, and you can start playing with your model. Change your model, run the app again and interact with your changes. How simple is that?

If you want to have a bit more of a sniff around, double-click on the Borland.Eco.Windows.Forms.dll in the References section of the Project manager, and drill down into the Borland.Eco.Diagnostics namespace using the Reflection tool built into the IDE.

I did say I was ungrateful. Now that I have this, I want to get rid of that button and line of source. Like maybe by creating a non-visual component that shows the debugger on create, if a boolean property is set to true. Hmmm, maybe on my next flight...

Custom OCL Operations

Tue, 19 Apr 2005 20:56:40 GMT

Jonas has just updated the ECO pmwiki with an interesting post on creating custom OCL operations, along with an example that implements a bunch of DateTime functionality that you can invoke from OCL. One of the guys mentioned this a few months back, and I've been waiting since then to get my hands on it. Hmmm, wonder if I have time to play tonight.....

ECO is Love

Thu, 14 Apr 2005 06:44:48 GMT

Part of the reason I've been quiet on the blog lately (apart from work, travel, family life, ill dogs, and just general laziness) is that I've been working on a reasonably large ECO/ASP.NET application for use internally in Borland. Eventually I'd like to publish the source code (inspired as I am by Peter Morris) but trust me, you wouldn't want to see it in its current state.

Anyway, back to the point. Being a web app, part of it follows a fairly common web standard of organising content in a hierarchy of categories that users can use to navigate down into more specific areas. Think of the directory structure at Yahoo in the screenshot below

Anyway, this was relatively easy to implement in a model: a Category class that has an auto-association (ie. an association to itself) such that a Category can have 0..* child categories, and a Category can have 0..1 parent categories. It was also relatively easy to set up in ASP.NET so I could browse my way up and down these categories.

What had me stumped for awhile were the breadcrumbs. Breadcrumbs? Look in the Yahoo screenshot above. Near the top, it has a list of all the ancestor categories as links, so you can work your way back up to where you came from. I wanted to be able to get a list of the Category objects that make up the path from a specific Category all the way to the root. In the screenshot, it's Directory, Computers and Internet, Programming and Development, Languages, Delphi from least specific down to most specific. Once I had this in a handle, I could bind it to an ASP.NET Repeater component and Robert's your mother's brother. I didn't only need to access this path for the breadcrumbs, but that's a nice, visible example of what I needed.

I eventually came up with some fairly convoluted code that walked up the Parent association, adding each to a handle as I went (which involved some pretty funky casting along the way). That worked, but it left a fairly foul taste in my mouth. I thought ECO was supposed to stop me from having to write this sort of pointless plumbing code?

Well, obviously if there wasn't a better way I wouldn't be writing this article. After some help from Jesper and Jonas (thanks guys!) here's my current solution. I'm sure there are others, but I'm kinda fond of this one at the moment.

I've added a Derived Association, in fact another auto-association, called Path and made it uni-directional. When you reference this association you should get back all categories from the root down to the current Category. To make this happen, the Derivation OCL for the Path association looks like this:

if self.Parent.isNull then
self->asSet
else
self.Parent.Path->including(self)
endif

If the current Category is the root, its Parent will be null, and as a result we return a collection of just the current Category. However, if we are somewhere down the tree, then we use the including operator to add the current Category to its Parent's Path collection (ie. we're recursively calling this derived association).

Works like a bought one, as you can see in the screenshot below. The top left grid is showing all the Category objects, and also serves to let us select a particular category. The bottom left grid is showing the children of the currently selected Category, and the bottom right grid is showing the contents of the currently selected Category's Path association. Exactly what I needed.

Yes, the result is exactly the same as my convoluted code, and yes I had to learn a bit of OCL (this is the best OCL reference I've found so far, BTW. Thank you Anthony), but it just feels so much more ECO-like to be able to tell the framework what I want at a higher level, rather than having to explicitly say how to do it. Sure, I always want to have the option to take control over how things happen, but for stuff like this, I couldn't care less.

<Sigh> Once again I'm reminded, ECO is love.

Oh, you can download the source for this example here (and yes, I realise I can't spell, but then Delphi doesn't spell check my Project names for me, so it's not my fault).

WooHoo! An ECO blog from a non-Borlander

Wed, 22 Dec 2004 05:06:49 GMT

I have a page in OneNote where I grab snippets of newsgroup conversations, emails, etc about ECO that I store away for future reference. The title of this page is "ECO Gems". Well, I just looked through it and a high percentage of my ECO Gems are from Peter Morris.

Why do you care? Well, Peter has started a blog. Definitely subscribed!

ECO 2 Under The Hood

Thu, 28 Oct 2004 11:24:31 GMT

Has somebody put something in the water over there on the ECO team? Only a couple of days ago Jonas kicked off his blog, now Anders weighs in with hi post on some of the guts of the framework. Cool stuff!

Jan? Jesper? Henrik? Nothing to say? :-)

From the Horses Mouth

Tue, 26 Oct 2004 01:20:27 GMT

That is Jonas's phrase not mine.

Anyway, Jonas is blogging! Yay!

I don't even mind that he pointed out all my mistakes. If it keeps him writing these sorts of useful blogs, I'm happy to keep making mistakes :-)

ECO : OCLPSHandle

Wed, 20 Oct 2004 20:24:26 GMT

So far in my ECO examples, I've been ignoring the issue of performance. I've been behaving as if my application will perform identically whether I have 10 objects or 1,000,000 objects. Obviously, this is absurd, so I want to start dealing with this issue. There are many things you can do to control the performance of your ECO app, and this first article will look at one of them, specifically the OCLPSHandle.

Look at the following OCL for example

Person.allInstances->select(Age < 18)

Hopefully by now you recognise that this OCL will return a collection of all Person objects that have the value of their Age attribute less than 18. If we use an ExpressionHandle to execute this OCL, as we have been in all our examples so far, a few things could happen. Firstly, let's assume that our ECOSpace is empty, so any Person object we wish to access will need to be loaded from the database (we'll deal later with the case where our ECOSpace is not empty).

So, how can we see what happens when we request this OCL to be executed? There are a couple of tools that I find useful in this type of situation. One is some sort of SQL monitor, so that I can view the actual SQL being executed by the ECO Framework. The other is the OptimizeIt Profiler for .NET, a CPU and Memory profiler that ships with the Architect edition of Delphi and C#Builder. The Memory Profiler in OptimizeIt allows me to peer inside my ECOSpace and see exactly what objects are in memory.

Back to our example, however. The ExpressionHandle behavior is that the select filter above will be executed by the ECOSpace. If we look at the contents of our ECOSpace before executing this OCL in an ExpressionHandle we can see that there are no Person objects instantiated (note the filter I have placed in OptimizeIt, allowing me to only view my domain objects).

When I execute this OCL using an ExpressionHandle, a number of SQL statements are executed. My example is using SQL Server, and in this case, firstly ECO executes this:

SELECT BOLD_ID, BOLD_TYPE FROM Person

Then the BOLD_ID's returned from this statement are used in the following SQL, to actually return the complete objects:

SELECT BOLD_ID, BOLD_TYPE, Firstname, Lastname, Age FROM Person WHERE BOLD_ID IN (...)

where the list of BOLD_ID's are inserted between the braces after the IN statement.

Think about this for a moment. This means that all my Person objects will be loaded from my database into my ECOSpace, then the ECOSpace will filter out the correct Person objects and return my collection. While this might be fine for 9 objects as I have, what if I have 10,000 objects, or 100,000, or 1,000,000? This will rapidly become a problem. Just to be sure, this screenshot from OptimizeIt shows that the ECOSpace after this statement is executed holds 9 Person objects, even though my Grid only displays the 2 that match my select statement.

So, how can we exercise some control over this? Well, this is where you can use a component called OCLPSHandle. The PS in the name stands for Persistent Store, because this component will attempt to convert the OCL into a SQL Statement so that the filtering in this case will be executed by the backend database rather than the ECOSpace. So, the exact same OCL as above, but loaded into an OCLPSHandle rather than an ExpressionHandle, results in the following SQL being executed:

SELECT BOLD_ID FROM Person WHERE (Age < 18)

Note the very important WHERE clause, which means the database will do the heavy lifting for us and only return the records that match the OCL filter. ECO can then request the full data only for the required objects. Again, OptimizeIt shows us that after this OCL is executed, only the 2 matching objects exist in our ECOSpace.

And note the end result in our Grid is the same:

Not only is this much more efficient over the network and more efficient in terms of memory, it also executes a lot faster. There are a couple of downsides (c'mon, nothing comes for free). Whereas an ExpressionHandle will execute its OCL automatically, we need to call the OCLPSHandle.Execute method in order for it to execute the OCL and return the result. Still, a small price to pay for such improved performance.

Secondly, the OCLPSHandle, by its very nature, can only return objects that are stored in the database. If there was a Person object in memory that matched my OCL filter, but that had not yet been persisted to the database, the OCLPSHandle would not by default include that in the resulting collection. This can be worked around of course, and Christophe Floury in his excellent "Unleashing Enterprise Models" (C#Builder version / Delphi version) whitepapers shows example source for this very issue. Basically he uses the OCLPSHandle as above, then interrogates the ECOSpace and adds any Person objects to the resulting collection that have not yet been saved and that match the filter.

So, we can now deal much more effectively with large numbers of objects. There is more we can do to tweak ECO's performance, but that will have to wait for a future article.

ECO Variables : Part 1

Wed, 25 Aug 2004 12:59:38 GMT

If you’ve done any Delphi or C#Builder database programming, think about the SQL statements you’ve used. Have you always known all the SQL you want to use at design time? I’m guessing the answer is no. You quite often know most of the statement, but maybe at runtime you have to substitute in some parameters for your Where clause, for example.

Well, it’s the same thing with OCL. So far we’ve been acting like we can hope to know all the OCL we ever intend to use at design time. Far more common is that you want the same ability to use Parameters in your OCL, just as you do with SQL. However, in ECO they are called Variables, rather than Parameters, but it’s the same concept. They allow us to create OCL that dynamically responds to changes at runtime.

Let me give you an example. Say we want a search screen, like this:

Here I have a grid of Person objects, and some TextBoxes above each field. As I type into one or more of the TextBoxes, the grid only displays the objects that match. How to achieve this?

Well, with static OCL, one way of achieving the end result would be with OCL like this:

Person.allInstances->select( Firstname.regExpMatch(“Ja”) and
Lastname.regExpMatch(“”) and
Country.regExpMatch(“U”))

Note that I’m using the select operator, which returns a collection of Person objects that match the Boolean expression inside the brackets. In this case, I’m doing Regular Expression matching on each of the fields in order to return the Boolean expression expected by the select function.

Well, this will work, but really we want to be able to substitute in the values to match against at runtime. You could build up this string dynamically I guess, then shove it into the ExpressionHandle, but another way is to use Variables. Let’s look at how you do it.

Apart from the DataGrid and TextBoxes above, you’ll have a ReferenceHandle pointing at your ECOSpace, and an ExpressionHandle connected up to the ReferenceHandle. The DataGrid is connected to your ExpressionHandle. If you’ve worked your way through the tutorials, all of that should not be terribly difficult. Don’t worry about what OCL to put in the ExpressionHandle just yet.

What we need to do is to take the text entered into the TextBoxes and somehow get it into some OCL. We’ll start with just searching on the Firstname attribute, then look at what you’d do to search on all three.

Drop down a component called a VariableHandle and name it vhFirstname. The VariableHandle is responsible to holding the value of a Variable we wish to use in our OCL. A VariableHandle is a bit like a ReferenceHandle, in that needs you to give it a reference to your EcoSpace. For the ReferenceHandle, the File | New | Other | ECO Winforms App wizard did this automatically, but for the VariableHandle, you'll have to do it yourself.

Two steps are required. Dropdown the VariableHandle's ECOSpaceType property and select the type of the ECOSpace you are using. Then, have a look in the get_EcoSpace method of our form, and add the line in bold below. Note the Wizard has inserted the equivalent line for the ReferenceHandle (named rhRoot) just above it.

function TWinForm.get_EcoSpace: TECOSimpleSearchEcoSpace;
begin
if not Assigned(fEcoSpace) then
begin
    fEcoSpace := TECOSimpleSearchEcoSpace.Create;
    rhRoot.EcoSpace := fEcoSpace;
    vhFirstname.EcoSpace := fEcoSpace; // insert this line
end;
result := fEcoSpace;
end;

We also need to specify the type of this Variable. In our case, it’s a string, but it could be a number, a date or time value, etc. Unlike SQL Parameters, it could be even more than this. Our variable could be a collection of strings, dates, etc, an object, or even a collection of objects! Think for awhile about the flexibility that would provide. (For those who don't want to think about it, don't worry, I'll cover it in the next article)

So, to specify the type of our Variable, we use the VariableHandle's StaticValueTypeName property. Click on the Ellipsis button for this property and you should see the Type name Selector dialog shown below, which allows you to select the simple type or class, or collection of either, that you want this VariableHandle to hold. In our case, select System.String.

OK, so we have a VariableHandle to hold the value entered into the TextBox. How do we get the value in there? Go to the TextBox component, and put the following code into its TextChanged event:

vhFirstname.Element.AsObject := txtFirstname.Text;

Now, whenever the user changes the text in the TextBox, our VariableHandle component will be updated with the new value. You can replicate this for the other attributes we want to search on (ie. Drop down two more VariableHandles, set their ECOSpaceType and StaticValueTypeName properties, add the relevant code to the get_ECOSpace method, and set up TextChanged events on the relevant TextBoxes so that the variableHandles get updated as the user changes the search text)

That’s great, but we still have no connection between the VariableHandles and the OCL in our ExpressionHandle. So, to hook them up, we need to drop down an OCLVariables component. This component is responsible for holding a collection of variables used in OCL, and the relevant VariableHandles from which their values should be retrieved. Select the OCLVariable component, and bring up the property editor for the OclVariablesCollection property. Add three members to the collection, and for each one, set the ElementHandle and VariableHandle properties. In the screenshot below, you can see how I’ve set the first one.

What this screenshot shows is I’ve created a connection between the vhFirstname VariableHandle component and a Variable called vFirstname. I’ve done the same for LastName and Country.

The last piece is to connect the ExpressionHandle that is connected to my DataGrid to my OCLVariables component, using the ExpressionHandle’s Variables property. Then, enter the following OCL into your ExpressionHandle:

Person.allInstances->select( Firstname.regExpMatch(vFirstname) and
Lastname.regExpMatch(vLastname) and
Country.regExpMatch(vCountry))

And we’re done. In concept, what happens when the OCL is evaluated, is that the OCL Parser will come across vFirstname, and now knowing what that is, will go out to the ExpressionHandle and request the value. It will, using its Variables property, look in the OCLVariables component and see that the value of vFirstname needs to come from the VariableHandle called vhFirstname. This value will be retrieved, and will either be empty or some string value that was assigned when the user typed into the TextBox. This value will be substituted into the OCL. The same happens for the other two variables and we’re away. The image below hopefully clarifies the relationships between the non-visual controls:

Now a few things to realize. In this case we’re using variables in the regExpMatch OCL function, but we can use variables in many different OCL expressions. Also, as I mentioned before, our Variable could contain more than a simple data type like a string, maybe a collection or an object (or a collection of objects), and provided that type was valid where you were placing your variable in your OCL, that’s fine. As I mentioned earlier, in the second part of this article I'll do another example using a collection of objects as a variable, however the steps involved are basically the same, so you can porbably figure it out from here.

Ping

Sun, 27 Jun 2004 23:23:27 GMT

You'd be forgiven for wondering if I was still alive, but life has kinda gotten in the way of blogging over the last few weeks.

First, my wife and I escaped the winter in Sydney for a 2 week surfing holiday in Bali. Then I returned to work right at the end of quarter, so it's been a little hectic.

That said, I have a couple of articles on Variables that are moving towards completion, and also one on Constraints that is less far along. If I can get past Wednesday I'll get stuck in and finish them off.

Evaluate OCL in Code

Mon, 31 May 2004 01:23:27 GMT

A quick one for today.

Just had a question from someone on how to evaluate OCL from code. Assuming you have our Person class from the previous examples, place the following code in a button's click event:

procedure TWinForm.Button1_Click(sender: System.Object; e: System.EventArgs);
var
OCLResult : IElement;
ObjList : IObjectList;
i : Integer;
begin
OCLResult := ECOSpace.OclService.EvaluateAndSubscribe(nil, 'Person.AllInstances',
nil, nil);
if OCLResult is IObjectList then
begin
ObjList := IObjectList(OCLResult);

    for i := 0 to ObjList.Count - 1 do
    begin
      MessageBox.Show(Person(ObjList.Item[i].AsObject).Firstname);
    end;
end;
end;

Here, I'm executing some simple OCL (Person.AllInstances) and then iterating through the resulting collection. The Item property of IObjectList returns an IObject. You can then reference its AsObject method to get back a TObject, which you can cast as your Person and away you go.

Once you have your Person, dealing with any attributes or associations that it has will be much easier, as they will be correctly typed. It's just "getting inside" our object model where we need to cast all over the shop.

Obviously, if your OCL doesn't return a collection, then you'd deal differently, but the above code should get you started.

Optimistic Locking in ECO

Sun, 30 May 2004 04:10:55 GMT

One of the ECO Tutorials up on the Borland website provides a good introduction to ECO and databases. But I've had a couple of different people ask me about how to deal with locking. I'm assuming you've read that tutorial before reading the rest of this article. Also, I'm assuming that you're actually using a PersistenceMapper component that persists to a relational database. If you're using the PersistenceMapperXML component then the rest of this article doesn't apply to you. Sorry.

Here's the problem: Using my ECO application, I load a particular Person object from the database and start editing values. Meanwhile, Damien who's also running the same application, loads up the same Person object. Given that I have not yet persisted my changes to the database, when Damien loads his instance, he gets the data from the database. He then changes the Firstname property. I persist my changes to the database, and all is fine. However, at some point Damien is going to try and persist his changes to the database. Should his changes overwrite mine? Should his attempt to persist the changes fail? What if I didn't change the Firstname attribute? Should it still fail?

What happens when he does try and persist his changes depends on how you, the developer of this app, have configured optimistic locking.

First, let's look at where you setup optimistic locking, then we'll look at what the different options mean. Firstly, you need to turn optimistic locking on. Bring up your ECOSpace, click on an empty area of the designer so that the Object Inspector shows the properties of the ECOSpace. In the ECO | Persistence section, you should see a boolean property called OptimisticLocking. Set this to True.

But that's not all. You need to specify the type of optimistic locking you want to occur for each class in your system. Bring up one of your class diagrams, select a class (make sure it's the class you have selected, and not one of its attributes or methods) and look in the Object Inspector. Once you've expanded the Eco sub-property, you should see a property called OptimisticLocking. The default value of this is, funnily enough, Default, but you can also choose Off, ModifiedMembers, AllMembers or Timestamp. In the rest of this article we'll be looking at what happens when Damien tries to persist his changes to the Person object, depending on which of these values you've selected.

OptimisticLocking set to Off

Setting OptimisticLocking to Off on your class means that no checks are performed before this object is persisted. So, when Damien persists his changes, the following SQL is executed:

update Person
set Firstname = 'Barney'
where BOLD_ID = 3

Not surprisingly, this will overwrite any changes I may have made to the Firstname attribute for this Person. Maybe that's what you want? Certainly it will execute faster than some of the other setting I'll mention shortly :-)

OptimisticLocking set to Default

Default basically means that the OptimisticLocking behaviour is determined by this class' ancestor. So, if Person descended from some other class, say a Contact class, then how Damien's Person class behaved in this situation depends on the value of Contact's OptimisticLocking property.

OptimisticLocking set to ModifiedMembers

As the name might suggest, this value will mean that before ECO persists the Person object, it will check to see if any of the attributes that have been changed on the class, have also been changed in the database. What this means, in the case of our Person object where Damien edited the Firstname property, is that the following SQL will be executed first:

SELECT B.BOLD_ID, B.BOLD_TYPE, B.Firstname
FROM Person B
WHERE B.BOLD_ID = 3

ECO will then check to see if the returned value for Firstname is the same as the value in the class before Damien edited it. If its the same, then ECO assumes that this field has not been changed in the database, and proceeds to execute this:

UPDATE Person
SET Firstname = 'Barney'
WHERE BOLD_ID = 3

However, if after executing the select, it finds that the value returned is different from the Firstname field prior to Damien's changes, it throws a Borland.Eco.Internal.BoldSystem.EBoldOperationFailedForObjectList exception with the message "Optimistic locking failed for 1 objects".

OptimisticLocking set to AllMembers

Hopefully by now you can guess this one. Like the previous example, ECO will check the database to see if the values are the same as when this Person object was first loaded, but this time it will check all attributes on the class, not just those that have been changed. So, in our example it will first execute SQL like this:

SELECT B.BOLD_ID, B.BOLD_TYPE, B.Firstname, B.Lastname
FROM Person B WHERE B.BOLD_ID = 3

If all fields have the same value as the attributes of our Person did prior to Damien's changes, it will then execute the following SQL:

UPDATE Person
SET Firstname = 'Barney'
WHERE BOLD_ID = 3

Note that it still only updates the fields that Damien changed, even though it first checks all fields.

Pitstop

So far I don't think any of these have been very difficult to grasp. One way to look at them is that each setting gradually increases the requirements that must be satisfied in order for an object to be persisted successfully.

We started with no requirements (OptimisticLocking = Off), then we went to the requirement that any attributes that are changed must not have been changed by anyone else (OptimisticLocking = ModifiedMembers). We then stepped up a level again, requiring that none of the attributes of the class can have changed (OptimisticLocking = AllMembers). Well the last setting (OptimisticLocking = Timestamp) increases the strictness of these requirements another level again, but does it in a slightly different way.

OptimisticLocking set to Timestamp

If you set OptimisticLocking to Timestamp on one or more of you classes, you'll need to go out to your PersistenceMapper component (in your ECOSpace) and change the SqlDatabaseConfig.UseTimestamp property to True (see the picture below if that doesn't make sense). You'll also need to invoke the Evolve Database function so that ECO can create you a new table called ECO_TIMESTAMP. This table contains a single field called BOLD_TIME_STAMP, which despite its name, is an Int field (at least in the SQLServer example I'm playing with here).

So, sticking with the same Person object example above, if we have OptimisticLocking set to Timestamp, here's what happens when Damien tries to persist his Person object:

First, ECO will execute the following SQL:

UPDATE ECO_TIMESTAMP SET BOLD_TIME_STAMP = BOLD_TIME_STAMP + 1

This does two things. It increments the Timestamp field, and also returns the current value. ECO can then check that this value has not changed since this objects' fields were loaded from the database. If this value is the same, ECO will then execute this SQL to persist the object:

UPDATE Person SET Firstname = 'Barney' WHERE BOLD_ID = 3

If it finds the timestamp field has been changed since this object was loaded (ie. the value in the field is greater than the one stored with the object) it will, like the other OptimisticLocking settings, throw a Borland.Eco.Internal.BoldSystem.EBoldOperationFailedForObjectList exception with the message "Optimistic locking failed for 1 objects".

It should be noted that all classes that are set to use Timestamp as their locking type will share the Timestamp field. So if Person and Appointment are both Timestamp-locked classes, and both persist to the same database, saving an Appointment object has the potential to stop someone else saving their Person object. This is neither good nor bad, it's just how it works. Sometimes, given certain relationships between classes, this may be the exact behaviour you want. If not, use one of the other techniques.

Now, obviously this is a very simplistic example, but hopefully it's given you a feel for how Optimistic Locking works. The ability to assign different locking settings to different classes opens up quite a bit of flexibility. Looking at how each setting works, you might notice that each gradually increases the potential scope that ECO will check before persisting an object: from nothing, to changed fields of an object, to all fields of an object, and finally, with Timestamp, to potentially other classes. And if you want even more control, in a future article we'll have a look at the concept of Regions.

If you want to dig deeper, I would recommend you do what I did: Spend a little time in SQL Profiler (or a similar SQL monitoring tool) and play with the various Locking settings and see what SQL is thrown.

Update: Krishnan has some follow up comments, concerns, suggestions, and Jonas responds in turn, along with some corrections for my article above. See what I've started?

Next ECO Articles cont'd

Wed, 19 May 2004 05:41:42 GMT

Ok, thanks for everyone who commented or emailed their requests. Here's the list I have so far (in no particular order):

Optimistic Locking (off being reviewed as we speak)
ECO Variables
Constraints
ECO from code (this will possibly be a few articles)
ASP.NET and ECO
Bold <-> ECO migration
Optimisation (ie. lots of objects, lots of classes, lots of relations, what do I do?)
Services (ie. UndoServices, DirtyListServices, etc)
Autoforms
Legacy Databases

Some of these I'll delay until the next release (not telling which of course :-P ). Don't be too harsh on me for that, the others will probably take me that long to write anyway, and trust me, some of them will benefit for waiting until then. Of course, keep telling me others and I'll keep updating the list. Also, feel free to jump in and write some of these yourself :-)

Next ECO Articles

Fri, 14 May 2004 05:28:12 GMT

I've got an article mostly done on Optimistic Locking in ECO, and have the examples for one on ECO Variables, but just wondering what else people are interested in me covering here? I'm not really interested in duplicating the tutorials that are already up on the Borland site, but feel free to leave a comment telling me what topics you'd like to see. Speak up, or you'll just have to put up with me covering whatever takes my fancy.

Association Classes

Thu, 13 May 2004 02:56:38 GMT

OK, one more topic to go and then we'll leave the modelling surface in ECO for awhile to look at other areas. Today's topic is Association classes. (BTW. I've borrowed the idea for this example from the MeetingManager example that ships with Delphi, but the implementation varies a little bit.)

Let's forget ECO for a second and talk about why we might want Association classes in general.

Think of the model we looked at in the Derived Association example last time. Here it is again to jog your memory.

We have a Person class and an Appointment class, and a relationship between them. The Appointment class has attributes for Start, Duration and one for whether or not it is confirmed. It's this Confirmed attribute I want to focus on.

There is an argument that the Confirmed attribute does not belong on the Appointment class because you don't actually confirm an appointment, only whether you will attend the appointment. This problem is highlighted if you consider the case of a meeeting with multiple attendees. You need to allow for the fact that some people will attend and some won't. (Note: The example in this tutorial doesn't support multiple Person's per appointment, but it would be reasonable to expect this to occur in a real world application). So where does the Confirmed attribute belong if not on the Appointment ? I'm pretty sure it doesn't belong on the Person class. The argument goes that Confirmed is actually an attribute of the relationship between the Person and the Appointment. Put another way, you do not confirm an Appointment, you confirm a Person's participation in an Appointment.

Let's think of another example. The example that was used to explain this concept to me was employment. If you have a Person class and a Company class, and a relationship between them that indicates employment, where would you put the Start Date of the employment. You wouldn't put it on the Person (what if they have multiple jobs) and you wouldn't put it on the Company (what if they have multiple employees). StartDate is really an attribute of the employment itself, which in this case is an association between the two classes.

You may not agree with either of these examples, and there are certainly other ways you can model them. That's OK. Like most things in software development, there is usually no one right way of doing anything. But Association classes are a perfectly valid modelling construct to use, and can be extremely powerful (more about that further down). Try using them for awhile. Dismissing something from a position of authority is fine, dismissing something from any other position is kinda scary.

So, how do we create an attribute on an association? Well, perhaps not surprisingly, we use an Association class. We create a class and relate it to our association. Any attributes we want to add to the association, we add to our Association class instead. Let's look at how we might model the changes to our Appointment we discussed above.

I've removed the Derived Relationship for now, but we'll add it back later. You can see I've removed the Confirmed attribute from our Appointment, and added another class called Participancy which contains our Confirmed attribute. this Participancy class is going to be our Association class. An Association class is just a standard ECO class, you don't do anything special when creating the class to make it an Association class. Just select the association between the two classes and enter the name of the Association class, in this case Participancy, into the AssociationClass attribute. Just to make it stand out, I've also change the foreground colour of my participancy class.

So, that was pretty easy, but what does it all mean? In the diagram below, I've tried to show what the above arrangement looks like in sourcecode. Note, I've built this diagram manually, purely to try and explain what is going on. Don't go looking for a picture like this in the IDE.

As you can see, we still have our association between Person and Appointments, and we can navigate that with absolutely no reference to our Association class. However, we also have a path between Person and Appointment that goes via our Association class. This effectively gives us two ways of navigating from Person to Appointment. One way we use the existing direct association, and the other way we go via the Association class.

From a Person object, we have an association to a collection of Participancy objects, one for each Appointment we have an association with. From an Appointment object, we have an association back to a single Participany object. This makes sense as an Appointment is only associated with a single Person.

So, I'll repeat, what does it all mean? Well, it means that I can navigate from my Person to my Appointment (or vice versa) a few ways. Starting at my Person object, I can still say self.Appointments which will return me a collection of Appointment objects, but I can also do this:

Notice my context (in the caption bar) is still Person. As it says down the bottom, self.Participancy will return me a collection of Participancy objects. Also note on the right hand side that each of these Participancy objects have the confirmed attribute, as well as an Appointments collection and Owner.

If we use that Appointments attribute of the Participancy object by using OCL like this:

We are now getting back a collection of Appointment objects, with the correct looking attributes (but note, as I mentioned before, our Appointment class now has a Participancy attribute as well).

Using OCL like this:

We are now getting back a collection of Participancy objects, but only those where the Confirmed attribute is True. And to complete the set, if we use OCL like this:

We are getting back a collection of all Appointments for this Person that are confirmed. Of course, you can access things in a similar way from C# or Delphi code, as the attributes are there in code, there's no black magic going on (We'll look at accessing ECO from code in much more detail in a later article)

So,hopefully that gives you some feeling for accessing the attributes of an Association class. But my model is still broken, I need to put back the derived relationship from last week, but this time using our Association class. this is pretty easy now, as the last lot of OCL I showed is exactly the OCL I need. So, like last week, create your one way association between Person and Appointment, set it as Derived and Transient, and enter the OCL shown below in the DerivationOCL property

Now, our model is restored and our ConfirmedAppointments derived relationship should work as before. However, by using our Association class, we have hopefully more correctly modelled the true nature of our system. In addition, hopefully you realise that our Participancy class, while an Association class, is still just a class, so it can have attributes, methods and even associations with other classes. Think about that last one for awhile and you might start to see some interesting applications for Association classes.

Like I said before, a lot of times this comes down to personal taste. I'm very happy to argue the relative merits of Association classes, but only if we can do it over a drink :-)

Derived Associations

Fri, 30 Apr 2004 01:36:28 GMT

OK, we've spent the last few days in the model, talking about Packages, and all sorts of Derived Attributes. I want to spend a bit more time in this area, specifically on Derived Associations and Association Classes, then we'll head off to other areas such as Persistence and Optimistic Locking, before starting to look at UI stuff. Feel free to let me know other areas you'd like to see covered.

OK, let's look at Derived Associations. I'm assuming you've worked through the ECO Tutorial on Associations, or at the very least have created a few associations in ECO before. I won't be covering the same territory here. If you're not comfortable creating associations and what all the bits like Multiplicity mean, then off you go, this'll still be here when you get back.

Look at the model below. I'm trying to stick with the same type of problem domain for a few articles, so this is still in the realm of Appointments (albeit cleaned up a little, just to keep it simple).

We have a Person class and an Appointment class, with an association between them where an Appointment can belong to only one Person, and a Person can have zero to many Appointments. Note however, that the Appointment has a Confirmed attribute. You may decide that you need to deal with only confirmed appointments so often, that you want another association between these two classes that only displays appointments that have the Confirmed attribute set.

However, this isn't really a new association, as it should be possible to calculate the collection of confirmed appointments from our existing association. If you're thinking that kinda sounds like Derived Attributes, you'd be right. We can define a new association, that doesn't get persisted to the database, but exists in our model. We use OCL to derive the collection of Appointments we want to appear as part of this association.

So, in the model below, I've added a new association between the two classes. You define the association pretty much the same way you define any association. However, note I've set it to be a one way association (by setting the Navigable property on the Appointment end (End2) to False). This association is for navigating from the Person down to the Appointment. In this scenario we can still use our existing association to get from the Appointment back up to the Person. Whether an Appointment is confirmed or not does not change the Person who owns it.

Note I've also set the derived property to True, and the Persistence property to Transient. Lastly I've specified some OCL in the DerivationOCL property. This is the OCL that is going to determine which Appointment objects appear as part of this association:

Appointments->select(Confirmed)

This is basically saying, from all Appointments associated with this Person, select the subset where the Confirmed attribute is True.

The screen shot below shows the two associations at runtime. Person.Appointments shows all appointments for a specific person (the second grid from the top), while Person.ConfirmedAppointments (the bottom grid) shows only those appointments for a specific Person that have the Confirmed attribute set to True.

Derived Attributes Part 3 - Reverse Derived Attributes

Thu, 29 Apr 2004 04:17:09 GMT

If you take a look at sourcecode for the Finish derived attribute declaration from the previous model, you'll note it looks like this:

property Finish: DateTime read get_Finish;

i.e. it is a read-only property. This kinda makes sense, given what we now know about derived attributes. If the value of my attribute is calculated, the framework by itself cannot figure out how to undo it i.e. how to tear apart the value into the original parts used to calculate it in the first place. This may not even be algorithmically possible.

However, sometimes it is possible, and in these cases, we need a way to tell the framework how to do it. Let's stick with our Appointment example. The Finish time was derived by taking the Start time and adding the number of minutes held in the Duration attribute. In my case, if someone assigns a new value to the Finish attribute, I'll change the Duration to reflect the difference between my Start time and this new Finish value.

How? Well, select the Finish attribute in your model, and in the object inspector, set the DerivedSettable property to True. If you now look at the sourcecode for the Finish declaration, a setter method (called set_Finish) has been added. We'll add our logic to recalculate the Duration in this setter method, but first we need to tell ECO that we are changing the logic in here, and to leave it alone in the future. We do this by removing the [ECOAutoMaintained] attribute from the property declaration in our sourcecode (Don't worry, there is a comment reminding you to do this in the generated setter method). My new set_Finish method looks like this:

procedure Appointment.set_Finish(Value: DateTime);
begin
// If you add user code here, please remove the [EcoAutoMaintained] attribute
// from the property declaration in the interface section
Duration := Convert.ToInt32(Value.Subtract(Start).TotalMinutes);
end;

The new value for Finish is passed in as the Value parameter. I subtract from this the Start time, and use the the difference in minutes to set the value of the Duration attribute.

What this means is that not only can I set the Start and Duration and it will calculate the Finish, but I can set the Finish and it will calculate a new Duration.

Derived Attributes Part 2 - Code Derived Attributes

Thu, 29 Apr 2004 03:43:57 GMT

Ok, so yesterday we looked at adding attributes to our ECO classes where the value of those attributes was calculated at runtime using OCL. If you haven't already, look through the link I gave yesterday to Anthony Richardson's OCL Tutorial, as it is possible to embed some fairly rich logic into your model using this language.

That said, lets not kid ourselves. Delphi and C# are much richer languages than OCL, so there will come a time where either it's not possible to calculate your attribute's value using OCL, or where you are more comfortable doing it in code. So, let's look at Code Derived Attributes.

I've created a new class called Appointment, which has a Start attribute of type System.DateTime, which represents the start time of the Appointment and a Duration attribute of type Integer, which is the length of the Appointment in minutes. I've also then created a Derived Attribute called Finish, also of type System.DateTime. Just like yesterday, I've set its Derived property to True and its Persistence property to Transient. However, unlike yesterday, I have not specified any OCL to calculate the value.

When the ECO framework finds a derived attribute that has no OCL, it goes looking for a method, using reflection, of a particular signature and name, specifically:

function <Attribute Name>DeriveAndSubscribe(reevaluateSubscriber, resubscribeSubscriber: ISubscriber): system.object;

In this case, my attribute is called Finish, so it looks for a method called:

function FinishDeriveAndSubscribe(reevaluateSubscriber, resubscribeSubscriber: ISubscriber): system.object;

If it finds this method, it executes it, and uses the return value as the attribute's value. So its your job inside this method to do whatever you need to calculate the attribute's value. In my case, I want to add the Duration in minutes to my Start time, so my method looks like this:

function Appointment.FinishDeriveAndSubscribe(reevaluateSubscriber, resubscribeSubscriber: ISubscriber): system.object;
begin
AsIObject.Properties['Start'].SubscribeToValue(reevaluateSubscriber);
AsIObject.Properties['Duration'].SubscribeToValue(reevaluateSubscriber);
result := Start.AddMinutes(Duration);
end;

Now hang on a sec, the last line makes sense, but what are the first two lines doing?

Well, let's step back a bit. ECO does not actually derive the value of your attribute every time someone asks for it. Instead it caches the value of the attribute after it is first calculated, and returns this cached value on subsequent requests, provided the attrbiute is not marked as out of date. How would our attribute get marked as out of date? Well, that's where the first two lines of code above come in. We've subscribed to be notified whenever Start or Duration are changed. When we are notified, the ECO framework will flag our Finish attribute as out of date. Then, when the next request for its value is made, before the cached value is returned this flag will be checked and, the value of the atribute will be recalculated.

Subscriptions in ECO are an important topic that I plan to cover in future posts, but in the meantime, make sure you subscribe to any other attributes on which you are depending.

Not quite as easy as using OCL, but way more powerful, as you now have full access to the entire .NET Framework to use in calculating your attribute's value.