NexusDB

This step by step guide will show you how to create very simple ECO 2 application with persistent data stored in a NexusDB database.

Hint

If you don't want to create this example on your own you can find the complete source in the Examples\Manual\BDSWinforms subdirectory of your NexusDB installation. If you don't have this directory you download the examples from our web page.

Hint

The ECO persistence mapper is built on top of the NexusDB ADO.NET provider and is thus using the Direct TCP/.NET transport to communicate with the database server. Make sure it is enabled on the server!

Step 1 - Creating a new project

Start Borland Delphi 2005 and create a new project using the File \ New \ Other menu item. You will see the New Items dialog.

Select the Delphi for .NET Projects in the categories and ECO WinForms Application, then press OK. This will create new ECO project.

Step 2 - Defining the classes

Next we use the ECO diagraming to define our classes. For this open the Model View and right click the CoreClasses menu item.

This will open the diagram editor. Since a complete introduction into ECO is not the target of this chapter, we simply add one simple class Person with the string attributes Name, Address and City. First drag an ECO Class from the component palette on the form and name it Person. Then right click the create class and Select Attribute: enter Name: String and press <RETURN>. Do the same for Address and City.

Your diagram should then look like this:

Now save your project and compile it.

Step 3 - Adding the User Interface

Switch back to the main form and add a DataGrid (from the Data Controls tab of the component palette) and two Buttons to it.

Step 4 - Hooking the UI to the ECO class

Then add an ExpressionHandle from the Enterprise Core Objects tab. Set the ExpressionHandle's RootHandle property to rhRoot in the Object Inspector. Select the rhRoot component and set its EcoSpaceType property to our Project2EcoSpace.TProject2EcoSpace (or similar).

At this stage save and compile the project.

Now select the ExpressionHandle again and press the ellipse button of the Expression property in the Object Inspector. This brings up the OCL Expression Editor.

To connect the ExpressionHandle to the actuall class either type Person.allInstances into the expression memo or navigate the epxression tree by double-clicking, when finished confirm with OK.

Now we just need set the DataSource property of the grid to the ExpressionHandle to interface the class.

Step 5 - Creating new instances

Next we add in a Click event handler for the New Person button:

 Person.Create(EcoSpace);

This line will create a new person instance connected to the EcoSpace. If you press the button in the running application each click will add a new row in the grid.

The application can be compiled and run now. Please note thought that we've not yet defined how the application persists the data, thus on closing the app all data is lost.

Step 6 - Setting up data persistence

Open the Project2EcoSpace.pas (or similar) in the form editor. Now drag a and drop a NxConnection from the NexusDB tab of the component palette. Then right click the new connection component to bring up the context menu and select the Build Connection String menu item. This will show the NexusDB ConnectionString Builder:.

If your NexusDB server is running on a different machine, you'll need to change the Server to point to the correct IP address. You might also need to change the Port if you have changed the port settings on the server. If you've enabled the Secure Server option on the database server, you'll also need to supply correct authentication details here, otherwise just leave the fields blank.

Change the database to Northwind and press Test Connection. If everything is fine you should see a Connection Successful message. If there's a problem most likely your server or the Direct TCP/.NET is not active or you're pointing to the wrong server or database. Once you've successfully tested the connection, press Use to return to the DataAdapter Wizard.

You should now see the Connection string similar to

Server=nexusdb@127.0.0.1;Port=16080;Database=Northwind;UserName=;PassWord=;

in the ConnectionString property of the NxConnection component (you might need to refresh the Object Inspector to see it).

The second thing to do here, is to drag and drop a NxPersistenceMapper onto the form and connect it's Connection property to the NxConnection created before.

Step 7 - Setting up the schema and persisting the data

Make sure that the PersistenceMapper property of the EcoSpace form points to our newly created NxPersistenceMapper.

(At this stage please make sure that the AllowMetadataChangesInTransaction option in the SQLDatabaseConfig property of the NxPersistenceMapper is set to false - early versions of it had this set to true by default).

Then press the Generate Schema button (at the bottom of the form):

This will pop up some information dialog about the required actions and after confirming it, the new tables will be created.

The last step before compiling and running the application is to add

 EcoSpace.UpdateDatabase;

to the click event handler of the Update Database button.

Step 7 - Compile and run

That's it. You can now persist the entered data by pressing the Update Database button.