Creating an ActiveRecord class

» Home » ActiveRecord » Documentation » ActiveRecord RC1 Documentation » User's Guide » Creating an ActiveRecord class

Castle ActiveRecord acts on what we call ActiveRecord types. Those are classes that uses the ActiveRecordAttribute and extend from one of the ActiveRecord base classes. Ultimately the base class is ActiveRecordBase. There is a generic base class documented at Generics support article and another one that support validation, documented at Validation support article.

The ActiveRecordAttribute

The ActiveRecordAttribute is used to define a class as an ActiveRecord type and to associate mapping information.

The example below uses the parameterless constructor of the attribute:


using Castle.ActiveRecord;

[ActiveRecord]
public class Product : ActiveRecordBase
{
    ...

For the situation above the programmer did not made explicit the table name nor the database schema. ActiveRecord then assumes the class Product is being mapped to a database table with the same name. The schema will be null.

The following code snippet make the table name explicit:


using Castle.ActiveRecord;

[ActiveRecord("Products")]
public class Product : ActiveRecordBase
{
    ...

You can also use the Table and Schema properties to make the information more clear to newcomers:


using Castle.ActiveRecord;

[ActiveRecord(Table="Products",Schema="dbo")]
public class Product : ActiveRecordBase
{
    ...

Please refer to the Reference Manual's Attributes article for further information.

The ActiveRecordBase class

Quick Note

An ActiveRecord type must have a parameterless contructor.

The ActiveRecordBase is an abstract class that exposes public and protected members you are likely to use on your ActiveRecord class. The most basic one is to find a record by the primary key.


using Castle.ActiveRecord;

[ActiveRecord]
public class Product : ActiveRecordBase
{
    // mapping omitted
    
    public static Product Find(int id)
    {
        return (Product) FindByPrimaryKey(typeof(Product), id);
    }
}

The mapping is omitted on the class above but it is assumed that the primary key's type is int. The usage is very simple:


Product product1 = Product.Find(1); // Exists

Product product2 = Product.Find(10000); // Does not exists, throws NotFoundException

Some people prefer to return null instead of throwing an exception. As Castle Project as a whole is not opinionated software, we allow one to define if he wants an exception or not if a search by primary key fails. Check the following example:


using Castle.ActiveRecord;

[ActiveRecord]
public class Product : ActiveRecordBase
{
    // mapping omitted
    
    public static Product Find(int id)
    {
        // Note the 'false' value to the argument 'throwOnNotFound'
        return (Product) FindByPrimaryKey(typeof(Product), id, false);
    }
}

The ActiveRecordBase class also exposes instance members to Save, Create, Update and Delete. The Save operation is able to find out if a class needs to be created or updated. Create and Update do not perform this check.

Warning

If a class has an assigned primary key type (i.e. the primary key is not generated by the database) you can not use Save. For those classes you must use Create or Update only.

Please refer to the Reference Manual's ActiveRecord operations article for further information.

Home

Castle Stronghold

Table of contents

Creating an ActiveRecord class

The ActiveRecordAttribute

The ActiveRecordBase class