Introduction to Programming with FastObjects .NET

Nearly every application deals with data that needs to live longer than the actual execution of the program – this is also true for .NET applications. There are many ways to store this application data, many of which involve parsing the data to and from disk files. Although this is an easy way to make data persistent, realistically it can only be used for simple object networks. Furthermore, essential features such as transactions, recovery, and reorganization utilities are missing.

FastObjects provides a powerful and natural option for data storage – a truly object-oriented database management system (ODBMS) that fully conforms to the .NET standard allowing easy storage of your .NET application objects.

The following sections give you a quick overview of the capabilities of the FastObjects SDK for .NET. However, not all of the functionality – classes, methods, options, settings, etc. – is described here. For a complete description of the classes and methods available to you when using FastObjects .NET, refer to the FastObjects .NET Programmer's Guide.

Transparent Persistence

The FastObjects .NET provides transparent persistence for the .NET framework. It is intended to be used with all managed languages and has very few restrictions on the data model used. Transparent persistence means that no SQL statements are needed to retrieve, insert, or update objects in the database.

When retrieving an object network from the database transparent, lazy loading takes place. This means only objects that are really accessed are retrieved, objects that have not been accessed are not in memory. As soon as an object is accessed it is retrieved from the database. This retrieval is performed transparently from the users point of view.

Change tracking allows to commit all of your changes to the database without any explicit store calls. During the transaction commit call all changed objects are written to the database.

Creating Persistence Capable Classes

Persistence capable classes in .NET are written in exactly the same way as any class – with the addition of special class and member attributes. A class is designated as persistence capable by adding the Persistent attribute to the class definition.

[Persistent]
class MyClass
{
  MyClass() {
    // . . .
  }
  // . . .
}

To reflect this attribute as functionality the .NET assembly needs to be enhanced. Enhancement re-writes the intermediate code in the assembly files, adding the necessary implementation and special accessor methods needed for tracking changes. The classes and their fields that you want to be persistence capable are specified with the persistent attribute.

All persistence capable classes must have a "no-args" constructor. This constructor may be private. The constructor may be the default no-args constructor created by the compiler when the source code does not define any constructors. If the no-args constructor is missing, an error will be reported by the FastObjects .NET enhancer.

Inheritance

The [Persistent] attribute is not inherited. You must specify the [Persistent] attribute for every class in a class hierarchy that you want to be persistence capable. That means that a class might be persistence capable even if its baseclass is not. This allows you to extend classes that were not designed to be persistence capable. And, if a given class is persistence capable, its derived need not be. It is even possible for classes in the "middle" of and inheritance hierarchy to be independently made persistence capable or not. Fields specified as persistent in persistence capable classes will be persistent in derived classes and fields specified as transient in persistence capable classes will be transient in derived classes.

The following example shows an inheritance hierarchy with three classes.

[Persistent]
public class BaseClass
{
  int baseVal;
  [Transient]
  int transientVal; // also transient in derived classes
}

// following class is not persistence capable
public class DerivedClass : BaseClass
{
  int derivedVal; // transient in all derived classes
}

[Persistent]
public class ThirdClass : DerivedClass
{
  int thirdVal;
}

Only the classes explicitly specified as persistence capable, i.e. BaseClass and ThirdClass, are registered in the FastObjects schema. For ThirdClass the fields baseVal (from BaseClass) and thirdVal will be made persistent. The field transientVal (declared transient in BaseClass) is also transient for ThirdClass. And the field derivedVal (from DerivedClass) is transient in ThirdClass because DerivedClass is not persistence capable.

Interfaces

The [Persistent] attribute may also be applied to interfaces. A persistence capable interface type can, for example, be useful for maintaining extents of all (persistence capable) classes that implement the interface.

Value Types

FastObjects also supports persistence capable ValueType class types. A ValueType instance is an object without its own identity which is strongly dependent on another object called the container object. ValueType instances can only be made persistent as field values of other persistent instances. For information about using ValueType instances in FastObjects .NET, refer to FastObjects .NET Programmer's Guide, chapter "The FastObjects .NET Data Model".

Managing the Persistent Objects

The persistent objects in your .NET application are managed within the context of an object scope represented by an instance that implements the IObjectScope interface. The IObjectScope instances are retrieved from the Database instance in your application.

The Database Object

The database in your application is represented by an instance of the class Database. The actual FastObjects database is specified using URL syntax. Here is a code fragment that shows how to connect to a FastObjects database.

Database db = Database.Get( "fastobjects://LOCAL/MyBase" );

FastObjects databases are discussed in detail in FastObjects .NET Programmer's Guide, chapter "The FastObjects Database".

The Object Scope

Once you have established a connection to a database, you gain access to the persistent objects contained therein by using an object scope. The object scopes manage the persistent objects in your application.

The following code fragment shows how the IObjectScope instance is retrieved. The database is specified by the URL "fastobjects://LOCAL/MyBase".

string dbURL = "fastobjects://LOCAL/MyBase";
Database db = Database.Get( dbURL );

From the Database instance, you can retrieve an IObjectScope instance.

IObjectScope scope = db.GetObjectScope();

It is easier to simply combine the two calls.

IObjectScope scope = Database.Get( dbURL ).GetObjectScope();

Creating a Persistent Object

A class is designated as pesistence capable by adding the Persistent attribute to the class definition.

[Persistent]
class MyClass
{
  // . . .
}

When you first construct a new object, whether of a persistence capable class or not, the object is in a transient state. Objects in a transient state will not be stored in the data store. To change your persistence capable class object from a transient to a persistent state, you need to call the object scope method Add(). This method takes a single parameter, the object, and if the object is of a persistence capable class, places the object under the management of the calling IObjectScope instance. All other referenced persistent capable objects are also placed inside the object scope. The object will then be considered as part of the database. The following code fragment shows how this is done.

IObjectScope scope = 
  Database.Get( dbURL ).GetObjectScope();
scope.Transaction.Begin();
  // all operations with persistent objects 
  // must be performed in an active transaction
MyClass obj = MyClass();
  // obj is now in a transient state
  // (assume that MyClass is persistence capable)
scope.Add( obj );
  // obj is now in a persistent state
  // and it is associated with the database
  // represented by the object scope
  // but it is not stored yet
scope.Transaction.Commit();
  // the commit insures that the object is 
  // written to the database
scope.Dispose()
  // all resourced from the object scope are
  // freed.

If the MyClass object has references to other objects, these objects will also be moved to the persistent state. This is referred to as "persistence-by-reachability" and is discussed further in FastObjects .NET Programmer's Guide, chapter "Object Retrieval".

You may have noticed that a transaction is used in the example above. There is a one-to-one relationship between an object scope and a transaction. Transactions ensure that any changes to the database are consistent. Transactions are discussed in FastObjects .NET Programmer's Guide chapter "Transactions".