EntityDAC

Attribute-Mapped Entities

There are two main attribute types in EntityDAC used to define entity class mapping. Class attributes are used to specify particular mapping parameters of the whole class. Property attributes are used to define specific mapping parameters of the class properties/fields. Also, attributes can be required and optional.

Table

A basic attribute that marks the class as an entity. When the class is marked with this attribute, the entity manager automatically builds corresponding meta-type and sets up the class mapping. Classes not marked with the Table attribute are ignored.

Attribute type:
class attribute, required

Declaration:

 [Table[(table)]]

Parameters:

 table = string

An optional parameter that specifies the name of the database table which stores entity instances. If the parameter is not specified, the table name is automatically generated basing on the name of the class (if the first character in the name is "T" - the first character is omitted).

Example:

 [Table('EMP')]
 TEmp = class
 end;

Note:

For entities which implement Table-Per-Hierarchy inheritance, the Table attribute with the table name has to be specified only for the basic entity class. All descendant classes have to be marked with the Table attribute with blank table name.

Model

An attribute that specifies the meta-model name, which will contain the entity meta-type. The attribute has to be specified after the Table attribute.

Attribute type:
class attribute, required

Declaration:

 [Model(model)]

Parameters:

 model = string

A required parameter that specifies the name of the meta-model. If the meta-model with the specified name does not exist, it will be created automatically. The name can not be blank. In this case, an exception will be raised.

Example:

 [Table]
 [Model('TestModel')]
 TEmp = class
 end;

Key

An attribute that specifies a unique key that identifies an entity instance. The key has not necessarily to be corresponding to the unique key of the database table.

Attribute type:
class attribute, required

Declaration:

 [Key(members)]

Parameters:

 members = string

A required parameter that specifies the name (or the comma-separated list of names) of the class properties/fields that constitute the key. All the class members listed as components of the key have to be marked with the Column attribute.

Example:

 [Table]
 [Model('TestModel')]
 [Key('FId')]
 TEmp = class
 end;

Note:
When declaring inheritance, the attribute has to be specified only for the basic class in the hierarchy. For all descendant classes it has to be omitted. Otherwise, an exception will be raised.

Inheritance

An attribute that specifies the inheritance settings.

Attribute type:
class attribute, optional

Declaration:

 [Inheritance(type [, link] | (, discriminator, value))]

Parameters:

 type = TInheritanceKind

 TInheritanceKind = (ikTablePerType, ikTablePerHierarchy) 

A required parameter that specifies the type of inheritance: Table-Per-Type (TPT) or Table-Per-Hierarchy(TPH).

 link = string

An optional parameter for TPT inheritance that specifies the name of the database column which is the key for ancestor-descendant link. For the basic class in the hierarchy the parameter can be omitted. In this case, the column which holds the entity key is used in the link.

 discriminator = string

A required parameter for TPH inheritance that specifies the name of the database column which holds the value that uniquely identifies the entity class type in the hierarchy.

 value = string

A required parameter for TPH inheritance that specifies the unique value of the discriminator for the class type.

Example:

// TPT ancestor and descendant

 [Table]
 [Model('TestModel')]
 [Key('FId')]
 [Inheritance(ikTablePerType)]
 TTPTBase = class
 private
   [Column]
   FId: integer;
 end;

 [Table]
 [Model('TestModel')]
 [Inheritance(ikTablePerType, 'BASEID')]
 TTPTDerived = class(TTPHBase)
 private
   [Column]
   FBaseId: integer;
 end;

// TPH ancestor and descendant

 [Table]
 [Model('TestModel')]
 [Key('FId')]
 [Inheritance(ikTablePerHierarchy, 'DISCRIMINATOR', '0')]
 TTPHBase = class
 private
   [Column]
   FId: integer;
   [Column]
   FDiscriminator: integer;
 end;

 [Table('')]
 [Model('TestModel')]
 [Inheritance(ikTablePerHierarchy, 'DISCRIMINATOR', '1')]
 TTPHDerived = class(TTPHBase)
 end;

TablePerType

An attribute that specifies the Table-Per-Type inheritance settings. The attribute is a special case of the Inheritance attribute, and is introduced to simplify the notation.

Attribute type:
class attribute, optional

Declaration:

 [TablePerType[(link)]]

Parameters:

 link = string

An optional parameter that specifies the name of the database column which is the key for ancestor-descendant link. For the basic class in the hierarchy the parameter can be omitted. In this case, the column which holds the entity key is used in the link.

Example:

 [Table]
 [Model('TestModel')]
 [Key('FId')]
 [TablePerType]
 TTPTBase = class
 private
   [Column]
   FId: integer;
 end;

 [Table]
 [Model('TestModel')]
 [TablePerType('BASEID')]
 TTPTDerived = class(TTPHBase)
 private
   [Column]
   FBaseId: integer;
 end;

TablePerHierarchy

An attribute that specifies the Table-Per-Hierarchy inheritance settings. The attribute is a special case of the Inheritance attribute, and is introduced to simplify the notation.

Attribute type:
class attribute, optional

Declaration:

 [TablePerHierarchy(discriminator, value)]

Parameters:

 discriminator = string

A required parameter for TPH inheritance that specifies the name of the database column which holds the value that uniquely identifies the entity class type in the hierarchy.

 value = string

A required parameter for TPH inheritance that specifies the unique value of the discriminator for the class type.

Example:

 [Table]
 [Model('TestModel')]
 [Key('FId')]
 [Inheritance(ikTablePerHierarchy, 'DISCRIMINATOR', '0')]
 TTPHBase = class
 private
   [Column]
   FId: integer;
   [Column]
   FDiscriminator: integer;
 end;

 [Table('')]
 [Model('TestModel')]
 [Inheritance(ikTablePerHierarchy, 'DISCRIMINATOR', '1')]
 TTPHDerived = class(TTPHBase)
 end;

Column

An attribute that defines the mapping of the class property/field to the database table column. All class members that does not have the Column attribute are not mapped.

Attribute type:
property attribute, optional

Declaration:

 [Column([name[(, precision, scale) | , length][, default]][, options])]

Parameters:

 name = string

An optional parameter that specifies the name of the database table column. If the name is not specified, the column name is automatically generated based on the class member name (if the first character in the name is "F" - the first character is omitted).

 precision = integer
 scale = integer

An optional parameters that specify the precision and scale for the class member of the numeric type. These parameters are used when comparing properties values and for a database creation.

 length = integer

An optional parameter that specifies the length for the string-type class member. The parameter is used when comparing properties values and for a database creation.

 default = string

An optional parameter that specify the default value for the class member. Since the parameter is of string type, its value is converted into the exact value depending on the class member type. Therefore, additional quotation for string or date-time values is not required.

 options = TColumnAn attributeOptions

 TColumnAn attributeOption = (CanBeNull, ReadOnly)
 TColumnAn attributeOptions = set of TColumnAn attributeOption

Optional set parameter that specify additional options. By default the parameter value is empty, that means that the class member is non-nullable and writable.

Example:

 [Table]
 [Model('TestModel')]
 [Key('FId')]
 TEmp = class
 private
   [Column('ID')]
   FId: integer;
   [Column('NAME', 50, [CanBeNull])]
   FName: string;
 end;

Note:

The Column attribute can only be used for class members of scalar types. If the class member has any other(class, record, array, set) type, then the attribute is ignored. The only exception is properties of the special Reference<> and Collection<> types used for specifying entity associations.

Generator

An attribute that sets up the automatic property/field value generation.

Attribute type:
property attribute, optional

Declaration:

 // gtTable, gtGuid, gtCustom
 [Generator([type][, fires])]
 // gtSequence, gtSequenceHiLo
 [Generator(sequence[, max-lo][, fires])]
 // gtTableHiLo
 [Generator(table, column, key-field, key-value, max-lo[, fires])]

Parameters:

 type = TGeneratorType

 TGeneratorType = (gtTable, gtTableHiLo, gtSequence, gtSequenceHiLo,
                   gtGuid, gtCustom)

An optional parameter that specifies the generator type.

Generator type Algorithm to compute the next value of the class property
gtTable3 Maximum existing value of the table column + 1
gtTableHiLo The result of the the HiLo algorithm using the specified table column as a "high" value source
gtSequence The next value of the specified sequence
gtSequenceHiLo The result of the HiLo algorithm using the specified sequence as a "high" value source
gtGuid A unique GUID value
gtCustom The property value is generated in the TEntityContext.OnGetGeneratorValue event handler1

Type parameter can be specified only for gtTable, gtGuid and gtCustom generator types. The default parameter value is gtCustom. For gtTableHiLo, gtSequence and gtSequenceHiLo generators the type parameter is omitted.

 fires = TGeneratorFires

 TGeneratorFires = (gfOnCreate, gfOnInsert)

An optional parameter that specifies the moment when the generator fires and the property obtains its new value. When the parameter is set to gfOnCreate, then the generator fires immediately on entity creation. When the parameter is set to gfOnInsert, then the generator fires when the entity is saved. The default parameter value is gfOnCreate.

 sequence = string

A required parameter that specifies the sequence name for gtSequence and gtSequenceHiLo generators. When the generator is gtSequence, then the property obtains its next value of the specified sequence. When the generator is gtSequenceHiLo, then the property value is calculated using the HiLo algorithm, and the specified sequence is used as a "high" value source.

 table, column, key-field, key-value = string

Required parameters that specifies the HiLo algorithm options of the gtTableHiLo generator. Table and column parameters specify the table and the column that holds the "high" value for the algorithm. Key-field specifies the table key field, and key-value specifies the table key field value, that identifies the record that holds the "high" value for the specified generator.

 max-lo = integer

A required parameter for gtTableHiLo and gtSequenceHiLo generators that specifies the "max-low" value for the HiLo algorithm (the maximum "low" value, when the "high" value needs to be increased).

The HiLo (High/Low) algorithm is used to generate unique number series using two values: the "high"and the "low". The high value is used as a base for a series (or range) of numbers, while the size of this series is donated by the low value. A HiLo generator calculates a unique result value using the following steps:
- obtains and atomically increments the "high" value (from the sequence or from the specified table column);
- consequentially increments the "low" value from 0 to "max-low" and calculates the result as the "high*max-low +low";
- when the "low" value exceeds the "max-low" limit, the algorithm goes back to the first step.

Reference

An attribute that defines a "side" of the One-To-One or One-To-Many entity association, and marks a class property/field as a reference to another entity. Property that represents the reference, has to be of the Reference<T: class> type, a special generic record type declared in the ObjectContext unit. Reference<T: class> has the only public property used to access the referenced entity instance.

 Reference<T: class> = record
 public
   property Value: T;
 end;

Attribute type:
property attribute, optional

Declaration:

 [Reference(other-class, other-member, this-key, other-key[, save, delete])]

Parameters:

 other-class = string

A required parameter that specifies the class name of the entity, which is the "opposite side" of the association.

 other-member = string

A required parameter that specifies the name of corresponding member of another entity class, which represents the link to this entity class. The opposite property/field has to be either of type Reference<T: class> (One-To-One association), or of type Collection<T: class> (One-To-Many association).

 this-key = string

A required parameter that specifies the name (or the comma-separated list of names) of the class member, which is used as a key for class association. When the reference is the "main side" in the One-To-One association, specified class members have to constitute the unique entity key. When the reference is a dependent in the One-To-One association (or is a side in the One-To-Many association), specified class members have to constitute the foreign key to the opposite class. All the class members listed as components of the key have to be marked with the Column attribute.

 other-key = string

A required parameter that specifies the name (or the comma-separated list of names) of the member of the related class, which is used as the corresponding key for class association. All the opposite class members listed as components of the key have to be marked with the Column attribute.

 save = TSaveRule

 TSaveRule = (srNone, srCascade)

An optional parameter that specifies saving rules for the referenced class. When the property is set to srCascade, the Save method is called cascade for the referenced entity, and for all its associated entities. The default value is srNone.

 delete = TDeleteRule

 TDeleteRule = (drNone, drCascade, drRestrict, drNoAction,
                drSetNull, drSetDefault)

An optional parameter that specifies an action applied for the referenced entity when this entity is deleted.

drNone Nothing happened with the referenced entity when this entity was deleted
drCascade The Delete method is called as a cascade for the referenced entity
drRestrict The exception is raised when attempting to delete the entity
drNoAction The entity is not deleted, no exception raised
drSetNull The value of the opposite class member is set to the null value
drSetDefault The value of the opposite class member is set to its default value

The default value is drNone.

Example:

 [Table]
 [Model('TestModel')]
 [Key('FId')]
 TEmp = class
 private
   [Column('ID')]
   FId: integer;
   [Column('NAME', 50, [CanBeNull])]
   FName: string;
   [Column('DEPTNO')]
   FDeptno: Integer;
   [Column]
   [Reference('TDept', 'FEmps', 'FDeptno', 'FDeptno', srCascade, drNone)]
   FDept: Reference<TDept>;
 end;

Note:
The Reference attribute has to be applied only on a class property/field having the Column attribute. There is no need to mark the corresponding properties of both related classes using association attributes. Since a property/field of one class is marked as Reference, the corresponding property of the opposite class requires only the Column attribute.

Collection

An attribute that defines a "side" of the One-To-Many or Many-To-Many entity association, and marks a class property/field as a list of another entities. Property that represents the list, has to be of the Collection<T: class> type, a special generic record type declared in the ObjectContext unit. Collection<T: class> implements several properties and methods for access the collection members.

 Collection<T: class> = record
 public
   property Count: integer;
   property Value[Index: integer]: T; default;

   procedure Clear;
   procedure Add(const Value: T);
   function Contains(const Value: T): boolean;

   property ToEnumeration: IObjectCollection<T>;
 end;

Attribute type:
property attribute, optional

Declaration:

 [Collection(other-class, other-member, other-key[, save, delete])]

Parameters:

 other-class = string

A required parameter that specifies the class name of the entity, which is the "opposite side" of the association.

 other-member = string

A required parameter that specifies the name of corresponding member of another entity class, which represents the link to this entity class. The opposite property/field has to be either of type Reference<T: class> (One-To-Many association), or of type Collection<T: class> (Many-To-Many association).

 other-key = string

A required parameter that specifies the name (or the comma-separated list of names) of the member of the related class, which is used as a key for class association. All the opposite class members listed as components of the key have to be marked with the Column attribute.

 save = TSaveRule

 TSaveRule = (srNone, srCascade)

An optional parameter that specifies saving rules for entities within the collection. When the property is set to srCascade, the Save method is called cascade for all classes in the collection. The default value is srNone.

 delete = TDeleteRule

 TDeleteRule = (drNone, drCascade, drRestrict, drNoAction,
                drSetNull, drSetDefault)

An optional parameter that specifies an action applied for entities within the collection when thies entity is deleted.

drNone Nothing happened with associated entities when the entity is deleted
drCascade The Delete method is called as a cascade for associated entities
drRestrict The exception is raised when trying to delete the entity
drNoAction The entity is not deleted, no exception raised
drSetNull The value of the opposite classes members is set to the null value
drSetDefault The value of the opposite classes members is set to their default value

The default value is drNone.

Example:

 [Table]
 [Model('TestModel')]
 [Key('FDeptno')]
 TDept = class
 private
   [Column('DEPTNO')]
   FDeptno: integer;
   [Column('NAME', 50, [CanBeNull])]
   FName: string;
   [Column]
   [Collection('TEmp', 'FDept', 'FDeptno', 'FDeptno', srCascade, drCascade)]
   FEmps: Collection<TEmp>;
 end;

Note:
The Collection attribute has to be applied only on a class property/field having the Column attribute. There is no need to specify the "this-key" parameter for Collection as it is required for Reference, because Collection always uses the unique entity key for association.

There is no need to mark the corresponding properties of both related classes using association attributes. Since a property/field of one class is marked as the Collection, the corresponding property of the opposite class requires only the Column attribute.

When defining the Many-To-Many association, the LinkClass attribute has also be specified for both association sides.

LinkClass

An attribute that specify the junction(cross-reference) entity class parameters for the Many-To-Many association. The attribute is used as an auxiliary attribute for the Collection attribute.

Attribute type:
property attribute, optional

Declaration:

 [LinkClass(link-class, link-member, this-key, link-key)]

Parameters:

 link-class = string

A required parameter that specifies the junction class name.

 link-member = string

A required parameter that specifies the name of junction class member, which represents the reference to this entity class. The junction class property/field has to be of type Reference<T: class>.

 this-key = string

A required parameter that specifies the name (or the comma-separated list of names) of the class member, which is used as a key for link with the junction class. All the class members listed as components of the key have to be marked with the Column attribute.

 other-key = string

A required parameter that specifies the name (or the comma-separated list of names) of the junction class member, which is used as a foreign key for link. All the junction class members listed as components of the key have to be marked with the Column attribute.

Example:

 [Table]
 [Model('TestModel')]
 [Key('FIdAuthor')]
 TAuthor = class
 private
   [Column('ID_AUTHOR')]
   FIdAuthor: Integer;
   [Column('AUTHORNAME', 128, [CanBeNull])]
   FAuthorname: String;

   [Column]
   [Collection('TBook', 'FAuthors')]
   [LinkClass('TAuthorsBooks', 'FAuthors', 'FIdAuthor', 'FAuthorId')]
   FBooks: Collection<TBook>;
  end;

  [Table]
  [Model('TestModel')]
  [Key('FIdBook')]
  TBook = class
  private
    [Column('ID_BOOK')]
    FIdBook: Integer;
    [Column('BOOKNAME', 128, [CanBeNull])]
    FBookname: String;

    [Column]
    [Collection('TAuthor', 'FBooks')]
    [LinkClass('TAuthorsBooks', 'FBooks', 'FIdBook', 'FBookId')]
    FAuthors: Collection<TAuthor>;
  end;

  [Table('AUTHORS_BOOKS')]
  [Model('TestModel')]
  [Key('FAuthorId, FBookId')]
  TAuthorsBooks = class
  private
    [Column('AUTHOR_ID')]
    FAuthorId: Integer;
    [Column('BOOK_ID')]
    FBookId: Integer;

    [Column]
    FAuthors: Reference<TAuthor>;
    [Column]
    FBooks: Reference<TBook>;
  end;

Note:
The LinkClass attribute has to be applied only to a class property/field which has the Column attribute.

ColumnType

A special attribute designed to fix RTTI bug in Delphi version from XE to XE3. This attribute has to be specified for attribute-mapped object fields of type TBytes. The attribute has to precede to the Column attribute.

Attribute type:
property attribute, optional

Declaration:

 {$IFDEF FIXBYTES}
   [ColumnType(TypeInfo(TBytes))]
 {$ENDIF}
© 1997-2024 Devart. All Rights Reserved. Request Support DAC Forum Provide Feedback