Setting up the Opf3 Framework

Welcome! This lesson shows you how to set up the Opf3 Framework. We are going to create a storage class, an ObjectContext and a concurrency manager. Let's start!

Create a new project

First, please open Microsoft Visual Studio, create a ConsoleApplication (File -> New -> Project...) and add a reference to the Opf3 assembly.

Include the required namespaces

The next step takes us to include (import) all required namespaces. For this lesson we need the Chili.Opf3, Chili.Opf3.Storages.OleDb and the Chili.Opf3.Concurrency.Md5 namespace:

C#
// Required namespaces for Lesson 1.
using Chili.Opf3;
using Chili.Opf3.Storages.OleDb;
using Chili.Opf3.Concurrency.Md5;

VB.NET
' Required namespaces for Lesson 1.
Imports Chili.Opf3
Imports Chili.Opf3.Storages.OleDb
Imports Chili.Opf3.Concurrency.Md5

Namespace Chili.Opf3: This namespace contains the most common classes to access the functionality of the framework. The most important class of this namespace is the ObjectContext, one of the most important classes when working with the Opf3 Framework. The class allows loading, saving and deleting persistent objects or lists of persistent objects (for example the ObjectSet).

Namespace Chili.Opf3.Storages.OleDb: This namespace contains the storage class for Microsoft Office Access. We use that database in our sample application. It's easy to set-up and runs on a lot computers.

Namespace Chili.Opf3.Concurrency.Md5: This namespace contains a concurrency manager class. A concurrency manager handles the problems that may be caused by multiple user working on the same datebase items (also known as the "concurrent user problems"). We use the concurrency manager later in this lesson.

Create an instance of the storage class

Now it's time to create an instance of the storage class for Microsoft Office Access. This class encapsulates the physical database. Each supported database has it's storage class in Opf3. It's easy to write an own storage class, as well. The class acting as a storage has only to implement the IStorage interface. To support transactions you have also to implement the ITransactionStorage interface. The instance of the AccessStorage class is created in the following snippet:

C#
// Create a storage class that encapsulates the physical MS Access database.
AccessStorage storage = new AccessStorage(@"..\..\..\..\..\Database\", "Database.mdb");

VB.NET
' Create a storage class that encapsulates the physical MS Access database.
Dim storage As New AccessStorage("..\..\..\..\..\Database\", "Database.mdb")

The storage class' constructor for Microsoft Office Access takes either a connection string or the path and file name of the database file as parameters. We use the second option in this lesson. That's everything you need to set-up the storage class for the framework.

Create an instance of the ObjectContext

The ObjectContext is one of the most important classes of the Opf3 Framework. This class allows you to load, save and delete peristent objects or lists of persistent objects from/to a database (have a look at the ObjectContext's members to understand why the class is so important). The constructor of the context takes an instance of a storage (see IStorage interface). This storage instance is then (internally) used by the class to load, save or delete persistent objects.

C#
// The context allows to save and load persistent objects.
ObjectContext context = new ObjectContext(storage);

VB.NET
' The context allows to save and load persistent objects.
Dim context As New ObjectContext(storage)

Optional: Multi user handling

The Opf3 Framework is now set-up to work in a single user environment. But we want more! We want Opf3 ready to work in a multi user environment.

It's very easy to accomplish that! We need only to bind an instance of a concurrency manager to the ObjectContext. The ObjectContext has a property "ConcurrencyManager" that takes a class, which is implementing the IConcurrencyManager interface.

We use the Md5ConcurrencyManager. This class handles multi user problems by creating MD5 checksums of the persistent objects and validating them everytime the objects are saved. The following code sample shows how to make the framework ready for a multi user environment:

C#
// Create a concurrency manager to avoid multi user problems.
context.ConcurrencyManager = new Md5ConcurrencyManager();

VB.NET
' Create a concurrency manager to avoid multi user problems.
context.ConcurrencyManager = New Md5ConcurrencyManager()

That's it! Opf3 is set-up and ready to use. Please, visit the next lesson to see how persistent objects are created.

Last edited Nov 24, 2009 at 3:16 AM by davidbrown, version 2

Comments

No comments yet.