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.
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.
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;
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.
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;
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;
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;
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.
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.
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.
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.
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.
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}