Derived Models

This sections describes the concept of Derived Models, what they are, what they mean in the context of LLBLGen Pro, what they contain and what they're for.

Reasons why to use an Entity Model as the basis of a Derived Model

Models can both be a theoretical basis for a projection as also a way to communicate a vision on how reality looks like. By using an entity model as a basis for a derived model (and not let the derived model be created without one) a way is created to communicate the basis of the model that's used in code (the derived model) by using the abstract entity model used in the designer.

Another reason is that it gives the derived model a dedicated schema. Schemas in e.g. document databases are implicit (defined through the code) and it's not clear how the schema is really defined, and what the theoretical basis is for that schema. The approach using an abstract entity model solves that.

Derived Model types

Derived Models are models which derive from the Abstract Entity Model and which contain one or more Derived Elements. In the context of LLBLGen Pro, Derived Models are meant for the following purposes:

Data Transfer Object (DTO) model

for exposure in a service or to be used inside MVC models. This means a derived model which is based on an ORM mapped Abstract Entity Model.

Document model

to be used in document databases.

These two types are briefly described below. The Derived Element definitions in the two Derived Model types are the same in the Designer.

Data Transfer Object (DTO) model

This model is mainly used as a DTO model for exposure in a service, or e.g. as a DTO model to be used with MVC implementations. These models have a strong connection with the entity class model that's used to communicate with the database. The aspects for these models are:

• The Derived Elements are Data Transfer Objects (DTO)s
• Projections are to be defined to move data back and forth to/from the database. The route back to the database is only for the Root Entity.
• Requires as source for its data a live entity model at runtime.
• Can be used as a typed result of a custom query to avoid anonymous types or hand-written DTO classes.
• Likely to be less de-normalized than Document models.

Document model

This model is meant to be used in document databases. Document models have no ties at runtime with a live entity class model: the derived model is used in combination of a document database and is used to supply the types for the data (the documents) in a document database.

The aspects of these models are:

• The Derived Elements are Data Transfer Objects (DTO)s
• Has as source a document database
• No ties between an actual entity model available at runtime
• In general Derived Elements are more de-normalized than Derived Elements in Data Transfer Object (DTO) models.
• The Derived Elements have an ID field.

Target Frameworks decide the model type

Per Derived Model a target framework has to be specified, like with the Entity Model. This target framework decides what type the model is (DTO model or Document model) and also which presets are available to generate code with.

Derived Element basics

Derived Elements are elements which derive from an abstract entity definition. In the most purest form, a Derived Element contains for each field in the entity it derives from an equivalent field. A Derived Element can also contain de-normalized fields however, fields which originate from entities related to the entity the derived element derives from.

As the derived element derives from an abstract entity definition, it follows the abstract entity closely: e.g. if a field in the entity definition it derives from is removed, and the derived element has a field deriving from this field, the derived element field is removed automatically.

Example

The following abstract entity model has been defined:

We can now define a Derived Model on this entity model with two Derived Elements: Author and Book. They're given below.

In the example above we see that a hierarchical derived element has been defined for Author and for Book. In the Derived Element 'Author', we also see, as part of the embedded derived element 'Book', a de-normalized field, Publisher which is the related field Book.Publisher.Name. This illustrates the connection between Derived Elements and the abstract entity definitions they're derived from.

The derived elements can also be expressed in e.g. JSON, with data:

Author:
{
    Id: 1,
    FirstName: "John",
    LastName: "Doe",
    BooksWritten: 
    { 
        { Id: 1101, Title: "Foos Errant", Publisher: "Foo Books" }
    }
}

Book:
{
    Id: 1101,
    Title: "Foos Errant",
    PublisherId: 2,
    Author: 
    { 
        { Id: 1, FirstName: "John", LastName: "Doe" }
    }
}

Here, an Author Derived Element is shown with a couple of name-value pairs and a set of nested pairs, which are said to be embedded. The Book Derived Element stores data redundantly (de-normalized) in itself too and links to the publisher Derived Element semantically by storing its ID.

Root entity

A Derived Element has a Root Entity. This is the entity the Derived Element is directly derived from. In our example above, the derived element 'Author' has as root entity the 'Author' entity, shown in the abstract entity model earlier. The Root Entity can't be changed for a Derived Element, as that would mean the Derived Element is essentially another Derived Element.

Root derived element

A derived element that's a direct element in a derived model is called a root derived element. In our example above, 'Author', and 'Book', are root derived elements.

Embedded derived element

A derived element which is the source of a field in another derived element, in our example above, the 'Book' element in the field 'BooksWritten' in the Author derived element, is called an embedded derived element.

Mandatory ID

Each Derived Element that is a root derived element has an ID which is used as a PK. In LLBLGen Pro, IDs in root derived elements consists of one single field. This is in line with what Document Databases dictates as they require IDs to be a single field.

Value Typed fields and derived elements

If a field in a root entity has as type a valuetype, the value type is used to produce an Embedded derived element definition, which is the source of the derived element field. The fields of the valuetype are then simply added as fields of the embedded derived element, referencing the fields in the valuetype. If a field in a valuetype itself is a valuetyped field, it's simply again resulting in an embedded derived element created from that valuetype, and so on.

The embedded derived element created from a valuetype is a derived element like any other and will receive the same output, interfaces, attributes and the like as an embedded derived element created from an entity reachable from a navigator.

Fields in a valuetyped sourced embedded derived element can be de-normalized.

Type Inheritance with embedded derived elements: Set of Subtypes

A derived element defines a Set of subtypes. This set is a set of derived elements which can appear in place of the embedded derived element as the source. In our example above, if Book is an entity not in an Inheritance hierarchy, the Set of subtypes is empty. If Book is in an inheritance hierarchy (doesn't matter which kind), the Set of subtypes contains for each direct subtype of Book an embedded derived element with potentially all fields defined for the root entity of the embedded derived element.

Inherited fields.

If the embedded derived element contained in the Set of subtypes has subtypes as well, they're stored in the embedded derived element's Set of subtypes and so on. Fields part of an embedded derived element which contains subtypes are inherited by all subtype derived elements in the Set of Subtypes and so on.

Detailed Example

We have a root derived element Department. This derived element contains a field Employees. This field has as source the Employee embedded derived element with as root entity Employee. This entity is a hierarchy root in an inheritance hierarchy: it has as direct subtypes Clerk and Manager, and Manager has as direct subtype BoardMember.

You can then select the fields in Employee to be part of the embedded derived element which is the source of the field Employees. These fields are inherited by all the subtype derived elements part of the Set of subtypes of Employee. If you select Manager to be part of the set of subtypes for Employee, it means the field Employees in Department can contain instances of Employee and Manager. This is shown below.

If you then also select BoardMember as subtype for Manager (which is then placed in the set of subtypes of Manager) the field Employees in Department can then also contain BoardMember instances. Each embedded derived element defines only the fields of its own root entity, and doesn't contain any inherited fields, as the code generated will utilize inheritance here, if possible.

Groups and derived models.

Groups in the entity model can be generated as VS.NET projects, besides also being used as a visual grouping mechanism. Although within a derived element it's not possible to have entities from two groups if the grouping mechanism is set to separate projects, it isn't workable to have derived elements in one derived model which are from separate groups if the grouping mechanism is set to separate projects, as the generated code will then potentially have types which are named the same but are originating from different vs.net class models.

Validation within a derived model is performed to check whether there are entities from one group if the grouping mechanism is set to separate projects. If the grouping mechanism is set to visual grouping mechanims, the validator isn't doing anything.

Editor restrictions

To make it easier for the user, when adding a root derived element to a derived model, if there's already a root derived element in that model, the Designer filters on the group for the entities to choose from if the project grouping setting is set to 'as separate projects'. This mitigates the chance the user will store root derived elements deriving from entities in different groups in the same model.

Additionally, when the user selects one or more entities in project explorer and AsSeparateProjects is the grouping mechanism, the Derived Models shown in the selector when 'Add entities to new or existing Derived Model...' is filtered on the group name of the entities selected so the user can only add root derived elements based on these entities to derived models which have derived elements derived from entities from the same group.