This project is read-only.

Creating Persistent Objects

Welcome back! This lesson shows you how to create a persistent object for the Opf3 Framework. We are going to create a table in the database, add a simple class named News to our project of Lesson 1, add FieldAttributes and PersistentAttributes to mark the class a persistent object. Let's start!

What's a persistent object?

A persistent is a class that inherits from any base class (also from System.Object) and is decorated by a PersistentAttribute. Each bound property (to a column in the database) is also marked with a FieldAttribute. The PersistentAttribute takes as arguments the name of the table (entity) in the database and each FieldAttribute takes the name of the column and its constraints (primary key, mandatory, ...).

Create the table in the database

First, we need to create the NEWS table in our database (in this example: Microsoft Office Access). The persistent is then bound to this table. The table schema looks the following:

Name Type Constraints
ID LONG Primary Key, Auto Increment
TITLE VARCHAR(50) Mandatory
TEXT TEXT -
PUBLISH_DATE DATETIME Mandatory


This schema needs now to be mapped to our persistent class.

Create the persistent class

This step takes us to create the persistent class. First we create only the class without the properties. The class needs to be decorated with a PersistentAttribute. The Opf3 Framework uses this attribute to understand to which entity the persistent class is bound.

The following sample shows the persistent class with the attribute:

C#
// Persistent class mapping to the "NEWS" table.
[Persistent("NEWS")]
class News
{
    // ...
}

VB.NET
' Persistent class mapping to the "NEWS" table.
<Persistent("NEWS")> Public Class News
    ' ...
End Class

The class is now associated with the NEWS table of the database.

Adding the properties

The next step takes us to add the properties and FieldAttributes to the persistent class. Every property that is bound to a column of the table needs to be marked with a FieldAttribute. The attribute specifies the name of the column and the constraints of the property. To add properties that are not bound to any column, just don't add the attribute.

The next sample shows the property bound to the ID column:

C#
// ID property. Mapping to the "ID" field. Identifier.
[Field("ID", AutoNumber=true, Identifier=true, AllowDBNull=false)]
public int ID
{
    get { return _id; }
    set { _id = value; }
}

VB.NET
' ID property. Mapping to the "ID" field. Identifier.
<Field("ID", AutoNumber:=True, Identifier:=True, AllowDBNull:=False)> _
Public Property ID() As Integer
    Get
        Return m_id
    End Get
    Set(ByVal value As Integer)
        m_id = value
    End Set
End Property

The FieldAttribute specifies that the property is bound to the ID column. It also specifies that the column is part of the identifier (primary key) of the table, it is mandatory and the value for the property (during insert) is created by the database (see AutoNumber=true). The attribute's AutoNumber property corresponds to the auto increment types supported by many databases.

This property was one of the most complicated to bind. You needed to specify that the property is an identifier, autonumber and does not allow null values. Other properties are much easier. Often only the name of the column is enough (for example the Text property in the next example)!

The next sample shows the full persistent class with all properties:

C#
// Persistent class mapping to the "NEWS" table.
[Persistent("NEWS")]
class News
{
    private int _id;
    private string _title;
    private string _text;
    private DateTime _publishDate;

    // ID property. Mapping to the "ID" field. Identifier.
    [Field("ID", AutoNumber=true, Identifier=true, AllowDBNull=false)]
    public int ID
    {
        get { return _id; }
        set { _id = value; }
    }

    // Title property. Mapping to the "TITLE" field. Mandatory.
    [Field("TITLE", AllowDBNull=false)]
    public string Title
    {
        get { return _title; }
        set { _title = value; }
    }
    
    // Text property. Mapping to the "TEXT" field.
    [Field("TEXT")]
    public string Text
    {
        get { return _text; }
        set { _text = value; }
    }

    // PublishDate property. Mapping to the "PUBLISH_DATE" field. Mandatory.
    [Field("PUBLISH_DATE", AllowDBNull=false)]
    public DateTime PublishDate
    {
        get { return _publishDate; }
        set { _publishDate = value; }
    }
}

VB.NET
' Persistent class mapping to the "NEWS" table.
<Persistent("NEWS")> Public Class News

    Private m_id As Integer
    Private m_title As String
    Private m_text As String
    Private m_publishDate As DateTime

    ' ID property. Mapping to the "ID" field. Identifier.
    <Field("ID", AutoNumber:=True, Identifier:=True, AllowDBNull:=False)> _
    Public Property ID() As Integer
        Get
            Return m_id
        End Get
        Set(ByVal value As Integer)
            m_id = value
        End Set
    End Property

    ' Title property. Mapping to the "TITLE" field. Mandatory.
    <Field("TITLE", AllowDBNull:=False)> Public Property Title() As String
        Get
            Return m_title
        End Get
        Set(ByVal value As String)
            m_title = value
        End Set
    End Property

    ' Text property. Mapping to the "TEXT" field.
    <Field("TEXT")> Public Property Text() As String
        Get
            Return m_text
        End Get
        Set(ByVal value As String)
            m_text = value
        End Set
    End Property

    ' PublishDate property. Mapping to the "PUBLISH_DATE" field. Mandatory.
    <Field("PUBLISH_DATE", AllowDBNull:=False)> _
    Public Property PublishDate() As DateTime
        Get
            Return m_publishDate
        End Get
        Set(ByVal value As DateTime)
            m_publishDate = value
        End Set
    End Property

End Class

All mandatory properties are marked with the FieldAttribute's AllowDBNull property, which is set to false. If a property is not mandatory you don't need to add the AllowDBNull property. It's default value is false.

That's it! The persistent ready to use. Please, visit the next lesson to see how persistent objects are loaded, saved and deleted.

Last edited Nov 24, 2009 at 4:28 AM by davidbrown, version 1

Comments

No comments yet.