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:
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;
public class Manager : Employee {
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;
dbcon = new MtDatabase("localhost", "example",
new MtPackageObjectFactory("MatisseApp,PersistentClasses"));
dbcon.Open();
dbcon.BeginTransaction();
Employee emp1 = new Employee(dbcon);
emp1.Name = "John Venus";
emp1.BirthDate = new DateTime(1955, 10, 1);
Employee emp2 = new Employee(dbcon);
emp2.Name = "Amy Mars";
emp2.BirthDate = new DateTime(1965, 9, 25);
Manager mgr = new Manager(dbcon);
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};
Project prj = new Project(dbcon);
prj.ProjectName = "Whidbey";
prj.ManagedBy = mgr;
prj.Members = members;
dbcon.Commit();
dbcon.Close();
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 >>