An Introduction to a Post-relational Database for .NET, Matisse - Part 3

• Download source files - 8.1 KB

Introduction

In the first article of this series, I gave a quick overview of the Matisse post-relational database and showed how to install it. In the second one, I covered the basics of schema definition for the post-relational database. In this third article, I will demonstrate how to write .NET programs that access a Matisse database, using the schema defined in the second article's appendix.

Although Matisse works well with ADO.NET, I find it easier and more maintainable to use "object APIs" to insert objects into a database instead of ADO.NET. This article focuses on how to create and store objects in a database using the "object APIs", and the next article will show how to insert or retrieve objects using ADO.NET.

Installation

If you have not installed Matisse yet, get the two files from the download page:

• Intel - MS Windows (file name is matisse70x.exe)
• .NET binding (file name is matisseDotNet70x.exe)

And, install matisse70x.exe first, then matisseDotNet70x.exe. The destination folders for both installations need to be the same (C:\Program Files\Matisse by default). Then, you need to install the .NET assembly file MatisseNet.dll into GAC (Global Assembly Cache). The file is located in C:\Program Files\Matisse\bin by default. You can simply drag and drop the file into the GAC folder or use the gacutil command:

> gacutil /i "C:\Program Files\Matisse\bin\MatisseNet.dll"

The .NET binding installation comes with several demo applications, which are accessible from the menu.

There are two documents for the .NET binding:

• Matisse .NET Programming Guide
• API Reference (accessible from the menu: see the above figure)

Code Generation

After you have defined a database schema, the first step you need to take is to generate stub classes from the database using the mt_stbgen command line utility. The generation is quite simple. You do not need to specify any mapping rules like object-relational mapping. Execute the mt_stbgen utility with your hostname, database, and an option to specify which language (C# or VB) you want to use:

> mt_stbgen your_host your_db C#

This will generate four C# classes (Project, Employee, Manager, and Task) in the folder you executed the utility. These classes contain methods and properties that map to attributes and relationships in the database schema, and provide access to the database.

There are a few options you can specify with the utility. One of them is '-p'. With '-p', you can specify a namespace in which stub classes are defined. For instance, the next command generates stub classes in the namespace MatisseApp.

> mt_stbgen your_host your_db C# -p MatisseApp

A part of a generated stub class looks like this:

namespace MatisseApp {
    using System;
    using com.matisse.reflect;
    using com.matisse.Data;
    using com.matisse;

    //  A class generated by Matisse
    /// <summary>
    /// Manager is a schema class generated by Matisse.
    /// </summary>
    public class Manager : Employee {

 
        //  Generated constructor
        /// <summary>
        /// Default constructor provided as an example.
        /// You may modify or delete this constructor
        /// </summary>
        public Manager(MtDatabase db) : 
                base(GetClass(db)) {
        }

For more information about the mt_stbgen utility, run mt_stbgen without any parameter, or refer to the ‘Code Generation and Data Classes’ section in the Matisse .NET Programming Guide.

Create a New Project

For this article, I created a new solution with two projects: an application project DemoApp and a class library PersistentClasses for the generated stub classes. The projects look like this:

In order to add MatisseNet.dll to References, right-click on References to select the Add Reference… menu, then click the Browse… button at the top-right corner and select MatisseNet.dll located in C:\Program Files\Matisse\bin by default.

Store Objects into Database

Now, we are ready to create .NET objects and store them into a database. The next program creates two Employee objects and a Manager object:

static void Main(string[] args)
{
  MtDatabase dbcon;
  // --(A), see below for notes
  dbcon = new MtDatabase("localhost", "example",
    new MtPackageObjectFactory("MatisseApp,PersistentClasses"));
  dbcon.Open(); // connect to the database
  dbcon.BeginTransaction(); // start a transaction

  // create an Employee object
  Employee emp1  = new Employee(dbcon); // --(B)
  emp1.Name      = "John Venus";
  emp1.BirthDate = new DateTime(1955, 10, 1);

  // create another Employee object
  Employee emp2  = new Employee(dbcon); // --(C)
  emp2.Name      = "Amy Mars";
  emp2.BirthDate = new DateTime(1965, 9, 25);

  // create a Manager object
  Manager mgr   = new Manager(dbcon);   // --(D)
  mgr.Name      = "Ken Jupiter";
  mgr.BirthDate = new DateTime(1952, 12, 15);
  mgr.Title     = "Director";

A couple of explanations about this program:

Line (A) creates an MtDatabase object that represents a database connection to a Matisse database. The third parameter of the MtDatabase constructor is required by the Matisse .NET binding so that it can find the stub classes, such as Employee, in the namespace MatisseApp in the assembly named PersistentClasses.

Lines (B), (C), and (D) are creating objects that will be stored in the database when the transaction is committed. They are using the default constructors generated by the mt_stbgen utility, which take a MtDatabase object as its parameter to specify to which database the object be stored.

Set Relationships between Objects

The next segment of code is the continuing part of the above program. It creates a Project object, and assigns the above Manager object and two Employee objects to the project as the manager and members, respectively.

Employee[] members = new Employee[2] {emp1, emp2};

// create a Project object, assign the two employees to the
// project, and set the manager for the project
Project prj = new Project(dbcon);
prj.ProjectName = "Whidbey";
prj.ManagedBy   = mgr;     // --(E)
prj.Members     = members; // --(F)

dbcon.Commit(); // commit the transaction
dbcon.Close();  // disconnect from the database

Instead of managing Primary Key – Foreign Key (with an intermediate table), you simply assign the Manager and Employee objects to the project object’s properties (line (E) and (F)).

After you successfully compile the Visual Studio .NET project and run it, execute an SQL query to select all the employees. You will see the result like this:

You can see each employee that participates in the “Whidbey” project.

Summary and Next Article

This article demonstrated how to generate stub classes (persistent classes) from a database, and how to store .NET objects in the database.

The next article will show how to retrieve objects from a database into your .NET application using ADO.NET and/or object-oriented APIs as well as how to insert objects using ADO.NET.

<< Back | Next >>

History

• 26^th March, 2004: Initial version

License

This article has no explicit license attached to it, but may contain usage terms in the article text or the download files themselves. If in doubt, please contact the author via the discussion board below. A list of licenses authors might use can be found here.