Glossary

Data object

Application domain objects mapped (statically or dynamically) to database representation. Data object instances can be obtained through generic repository typed by data object type. Data objects non read-only properties can be changed and that changes may be submitted to database. The data object in XData is considered as exactly the object of the domain (in DDD terminology). Moreover, its reflection on the database structure is not limited. So a data object can be reflected on the contents of one table:

t_doc_statedoc_state_idcodename 
public partial class DocState
{
    public long DocStateId => this.GetProperty(x => x.DocStateId);
    public string Code { get; set; }
    public string Name { get; set; }
}

A few tables:

t_doc_statet_doc_typedoc_type_idcodenamet_docdoc_iddoc_datenumbdoc_state_iddoc_type_idgenerationchangedt_catalog_doccatalog_iddoc_idt_catalogt_doc_deliverydoc_iddelivery_typedelivery_datet_doc_scandoc_idscant_doc_sourcedoc_idsourcedoc_state_iddoc_type_idcatalog_iddoc_iddoc_iddoc_iddoc_id 
public partial class Invoice
{
    public long DocId => this.GetProperty(x => x.DocId);
    public string DocStateCode => this.GetProperty(x => x.DocStateCode);
    public Link<string, DocState> DocState { get; set; }
    public long DocCatalogId { get; set; }
    public string Numb { get; set; }
    public DateTime? DocDate { get; set; }
    public Guid Generation => this.GetProperty(x => x.Generation);
    public DateTime Changed => this.GetProperty(x => x.Changed);
    public Lob Scan { get; set; }
    public Xml Source { get; set; }
    public DeliveryTypeEnum DeliveryType { get; set; }
    public DateTime DeliveryDate { get; set; }
}

And also several objects can be reflected in the same tables: for example, different types of documents from the previous example can be based on the same table T_DOC and having another link to T_DOC_TYPE store their attributes in the same and/or other tables related T_DOC as one-to-one.

Updatable tables hierarchy

The mapping of the data object to the storage structure can include mutable (updatable) tables — which will be updated when the data object changes and that changes are reflected in the database. And information tables — which contain reference data values, references to which (for example) are contained in the mutable tables but this data itself will not be updated even if we change the link to this directory in the data object. The link will change but the dictionary itself will remain unchanged.

Updatable tables are arranged in a hierarchy according to the relationships between the tables from the root - base table into which, when inserting, it is necessary to insert data first of all. The base table has no dependencies on mutable tables of this data object, only on informational ones (if any). Further along the hierarchy, updatable tables will be directly dependent on the base table and so on. Information tables are not included in the tree of updated tables and in the description of the mapping of the data object are placed on the first level sibling to the base table.

Real update of one or subtree of a tables in that hierarchy depends on changes of properties that mapped to concrete tables. When optional references is declared between tables inside updatable tables hierarchy, update of data objects can be automatically translated to insert or delete SQL statement applied to concrete table.

Base table

Root table of updatable tables hierarchy. In case of using read-only repository mapping, base table role can be assigned to any table (or virtual table) with which it will be logical to begin the construction of the SQL SELECT expression.

Optional references

The outer join references between tables within updatable tables hierarchy. Referenced (detail) table must contain one or more properties marked as mandatory or OuterFlag. At least one mandatory property are required and it can not be mapped on primary key (or part of primary key). In most cases that properties is natural key of the table. The values assigned to that properties will be used to make a decision over operation applied to table.

This property value used as indicator of whether or not to insert an entry into the table connected by the outer join (when inserting). If value is null inserting to this table (and their child tables in updatable tables hierarchy) will be skipped. When updating to an empty value, it signals the need to delete the record from the table optionally connected and their child tables in updatable tables hierarchy.

Data scope

Data scope term is required to describe an independent environment of operating the same data inside the application. Each data scope has an GUID identifier - layer. In each data scope application logic can set independent filters values over the same repository. Same repositories can be linked over different data scopes using different ways and rules.

Repository

Repository grant access to acquire data objects and apply their changes to database. Repository is represented by XData internal structures and available using interface IRepository<T> extend IQueryable<T>, where T is data object type.

Context

String alias associated to one of application database instance and all configuration options to use it inside XData environment. Configuration options can be obtained from configuration file or registered dynamically during runtime (see Installation & configuration).

Repository alias

Optional repository alias string. Required to unique identification repository used multiple times within one data scope. Sometimes the same repository (but arranged by different runtime filters and variables) can be useful as multiple detail data sources in master-detail relations inside single data scope (master-detail relations is limited to use single data scope).

Filters

Filters statically (by mapping) or dynamically applied to repository.

To define complex filtration rules filters can be grouped in filter groups characterized by name and logical filter combination operation (AND or OR). Filter groups can combine filters and/or depended filter groups. Root filter group of repository with filters combined using AND logical operation, can be omitted and will be automatically created in runtime. Default filter group name is empty string. By default all filters are linked to default filter group. To specify other filter group to certain filter set filter property Combination to name of this filter group.

The master-detail relations is realized on detail repository filters values set up also. In other cases, repository can be filtered by apply LINQ expressions on it.

Runtime filters

Filters, that allow set the value during runtime. Runtime filter value set can be automated using describing master-detail relation between repositories, or manually, using SetFilterValue method of repository.

The runtime filter can be defined as part of the mapping of the data object or added dynamically when the filter value is assigned. However, to dynamically add a runtime filter, it is required that the field to which that filter will be applied be described in mapping (as a property, read-only property or a hidden property).

In addition, using the runtime filter, you can change (or set) the filter value described in mapping. In this case, the property is not specified when describing such a filter, and the filter name must match the one described during mapping.

Data source flags

DataStructureFlags enumeration contains set of flags that defines structure of data source. Data source can be marked with combination of values:

  • None - default data source structure, plain object structure, can be edited, data grouping not applied.
  • ReadOnly - data source marked as read-only. In optimization goals is recommended to use this flag for all data sources read-only by application logic.
  • Tree - data source is marked as hierarchically organized. Allow to use multiple ways to filter detail data sources (when master is marked as Tree) - using plain links to active tree node, or to active tree node and subtree.
  • Grouping - data source is marked as grouped. Required to describe grouped data source.

Property flags

DataPropertyFlag enumeration contains set flags that defines specific role of property of the data object during its mapping:

  • None - default value, property marked with no specific roles
  • Id - property is part of data object primary key
  • OuterFlag - property is marked as mapped to mandatory field of optional referenced table. The value of this property is used to make a decision over operation applied to optional referenced table.
  • ConcurrencyToken - concurrency token used within optimistic locking.

SQL expression type

DataExpressionType enumeration contains types of SQL expression description when using in data object mapping:

  • PlainSql - SQL expression is plain SQL code,
  • SubQuery - SQL expression is subquery with specified alias,
  • LinqExpression - SQL expression defined as a static private field typed as Calculate<T>, where T is a SQL expression result type, and the field value is LINQ style expression reflects SQL expression logic.

Default value type

When inserting data into a database table, the concept of a default field value is often used. DefaultType enumeration contains types of values used to set default values of properties:

  • CurrentDate - current date (database time settings used)
  • CurrentDateTime - current date and time (database time settings used)
  • CurrentDateTimeUTC - current date and time UTC (database time settings used)
  • Variable - variable value with name stored in DefaultValue (see here for details)
  • Const - constant value stored in DefaultValue
  • AutoIncrement - value generated by database by auto increment fields or sequence. In case of using sequence is required to match the rules described here.
  • NewGuid - new GUID value is generated
  • UserName - current user name. Security provider subsystem using is required to fill this type of default value.

Default value features

DefaultFeature enumeration contains extension features used with default values of properties is assigned:

  • UseOnInsert - use default value on insert (by default, always applied)
  • UseOnUpdate - use default value on update
  • SkipWhenAssigned - skip insert into table when PK value assigned explicitly (see here for details)
  • UpdateWhenAssigned - change insert operation over table to update when PK value assigned explicitly (see here for details) Default features can be combined. For example: 
DefaultFeature.UseOnUpdate | DefaultFeature.SkipWhenAssigned

Aggregation type

DataGrouping enumeration contains data aggregation functions used inside grouped data source:

  • None - mapped field or SQL expression is one of data source grouped by.
  • Count, Sum, Min Max, Avg - corresponded function is applied to mapped field or SQL expression.

Property data source

Table field, view field, SQL procedure (or function) parameter or SQL expression mapped to data object property value.

Virtual table

Various RDBMS has mechanics to select the data without specifying real source ("dual" table in ORACLE, omit "from" section in MsSqlServer and so on). Virtual data table is recommended for use as source of calculated fields, SQL expressions, when virtual data processing is required. Virtual table is not described in mapping. To set virtual data source as source of property set data source alias as empty string.

Filter group

Named group of filters (or submittal filter groups) linked with the same logical operator (AND or OR). Root filter group named as empty string and have an AND logical operator. Root filter group can be omitted in mapping description. All filters without explicit group specification is assigned to root filter group. Filter group names must to be unique named within data object mapping description.

Filter null processing behavior

FilterNullable enumeration contains behaviors applied to null value processing while comparing data to filter value:

  • Nullable - (default) filter null value is omits the filter (no filter limitation applied)
  • NullsAllowed - null and not null values of filter and data is compared separately (filter within SQL query will looks like ((field is null and :param is null) or field = :param))
  • NullsNotAllowed - filter null value is translated as non valid and query will return no records (filter within SQL query will looks like (:param is not null and field = :param))
  • NullsCompared - only null values of filter and data is translated as valid (filter within SQL query will looks like (:param is null and field is null))

Variables

Using variables allows you to customize the existing mapping for a specific situation. Using Constant filters or Dictionary filters (or see here and here for dynamic mapping) with a value of the type variable value, you can delay the substitution of a particular value until it is used. To do this, use the "variables" parameter of the GetRepository method.

Another use of variables is to set stored procedure parameters (or see here for dynamic mapping).

In addition, you can use the variables to define the default field values.

In the case of using a subquery (or inner view), you can specify variables for a specific subquery in the mapping (or see here for dynamic mapping). This is useful when the subquery structure is used several times with slightly different filter values.

Note that you can use the SetVar extension method to describe variables:

"TestVar".SetVar(1)