EntityDAC XML-Mapped Entities

When using the XML mapping, only entity classes unit are required in Delphi, and the mapping are defined in an external XML file of special format. This type of mapping are suitable when there is need to set up EntityDAC data-aware components at design-time. To using the XML mapping at run-time, the corresponding entity classes have to be marked with the [XmlMapped] class attribute.

Overall file structure

The overall structure of the document looks as follows:

 <?xml version="1.0" encoding="utf-8"?>
 <Database>
   <Table></Table>
   <Table></Table>
   ...
 </Database>

The document begins with the standard XML declaration. Body of the document consists of the root Database element which describes the meta-model parameters. The Document element includes a set of Table elements. Each Table element describes a particular entity class mapping.

Database

The root document element which describes the model parameters. Contains one or more Table elements.

Declaration:

 <Database attributes>
   ...
 </Database>

Attributes:

 Name="model-name"

A required attribute which specifies the name of the meta-model being created.

Example:

 <Database Name="TestMetaModel">
 </Database>

Table

The document element which describes a particular entity class mapping. Located inside the Document element. Contains the one Type element which describes the meta-type, its attributes, associations and inheritance.

Declaration:

 <Table attributes>
   <Type>
     ...
   </Type>
 </Table>

Attributes:

 Name="table-name"

A required attribute which specifies the name of the database table to which the meta-type is mapped.

Example:

 <Database Name="TestMetaModel">
   <Table Name="EMP">
   </Table>
 </Database>

Type

The document element which describes the meta-type, its attributes, associations and inheritance. Located inside the Table element. Contains one or many Column elements which describes the meta-type attributes. Also, can contain Association elements which describes associations, and nested Type elements which describes inherited meta-types.

Declaration:

 <Type attributes>
   <Column>
     ...
   </Column>
   <InheritanceColumn/>
   <Association/>
   <Type>
     ...
   </Type>
 </Type>

Attributes:

 Name="type-name"

A required attribute which specifies the meta-type name. The specified meta-type name with the "T" prefix is used to locate the corresponding entity class to map to.

 ed:Guid="guid"

A required attribute which specifies the unique identifier of the meta-type. The identifier has to be specified in the UUID format and is used internally when processing the XML document.

 ed:InheritanceGuid="guid"

A required attribute for an inherited meta-type, which specifies the unique identifier of the meta-type in the hierarchy. The attribute has to be specified only for nested Type element which describes an inherited meta-type inside the parent Type element. The identifier has to be specified in the UUID format and is used internally when processing the XML document.

 TableName="table-name"

A required attribute for a Table-Per-Type descendant meta-type, which specifies the database table name that stores corresponding mapped entities. The attribute has to be specified only for a nested Type element which describes the Table-Per-Type descendant meta-type.

 InheritanceCode="value"

A required attribute for a Table-Per-Hierarchy meta-type, which specifies the unique value of the discriminator for the meta-type. The attribute has to be specified for all Type elements which describes the Table-Per-Hierarchy inheritance.

Example:

// a simple entity mapping definition
 <Type Name="Emp" ed:Guid="ba491fdd-b2ae-4105-9ea3-fcb43d5bc8ad">
 </Type>

// a TPT inheritance definition
 <Type Name="Emp" ed:Guid="ba491fdd-b2ae-4105-9ea3-fcb43d5bc8ad"
       ed:InheritanceGuid="0d372a81-5ffe-476a-ae48-fb3ec75f5127">
   <Type Name="EmpInherited" ed:Guid="41cefe39-ac7f-4c35-8b9c-92d066820feb"
         ed:InheritanceGuid="20e82c82-284c-4301-b214-b3c5ea72eedc"
         TableName="EMP_INHERITED">
   </Type>
 </Type>

// a TPH inheritance definition
 <Type Name="Emp" ed:Guid="ba491fdd-b2ae-4105-9ea3-fcb43d5bc8ad"
       ed:InheritanceGuid="0d372a81-5ffe-476a-ae48-fb3ec75f5127"
       InheritanceCode="0">
   <Type Name="EmpInherited" ed:Guid="41cefe39-ac7f-4c35-8b9c-92d066820feb"
         ed:InheritanceGuid="20e82c82-284c-4301-b214-b3c5ea72eedc"
         InheritanceCode="1">
   </Type>
 </Type>

Column

The document element which describes the meta-type attribute. Located inside the Type element. Can contain the Generator element which describes the meta-attribute value generator.

Declaration:

 <Column attributes>
   <Generator>
     ...
   </Generator>
 </Column>

Attributes:

 Name="column-name"

A required attribute which specifies the table column name which stores the corresponding meta-attribute values.

 Member="member-name"

A required attribute which specifies the meta-attribute name.

 Type="type-name"

A required attribute which specifies the meta-attribute type. The type name can be one of the following names:

• AnsiMemo
• AnsiString
• BCD
• Boolean
• Blob
• Byte
• Bytes
• Currency
• Date
• DateTime
• Double
• Extended
• GUID
• Int64
• Integer
• LongWord
• Memo
• Object
• ShortInt
• Single
• SmallInt
• SQLTimeStamp
• String
• Time
• UInt64
• WideMemo
• WideString
• Word
• XML

 CanBeNull="true/false"

A required attribute which specifies, whether the meta-attribute can be set to a null value.

 ed:Guid="guid"

A required attribute which specifies the unique identifier of the meta-attribute. The identifier has to be specified in the UUID format and is used internally when processing the XML document.

 IsPrimaryKey="true/false"

An optional attribute which specifies, whether the meta-attribute constitutes the entity primary key.

 IsDbGenerated="true/false"

An optional attribute which specifies, whether the meta-attribute value is generated by the database, and the meta-attribute is read-only.

 MaxLength="value"

An optional attribute for string meta-attributes which specifies the maximum value length.

 Precision="value"

An optional attribute for numeric meta-attributes which specifies the value precision.

 Scale="value"

An optional attribute for numeric meta-attributes which specifies the value scale.

 IsDiscriminator="true/false"

An optional attribute which defines the meta-attribute as the discriminator for the meta-type. The attribute has to be specified for one of the meta-attributes of the base meta-type in the Table-Per-Hierarchy inheritance.

Example:

<Column Name="ID" Member="Id" Type="Integer" IsPrimaryKey="true"
        CanBeNull="false" ed:Guid="fcbbb349-6e86-4fa8-bf71-1fd735b0e22e" />

InheritanceColumn

The document element which describes the link between the descendant and base meta-types in the Table-Per-Type inheritance. Has to be the first sub-element of the Type element for all descendant meta-types in the Table-Per-Type hierarchy.

Declaration:

 <InheritanceColumn attributes />

Attributes:

 ThisName="column-name"

A required attribute which specifies the database table column of the descendant meta-type, which constitutes the link.

 BaseName="column-name"

A required attribute which specifies the database table column of the base meta-type, which constitutes the link.

Example:

<InheritanceColumn ThisName="ID_REF" BaseName="ID" />

Generator

The document element which describes the meta-attribute value generator. Can be located inside the Column element. Contains one or more GeneratorParameter attributes which describe its parameters.

Declaration:

 <Generator Name="generator-name">
   <GeneratorParameter/>
 </Generator>

Attributes:

 Name="generator-name"

A required attribute which specifies generator type. The attribute can have one of the following values:

Attribute value	Algorithm to compute the next value of the meta-attribute
Identity	Maximum existing value of the table column + 1
TableHiLo	The result of the the HiLo algorithm using the specified table column as a "high" value source
Sequence	The next value of the specified sequence
SequenceHiLo	The result of the HiLo algorithm using the specified sequence as a "high" value source
Guid	A unique GUID value
Custom	The meta-attribute value is generated in the TEntityContext.OnGetGeneratorValue event handler

Example:

<Generator Name="Identity" />

GeneratorParameter

The document element which describes the generator parameter. Located inside the Generator element.

Declaration:

 <GeneratorParameter Name="parameter-name" Value="parameter-value" />

A GeneratorParameter element necessarily has two attributes: Name and Value.

Attributes:

 Name="generator-name"

A required attribute which specifies the parameter name.

 Value="generator-value"

A required attribute which specifies the parameter value.

Example:

<GeneratorParameter Name="GeneratorFires" Value="OnCreate" />

Parameter combinations for different generator types:

Generator type	Parameter name	Parameter value	Description
All generators	GeneratorFires	OnCreate	The generator fires and the property obtains its new value immediately on entity creation
		OnSave	The generator fires and the property obtains its new value immediately when the entity is saved
TableHiLo	Table	<table-name>	The table that holds the "high" value for the HiLo algorithm
	Column	<column-name>	The table column that holds the "high" value for the HiLo algorithm
	KeyField	<key-field>	The table key field
	KeyFieldValue	<key-value>	The table key field value, that identifies the record that holds the "high" value
	MaxLo	<max-value>	The "max-low" value for the HiLo algorithm (the maximum "low" value, when the "high" value needs to be increased)
Sequence	Sequence	<sequence-name>	The sequence from which the property obtains its next value
SequenceHiLo	Sequence	<sequence-name>	The sequence which is used as a "high" value source for the HiLo algorithm
	MaxLo	<max-value>	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.

Association

The document element which describes an association "side". Located inside the Type element. Full association declaration consists of two Association elements in the corresponding Type-s. The association type (One-To-Many, One-To-One, Many-To-Many) depends on its Cardinality attribute.

Declaration:

 <Association attributes />

Attributes:

 Name="association-name"

A required attribute which specifies the association name.

 ed:AssociationGuid="guid"

A required attribute which specifies the unique identifier of the association. The corresponding Association element of the opposite "side" of the association must have the same AssociationGuid. The identifier has to be specified in the UUID format.

 Cardinality="cardinality"

A required attribute for One-To-One and Many-To-many associations which specifies the association type. Both sides of the One-To-One association have to be marked with the Cardinality="One" attribute. Both sides of the Many-To-many association have to be marked with the Cardinality="Many" attribute. For the One-To-Many association the attribute has to be omitted.

 Type="type-name"

A required attribute which specifies the meta-type name of the opposite side of the association.

 IsForeignKey="true"

A required attribute for the One-To-Many association which specifies the "many" side of the association. For the "one" side the attribute has to be omitted.

 Member="member-name"

A required attribute which specifies the meta-data member (either the meta-reference for "one" and the meta-collection for "many") name for the association "side".

 ThisKey="member-name"

A required attribute which specifies the name of the meta-attribute which constitutes the link to the other "side" of the association.

 OtherKey="member-name"

A required attribute which specifies the name of the opposite meta-attribute which constitutes the link.

 LinkTableName="table-name"

A required attribute for the Many-To-Many association that specifies the name of the junction(cross-reference) table that contains links to both association sides.

 LinkThisKey="column-name"

A required attribute for the Many-To-Many association that specifies the column name of the junction(cross-reference) table that contains the link to "this" side of the association.

 LinkOtherKey="column-name"

A required attribute for the Many-To-Many association that specifies the column name of the junction(cross-reference) table that contains the link to the opposite side of the association.

 Cascade="true/false"

A required attribute for the "parent" side of the association that specifies whether "child" entities have to be saved cascade when the parent entity saved.

 DeleteRule="delete-rule"

A required attribute for the "parent" side of the association that specifies the behavior of "child" entities when attempting to delete the parent entity:

Attribute value	Description
Cascade	Child entities will also be deleted
Restrict	If child entities exist, the parent entity will not be deleted and the exception will be raised
NoAction	The parent entity will be deleted, child entities will not be affected
SetNULL	Link properties of child entities will be filled with the NULL value
SetDefault	Link properties of child entities will be filled with the default value