Typed DataSets - XML Format

Overview

OpenPetra's Typed DataSets are are specified using XML files. The resulting source code that defines the resulting Typed DataTables is automatically created by a generator (invoked by 'nant generateORM').

This wiki page describes the XML Format that we use to specify OpenPetra's Typed DataTables.

XML Format Description

• The root element is PetraDataSets, which can contain 1..n ImportUnit Elements followed by 1..n DataSet Elements.

• The ImportUnit Element has a "name" Attribute. It specifies the name of a Namespace that needs to be imported for this DataSet in order for it to compile.
  • The generator emits a 'using' clause in the generated source code for each "ImportUnit" Element.
  • Example:

<ImportUnit name="Ict.Petra.Shared.MPartner.Partner.Data.Tables"/>

• The DataSet Element contains 1..n Table, CustomTable and CustomRelation Sub-Elements.
  • "DataSet" Elements become Typed DataSets in the generated source code.
• The Table Element describes a DataTable that is based on a Database table as defined in the \db\petra.xml file; this table is defined by the attribute "sqltable".
  • "Table" Elements become Typed DataTables in the generated source code.
  • The Attribute "name" can be used to assign a different name to the table, otherwise the "beautified" name of the database table is used (e.g. 'PPartnerLocation' for the 'p_partner_location' DB Table).
  • The "Table" Element can contain CustomField Sub-Elements, which have "name" and "type" Attributes and an optional "comment" Attribute.
    • "CustomFields" become DataColumns in the generated source code.
    • "CustomFields" are in created in addition to the DataColumns that are auto-generated for the Database table (as defined in the \db\petra.xml file).
    • Use ordinary .NET data types for the "type" attribute (e.g. int32, DateTime).
    • NB When you add any custom field(s) to a table definition of the Dataset (followed by Generate ORM and a quick compile of the full solution) it may result in compilation errors for forms using the Dataset, saying that a Using is missing. Simply add the required namespace to the relevant yaml.

• CustomTable describes a DataTable that does not represent a Database table as defined in the \db\petra.xml file.
  • "CustomTable" Elements become Typed DataTables in the generated source code.
  • The DataColumns of a "CustomTable"' can either consist of fields from Database Tables using the Field element, or can contain CustomField Elements (see above).
  • The Field Element refers the Database Table by its name in the Attribute "sqltable" and its field in Attribute "sqlfield". To assign an alias, the Attribute "name" can be used, otherwise the beautified name of the database table's name of the field is used (e.g. PPartnerKey for p_partner_key).
  • A PrimaryKey Element can optionally be specified. It consists of a comma-separated list of the fields in the Attribute "thisFields".
• Generally, the order of Table or CustomTable Elements within the DataSet Element is not important. However, if there is a DataTable that references a value of a Column of another DataTable and the Columns' value of the other DataTable is based on a Sequence, then the Table Element of the DataTable that references the Column which is based on a Sequence must come after the Table Element of the other DataTable whose column is based on a Sequence! (Reason for that requirement: when INSERTs are done on both DataTables using the DataSet's SubmitChanges Method, the generated code will take over the value that was assigned in the Sequence into the Column that references the Column which is based on a Sequence. That must happen in the right order, otherwise it will not work and Referential Integrety-based Exceptions will be thrown by the RDBMS because the Column values will not match up.)
  • Example: Typed DataSet file \csharp\ICT\Petra\Shared\lib\MPartner\data\PartnerTypedDataSets.xml - the "p_partner_location" Table must come after the "p_location" Table in the DataSet "PartnerEditTDS" because "p_location.p_location_key_i" is based on a Sequence and the value of that Column is referenced in "p_partner_location.p_location_key_i".

• CustomRelation Elements describes a relationship between tables based on fields. The attributes are called "childTable", "parentTable", "childFields" and "parentFields".
  • "CustomRelation" Elements become TTypedRelations in the generated source code.
  • The boolean attribute "createConstraints" determines whether constraints should be created based on this relation or not.

• Constraints between the tables are be picked up automatically, using the \db\petra.xml file.
  • Constraints become TTypedConstraints in the generated source code.

Example XML Files for Typed DataTables

\csharp\ICT\Petra\Shared\lib\data\Common.DataSets.cs
\csharp\ICT\Petra\Shared\lib\data\Partner.DataSets.cs