S2Dao.NET - Entity Class

Entity class is used to define relationship to a table. Entity class implements property to map to a table column.

• Implementing Properties

In some cases, Entity class requires the following attributes. Attributes in S2Dao.NET are defined to be in Seasar.Dao.Attrs namespace.

• Table attribute to define a relation to a table
• Column attribute to define a relation to a column.
• RelNo attribute and Relkeys attribute (N to 1 mapping) to specify concatenation with a different table.
• ID attribute to specify auto-generation of ID's.
• NoPersistentProps attribute to specify non-persistent columns.
• VersionNoProperty attribute to specify locks using VersionNo.
• TimestampProperty attribute to specify locks using Timestamp.

Implementing Properties

Entity class declare and implement fields and properties that shows relations to tables and columns. It is recommended to name classes (without the namespace) the same as the name of the table they correspond to, and to name properties to be the same as the name of the column they correspond to.�B

If a column is Null, specifying primitive datatype (e.g. System.Init32) returns 0. To use Null, specify either datatype in the System.Data.SqlTypes namespace or NHibernate Nullables datatype. Nullables.dll is included in the distributed S2Dao archive file. System.Nullable introduced in .NET Framework 2.0 is not yet supported.

Following is an example of an Entity class to represent EMP table.

using System;
using Seasar.Dao.Attrs;

namespace MyNamespace
{
    [Table("EMP")]
    public class Employee
    {
        private int empno;
        private string ename;
        private short deptnum;

        public Employee()
        {
        }
        public int Empno
        {
            set { empno = value; }
            get { return empno; }
        }

        public string Ename
        {
            set { ename = value; }
            get { return ename; }
        }

        public short Deptnum
        {
            set { deptnum = value; }
            get { return deptnum; }
        }
    }
}

Imports System
Imports Seasar.Dao.Attrs

Namespace MyNamespace
   <Table("EMP")> _
   Public Class Employee
      Private empno As Integer
      Private ename As String
      Private deptnum As Short
      
      
      Public Sub New()
      End Sub 'New
      
      Public Property Empno() As Integer
         Get
            Return empno
         End Get
         Set
            empno = value
         End Set
      End Property
      
      
      Public Property Ename() As String
         Get
            Return ename
         End Get
         Set
            ename = value
         End Set
      End Property
      
      
      Public Property Deptnum() As Short
         Get
            Return deptnum
         End Get
         Set
            deptnum = value
         End Set
      End Property

   End Class
End Namespace

Table attribute to relate to a table

To relate an Entity class to a table, table name is specified in the Table attribute in an Entity class. Syntax to specify a schema name is schema name.table name.

Note: If the class name (without the namespace) is the same as the table name, Table attribute may be omitted.

Following is an example of specifying an EMP table.

[Table("EMP")]
public class Employee

<Table("EMP")> _
Public Class Employee

Column attribute to define a relation to a column

To relate an property to a column, column name is specified in the Column attribute.

Note: If the property name is the same as the column name, Column attribute may be omitted. Properties that do not exist in a table are disregarded.

Following is an example to relate EmployeeNo property to EMPNO column.

[Column("EMPNO")]
public int EmployeeNo
{
   set { _employeeNo = value; }
   get { return _employeeNo; }
}

<Column("EMPNO")> _
Public Property EmployeeNo() As Integer
   Get
      Return _employeeNo
   End Get
   Set
      _employeeNo = value
   End Set
End Property

RelNo attribute and Relkeys attribute (N to 1 mapping) to specify concatenation with a different table

N:1 mapping is used to map several elements to a single element. Relating several employees to a department is an example of N:1 mapping. RelNo attribute and Relkeys attribute must be specify to establish a N:1 mapping.

Relno attribute and Relkeys attribute are specified in a property of an Entity class that holds a concatenated data.

Relno attribute is set to consecutive number starting with 0.

For example, to N:1 map table AAA to table BBB and table CCC, Relno attribute of BBB is set to 0, Relno attribute of CCC is set to 1.

Relno attribute may also be used to determine which table a column in a result set relates to.

For example, in SQL statement SELECT ..., BBB.HOGE AS HOGE_0, ... FROM AAA, BBB ..., HOGE_0 relates to column HOGE in table BBB. Result of the query is set to corresponding properties in the Entity class.

Relkeys attribute specifies keys. Composite key is specified by separating key names with a comma (,). For example, composite key composed from mykey1:yourkey1 and mykey2:yourkey2 is specified by "mykey1:yourkey1,mykey2:yourkey2".

Following is an example that relates column DEPTNUM in table EMP with column DEPTNO in table DEPT.

[Relno(0), Relkeys("DEPTNUM:DEPTNO")]
public Department Department
{
   set { _department = value; }
   get { return _department; }
}

<Relno(0), Relkeys("DEPTNUM:DEPTNO")> _
Public Property Department() As Department
   Get
      Return _department
   End Get
   Set
      _department = value
   End Set
End Property

If the name of column with a single row is the same as the name of the column with multiple rows, name of column in a single row may be omitted. Following is an example of such an case:�B

[Relno(0), Relkeys("DEPTNO")]

<Relno(0), Relkeys("DEPTNO")>

If the name of column with a single row is the same as the name of the column with multiple rows and the column with a single row is a primary key, Relkeys attribute may be omitted.

ID attribute to specify auto-generation of ID's

ID attribute is used to make RDBMS (relational database management system) generate IDs (primary key) and set the generated value to an Entity. If ID attribute is specified and an INSERT sql command is generated by S2Dao.NET, property, which is specified by Entity ID attribute that is passed as an argument, is set to the value generated by a RDBMS. However, if ID attribute is specified, local transaction must be used.

ID attribute is specified in a property.

[ID("identity")]
public int ID
{
   set { _id = value; }
   get { return _id; }
}

<ID("identity")> _
Public Property ID() As Integer
   Get
      Return _id
   End Get
   Set
      _id = value
   End Set
End Property

SEQUENCE may also be used. In actual usage, replace "myseq" with SEQUENCE in the following examples:

[ID("sequence", "myseq")]

<ID("sequence", "myseq")>

If ID is specified manually, no other specification is necessary. Primary key information is retrieved from the table definition. "assigned" may explicitly be assigned.

[ID("assigned")]

<ID("assigned")>

NoPersistentProps attribute to specify non-persistent columns

Whether a property in an Entity class should be persistent (table and mapping) or not is retrieved from the table definition. Property may also be explicitly specified not to be persistent by setting NoPersistentProps attribute.

NoPersistentProps attribute is specified in a class. Names of properties that are non-persistent are specified in a variable length argument (params in C#, ParamArray in VB).

Following is an example to specify Property1 and Property2 to be non-persistent.

[NoPersistentProps("Property1", "Property2")]
public class Employee

<NoPersistentProps("Property1", "Property2")> _
Public Class Employee

VersionNoProperty attribute to specify locks using VersionNo

Locking using VersionNo is activated by specifying in an Entity class a property named VersionNo of datatype System.Int32.

VersionNo locking is effective on UPDATE and DELETE sql commands generated by S2Dao.NET. Entity that is to be passed to an update method in Dao interface, must have a value set to the VersionNo property.

If two users retrieved a data while VersionNo was 0, only the first user who issued either a UPDATE or a DELETE sql command is able to update the data. When the data is updated, VersionNo property and VersionNo column in the database is incremented to 1. If the other user tries to update the data, S2Dao.NET compares the VersionNo the user has (which is 0) with the current VersionNo (which is now 1), and throws Seasar.Dao.NotSingleRowUpdatedRuntimeException because they are different.

To use a property name other than the default VersionNo, set the property name to the VersionNoProperty attribute in a class. Following is an example to set the lock property name to "MyVersionNo".

[VersionNoProperty("MyVersionNo")]
public class Employee

<VersionNoProperty("MyVersionNo")> _
Public Class Employee

TimestampProperty attribute to specify locks using Timestamp

Locking using Timestamp is activated by specifying in an Entity class a property named VersionNo of datatype System.DateTime.

VersionNo locking is effective on UPDATE and DELETE sql commands generated by S2Dao.NET. Entity that is to be passed to an update method in Dao interface, must have a value set to the Timestamp property.

If an INSERT sql command is generated by S2Dao.NET, current time is set to the Timestamp property before executing the Insert command.

When either UPDATE or a DELETE sql command is issued, S2Dao.NET compares the Timestamp property of an Entity with the Timestamp column in the database. If the two values differ, Seasar.Dao.NotSingleRowUpdatedRuntimeException is thrown.

To use a property name other than the default Timestamp, set the property name to the TimestampProperty attribute in a class. Following is an example to set the lock property name to "MyTimestamp". C#

[TimestampProperty("MyTimestamp")]
public class Employee

<TimestampProperty("MyTimestamp")> _
Public Class Employee