REIMERS CONSULT Company Logo

REIMERS CONSULT GmbH

Home Feedback Contents

RC.Dbo Tutorial

HOME
Up

RC.Dbo Download

RC.Dbo Product Logo medium

Object oriented view on relational data



Content


Introduction

This tutorial gives a short introduction into the usage of the C# class library RC.Dbo. The first step explains common issues. Then a small example shows a way, how an application can build upon RC.Dbo. The example application is written in C#. It is a simple console program, that deletes the content of a table, inserts two new rows and finally prints the new content of the table to the console. The source code of the program can be found here. Parts of the source code explained in this tutorial are written in Courier New with grey background.

to top


Requirements

to top


Common issues to RC.Dbo

RC.Dbo is a class library for object oriented projection of database contents to classes. Internally the potential of RC.Sql is used. The full advantages of RC.Sql migrate into RC.Dbo (e.g. the independence from the driver-implementation of different databases).
An application using RC.Dbo for database access is fundamentally divided into four parts: Dom-class, Ref-class, Dbi-class and application logic.
For each table a Dom-class must be implemented. In a Dom-class the columns of the table are defined as properties.
The Ref-class is an interface from the application logic to instances of the Dom-classes.
The Dbi-class is the interface from the application to the database.
The first step in an application to get database access is to create an RcsqlDatabase instance for this database. This instance is to be given to the Dbi-class. After that data manipulation can be done using the Ref-classes. Each Ref-class uses the appropriate Dom-class which represents the data from a certain database table.

to top


Example Application

This example works with a table named USER contained in a Microsoft Access database. The table consists of the columns USER_RECNO, USER_ID, USER_NAME. USER_RECNO is the primary key and is generated automatically (Autokey). USER_ID is defined as unique.
For the sake of a clear overview all database specific parameters are outsourced into an own file (DBInfo).
Dom-class
The Dom-class itself and its column properties have attributes. The class-attributes are used by the Library and especially the MapGenerator. The property attributes are used by the MapGenerator only.
[RcdboSqlDom ( DBInfo.tableName, typeof( MyDbi ), typeof( BenutzerRef ) )]
[RcdboSqlDomPrimaryKey ( DBInfo.columnRecno )]
The column of a table is implemented by a property of the Dom-class. It is designated as column property by assigning a ColumnAttribute. The MapGenerator gets access to this property using the attribute, too. The application gets access to the property by defining the get- and set-methods within.
[RcdboSqlDomColumn ( DBInfo.columnRecno )]
public RcsqlLong Recno {
   get { return recno; }
   set { recno = value; }
}
Ref-class
For each Dom-class an appropriate Ref-class must be implemented. All constructors must be overridden. They all need to get the type of the Dom-class for which the Ref-class is the interface (see source code).
The property Dbi must be implemented to avoid typecasts from RcdboDbi to the derived Dbi-class.
static public new MyDbi Dbi {...}
Access to the represented Dom-object is granted by using the property Obj.
public BenutzerDom Obj {
    get { return (BenutzerDom)DomObj; } }
Dbi-class
In the first line the custom implementation of the Dbi-class embeds the database parameters into the application. RC.Dbo gets the database classes on database access from the Dbi-class.
public class MyDbi : RcdboDbi {
    public MyDbi ( Type domType ) : base ( domType ) { }
    public override RcsqlDatabase Database {
        get { return DBInfo.Database; }
    }
The Example Application
The application executes the following action-sequence: Delete the content of the table, insert two rows into the table, print the new content to the console, update one row and print the whole content to the console again.

Delete
In order to delete a row from the table a reference to the desired row must be fetched. This reference is implemented in a Ref-class, so the result of getting a reference is a Ref-object. For deleting the specific row, the Delete-method from the Ref-object must be called. For deleting the complete table content the Ref-objects for all rows must be fetched and their Delete-methods called.
refs = BenutzerRef.Dbi.Read( dboConn, new RcsqlExpr(), null );
foreach ( RcdboRef rcdboRef in refs )
    rcdboRef.Delete();


The data of a row is represented by a corresponding Dom-instance. To get an empty Dom-object the CreateNewDom-method within the Ref-class is used. The Dom-object can then be filled with values using the Ref-class. To finally write the data into the database the Write-method is called.
BenutzerRef benRef = new BenutzerRef(null, dboConn);
benRef.CreateNewDom();
benRef.Obj.Id = "TU3";
benRef.Obj.Name = "Test User3";
benRef.Write();

Select
For viewing rows in the first place their references (Ref-classes) are read. The result is an ArrayList of Ref-objects. Every Ref-object has a link to the corresponding Dom-object. After that this list is processed in a sequent way and written to the output device element by element.
RcsqlOrderByList orderBy = new RcsqlOrderByList();
orderBy.Add(BenutzerRef.Dbi.Column("Name"), true);
refs = BenutzerRef.Dbi.Read( dboConn, new RcsqlExpr(), orderBy );
foreach ( BenutzerRef benutzerRef in refs )
Console.WriteLine(benutzerRef.Obj.Recno + " " + benutzerRef.Obj.Id + " " + benutzerRef.Obj.Name);

Update
To change the content of a row the first step is to read it from the table as a Dom-object. The corresponding Ref-object grants methods and properties to change the content and write it back to the data storage.
benRef = (BenutzerRef)BenutzerRef.Dbi.ReadFirst(dboConn, BenutzerRef.Dbi.Column("Id") == "TU4");
benRef.Obj.Name = "Test-User4";
benRef.Write();

to top


Troubleshooting

RC.Dbo and RC.Sql in GAC
To enable an application to use a class library, which doesn't belong to the standard .NET framework nor it is located in the application's directory, it must be registered in the Global Assembly Cache (GAC). For the reason, that RC.Dbo and RC.Sql are licensed in the meaning of the .NET framework, the license implementation must be present at the same location as the class library files (dll-files).
valid license for RC.Dbo and RC.Sql
The class libraries RC.Dbo and RC.Sql are licensed in the context of the .NET framework. On any call of the licensed classes it will be checked, if a valid license is available. The license-files (RCDbo.lic and RCSql.lic) must be present in the same location as their corresponding class library file (like RC.Dbo.dll). If this is not the case, an exception is thrown at runtime.
Help-file for licensing in the application's source directory
On compile time the help-file for licensing (licenses.licx) for RC.Dbo and RC.Sql must be present in the source directory of the application. Microsoft Visual Studio .NET and corresponding Borland products use this file to determine, which classes in which library are licensed. With this information the license compiler is executed for these classes.
Database connection
The example shown above cannot be executed, if no connection to a database can be established. If this situation appears, in most cases the reason lies in invalid database parameters.

to top