Mapping to an Existing Database

Download C# sources for this article

Purpose of this Article

This article demonstrates how to use eXpress Persistent Objects for .NET (XPO) in a project that already uses a relational database management system (RDBMS) such as MS Access or SQL Server and standard datasets.

Contents

• Some Background on the Impedance Mismatch Problem
• The One-to-Many Data Model
• Simple Many-to-Many Data Model
• Complex Many-to-Many Data Model
• Adjusting the Business Object Model to Work with Several Databases that Have Different Structures
• Reading Data from A Database View
• Custom Identity Values Generators
• Notes
• Triggers
• Multiple Connections

Some Background on the Impedance Mismatch Problem

An application can be described as a system that manipulates data and is able to store the state of that data somewhere between invocations. It can also be said that the data that is manipulated almost always represents information about real world things like people, employees, and library books.

With the prevalence of RDBMSs like Oracle, SQL Server and DB/2 it is clear that the dominant way to store this information is in the uniform tables of an RDBMS. This is clearly efficient for data retrieval and storage – the most important two tasks of a persistence layer.

Internally inside an application the only way to deal with such data has traditionally been to use synthetic structures such as arrays to represent that data for manipulation and to bend the remainder of the application around this model.

The problem is that not all Library books, or people, or employees have the same uniform interesting pieces of information and so a better way to represent data about things was invented and named OOP – Object Oriented Programming. Objects allow a representation of a thing to not only have information - in many more flexible ways than uniform arrays - but they also carry with them the unique functionality for dealing with that data – allowing Objects to more closely map to the real world things that they abstract. Business Objects are just regular objects where the functionality represents Business rules.

With the prevalence of Object Oriented and Object Based languages like C++, C#, Object Pascal and Visual Basic it is clear that Objects are a dominant way of representing data in an application.

The problem with a world made up of dominant RDBMSs and dominant OOP Languages is that it has not been easy to map the information in one to the other. Back in the early 90s when OOP languages started to appear, this problem was termed the impedance mismatch (a term borrowed from electrical engineering) and was solved by either making objects for dealing with uniform data (Records) or making completely new types of Storage mechanism called Object Oriented database management systems (OODBMS).

Impedance mismatch is the problem that eXpress Persistent Objects was designed to solve, allowing a developer to work directly with Business Objects inside an application and yet still have the data persisted in a conventional uniform RDBMS. Of course, the mention of business objects invariably leads to a question - often framed as:

Must the whole application be converted to Business Objects for XPO to be used?

The unfortunate reality is that most programmers are not building new systems but maintaining existing systems, and if you are maintaining a database driven system that was built using .NET, then there is a good chance that it is ADO.NET based and uses datasets. As you well know, the problem in this instance is that existing code is most likely working fine and it is unlikely that a developer can justify moving to a totally new architecture - something as fundamentally different as a persistence layer just to accommodate new development.

Since this issue is foremost in the minds of those who are considering moving to business objects as the basis of future development, we spent significant energy on addressing it. With XPO, you don’t have to change everything that has already been built just to start using it for new things… You can have both architectures co-exist and be able to pick and choose those parts of your application you wish to migrate over time.

The complexity of the migration process depends on functionalities of XPO that you want to implement in your application. Straightforward capabilities such as reading, update, saving and searching data do not require database structure modifications. In this case, all you have to do is to define object model for the persistent classes.

Although, additional functionalities introduced by XPO such as optimistic concurrency, persistent objects class inheritance, deferred record deletion and support for simple many-to-many relationships do require changes to the database structure by adding auxiliary database structure elements. In such an instance, you will have to take additional steps to implement these features, explanations of which are beyond the scope of this article.

We will examine several data models in the ascending order of model complexity. For now we will concentrate on the One-to-Many data model which is probably the most common.

The One-to-Many Data Model

This is commonly referred to in the RDBMS world as foreign key relationship between tables or in the world of client/server development a master-detail relationship. Let’s assume we have table of customers and each customer has multiple orders.

You need to write one persistent class for each table. In this example we assume that you are using auto-increment key fields to enforce unique row contents.

The class structure can be implemented as follows:

By default, XPO stores the object in the database table with the same name as the class, so Customer objects will be put in the Customer table. You can easily override this behavior by using the “MapTo” attribute. In the example below, the Customer objects could be stored in the Customers table, if necessary:

By default, XPO will store data in fields with the same name as the Class property. To specify a custom database field name for a class property, use the “Persistent” attribute. In the example below, the Name property will be stored in the FullName field of the Customer Table.

To enable cascading deletes of the dependent objects (When a customer is deleted all the related orders for that customer are also deleted), you can specify the “Aggregated” attribute for the corresponding properties (see the Orders collection in the definition of the Customer class above).

That is all you need to do. Now you have XPO business objects that map to the underlying data model represented in your RDBMSes tables.

Simple Many-to-Many Data Model

In order to demonstrate a Many-to-Many relationship let us consider a Company-Contacts data model where we are keeping information on say PR Contacts for companies. Now some companies in our list can have one or more internal PR people, and other companies might actually delegate that job to PR agencies that could well represent many of the companies in our list. So each PRContact can be working with many Companies, and each company can have many PRContacts – to model this we might have a Companies Table, a Contacts table, and a third table called PRLinks. The latter is used as an intermediate table in the database. It has one record for each Company-Contacts relationship that contains IDs of corresponding contact and company.

As in the previous example, this one uses auto-increment key fields and custom identification handling but we can still inherit the persistent classes from the XPBaseObject.

XPO handles Many-to-Many relationships automatically when it generates its own database schema. But in the case of an existing database, you will need to explicitly define a class for the intermediate link table, and add methods to manipulate this intermediate class. In this example, we added the AddCompany method at the Contact end and the AddPRContact method at the Company end to answer a need.

Note that we have marked the associations with the Aggregated attribute to make sure the deletion of a company or a contact results in the deletion of the corresponding PRLink as well.

That is all we need to map XPO business objects to the underlying model.

Complex Many-to-Many Data Model

Let us consider a more complex Company-Contacts data model. Assume that Contacts and Companies are stored in the same Subjects table and we distinguish them by SubjectType (0 for Contact, and 1 for Company).

Database designers sometimes put different types of records into one table when the data for those records has significant similarity and/or they need a universal reference. For this purpose, we will create a class called Subject which is mapped to the Subjects table:

That is all we need to map XPO business objects to the underlying model.

In another variant, the data from the Subjects table can be mapped to the Contact and Company objects inherited from the base class called Subject as shown in the following code example:

This variant is far too complicated as it requires additional database modifications; steps to prepare the existing database and synchronize applications to work with the database plus an in-depth knowledge about the inner XPO system table structure (see details in the help documentation shipped with your version of XPO). We do not recommend using this variant as the previous example is simpler and as effective.

Adjusting the Business Object Model to Work with Several Databases that Have Different Structures

In an ideal world, existing data appears in the task- or case-compliant form and all data sources providing it keep to these rules. Obviously we would not have this situation in the real world as the data sources generally provide data in different forms and data has a distinctive structure. Therefore, we have to provide additional integration logic for each data source. These tedious complexities can be handled by XPO for you.

Suppose we have two data sources (databases). The first one has the following structure.

While the latter has the following structure.

Data structures have something in common, though the names of the fields and tables differ. XPO can combine these differences in the following data model.

We have not specified in code into which exact tables and columns the data is saved. Instead, we’ll provide this information in the form of metadata files called Metadata_DB1.xml and Metadata_DB2.xml, one for the first data source

...and one for another data source.

These files contain only table and column names specific for a given data source. Now we can employ the Metadata_DB1.xml metadata file to access the first database as shown below.

The LoadXmlMetadata method loads the metadata information from the specified file and applies it for the current object model. Now we can freely address the first data source. Similar steps can be taken to address the second data source.

This unified technique lets you access different data sources in the same way as shown above.

Reading Data from A Database View

Generally, whenever it is necessary to restrict the resulting data set or to select only the data matching particular criteria, database views are used. Most database servers let the user add, modify and delete the data from database views. XPO accesses data views in the same way as it does with the tables. For instance, we have a Subjects table which holds two record types, Contact and Company, that are distinguished by the value stored in the SubjectType field.

In order to access contact and company information separately, let us create two database views. One to retrieve companies

and one to retrieve contacts.

The following object model can be exactly mapped to the views.

That is all you have to do to map persistent objects to database views. It clearly resembles the case when data tables were used for mapping.

Custom Identity Values Generators

The examples above assumed that key fields in the database are autogenerated integers (identity in MS SQL or AutoNumber in MS Access). Additionally, XPO automatically supports Guid key fields.

If you want to use your own identification scheme, you will have to implement your key generation logic. Let us consider a simple example.

Suppose we want to generate an integer type key value for the Customer table and store it in a specific table.

The generator is a class responsible for acquiring or calculating a new key value for a table record via specific method(s). To make key generation algorithms work and to maintain the uniqueness of the key values generated, a persistent storage is used to store the most recently generated key value. We will use the IDGeneratorsTable as a table to store generated key values for all data tables that correspond to the persistent objects, i.e. object tables.

The generator class implementation is shown in the following code example:

Now we can extend the IDGeneratorClass functionality with the GenerateID method. This method receives a name of the object table, generates a unique key value for this table and saves it in the database as the last generated key value:

Let us take a closer look at the GenerateID method of the IDGeneratorClass class. First, we try to find a persistent object (it is represented by the record in the IDGeneratorsTable) which contains a key value for the table whose name is passed as the method’s parameter.

When the persistent object matching the specified criteria is found, we generate a new key value by incrementing the LastGeneratedID field and saving its value in the IDGeneratorsTable.

Otherwise, we create an instance of the identity value generator for the object table prior to key value generation.

Now we can return the unique key value for the specified table.

The Customer and Order persistent objects should initialize their key fields before being saved. The obvious solution is to override their BeforeSave methods as shown below.

To enable the GenerateID method to work properly, we should generate key values in a separate session apart from the main session(s) - one(s) used to retrieve and update the persistent object values. That is why we extend the IDGeneratorClass with two methods that are responsible for the generator session’s initialization and disposal.

The obvious suitable places when these methods should be called are the Session.DefaultSession.AfterConnect and Session.DefaultSession.AfterDisconnect event handlers. We initialize them in the IDGeneratorClass’s static constructor as shown in the following code example.

That is all you have to do to make your own key or identity values generators.

Notes

Triggers

In the case of MSSQL you can also implement the update routine within the database itself via update and insert triggers which would require no changes to your legacy ADO.NET code. MS Access does not provide trigger support but you could use the Defaults attribute for this.

Multiple Connections

If you plan to implement XPO and ADO.NET functionality within multiple connections, you will have to refresh the collections and datasets in order to make the changes available for both connections.

Conclusion

Moving from ADO.NET development to XPO development does not have to be an “All or Nothing” proposition, you can ease XPO development in gracefully and it can co-exist with all your legacy ADO.NET code as long as you follow these simple precautions. We have only covered the simplest and most common data models here and will in future articles cover more complex structures.

Download C# sources for this article

To learn more about XPO, please write to us at: info@devexpress.com. To order your copy, visit our online order page.