OS.bee documentation - User contributions [en]

Entity DSL

2019-02-06T12:36:02Z

Worayeno: /* Reserved Keywords */

== Purpose ==

The Entity DSL facilitates the handling of persistence entities. Defining entities using the Entity DSL efficiently creates a clean entity model that contains all relevant semantic elements of the model text file.
This semantic model is used to automatically transform the semantic information into proper Java code with the respective annotations for a persistence provider. Additionally, if the entity model is located within a project with OSBP nature, "Auto-DTOs" and services are generated as well. In this case, attributes that are added to entities will automatically be transferred to the "Auto-DTOs".

== Overview ==

The main semantic elements of the Compex Entity DSL are the following:

* "Package" - the root element that contains all the other elements. A model can contain multiple packages.

* "Import" declarations - used to import external models or even Java classes.

* "Datatype" declarations - a way to define datatypes that can be used in entities and beans.

* "Entity" - the abstraction of a business model entity. It contains further elements such as properties and references.

* "Bean" - does not compile to a JPA Entity but to a Java Bean (POJO with getter and setter and PropertyChange-Support). Beans may be used as temporary containers in entity operations or can be embedded into JPA Entities.

* "Enum" - the abstraction for Java enums.

* "Property" - a reference to an embedded Bean, an Enum, a Java class or a simple datatype (as defined in the datatype declaration). Offers multiplicity.

* "Reference" - a reference to another Entity (or to another Bean in the case of a Bean). Offers multiplicity.

* "Operations" - similar to Java methods. The Xbase expression language can be used to write high-level code.

* "Annotations" can be placed on Entity, Property and Reference.

* "Comments" can be added to all elements.

== Entity model files ==

Entity models are described in .entitymodel files. These files describe the entity model and are the basis for the code generation. Entity models may be split over several .entitymodel files containing packages in the same namespace.
An .entitymodel file may contain several packages with entities. However, from a performance point of view, a complex entity model may work better with more and smaller .entitymodel files than the same model crammed into a few large files (or even a single file).

===package===
Entity model files must start with a package declaration. Packages are the root element of the Entity DSL grammar. Everything is contained in a package: Imports, Entities, Beans and Enums have to be defined inside the Package definition. One document can contain multiple packages with unique names.
The elements a package can contain are Entities, Beans and Enums. Additionally, a package allows Import statements and the declaration of datatypes.

<syntaxhighlight lang="java">
package name {
import importStatement;
datatype datatypeDefinition;
entities/beans/enums
}
</syntaxhighlight>

[[File:entity-1.png|center|frame|''Figure 1 - Entity model file - a package is the topmost element and contains other items.'']]

Marking a DTO as abstract (before the dto keyword) generates an abstract Java class for it.

The following modifiers may be placed after the dto keyword and the DTO name:

=== import ===
The Entity DSL allows the referencing of entities defined in different packages, even in different .entitymodel files. The import statement is a way to make these elements available in the current namespace without having to address them by their fully qualified name.

Import statements allow the use of the '*' wildcard.

<syntaxhighlight lang="java">
import importStatement;
</syntaxhighlight>

[[File:entity-2.png|center|frame|''Figure 2: Items contained in another package can be addressed if the package is imported using the import keyword and its fully qualified name.'']]

=== datatype ===
The Entity DSL allows the definition of datatypes. These are translated by the inferrer into their standard Java representation. The behavior of the generator can be controlled by the datatype definitions.
Datatypes defined in an .entitymodel file are local to that file. In order to define datatypes in one place and have them available in multiple .entitymodel files, the datatypes may be defined in a ".datatypes" file containing only datatype definitions inside a package statement.
There are three types of datatype definitions:

* '''jvmTypes''': Datatype definitons that map types to '''jvmTypes''' take the basic syntax of 
<blockquote><code>datatype <name> jvmType <type> as primitive;</code>.</blockquote>
<blockquote>Specifying datatypes in this manner uses an appropriate wrapper class in the generated Java code; adding the keywords <code>as primitive</code> enforces the use of primitive datatypes where applicable:
<code>datatype foo jvmType Integer;</code> compiles to an <code>Integer</code> whereas <code>datatype foo jvmType Integer as primitive;</code> results in <code>int</code>.

[[File:entity-3.png|center|frame|''Figure 3: The defined datatype is translated to a wrapper class.'']]

[[File:Entity-4.png|center|frame|''Figure 4: By adding the <code>as primitive</code> keywords, the datatype is translated to a primitive datatype.'']]

</blockquote>
* '''dateTypes''': The datatypes for handling temporal information can be defined by the following statement:
<blockquote><code>datatype <name> datetype date—time—timestamp; </code>
Datatypes that have been defined in this manner can be used as property variables in entities and beans.

[[File:Entity-5.png|center|frame|''Figure 5: Defining datatypes for handling temporal information. Content assist is available.'']]

</blockquote>
* '''blobs''': Binary blobs can be handled by defining a datatype with the <code>as blob</code> keywords. The Java implementation of such a blob is a byte array. Appropriate persistence annotations are automatically added.
<blockquote>
<code>datatype <name> as blob;</code>

[[File:Entity-6.png|center|frame|''Figure 6: Including binary blobs by using a datatype with the <code>as blob</code> keywords.'']]
</blockquote>

 After import statements and datatype definitions, the content of the .entitymodel file is made up of <code>entity</code>, <code>bean</code> and <code>enum</code> definitions.

== Entities ==
Entities are the most complex elements in the Entity DSL. An entity is an abstraction above a business object. Entities are defined by their name, properties, references and operations. Generally, an entity is an object which can keep the state of variables and references as well as be persisted.
For each entity that is defined in a package, a Java class and the corresponding persistence structure is automatically generated. Inside a project with Compex nature, "Auto-DTOs" and services are created as well.

Entities may extend other entities. In this case, they are derived from their parent entity. That means that the properties and references of the parent entity are inherited.

Syntax:
<syntaxhighlight lang="java">
[modifiers] entity <name> extends <parentEntity> {
[entityProperties]
}
</syntaxhighlight>

[[File:Entity-7.png|center|frame|''Figure 7: Items contained in another package can be addressed if the package is imported using the <code>import</code> keyword and its fully qualified name'']]

Entities may be defined with certain modifiers that change the generated Java Code. The following modifiers are supported:

=== abstract ===

<blockquote>
<code>abstract</code> marks the entity as "abstract". This generates an abstract Java class.

[[File:Entity-8.png|center|frame|''Figure 8: The <code>abstract</code> keyword causes the translation into an abstract Java class'']]

</blockquote>

=== historized ===
<blockquote>
<code>historized</code> marks the entity as "historized". Historized entities can have several entries in a database, but only one of them may be marked as current.

The <code>historized</code> keyword adds an object ID, a version field and a flag for the current version to the entity.

[[File:Entity-9.png|center|frame|''Figure 9: The <code>historized</code> modifier triggers the creation of an object ID, an object version and a flag for marking the current version.'']]

</blockquote>

=== cacheable ===
<blockquote>
<code>cacheable</code> marks the entity as "cacheable". The appropriate annotation for the persistence provider is added to the generated Java code.

[[File:Entity-10.png|center|frame|''Figure 10: Declaring an entity to be <code>cacheable</code> adds the <code>@Cacheable</code> annotation'']]
</blockquote>

=== timedependent ===
<blockquote>
<code>timedependent</code> marks the entity as "time-dependent". An object may have several entries in the database. Which entry is valid will be determined by '''valid from''' and '''valid until''' fields that are added to the entity.
An object ID is created in order to tie the entries together. The <code>timedependent</code> keyword recognizes the modifiers <code>(DATE)</code> and <code>(TIMESTAMP)</code>. Default is <code>timedependent(DATE)</code>.

[[File:Entity-11.png|center|frame|''Figure 11: The <code>timedependent</code> keyword causes an object ID, a validFrom and a validUntil field to be created in order to support multiple database entries for an object.'']]
</blockquote>

=== mapped superclass ===
<blockquote>
<code>mapped superclass</code> marks a class that provides persistent entity state and mapping information for its subclasses, but which is not an entity itself.

Typically, the purpose of a mapped superclass is to define state and mapping information that is common to multiple entities. All the mappings from the mapped superclass are inherited by its subclasses, as if they had been defined there directly.

[[File:Entity-12.png|center|frame|''Figure 12: The <code>mapped superclass</code> keyword sets the appropriate annotation which causes the persistence provider to move the mappings to the derived subclasses.'']]
</blockquote>

===extends===
<blockquote>
The modifier <code>extends</code> may be placed after the entity keyword and the entity name, as <code>entity foo extends bar {</code>, where <code>bar</code> has already been defined as an entity.

<code>extends</code> marks an entity that is derived from another entity. That means that the properties and references of the parent entity are inherited.
</blockquote>

==Entity Persistence Settings==

Apart from the mapped superclass modifier that moves all property columns to the tables belonging to derived classes, the following settings for table inheritance can be specified within an entity definition:
* inheritance per class
* inheritance per subclass

The structure of the database created from an entity model can be controlled by the following settings:
* schemaName
* tableName
* discriminatorColumn
* discriminatorType
* discriminatorValue

===inheritance per class===
<blockquote>
<code>inheritance per class{}</code> causes a table to be created for each class; subclasses share this table using a discriminator value. This statement has to be followed by braces, inside of which further details can be specified.

[[File:Entity-13.png|center|frame|''Figure 13: A single table for entity Base is created; the generated Java code for the “Derived” class shows that the “Derived” entity is added to this table by using a discriminator.'']]
</blockquote>

===inheritance per subclass===
<blockquote>
<code>inheritance per subclass{}</code> causes a table to be created for each subclass. This statement has to be followed by braces, inside of which further details can be specified. This is the default behaviour if no inheritance strategy is specified.

[[File:Entity-14.png|center|frame|''Figure 14: An <code>@Table</code> annotation is added to the generated Java code, so that the "Derived" entity is mapped to a table of its own.'']]
</blockquote>

===schemaName===
<blockquote>
<code>schemaName</code> allows the specification of a name for the database schema to be used. This setting is translated to the appropriate JPA annotation <code>@Table(schema = <xyz>)</code>. The schema name given is converted to snake case using capitals.
</blockquote>

===tableName===
<blockquote>
<code>tableName</code> allows the specification of a name for the table (within the database schema) to which the entity is mapped. This setting is translated to the appropriate JPA annotation
<code>@Table(name = <xyz>)</code>.

The table name specified is converted to snake case using capitals. The default value is the name of the entity.

[[File:Entity-15.png|center|frame|''Figure 15: Specifying the <code>schemaName</code> and <code>tableName</code> settings in an entity determines the name of the database schema and tables used for persistence.'']]
</blockquote>

===discriminatorColumn===
<blockquote>
<code>discriminatorColumn</code> optionally allows the specification of a name for the discriminator column in the case of <code>inheritance per class</code>. It appears within the braces after the inheritance-strategy statement and must be followed by a semicolon. It defaults to <code>DISC</code>.
</blockquote>

===discriminatorType===

<blockquote>
<code>discriminatorType</code> optionally allows the definition of the datatype of the discriminator within the single table. It can be set to <code>CHAR</code>, <code>INT</code>, <code>STRING</code> or <code>INHERIT</code>. It appears within the braces after the <code>inheritance</code> statement and must be followed by a semicolon. It defaults to <code>STRING;</code>.
</blockquote>

===discriminatorValue===

<blockquote>
<code>discriminatorValue</code> allows a custom value to be used for the discriminator within the single table. It appears within the braces after the <code>inheritance</code> statement and must be followed by a semicolon. It defaults to the entity name converted to snake case.

[[File:Entity-16.png|center|frame|''Figure 16: The <code>inheritance</code> statement allows the optional specification of discriminator column, type and value to be used in the case of a single table.'']]
</blockquote>

==Beans==

'''Beans''' are objects that are embedded in other entities, inheriting their persistence and lifecycle. Similar to entities, beans are characterised by their name, their properties and their references. For each bean that is defined in a package, a Java class is automatically generated.

Beans can be embedded into entities by defining them as properties of the respective entity. The appropriate annotations (<code>@Embeddable</code>, <code>@Embedded</code>, <code>@AttributeOverrides</code> etc.) are added in order to have beans persisted with their parent entities.

[[File:Entity-17.png|center|frame|''Figure 17: Beans can be embedded in entities and are persisted with them.'']]

==Enums==

'''Enums''' are an abstraction of the Java <code>enum</code>. They compile to <code>enum</code> classes and can be used as properties in entities and beans.

[[File:Entity-18.png|center|frame|''Figure 18: Defining <code>enums</code> allows using them as variables in entities and beans.'']]

==Properties==
Properties of entities and beans are references to datatypes or enums. They can be regarded as variables and are defined by a keyword followed by a datatype (Java type or datatype defined in the <code>datatype</code> section) and a name. By defining a bean as a property of an entity, it is embedded in it.

Properties can be determined with the following keywords:

===var===
<blockquote>
The basic property <code>var</code> defines a variable that is persisted in a table column. A property must have a type and a name.

'''Multiplicity''' of properties can be controlled by the following (optional) settings:

* <code>[1]</code> defines a non-nullable property.
* <code>[0..1]</code> defines a nullable property (this is the default behavior).
* <code>[1..*]</code> defines a list of properties that must not be empty.
* <code>[0..*]</code> or simply <code>[*]</code> defines a list of properties that may be empty.

[[File:Entity-19.png|center|frame|''Figure 19: Variables can be defined using the <code>var</code> keyword.'']]

The appropriate persistence settings are generated automatically. If a multiplicity is specified, the appropriate annotations (and, if necessary, a list rather than a single variable) are generated.
</blockquote>

===derived===
<blockquote>
<code>derived</code> defines a property that is derived from other properties. The derived property must be have a type, a name and the calculation logic that derives it from the other properties, written as an Xexpression in braces.

[[File:Entity-20.png|center|frame|''Figure 20: Properties may be derived from other properties using an Xexpression.'']]

The code is automatically translated to valid Java code.
</blockquote>

===dirty===
<blockquote>
<code>dirty</code> defines a property used as a flag to track the "dirty" state of the buffered data when editing values, before the changes have been written back to the persistence entity. Only one <code>dirty</code> flag is allowed per entity. The datatype has to be boolean.

[[File:Entity-21.png|center|frame|''Figure 21: The <code>dirty</code> property is used to flag whether changes have been made to the bufered data, but not yet written back to the persistence entity. '']]

The boolean field for this property and the appropriate annotation are generated with the <code>dirty</code> keyword.
</blockquote>

===domainDescription===
<blockquote>
<code>domainDescription</code> defines a property that is used as a domain description. The appropriate annotation is added to the property. A domain description must be of type <code>String</code>. Domain descriptions may be derived from other properties.

[[File:Entity-22.png|center|frame|''Figure 22: Domain description properties can be created with the <code>domainDescription</code> keyword.'']]
</blockquote>

===domainKey===
<blockquote>
<code>domainKey</code> defines a domain key. The appropriate annotation is added to the property. Primitive datatypes may be used as domain keys.

[[File:Entity-23.png|center|frame|''Figure 23: A field containing a domain key is created with the <code>domainKey keyword</code>.'']]
</blockquote>

===id===
<blockquote>
{{Deprecated}}

'''id''' defines an ID property (used as a primary key by the JPA compiler). '''This keyword is deprecated - use uuid instead'''. If no <code>id</code> is specified, a warning is given.

'''Caution''': ID autogeneration causes problems, since the value is not set before the entity is persisted, e.g., in the database. It is therefore advised to use the <code>uuid</code> keyword instead.

[[File:Entity-24.png|center|frame|''Figure 24: Entities are supposed to have an ID property that is used as a primary key to the underlying database.'']]

'''Caution''': The generated IDs are not necessarily unique if the deprecated <code>id</code> keyword is used!
</blockquote>

===index===
<blockquote>
The <code>index</code> keyword causes an index for the table to be generated. Indexes may be based on one or more properties (primitive only) and references (one-to-one only) of the entity. An index must be given a name and, in braces, a list of the fields it is based upon. If the <code>index</code> keyword is prefixed with <code>unique</code>, a unique index is created.

[[File:Entity-25.png|center|frame|''Figure 25: Database table indexes that map entities are generated with the <code>index</code> keyword.'']]

The <code>@Table</code> annotation is supplemented with the index definition.

</blockquote>

===properties===
<blockquote>
Features (properties and references) of entities and beans can optionally be given additional information in the form of key-value pairs. This information can then be retrieved from the semantic model. The key-value pairs are defined in parentheses after the properties keyword following the feature name. Multiple pairs can be defined (comma-separated).

[[File:Entity-26.png|center|frame|''Figure 26: Additional information about features can be defined by key-value pairs. This information is then stored in the semantic model and is retrievable.'']]

</blockquote>

===uuid===
<blockquote>
<code>uuid</code> allows the use of Universally Unique IDs as primary keys. A new UUID value is generated for each object as soon as that object has been created, independently of database operations. This circumvents the problems with the <code>id</code> keyword. UUIDs have to be of type <code>String</code>.

[[File:Entity-27.png|center|frame|''Figure 27: By using the <code>uuid</code> keyword, entities are created with a reliably unique identifier.'']]

</blockquote>

===version===
<blockquote>
<code>version</code> defines a version-property (used by the JPA-Compiler).

[[File:Entity-28.png|center|frame|''Figure 28: A <code>version</code> property can be added to entities and beans.'']]

</blockquote>

===transient===
<blockquote>
<code>transient</code> marks the property as transient. Instead of a <code>@Column</code>, a <code>@Transient</code> annotation is generated, so that the property is not persisted in the database.

[[File:Entity-29.png|center|frame|''Figure 29: The <code>transient</code> keyword enables the exclusion of properties from persistence.'']]

</blockquote>

==References==

The Entity DSL tracks relationships between entities by using the concept of "references". References can exist between objects of the same nature (entities to entities, beans to beans). Where appropriate, back references ("opposite") are added.
References are defined by the <code>ref</code> keyword, a target, an optional type and a name. The exact type of the reference can be specified with the following modifiers:

===Multiplicity and nullability===
<blockquote>
The Entity DSL supports the specification of multiplicities in square brackets appended to the type:
* <code>[1]</code> defines a non-nullable, one-to-one relationship.
* <code>[0..1]</code> defines a nullable, one-to-one relationship (this is the default behavior).
* <code>[1..*]</code> defines a non-nullable, one-to-many relationship. An <code>opposite</code> reference is needed.
* <code>[0..*]</code> or simply <code>[*]</code> defines a nullable, one-to-many relationship. An <code>opposite</code> reference is needed.

[[File:Entity-30.png|center|frame|''Figure 30: Adding multiplicity "[1]" causes the annotations for non-nullable database entries to be set.'']]

</blockquote>

===opposite reference===
<blockquote>
Lifecycle references need the specification of an opposite reference. This can be done with the <code>opposite</code> keyword.

Using the <code>opposite</code> reference, it is possible to navigate back to the original object after following the reference.

</blockquote>

===cascade===
<blockquote>
The <code>cascade</code> specifier controls the behavior of the database on delete operations. If an object with a <code>cascade</code> reference to other objects is deleted, those other objects will be removed as well.

[[File:Entity-31.png|center|frame|''Figure 31: By using the <code>cascade</code> and <code>opposite</code> keywords, bidirectional associations can be achieved.'']]

</blockquote>

==Operations==

Operations are other important features. They are based on Xbase and offer a huge set of semantic features, extending the featureset of Java. Xbase additionally offers features such as closures.
Operations can be declared by the <code>def</code> keyword followed by braces containing the inline operation.

[[File:Entity-32.png|center|frame|''Figure 32: The <code>def</code> keyword allows the inlining of custom methods in the Entity DSL code.'']]

These methods are translated into the appropriate Java methods along with the automatically generated getter and setter methods.

==Annotations==

Annotations can be added to all elements except import declarations. Specifying annotations in the Entity DSL works in a straightforward manner; content assist is available. The added annotations are taken over into the generated Java code.

[[File:Entity-33.png|center|frame|''Figure 33: Annotating elements in the Compex Entity DSL causes an annotation to be inserted into the generated Java code.'']]

These methods are translated into the appropriate Java methods along with the automatically generated getter and setter methods.

==Comments==

Comments can be added anywhere in an .entitymodel text file and are copied over into the generated Java code. Comments are enclosed in <code>/* ... */</code>.

[[File:Entity-34.png|center|frame|''Figure 34: The comments added in the Entity DSL are transformed to Java-style comments in the generated code.'']]

Comments before the <code>package</code> keyword are copied over to all generated Java classes – this is the place for copyright notices.

[[File:Entity-35.png|center|frame|''Figure 35: A comment before the package keyword ends up in all generated Java classes.'']]

==Reserved Keywords==

The keywords of the Entity DSL are syntactic features and can therefore not be used as semantic identifiers.

In order to circumvent this, it is possible to escape them with the <code>^</code> character. During the generation of the Java code, this escape character is removed.

[[File:Entity-36.png|center|frame|''Figure 36: Using the escape character '^', it is possible to achieve an identifier in the generated Java code with a name that would be a reserved word in the Entity DSL. In this case, a variable named <code>uuid</code> is generated that cannot be specified in the entity model file.'']]

Please note that you are '''not allowed to use identifiers corresponding to reserved keywords''' of the supported databases you can find here below:

[https://db.apache.org/derby/docs/10.2/ref/rrefkeywords29722.html Derby]

[http://www.h2database.com/html/advanced.html?highlight=reserved&search=reser#firstFound H2]

[https://docs.microsoft.com/en-us/sql/odbc/reference/appendixes/reserved-keywords?view=sql-server-2017 MS SQL]

[https://docs.oracle.com/database/121/SQLRF/ap_keywd001.htm#SQLRF55621 Oracle]

[https://dev.mysql.com/doc/refman/8.0/en/keywords.html MySQL]

[https://www.postgresql.org/docs/8.2/sql-keywords-appendix.html PostgreSQL]

== Copyright Notice ==
{{Copyright Notice}}

Entity DSL

2019-02-06T12:32:21Z

Worayeno: /* Reserved Keywords */

== Purpose ==

The Entity DSL facilitates the handling of persistence entities. Defining entities using the Entity DSL efficiently creates a clean entity model that contains all relevant semantic elements of the model text file.
This semantic model is used to automatically transform the semantic information into proper Java code with the respective annotations for a persistence provider. Additionally, if the entity model is located within a project with OSBP nature, "Auto-DTOs" and services are generated as well. In this case, attributes that are added to entities will automatically be transferred to the "Auto-DTOs".

== Overview ==

The main semantic elements of the Compex Entity DSL are the following:

* "Package" - the root element that contains all the other elements. A model can contain multiple packages.

* "Import" declarations - used to import external models or even Java classes.

* "Datatype" declarations - a way to define datatypes that can be used in entities and beans.

* "Entity" - the abstraction of a business model entity. It contains further elements such as properties and references.

* "Bean" - does not compile to a JPA Entity but to a Java Bean (POJO with getter and setter and PropertyChange-Support). Beans may be used as temporary containers in entity operations or can be embedded into JPA Entities.

* "Enum" - the abstraction for Java enums.

* "Property" - a reference to an embedded Bean, an Enum, a Java class or a simple datatype (as defined in the datatype declaration). Offers multiplicity.

* "Reference" - a reference to another Entity (or to another Bean in the case of a Bean). Offers multiplicity.

* "Operations" - similar to Java methods. The Xbase expression language can be used to write high-level code.

* "Annotations" can be placed on Entity, Property and Reference.

* "Comments" can be added to all elements.

== Entity model files ==

Entity models are described in .entitymodel files. These files describe the entity model and are the basis for the code generation. Entity models may be split over several .entitymodel files containing packages in the same namespace.
An .entitymodel file may contain several packages with entities. However, from a performance point of view, a complex entity model may work better with more and smaller .entitymodel files than the same model crammed into a few large files (or even a single file).

===package===
Entity model files must start with a package declaration. Packages are the root element of the Entity DSL grammar. Everything is contained in a package: Imports, Entities, Beans and Enums have to be defined inside the Package definition. One document can contain multiple packages with unique names.
The elements a package can contain are Entities, Beans and Enums. Additionally, a package allows Import statements and the declaration of datatypes.

<syntaxhighlight lang="java">
package name {
import importStatement;
datatype datatypeDefinition;
entities/beans/enums
}
</syntaxhighlight>

[[File:entity-1.png|center|frame|''Figure 1 - Entity model file - a package is the topmost element and contains other items.'']]

Marking a DTO as abstract (before the dto keyword) generates an abstract Java class for it.

The following modifiers may be placed after the dto keyword and the DTO name:

=== import ===
The Entity DSL allows the referencing of entities defined in different packages, even in different .entitymodel files. The import statement is a way to make these elements available in the current namespace without having to address them by their fully qualified name.

Import statements allow the use of the '*' wildcard.

<syntaxhighlight lang="java">
import importStatement;
</syntaxhighlight>

[[File:entity-2.png|center|frame|''Figure 2: Items contained in another package can be addressed if the package is imported using the import keyword and its fully qualified name.'']]

=== datatype ===
The Entity DSL allows the definition of datatypes. These are translated by the inferrer into their standard Java representation. The behavior of the generator can be controlled by the datatype definitions.
Datatypes defined in an .entitymodel file are local to that file. In order to define datatypes in one place and have them available in multiple .entitymodel files, the datatypes may be defined in a ".datatypes" file containing only datatype definitions inside a package statement.
There are three types of datatype definitions:

* '''jvmTypes''': Datatype definitons that map types to '''jvmTypes''' take the basic syntax of 
<blockquote><code>datatype <name> jvmType <type> as primitive;</code>.</blockquote>
<blockquote>Specifying datatypes in this manner uses an appropriate wrapper class in the generated Java code; adding the keywords <code>as primitive</code> enforces the use of primitive datatypes where applicable:
<code>datatype foo jvmType Integer;</code> compiles to an <code>Integer</code> whereas <code>datatype foo jvmType Integer as primitive;</code> results in <code>int</code>.

[[File:entity-3.png|center|frame|''Figure 3: The defined datatype is translated to a wrapper class.'']]

[[File:Entity-4.png|center|frame|''Figure 4: By adding the <code>as primitive</code> keywords, the datatype is translated to a primitive datatype.'']]

</blockquote>
* '''dateTypes''': The datatypes for handling temporal information can be defined by the following statement:
<blockquote><code>datatype <name> datetype date—time—timestamp; </code>
Datatypes that have been defined in this manner can be used as property variables in entities and beans.

[[File:Entity-5.png|center|frame|''Figure 5: Defining datatypes for handling temporal information. Content assist is available.'']]

</blockquote>
* '''blobs''': Binary blobs can be handled by defining a datatype with the <code>as blob</code> keywords. The Java implementation of such a blob is a byte array. Appropriate persistence annotations are automatically added.
<blockquote>
<code>datatype <name> as blob;</code>

[[File:Entity-6.png|center|frame|''Figure 6: Including binary blobs by using a datatype with the <code>as blob</code> keywords.'']]
</blockquote>

 After import statements and datatype definitions, the content of the .entitymodel file is made up of <code>entity</code>, <code>bean</code> and <code>enum</code> definitions.

== Entities ==
Entities are the most complex elements in the Entity DSL. An entity is an abstraction above a business object. Entities are defined by their name, properties, references and operations. Generally, an entity is an object which can keep the state of variables and references as well as be persisted.
For each entity that is defined in a package, a Java class and the corresponding persistence structure is automatically generated. Inside a project with Compex nature, "Auto-DTOs" and services are created as well.

Entities may extend other entities. In this case, they are derived from their parent entity. That means that the properties and references of the parent entity are inherited.

Syntax:
<syntaxhighlight lang="java">
[modifiers] entity <name> extends <parentEntity> {
[entityProperties]
}
</syntaxhighlight>

[[File:Entity-7.png|center|frame|''Figure 7: Items contained in another package can be addressed if the package is imported using the <code>import</code> keyword and its fully qualified name'']]

Entities may be defined with certain modifiers that change the generated Java Code. The following modifiers are supported:

=== abstract ===

<blockquote>
<code>abstract</code> marks the entity as "abstract". This generates an abstract Java class.

[[File:Entity-8.png|center|frame|''Figure 8: The <code>abstract</code> keyword causes the translation into an abstract Java class'']]

</blockquote>

=== historized ===
<blockquote>
<code>historized</code> marks the entity as "historized". Historized entities can have several entries in a database, but only one of them may be marked as current.

The <code>historized</code> keyword adds an object ID, a version field and a flag for the current version to the entity.

[[File:Entity-9.png|center|frame|''Figure 9: The <code>historized</code> modifier triggers the creation of an object ID, an object version and a flag for marking the current version.'']]

</blockquote>

=== cacheable ===
<blockquote>
<code>cacheable</code> marks the entity as "cacheable". The appropriate annotation for the persistence provider is added to the generated Java code.

[[File:Entity-10.png|center|frame|''Figure 10: Declaring an entity to be <code>cacheable</code> adds the <code>@Cacheable</code> annotation'']]
</blockquote>

=== timedependent ===
<blockquote>
<code>timedependent</code> marks the entity as "time-dependent". An object may have several entries in the database. Which entry is valid will be determined by '''valid from''' and '''valid until''' fields that are added to the entity.
An object ID is created in order to tie the entries together. The <code>timedependent</code> keyword recognizes the modifiers <code>(DATE)</code> and <code>(TIMESTAMP)</code>. Default is <code>timedependent(DATE)</code>.

[[File:Entity-11.png|center|frame|''Figure 11: The <code>timedependent</code> keyword causes an object ID, a validFrom and a validUntil field to be created in order to support multiple database entries for an object.'']]
</blockquote>

=== mapped superclass ===
<blockquote>
<code>mapped superclass</code> marks a class that provides persistent entity state and mapping information for its subclasses, but which is not an entity itself.

Typically, the purpose of a mapped superclass is to define state and mapping information that is common to multiple entities. All the mappings from the mapped superclass are inherited by its subclasses, as if they had been defined there directly.

[[File:Entity-12.png|center|frame|''Figure 12: The <code>mapped superclass</code> keyword sets the appropriate annotation which causes the persistence provider to move the mappings to the derived subclasses.'']]
</blockquote>

===extends===
<blockquote>
The modifier <code>extends</code> may be placed after the entity keyword and the entity name, as <code>entity foo extends bar {</code>, where <code>bar</code> has already been defined as an entity.

<code>extends</code> marks an entity that is derived from another entity. That means that the properties and references of the parent entity are inherited.
</blockquote>

==Entity Persistence Settings==

Apart from the mapped superclass modifier that moves all property columns to the tables belonging to derived classes, the following settings for table inheritance can be specified within an entity definition:
* inheritance per class
* inheritance per subclass

The structure of the database created from an entity model can be controlled by the following settings:
* schemaName
* tableName
* discriminatorColumn
* discriminatorType
* discriminatorValue

===inheritance per class===
<blockquote>
<code>inheritance per class{}</code> causes a table to be created for each class; subclasses share this table using a discriminator value. This statement has to be followed by braces, inside of which further details can be specified.

[[File:Entity-13.png|center|frame|''Figure 13: A single table for entity Base is created; the generated Java code for the “Derived” class shows that the “Derived” entity is added to this table by using a discriminator.'']]
</blockquote>

===inheritance per subclass===
<blockquote>
<code>inheritance per subclass{}</code> causes a table to be created for each subclass. This statement has to be followed by braces, inside of which further details can be specified. This is the default behaviour if no inheritance strategy is specified.

[[File:Entity-14.png|center|frame|''Figure 14: An <code>@Table</code> annotation is added to the generated Java code, so that the "Derived" entity is mapped to a table of its own.'']]
</blockquote>

===schemaName===
<blockquote>
<code>schemaName</code> allows the specification of a name for the database schema to be used. This setting is translated to the appropriate JPA annotation <code>@Table(schema = <xyz>)</code>. The schema name given is converted to snake case using capitals.
</blockquote>

===tableName===
<blockquote>
<code>tableName</code> allows the specification of a name for the table (within the database schema) to which the entity is mapped. This setting is translated to the appropriate JPA annotation
<code>@Table(name = <xyz>)</code>.

The table name specified is converted to snake case using capitals. The default value is the name of the entity.

[[File:Entity-15.png|center|frame|''Figure 15: Specifying the <code>schemaName</code> and <code>tableName</code> settings in an entity determines the name of the database schema and tables used for persistence.'']]
</blockquote>

===discriminatorColumn===
<blockquote>
<code>discriminatorColumn</code> optionally allows the specification of a name for the discriminator column in the case of <code>inheritance per class</code>. It appears within the braces after the inheritance-strategy statement and must be followed by a semicolon. It defaults to <code>DISC</code>.
</blockquote>

===discriminatorType===

<blockquote>
<code>discriminatorType</code> optionally allows the definition of the datatype of the discriminator within the single table. It can be set to <code>CHAR</code>, <code>INT</code>, <code>STRING</code> or <code>INHERIT</code>. It appears within the braces after the <code>inheritance</code> statement and must be followed by a semicolon. It defaults to <code>STRING;</code>.
</blockquote>

===discriminatorValue===

<blockquote>
<code>discriminatorValue</code> allows a custom value to be used for the discriminator within the single table. It appears within the braces after the <code>inheritance</code> statement and must be followed by a semicolon. It defaults to the entity name converted to snake case.

[[File:Entity-16.png|center|frame|''Figure 16: The <code>inheritance</code> statement allows the optional specification of discriminator column, type and value to be used in the case of a single table.'']]
</blockquote>

==Beans==

'''Beans''' are objects that are embedded in other entities, inheriting their persistence and lifecycle. Similar to entities, beans are characterised by their name, their properties and their references. For each bean that is defined in a package, a Java class is automatically generated.

Beans can be embedded into entities by defining them as properties of the respective entity. The appropriate annotations (<code>@Embeddable</code>, <code>@Embedded</code>, <code>@AttributeOverrides</code> etc.) are added in order to have beans persisted with their parent entities.

[[File:Entity-17.png|center|frame|''Figure 17: Beans can be embedded in entities and are persisted with them.'']]

==Enums==

'''Enums''' are an abstraction of the Java <code>enum</code>. They compile to <code>enum</code> classes and can be used as properties in entities and beans.

[[File:Entity-18.png|center|frame|''Figure 18: Defining <code>enums</code> allows using them as variables in entities and beans.'']]

==Properties==
Properties of entities and beans are references to datatypes or enums. They can be regarded as variables and are defined by a keyword followed by a datatype (Java type or datatype defined in the <code>datatype</code> section) and a name. By defining a bean as a property of an entity, it is embedded in it.

Properties can be determined with the following keywords:

===var===
<blockquote>
The basic property <code>var</code> defines a variable that is persisted in a table column. A property must have a type and a name.

'''Multiplicity''' of properties can be controlled by the following (optional) settings:

* <code>[1]</code> defines a non-nullable property.
* <code>[0..1]</code> defines a nullable property (this is the default behavior).
* <code>[1..*]</code> defines a list of properties that must not be empty.
* <code>[0..*]</code> or simply <code>[*]</code> defines a list of properties that may be empty.

[[File:Entity-19.png|center|frame|''Figure 19: Variables can be defined using the <code>var</code> keyword.'']]

The appropriate persistence settings are generated automatically. If a multiplicity is specified, the appropriate annotations (and, if necessary, a list rather than a single variable) are generated.
</blockquote>

===derived===
<blockquote>
<code>derived</code> defines a property that is derived from other properties. The derived property must be have a type, a name and the calculation logic that derives it from the other properties, written as an Xexpression in braces.

[[File:Entity-20.png|center|frame|''Figure 20: Properties may be derived from other properties using an Xexpression.'']]

The code is automatically translated to valid Java code.
</blockquote>

===dirty===
<blockquote>
<code>dirty</code> defines a property used as a flag to track the "dirty" state of the buffered data when editing values, before the changes have been written back to the persistence entity. Only one <code>dirty</code> flag is allowed per entity. The datatype has to be boolean.

[[File:Entity-21.png|center|frame|''Figure 21: The <code>dirty</code> property is used to flag whether changes have been made to the bufered data, but not yet written back to the persistence entity. '']]

The boolean field for this property and the appropriate annotation are generated with the <code>dirty</code> keyword.
</blockquote>

===domainDescription===
<blockquote>
<code>domainDescription</code> defines a property that is used as a domain description. The appropriate annotation is added to the property. A domain description must be of type <code>String</code>. Domain descriptions may be derived from other properties.

[[File:Entity-22.png|center|frame|''Figure 22: Domain description properties can be created with the <code>domainDescription</code> keyword.'']]
</blockquote>

===domainKey===
<blockquote>
<code>domainKey</code> defines a domain key. The appropriate annotation is added to the property. Primitive datatypes may be used as domain keys.

[[File:Entity-23.png|center|frame|''Figure 23: A field containing a domain key is created with the <code>domainKey keyword</code>.'']]
</blockquote>

===id===
<blockquote>
{{Deprecated}}

'''id''' defines an ID property (used as a primary key by the JPA compiler). '''This keyword is deprecated - use uuid instead'''. If no <code>id</code> is specified, a warning is given.

'''Caution''': ID autogeneration causes problems, since the value is not set before the entity is persisted, e.g., in the database. It is therefore advised to use the <code>uuid</code> keyword instead.

[[File:Entity-24.png|center|frame|''Figure 24: Entities are supposed to have an ID property that is used as a primary key to the underlying database.'']]

'''Caution''': The generated IDs are not necessarily unique if the deprecated <code>id</code> keyword is used!
</blockquote>

===index===
<blockquote>
The <code>index</code> keyword causes an index for the table to be generated. Indexes may be based on one or more properties (primitive only) and references (one-to-one only) of the entity. An index must be given a name and, in braces, a list of the fields it is based upon. If the <code>index</code> keyword is prefixed with <code>unique</code>, a unique index is created.

[[File:Entity-25.png|center|frame|''Figure 25: Database table indexes that map entities are generated with the <code>index</code> keyword.'']]

The <code>@Table</code> annotation is supplemented with the index definition.

</blockquote>

===properties===
<blockquote>
Features (properties and references) of entities and beans can optionally be given additional information in the form of key-value pairs. This information can then be retrieved from the semantic model. The key-value pairs are defined in parentheses after the properties keyword following the feature name. Multiple pairs can be defined (comma-separated).

[[File:Entity-26.png|center|frame|''Figure 26: Additional information about features can be defined by key-value pairs. This information is then stored in the semantic model and is retrievable.'']]

</blockquote>

===uuid===
<blockquote>
<code>uuid</code> allows the use of Universally Unique IDs as primary keys. A new UUID value is generated for each object as soon as that object has been created, independently of database operations. This circumvents the problems with the <code>id</code> keyword. UUIDs have to be of type <code>String</code>.

[[File:Entity-27.png|center|frame|''Figure 27: By using the <code>uuid</code> keyword, entities are created with a reliably unique identifier.'']]

</blockquote>

===version===
<blockquote>
<code>version</code> defines a version-property (used by the JPA-Compiler).

[[File:Entity-28.png|center|frame|''Figure 28: A <code>version</code> property can be added to entities and beans.'']]

</blockquote>

===transient===
<blockquote>
<code>transient</code> marks the property as transient. Instead of a <code>@Column</code>, a <code>@Transient</code> annotation is generated, so that the property is not persisted in the database.

[[File:Entity-29.png|center|frame|''Figure 29: The <code>transient</code> keyword enables the exclusion of properties from persistence.'']]

</blockquote>

==References==

The Entity DSL tracks relationships between entities by using the concept of "references". References can exist between objects of the same nature (entities to entities, beans to beans). Where appropriate, back references ("opposite") are added.
References are defined by the <code>ref</code> keyword, a target, an optional type and a name. The exact type of the reference can be specified with the following modifiers:

===Multiplicity and nullability===
<blockquote>
The Entity DSL supports the specification of multiplicities in square brackets appended to the type:
* <code>[1]</code> defines a non-nullable, one-to-one relationship.
* <code>[0..1]</code> defines a nullable, one-to-one relationship (this is the default behavior).
* <code>[1..*]</code> defines a non-nullable, one-to-many relationship. An <code>opposite</code> reference is needed.
* <code>[0..*]</code> or simply <code>[*]</code> defines a nullable, one-to-many relationship. An <code>opposite</code> reference is needed.

[[File:Entity-30.png|center|frame|''Figure 30: Adding multiplicity "[1]" causes the annotations for non-nullable database entries to be set.'']]

</blockquote>

===opposite reference===
<blockquote>
Lifecycle references need the specification of an opposite reference. This can be done with the <code>opposite</code> keyword.

Using the <code>opposite</code> reference, it is possible to navigate back to the original object after following the reference.

</blockquote>

===cascade===
<blockquote>
The <code>cascade</code> specifier controls the behavior of the database on delete operations. If an object with a <code>cascade</code> reference to other objects is deleted, those other objects will be removed as well.

[[File:Entity-31.png|center|frame|''Figure 31: By using the <code>cascade</code> and <code>opposite</code> keywords, bidirectional associations can be achieved.'']]

</blockquote>

==Operations==

Operations are other important features. They are based on Xbase and offer a huge set of semantic features, extending the featureset of Java. Xbase additionally offers features such as closures.
Operations can be declared by the <code>def</code> keyword followed by braces containing the inline operation.

[[File:Entity-32.png|center|frame|''Figure 32: The <code>def</code> keyword allows the inlining of custom methods in the Entity DSL code.'']]

These methods are translated into the appropriate Java methods along with the automatically generated getter and setter methods.

==Annotations==

Annotations can be added to all elements except import declarations. Specifying annotations in the Entity DSL works in a straightforward manner; content assist is available. The added annotations are taken over into the generated Java code.

[[File:Entity-33.png|center|frame|''Figure 33: Annotating elements in the Compex Entity DSL causes an annotation to be inserted into the generated Java code.'']]

These methods are translated into the appropriate Java methods along with the automatically generated getter and setter methods.

==Comments==

Comments can be added anywhere in an .entitymodel text file and are copied over into the generated Java code. Comments are enclosed in <code>/* ... */</code>.

[[File:Entity-34.png|center|frame|''Figure 34: The comments added in the Entity DSL are transformed to Java-style comments in the generated code.'']]

Comments before the <code>package</code> keyword are copied over to all generated Java classes – this is the place for copyright notices.

[[File:Entity-35.png|center|frame|''Figure 35: A comment before the package keyword ends up in all generated Java classes.'']]

==Reserved Keywords==

The keywords of the Entity DSL are syntactic features and can therefore not be used as semantic identifiers.

In order to circumvent this, it is possible to escape them with the <code>^</code> character. During the generation of the Java code, this escape character is removed.

[[File:Entity-36.png|center|frame|''Figure 36: Using the escape character '^', it is possible to achieve an identifier in the generated Java code with a name that would be a reserved word in the Entity DSL. In this case, a variable named <code>uuid</code> is generated that cannot be specified in the entity model file.'']]

Please note that you are also '''not allowed to use identifiers corresponding to reserved keywords''' of the supported databases you can find here below:

[https://db.apache.org/derby/docs/10.2/ref/rrefkeywords29722.html Derby]

[http://www.h2database.com/html/advanced.html?highlight=reserved&search=reser#firstFound H2]

[https://docs.microsoft.com/en-us/sql/odbc/reference/appendixes/reserved-keywords?view=sql-server-2017 MS SQL]

[https://docs.oracle.com/database/121/SQLRF/ap_keywd001.htm#SQLRF55621 Oracle]

[https://dev.mysql.com/doc/refman/8.0/en/keywords.html MySQL]

[https://www.postgresql.org/docs/8.2/sql-keywords-appendix.html PostgreSQL]

== Copyright Notice ==
{{Copyright Notice}}

Entity DSL

2019-02-06T10:44:25Z

Worayeno: /* Reserved Keywords */

== Purpose ==

The Entity DSL facilitates the handling of persistence entities. Defining entities using the Entity DSL efficiently creates a clean entity model that contains all relevant semantic elements of the model text file.
This semantic model is used to automatically transform the semantic information into proper Java code with the respective annotations for a persistence provider. Additionally, if the entity model is located within a project with OSBP nature, "Auto-DTOs" and services are generated as well. In this case, attributes that are added to entities will automatically be transferred to the "Auto-DTOs".

== Overview ==

The main semantic elements of the Compex Entity DSL are the following:

* "Package" - the root element that contains all the other elements. A model can contain multiple packages.

* "Import" declarations - used to import external models or even Java classes.

* "Datatype" declarations - a way to define datatypes that can be used in entities and beans.

* "Entity" - the abstraction of a business model entity. It contains further elements such as properties and references.

* "Bean" - does not compile to a JPA Entity but to a Java Bean (POJO with getter and setter and PropertyChange-Support). Beans may be used as temporary containers in entity operations or can be embedded into JPA Entities.

* "Enum" - the abstraction for Java enums.

* "Property" - a reference to an embedded Bean, an Enum, a Java class or a simple datatype (as defined in the datatype declaration). Offers multiplicity.

* "Reference" - a reference to another Entity (or to another Bean in the case of a Bean). Offers multiplicity.

* "Operations" - similar to Java methods. The Xbase expression language can be used to write high-level code.

* "Annotations" can be placed on Entity, Property and Reference.

* "Comments" can be added to all elements.

== Entity model files ==

Entity models are described in .entitymodel files. These files describe the entity model and are the basis for the code generation. Entity models may be split over several .entitymodel files containing packages in the same namespace.
An .entitymodel file may contain several packages with entities. However, from a performance point of view, a complex entity model may work better with more and smaller .entitymodel files than the same model crammed into a few large files (or even a single file).

===package===
Entity model files must start with a package declaration. Packages are the root element of the Entity DSL grammar. Everything is contained in a package: Imports, Entities, Beans and Enums have to be defined inside the Package definition. One document can contain multiple packages with unique names.
The elements a package can contain are Entities, Beans and Enums. Additionally, a package allows Import statements and the declaration of datatypes.

<syntaxhighlight lang="java">
package name {
import importStatement;
datatype datatypeDefinition;
entities/beans/enums
}
</syntaxhighlight>

[[File:entity-1.png|center|frame|''Figure 1 - Entity model file - a package is the topmost element and contains other items.'']]

Marking a DTO as abstract (before the dto keyword) generates an abstract Java class for it.

The following modifiers may be placed after the dto keyword and the DTO name:

=== import ===
The Entity DSL allows the referencing of entities defined in different packages, even in different .entitymodel files. The import statement is a way to make these elements available in the current namespace without having to address them by their fully qualified name.

Import statements allow the use of the '*' wildcard.

<syntaxhighlight lang="java">
import importStatement;
</syntaxhighlight>

[[File:entity-2.png|center|frame|''Figure 2: Items contained in another package can be addressed if the package is imported using the import keyword and its fully qualified name.'']]

=== datatype ===
The Entity DSL allows the definition of datatypes. These are translated by the inferrer into their standard Java representation. The behavior of the generator can be controlled by the datatype definitions.
Datatypes defined in an .entitymodel file are local to that file. In order to define datatypes in one place and have them available in multiple .entitymodel files, the datatypes may be defined in a ".datatypes" file containing only datatype definitions inside a package statement.
There are three types of datatype definitions:

* '''jvmTypes''': Datatype definitons that map types to '''jvmTypes''' take the basic syntax of 
<blockquote><code>datatype <name> jvmType <type> as primitive;</code>.</blockquote>
<blockquote>Specifying datatypes in this manner uses an appropriate wrapper class in the generated Java code; adding the keywords <code>as primitive</code> enforces the use of primitive datatypes where applicable:
<code>datatype foo jvmType Integer;</code> compiles to an <code>Integer</code> whereas <code>datatype foo jvmType Integer as primitive;</code> results in <code>int</code>.

[[File:entity-3.png|center|frame|''Figure 3: The defined datatype is translated to a wrapper class.'']]

[[File:Entity-4.png|center|frame|''Figure 4: By adding the <code>as primitive</code> keywords, the datatype is translated to a primitive datatype.'']]

</blockquote>
* '''dateTypes''': The datatypes for handling temporal information can be defined by the following statement:
<blockquote><code>datatype <name> datetype date—time—timestamp; </code>
Datatypes that have been defined in this manner can be used as property variables in entities and beans.

[[File:Entity-5.png|center|frame|''Figure 5: Defining datatypes for handling temporal information. Content assist is available.'']]

</blockquote>
* '''blobs''': Binary blobs can be handled by defining a datatype with the <code>as blob</code> keywords. The Java implementation of such a blob is a byte array. Appropriate persistence annotations are automatically added.
<blockquote>
<code>datatype <name> as blob;</code>

[[File:Entity-6.png|center|frame|''Figure 6: Including binary blobs by using a datatype with the <code>as blob</code> keywords.'']]
</blockquote>

 After import statements and datatype definitions, the content of the .entitymodel file is made up of <code>entity</code>, <code>bean</code> and <code>enum</code> definitions.

== Entities ==
Entities are the most complex elements in the Entity DSL. An entity is an abstraction above a business object. Entities are defined by their name, properties, references and operations. Generally, an entity is an object which can keep the state of variables and references as well as be persisted.
For each entity that is defined in a package, a Java class and the corresponding persistence structure is automatically generated. Inside a project with Compex nature, "Auto-DTOs" and services are created as well.

Entities may extend other entities. In this case, they are derived from their parent entity. That means that the properties and references of the parent entity are inherited.

Syntax:
<syntaxhighlight lang="java">
[modifiers] entity <name> extends <parentEntity> {
[entityProperties]
}
</syntaxhighlight>

[[File:Entity-7.png|center|frame|''Figure 7: Items contained in another package can be addressed if the package is imported using the <code>import</code> keyword and its fully qualified name'']]

Entities may be defined with certain modifiers that change the generated Java Code. The following modifiers are supported:

=== abstract ===

<blockquote>
<code>abstract</code> marks the entity as "abstract". This generates an abstract Java class.

[[File:Entity-8.png|center|frame|''Figure 8: The <code>abstract</code> keyword causes the translation into an abstract Java class'']]

</blockquote>

=== historized ===
<blockquote>
<code>historized</code> marks the entity as "historized". Historized entities can have several entries in a database, but only one of them may be marked as current.

The <code>historized</code> keyword adds an object ID, a version field and a flag for the current version to the entity.

[[File:Entity-9.png|center|frame|''Figure 9: The <code>historized</code> modifier triggers the creation of an object ID, an object version and a flag for marking the current version.'']]

</blockquote>

=== cacheable ===
<blockquote>
<code>cacheable</code> marks the entity as "cacheable". The appropriate annotation for the persistence provider is added to the generated Java code.

[[File:Entity-10.png|center|frame|''Figure 10: Declaring an entity to be <code>cacheable</code> adds the <code>@Cacheable</code> annotation'']]
</blockquote>

=== timedependent ===
<blockquote>
<code>timedependent</code> marks the entity as "time-dependent". An object may have several entries in the database. Which entry is valid will be determined by '''valid from''' and '''valid until''' fields that are added to the entity.
An object ID is created in order to tie the entries together. The <code>timedependent</code> keyword recognizes the modifiers <code>(DATE)</code> and <code>(TIMESTAMP)</code>. Default is <code>timedependent(DATE)</code>.

[[File:Entity-11.png|center|frame|''Figure 11: The <code>timedependent</code> keyword causes an object ID, a validFrom and a validUntil field to be created in order to support multiple database entries for an object.'']]
</blockquote>

=== mapped superclass ===
<blockquote>
<code>mapped superclass</code> marks a class that provides persistent entity state and mapping information for its subclasses, but which is not an entity itself.

Typically, the purpose of a mapped superclass is to define state and mapping information that is common to multiple entities. All the mappings from the mapped superclass are inherited by its subclasses, as if they had been defined there directly.

[[File:Entity-12.png|center|frame|''Figure 12: The <code>mapped superclass</code> keyword sets the appropriate annotation which causes the persistence provider to move the mappings to the derived subclasses.'']]
</blockquote>

===extends===
<blockquote>
The modifier <code>extends</code> may be placed after the entity keyword and the entity name, as <code>entity foo extends bar {</code>, where <code>bar</code> has already been defined as an entity.

<code>extends</code> marks an entity that is derived from another entity. That means that the properties and references of the parent entity are inherited.
</blockquote>

==Entity Persistence Settings==

Apart from the mapped superclass modifier that moves all property columns to the tables belonging to derived classes, the following settings for table inheritance can be specified within an entity definition:
* inheritance per class
* inheritance per subclass

The structure of the database created from an entity model can be controlled by the following settings:
* schemaName
* tableName
* discriminatorColumn
* discriminatorType
* discriminatorValue

===inheritance per class===
<blockquote>
<code>inheritance per class{}</code> causes a table to be created for each class; subclasses share this table using a discriminator value. This statement has to be followed by braces, inside of which further details can be specified.

[[File:Entity-13.png|center|frame|''Figure 13: A single table for entity Base is created; the generated Java code for the “Derived” class shows that the “Derived” entity is added to this table by using a discriminator.'']]
</blockquote>

===inheritance per subclass===
<blockquote>
<code>inheritance per subclass{}</code> causes a table to be created for each subclass. This statement has to be followed by braces, inside of which further details can be specified. This is the default behaviour if no inheritance strategy is specified.

[[File:Entity-14.png|center|frame|''Figure 14: An <code>@Table</code> annotation is added to the generated Java code, so that the "Derived" entity is mapped to a table of its own.'']]
</blockquote>

===schemaName===
<blockquote>
<code>schemaName</code> allows the specification of a name for the database schema to be used. This setting is translated to the appropriate JPA annotation <code>@Table(schema = <xyz>)</code>. The schema name given is converted to snake case using capitals.
</blockquote>

===tableName===
<blockquote>
<code>tableName</code> allows the specification of a name for the table (within the database schema) to which the entity is mapped. This setting is translated to the appropriate JPA annotation
<code>@Table(name = <xyz>)</code>.

The table name specified is converted to snake case using capitals. The default value is the name of the entity.

[[File:Entity-15.png|center|frame|''Figure 15: Specifying the <code>schemaName</code> and <code>tableName</code> settings in an entity determines the name of the database schema and tables used for persistence.'']]
</blockquote>

===discriminatorColumn===
<blockquote>
<code>discriminatorColumn</code> optionally allows the specification of a name for the discriminator column in the case of <code>inheritance per class</code>. It appears within the braces after the inheritance-strategy statement and must be followed by a semicolon. It defaults to <code>DISC</code>.
</blockquote>

===discriminatorType===

<blockquote>
<code>discriminatorType</code> optionally allows the definition of the datatype of the discriminator within the single table. It can be set to <code>CHAR</code>, <code>INT</code>, <code>STRING</code> or <code>INHERIT</code>. It appears within the braces after the <code>inheritance</code> statement and must be followed by a semicolon. It defaults to <code>STRING;</code>.
</blockquote>

===discriminatorValue===

<blockquote>
<code>discriminatorValue</code> allows a custom value to be used for the discriminator within the single table. It appears within the braces after the <code>inheritance</code> statement and must be followed by a semicolon. It defaults to the entity name converted to snake case.

[[File:Entity-16.png|center|frame|''Figure 16: The <code>inheritance</code> statement allows the optional specification of discriminator column, type and value to be used in the case of a single table.'']]
</blockquote>

==Beans==

'''Beans''' are objects that are embedded in other entities, inheriting their persistence and lifecycle. Similar to entities, beans are characterised by their name, their properties and their references. For each bean that is defined in a package, a Java class is automatically generated.

Beans can be embedded into entities by defining them as properties of the respective entity. The appropriate annotations (<code>@Embeddable</code>, <code>@Embedded</code>, <code>@AttributeOverrides</code> etc.) are added in order to have beans persisted with their parent entities.

[[File:Entity-17.png|center|frame|''Figure 17: Beans can be embedded in entities and are persisted with them.'']]

==Enums==

'''Enums''' are an abstraction of the Java <code>enum</code>. They compile to <code>enum</code> classes and can be used as properties in entities and beans.

[[File:Entity-18.png|center|frame|''Figure 18: Defining <code>enums</code> allows using them as variables in entities and beans.'']]

==Properties==
Properties of entities and beans are references to datatypes or enums. They can be regarded as variables and are defined by a keyword followed by a datatype (Java type or datatype defined in the <code>datatype</code> section) and a name. By defining a bean as a property of an entity, it is embedded in it.

Properties can be determined with the following keywords:

===var===
<blockquote>
The basic property <code>var</code> defines a variable that is persisted in a table column. A property must have a type and a name.

'''Multiplicity''' of properties can be controlled by the following (optional) settings:

* <code>[1]</code> defines a non-nullable property.
* <code>[0..1]</code> defines a nullable property (this is the default behavior).
* <code>[1..*]</code> defines a list of properties that must not be empty.
* <code>[0..*]</code> or simply <code>[*]</code> defines a list of properties that may be empty.

[[File:Entity-19.png|center|frame|''Figure 19: Variables can be defined using the <code>var</code> keyword.'']]

The appropriate persistence settings are generated automatically. If a multiplicity is specified, the appropriate annotations (and, if necessary, a list rather than a single variable) are generated.
</blockquote>

===derived===
<blockquote>
<code>derived</code> defines a property that is derived from other properties. The derived property must be have a type, a name and the calculation logic that derives it from the other properties, written as an Xexpression in braces.

[[File:Entity-20.png|center|frame|''Figure 20: Properties may be derived from other properties using an Xexpression.'']]

The code is automatically translated to valid Java code.
</blockquote>

===dirty===
<blockquote>
<code>dirty</code> defines a property used as a flag to track the "dirty" state of the buffered data when editing values, before the changes have been written back to the persistence entity. Only one <code>dirty</code> flag is allowed per entity. The datatype has to be boolean.

[[File:Entity-21.png|center|frame|''Figure 21: The <code>dirty</code> property is used to flag whether changes have been made to the bufered data, but not yet written back to the persistence entity. '']]

The boolean field for this property and the appropriate annotation are generated with the <code>dirty</code> keyword.
</blockquote>

===domainDescription===
<blockquote>
<code>domainDescription</code> defines a property that is used as a domain description. The appropriate annotation is added to the property. A domain description must be of type <code>String</code>. Domain descriptions may be derived from other properties.

[[File:Entity-22.png|center|frame|''Figure 22: Domain description properties can be created with the <code>domainDescription</code> keyword.'']]
</blockquote>

===domainKey===
<blockquote>
<code>domainKey</code> defines a domain key. The appropriate annotation is added to the property. Primitive datatypes may be used as domain keys.

[[File:Entity-23.png|center|frame|''Figure 23: A field containing a domain key is created with the <code>domainKey keyword</code>.'']]
</blockquote>

===id===
<blockquote>
{{Deprecated}}

'''id''' defines an ID property (used as a primary key by the JPA compiler). '''This keyword is deprecated - use uuid instead'''. If no <code>id</code> is specified, a warning is given.

'''Caution''': ID autogeneration causes problems, since the value is not set before the entity is persisted, e.g., in the database. It is therefore advised to use the <code>uuid</code> keyword instead.

[[File:Entity-24.png|center|frame|''Figure 24: Entities are supposed to have an ID property that is used as a primary key to the underlying database.'']]

'''Caution''': The generated IDs are not necessarily unique if the deprecated <code>id</code> keyword is used!
</blockquote>

===index===
<blockquote>
The <code>index</code> keyword causes an index for the table to be generated. Indexes may be based on one or more properties (primitive only) and references (one-to-one only) of the entity. An index must be given a name and, in braces, a list of the fields it is based upon. If the <code>index</code> keyword is prefixed with <code>unique</code>, a unique index is created.

[[File:Entity-25.png|center|frame|''Figure 25: Database table indexes that map entities are generated with the <code>index</code> keyword.'']]

The <code>@Table</code> annotation is supplemented with the index definition.

</blockquote>

===properties===
<blockquote>
Features (properties and references) of entities and beans can optionally be given additional information in the form of key-value pairs. This information can then be retrieved from the semantic model. The key-value pairs are defined in parentheses after the properties keyword following the feature name. Multiple pairs can be defined (comma-separated).

[[File:Entity-26.png|center|frame|''Figure 26: Additional information about features can be defined by key-value pairs. This information is then stored in the semantic model and is retrievable.'']]

</blockquote>

===uuid===
<blockquote>
<code>uuid</code> allows the use of Universally Unique IDs as primary keys. A new UUID value is generated for each object as soon as that object has been created, independently of database operations. This circumvents the problems with the <code>id</code> keyword. UUIDs have to be of type <code>String</code>.

[[File:Entity-27.png|center|frame|''Figure 27: By using the <code>uuid</code> keyword, entities are created with a reliably unique identifier.'']]

</blockquote>

===version===
<blockquote>
<code>version</code> defines a version-property (used by the JPA-Compiler).

[[File:Entity-28.png|center|frame|''Figure 28: A <code>version</code> property can be added to entities and beans.'']]

</blockquote>

===transient===
<blockquote>
<code>transient</code> marks the property as transient. Instead of a <code>@Column</code>, a <code>@Transient</code> annotation is generated, so that the property is not persisted in the database.

[[File:Entity-29.png|center|frame|''Figure 29: The <code>transient</code> keyword enables the exclusion of properties from persistence.'']]

</blockquote>

==References==

The Entity DSL tracks relationships between entities by using the concept of "references". References can exist between objects of the same nature (entities to entities, beans to beans). Where appropriate, back references ("opposite") are added.
References are defined by the <code>ref</code> keyword, a target, an optional type and a name. The exact type of the reference can be specified with the following modifiers:

===Multiplicity and nullability===
<blockquote>
The Entity DSL supports the specification of multiplicities in square brackets appended to the type:
* <code>[1]</code> defines a non-nullable, one-to-one relationship.
* <code>[0..1]</code> defines a nullable, one-to-one relationship (this is the default behavior).
* <code>[1..*]</code> defines a non-nullable, one-to-many relationship. An <code>opposite</code> reference is needed.
* <code>[0..*]</code> or simply <code>[*]</code> defines a nullable, one-to-many relationship. An <code>opposite</code> reference is needed.

[[File:Entity-30.png|center|frame|''Figure 30: Adding multiplicity "[1]" causes the annotations for non-nullable database entries to be set.'']]

</blockquote>

===opposite reference===
<blockquote>
Lifecycle references need the specification of an opposite reference. This can be done with the <code>opposite</code> keyword.

Using the <code>opposite</code> reference, it is possible to navigate back to the original object after following the reference.

</blockquote>

===cascade===
<blockquote>
The <code>cascade</code> specifier controls the behavior of the database on delete operations. If an object with a <code>cascade</code> reference to other objects is deleted, those other objects will be removed as well.

[[File:Entity-31.png|center|frame|''Figure 31: By using the <code>cascade</code> and <code>opposite</code> keywords, bidirectional associations can be achieved.'']]

</blockquote>

==Operations==

Operations are other important features. They are based on Xbase and offer a huge set of semantic features, extending the featureset of Java. Xbase additionally offers features such as closures.
Operations can be declared by the <code>def</code> keyword followed by braces containing the inline operation.

[[File:Entity-32.png|center|frame|''Figure 32: The <code>def</code> keyword allows the inlining of custom methods in the Entity DSL code.'']]

These methods are translated into the appropriate Java methods along with the automatically generated getter and setter methods.

==Annotations==

Annotations can be added to all elements except import declarations. Specifying annotations in the Entity DSL works in a straightforward manner; content assist is available. The added annotations are taken over into the generated Java code.

[[File:Entity-33.png|center|frame|''Figure 33: Annotating elements in the Compex Entity DSL causes an annotation to be inserted into the generated Java code.'']]

These methods are translated into the appropriate Java methods along with the automatically generated getter and setter methods.

==Comments==

Comments can be added anywhere in an .entitymodel text file and are copied over into the generated Java code. Comments are enclosed in <code>/* ... */</code>.

[[File:Entity-34.png|center|frame|''Figure 34: The comments added in the Entity DSL are transformed to Java-style comments in the generated code.'']]

Comments before the <code>package</code> keyword are copied over to all generated Java classes – this is the place for copyright notices.

[[File:Entity-35.png|center|frame|''Figure 35: A comment before the package keyword ends up in all generated Java classes.'']]

==Reserved Keywords==

The keywords of the Entity DSL are syntactic features and can therefore not be used as semantic identifiers.

In order to circumvent this, it is possible to escape them with the <code>^</code> character. During the generation of the Java code, this escape character is removed.

[[File:Entity-36.png|center|frame|''Figure 36: Using the escape character '^', it is possible to achieve an identifier in the generated Java code with a name that would be a reserved word in the Entity DSL. In this case, a variable named <code>uuid</code> is generated that cannot be specified in the entity model file.'']]

Please note that you are also '''not allowed to use identifiers corresponding to reserved keywords''' of the supported databases you can find here below:

[https://db.apache.org/derby/docs/10.2/ref/rrefkeywords29722.html Derby]

[http://www.h2database.com/html/advanced.html?highlight=reserved&search=reser#firstFound H2]

[https://docs.microsoft.com/en-us/sql/odbc/reference/appendixes/reserved-keywords?view=sql-server-2017 MS SQL]

[https://dev.mysql.com/doc/refman/8.0/en/keywords.html MySQL]

[https://docs.oracle.com/database/121/SQLRF/ap_keywd001.htm#SQLRF55621 Oracle]

[https://www.postgresql.org/docs/8.2/sql-keywords-appendix.html PostgreSQL]

== Copyright Notice ==
{{Copyright Notice}}

Entity DSL

2019-02-06T10:42:55Z

Worayeno: /* Reserved Keywords */

== Purpose ==

The Entity DSL facilitates the handling of persistence entities. Defining entities using the Entity DSL efficiently creates a clean entity model that contains all relevant semantic elements of the model text file.
This semantic model is used to automatically transform the semantic information into proper Java code with the respective annotations for a persistence provider. Additionally, if the entity model is located within a project with OSBP nature, "Auto-DTOs" and services are generated as well. In this case, attributes that are added to entities will automatically be transferred to the "Auto-DTOs".

== Overview ==

The main semantic elements of the Compex Entity DSL are the following:

* "Package" - the root element that contains all the other elements. A model can contain multiple packages.

* "Import" declarations - used to import external models or even Java classes.

* "Datatype" declarations - a way to define datatypes that can be used in entities and beans.

* "Entity" - the abstraction of a business model entity. It contains further elements such as properties and references.

* "Bean" - does not compile to a JPA Entity but to a Java Bean (POJO with getter and setter and PropertyChange-Support). Beans may be used as temporary containers in entity operations or can be embedded into JPA Entities.

* "Enum" - the abstraction for Java enums.

* "Property" - a reference to an embedded Bean, an Enum, a Java class or a simple datatype (as defined in the datatype declaration). Offers multiplicity.

* "Reference" - a reference to another Entity (or to another Bean in the case of a Bean). Offers multiplicity.

* "Operations" - similar to Java methods. The Xbase expression language can be used to write high-level code.

* "Annotations" can be placed on Entity, Property and Reference.

* "Comments" can be added to all elements.

== Entity model files ==

Entity models are described in .entitymodel files. These files describe the entity model and are the basis for the code generation. Entity models may be split over several .entitymodel files containing packages in the same namespace.
An .entitymodel file may contain several packages with entities. However, from a performance point of view, a complex entity model may work better with more and smaller .entitymodel files than the same model crammed into a few large files (or even a single file).

===package===
Entity model files must start with a package declaration. Packages are the root element of the Entity DSL grammar. Everything is contained in a package: Imports, Entities, Beans and Enums have to be defined inside the Package definition. One document can contain multiple packages with unique names.
The elements a package can contain are Entities, Beans and Enums. Additionally, a package allows Import statements and the declaration of datatypes.

<syntaxhighlight lang="java">
package name {
import importStatement;
datatype datatypeDefinition;
entities/beans/enums
}
</syntaxhighlight>

[[File:entity-1.png|center|frame|''Figure 1 - Entity model file - a package is the topmost element and contains other items.'']]

Marking a DTO as abstract (before the dto keyword) generates an abstract Java class for it.

The following modifiers may be placed after the dto keyword and the DTO name:

=== import ===
The Entity DSL allows the referencing of entities defined in different packages, even in different .entitymodel files. The import statement is a way to make these elements available in the current namespace without having to address them by their fully qualified name.

Import statements allow the use of the '*' wildcard.

<syntaxhighlight lang="java">
import importStatement;
</syntaxhighlight>

[[File:entity-2.png|center|frame|''Figure 2: Items contained in another package can be addressed if the package is imported using the import keyword and its fully qualified name.'']]

=== datatype ===
The Entity DSL allows the definition of datatypes. These are translated by the inferrer into their standard Java representation. The behavior of the generator can be controlled by the datatype definitions.
Datatypes defined in an .entitymodel file are local to that file. In order to define datatypes in one place and have them available in multiple .entitymodel files, the datatypes may be defined in a ".datatypes" file containing only datatype definitions inside a package statement.
There are three types of datatype definitions:

* '''jvmTypes''': Datatype definitons that map types to '''jvmTypes''' take the basic syntax of 
<blockquote><code>datatype <name> jvmType <type> as primitive;</code>.</blockquote>
<blockquote>Specifying datatypes in this manner uses an appropriate wrapper class in the generated Java code; adding the keywords <code>as primitive</code> enforces the use of primitive datatypes where applicable:
<code>datatype foo jvmType Integer;</code> compiles to an <code>Integer</code> whereas <code>datatype foo jvmType Integer as primitive;</code> results in <code>int</code>.

[[File:entity-3.png|center|frame|''Figure 3: The defined datatype is translated to a wrapper class.'']]

[[File:Entity-4.png|center|frame|''Figure 4: By adding the <code>as primitive</code> keywords, the datatype is translated to a primitive datatype.'']]

</blockquote>
* '''dateTypes''': The datatypes for handling temporal information can be defined by the following statement:
<blockquote><code>datatype <name> datetype date—time—timestamp; </code>
Datatypes that have been defined in this manner can be used as property variables in entities and beans.

[[File:Entity-5.png|center|frame|''Figure 5: Defining datatypes for handling temporal information. Content assist is available.'']]

</blockquote>
* '''blobs''': Binary blobs can be handled by defining a datatype with the <code>as blob</code> keywords. The Java implementation of such a blob is a byte array. Appropriate persistence annotations are automatically added.
<blockquote>
<code>datatype <name> as blob;</code>

[[File:Entity-6.png|center|frame|''Figure 6: Including binary blobs by using a datatype with the <code>as blob</code> keywords.'']]
</blockquote>

 After import statements and datatype definitions, the content of the .entitymodel file is made up of <code>entity</code>, <code>bean</code> and <code>enum</code> definitions.

== Entities ==
Entities are the most complex elements in the Entity DSL. An entity is an abstraction above a business object. Entities are defined by their name, properties, references and operations. Generally, an entity is an object which can keep the state of variables and references as well as be persisted.
For each entity that is defined in a package, a Java class and the corresponding persistence structure is automatically generated. Inside a project with Compex nature, "Auto-DTOs" and services are created as well.

Entities may extend other entities. In this case, they are derived from their parent entity. That means that the properties and references of the parent entity are inherited.

Syntax:
<syntaxhighlight lang="java">
[modifiers] entity <name> extends <parentEntity> {
[entityProperties]
}
</syntaxhighlight>

[[File:Entity-7.png|center|frame|''Figure 7: Items contained in another package can be addressed if the package is imported using the <code>import</code> keyword and its fully qualified name'']]

Entities may be defined with certain modifiers that change the generated Java Code. The following modifiers are supported:

=== abstract ===

<blockquote>
<code>abstract</code> marks the entity as "abstract". This generates an abstract Java class.

[[File:Entity-8.png|center|frame|''Figure 8: The <code>abstract</code> keyword causes the translation into an abstract Java class'']]

</blockquote>

=== historized ===
<blockquote>
<code>historized</code> marks the entity as "historized". Historized entities can have several entries in a database, but only one of them may be marked as current.

The <code>historized</code> keyword adds an object ID, a version field and a flag for the current version to the entity.

[[File:Entity-9.png|center|frame|''Figure 9: The <code>historized</code> modifier triggers the creation of an object ID, an object version and a flag for marking the current version.'']]

</blockquote>

=== cacheable ===
<blockquote>
<code>cacheable</code> marks the entity as "cacheable". The appropriate annotation for the persistence provider is added to the generated Java code.

[[File:Entity-10.png|center|frame|''Figure 10: Declaring an entity to be <code>cacheable</code> adds the <code>@Cacheable</code> annotation'']]
</blockquote>

=== timedependent ===
<blockquote>
<code>timedependent</code> marks the entity as "time-dependent". An object may have several entries in the database. Which entry is valid will be determined by '''valid from''' and '''valid until''' fields that are added to the entity.
An object ID is created in order to tie the entries together. The <code>timedependent</code> keyword recognizes the modifiers <code>(DATE)</code> and <code>(TIMESTAMP)</code>. Default is <code>timedependent(DATE)</code>.

[[File:Entity-11.png|center|frame|''Figure 11: The <code>timedependent</code> keyword causes an object ID, a validFrom and a validUntil field to be created in order to support multiple database entries for an object.'']]
</blockquote>

=== mapped superclass ===
<blockquote>
<code>mapped superclass</code> marks a class that provides persistent entity state and mapping information for its subclasses, but which is not an entity itself.

Typically, the purpose of a mapped superclass is to define state and mapping information that is common to multiple entities. All the mappings from the mapped superclass are inherited by its subclasses, as if they had been defined there directly.

[[File:Entity-12.png|center|frame|''Figure 12: The <code>mapped superclass</code> keyword sets the appropriate annotation which causes the persistence provider to move the mappings to the derived subclasses.'']]
</blockquote>

===extends===
<blockquote>
The modifier <code>extends</code> may be placed after the entity keyword and the entity name, as <code>entity foo extends bar {</code>, where <code>bar</code> has already been defined as an entity.

<code>extends</code> marks an entity that is derived from another entity. That means that the properties and references of the parent entity are inherited.
</blockquote>

==Entity Persistence Settings==

Apart from the mapped superclass modifier that moves all property columns to the tables belonging to derived classes, the following settings for table inheritance can be specified within an entity definition:
* inheritance per class
* inheritance per subclass

The structure of the database created from an entity model can be controlled by the following settings:
* schemaName
* tableName
* discriminatorColumn
* discriminatorType
* discriminatorValue

===inheritance per class===
<blockquote>
<code>inheritance per class{}</code> causes a table to be created for each class; subclasses share this table using a discriminator value. This statement has to be followed by braces, inside of which further details can be specified.

[[File:Entity-13.png|center|frame|''Figure 13: A single table for entity Base is created; the generated Java code for the “Derived” class shows that the “Derived” entity is added to this table by using a discriminator.'']]
</blockquote>

===inheritance per subclass===
<blockquote>
<code>inheritance per subclass{}</code> causes a table to be created for each subclass. This statement has to be followed by braces, inside of which further details can be specified. This is the default behaviour if no inheritance strategy is specified.

[[File:Entity-14.png|center|frame|''Figure 14: An <code>@Table</code> annotation is added to the generated Java code, so that the "Derived" entity is mapped to a table of its own.'']]
</blockquote>

===schemaName===
<blockquote>
<code>schemaName</code> allows the specification of a name for the database schema to be used. This setting is translated to the appropriate JPA annotation <code>@Table(schema = <xyz>)</code>. The schema name given is converted to snake case using capitals.
</blockquote>

===tableName===
<blockquote>
<code>tableName</code> allows the specification of a name for the table (within the database schema) to which the entity is mapped. This setting is translated to the appropriate JPA annotation
<code>@Table(name = <xyz>)</code>.

The table name specified is converted to snake case using capitals. The default value is the name of the entity.

[[File:Entity-15.png|center|frame|''Figure 15: Specifying the <code>schemaName</code> and <code>tableName</code> settings in an entity determines the name of the database schema and tables used for persistence.'']]
</blockquote>

===discriminatorColumn===
<blockquote>
<code>discriminatorColumn</code> optionally allows the specification of a name for the discriminator column in the case of <code>inheritance per class</code>. It appears within the braces after the inheritance-strategy statement and must be followed by a semicolon. It defaults to <code>DISC</code>.
</blockquote>

===discriminatorType===

<blockquote>
<code>discriminatorType</code> optionally allows the definition of the datatype of the discriminator within the single table. It can be set to <code>CHAR</code>, <code>INT</code>, <code>STRING</code> or <code>INHERIT</code>. It appears within the braces after the <code>inheritance</code> statement and must be followed by a semicolon. It defaults to <code>STRING;</code>.
</blockquote>

===discriminatorValue===

<blockquote>
<code>discriminatorValue</code> allows a custom value to be used for the discriminator within the single table. It appears within the braces after the <code>inheritance</code> statement and must be followed by a semicolon. It defaults to the entity name converted to snake case.

[[File:Entity-16.png|center|frame|''Figure 16: The <code>inheritance</code> statement allows the optional specification of discriminator column, type and value to be used in the case of a single table.'']]
</blockquote>

==Beans==

'''Beans''' are objects that are embedded in other entities, inheriting their persistence and lifecycle. Similar to entities, beans are characterised by their name, their properties and their references. For each bean that is defined in a package, a Java class is automatically generated.

Beans can be embedded into entities by defining them as properties of the respective entity. The appropriate annotations (<code>@Embeddable</code>, <code>@Embedded</code>, <code>@AttributeOverrides</code> etc.) are added in order to have beans persisted with their parent entities.

[[File:Entity-17.png|center|frame|''Figure 17: Beans can be embedded in entities and are persisted with them.'']]

==Enums==

'''Enums''' are an abstraction of the Java <code>enum</code>. They compile to <code>enum</code> classes and can be used as properties in entities and beans.

[[File:Entity-18.png|center|frame|''Figure 18: Defining <code>enums</code> allows using them as variables in entities and beans.'']]

==Properties==
Properties of entities and beans are references to datatypes or enums. They can be regarded as variables and are defined by a keyword followed by a datatype (Java type or datatype defined in the <code>datatype</code> section) and a name. By defining a bean as a property of an entity, it is embedded in it.

Properties can be determined with the following keywords:

===var===
<blockquote>
The basic property <code>var</code> defines a variable that is persisted in a table column. A property must have a type and a name.

'''Multiplicity''' of properties can be controlled by the following (optional) settings:

* <code>[1]</code> defines a non-nullable property.
* <code>[0..1]</code> defines a nullable property (this is the default behavior).
* <code>[1..*]</code> defines a list of properties that must not be empty.
* <code>[0..*]</code> or simply <code>[*]</code> defines a list of properties that may be empty.

[[File:Entity-19.png|center|frame|''Figure 19: Variables can be defined using the <code>var</code> keyword.'']]

The appropriate persistence settings are generated automatically. If a multiplicity is specified, the appropriate annotations (and, if necessary, a list rather than a single variable) are generated.
</blockquote>

===derived===
<blockquote>
<code>derived</code> defines a property that is derived from other properties. The derived property must be have a type, a name and the calculation logic that derives it from the other properties, written as an Xexpression in braces.

[[File:Entity-20.png|center|frame|''Figure 20: Properties may be derived from other properties using an Xexpression.'']]

The code is automatically translated to valid Java code.
</blockquote>

===dirty===
<blockquote>
<code>dirty</code> defines a property used as a flag to track the "dirty" state of the buffered data when editing values, before the changes have been written back to the persistence entity. Only one <code>dirty</code> flag is allowed per entity. The datatype has to be boolean.

[[File:Entity-21.png|center|frame|''Figure 21: The <code>dirty</code> property is used to flag whether changes have been made to the bufered data, but not yet written back to the persistence entity. '']]

The boolean field for this property and the appropriate annotation are generated with the <code>dirty</code> keyword.
</blockquote>

===domainDescription===
<blockquote>
<code>domainDescription</code> defines a property that is used as a domain description. The appropriate annotation is added to the property. A domain description must be of type <code>String</code>. Domain descriptions may be derived from other properties.

[[File:Entity-22.png|center|frame|''Figure 22: Domain description properties can be created with the <code>domainDescription</code> keyword.'']]
</blockquote>

===domainKey===
<blockquote>
<code>domainKey</code> defines a domain key. The appropriate annotation is added to the property. Primitive datatypes may be used as domain keys.

[[File:Entity-23.png|center|frame|''Figure 23: A field containing a domain key is created with the <code>domainKey keyword</code>.'']]
</blockquote>

===id===
<blockquote>
{{Deprecated}}

'''id''' defines an ID property (used as a primary key by the JPA compiler). '''This keyword is deprecated - use uuid instead'''. If no <code>id</code> is specified, a warning is given.

'''Caution''': ID autogeneration causes problems, since the value is not set before the entity is persisted, e.g., in the database. It is therefore advised to use the <code>uuid</code> keyword instead.

[[File:Entity-24.png|center|frame|''Figure 24: Entities are supposed to have an ID property that is used as a primary key to the underlying database.'']]

'''Caution''': The generated IDs are not necessarily unique if the deprecated <code>id</code> keyword is used!
</blockquote>

===index===
<blockquote>
The <code>index</code> keyword causes an index for the table to be generated. Indexes may be based on one or more properties (primitive only) and references (one-to-one only) of the entity. An index must be given a name and, in braces, a list of the fields it is based upon. If the <code>index</code> keyword is prefixed with <code>unique</code>, a unique index is created.

[[File:Entity-25.png|center|frame|''Figure 25: Database table indexes that map entities are generated with the <code>index</code> keyword.'']]

The <code>@Table</code> annotation is supplemented with the index definition.

</blockquote>

===properties===
<blockquote>
Features (properties and references) of entities and beans can optionally be given additional information in the form of key-value pairs. This information can then be retrieved from the semantic model. The key-value pairs are defined in parentheses after the properties keyword following the feature name. Multiple pairs can be defined (comma-separated).

[[File:Entity-26.png|center|frame|''Figure 26: Additional information about features can be defined by key-value pairs. This information is then stored in the semantic model and is retrievable.'']]

</blockquote>

===uuid===
<blockquote>
<code>uuid</code> allows the use of Universally Unique IDs as primary keys. A new UUID value is generated for each object as soon as that object has been created, independently of database operations. This circumvents the problems with the <code>id</code> keyword. UUIDs have to be of type <code>String</code>.

[[File:Entity-27.png|center|frame|''Figure 27: By using the <code>uuid</code> keyword, entities are created with a reliably unique identifier.'']]

</blockquote>

===version===
<blockquote>
<code>version</code> defines a version-property (used by the JPA-Compiler).

[[File:Entity-28.png|center|frame|''Figure 28: A <code>version</code> property can be added to entities and beans.'']]

</blockquote>

===transient===
<blockquote>
<code>transient</code> marks the property as transient. Instead of a <code>@Column</code>, a <code>@Transient</code> annotation is generated, so that the property is not persisted in the database.

[[File:Entity-29.png|center|frame|''Figure 29: The <code>transient</code> keyword enables the exclusion of properties from persistence.'']]

</blockquote>

==References==

The Entity DSL tracks relationships between entities by using the concept of "references". References can exist between objects of the same nature (entities to entities, beans to beans). Where appropriate, back references ("opposite") are added.
References are defined by the <code>ref</code> keyword, a target, an optional type and a name. The exact type of the reference can be specified with the following modifiers:

===Multiplicity and nullability===
<blockquote>
The Entity DSL supports the specification of multiplicities in square brackets appended to the type:
* <code>[1]</code> defines a non-nullable, one-to-one relationship.
* <code>[0..1]</code> defines a nullable, one-to-one relationship (this is the default behavior).
* <code>[1..*]</code> defines a non-nullable, one-to-many relationship. An <code>opposite</code> reference is needed.
* <code>[0..*]</code> or simply <code>[*]</code> defines a nullable, one-to-many relationship. An <code>opposite</code> reference is needed.

[[File:Entity-30.png|center|frame|''Figure 30: Adding multiplicity "[1]" causes the annotations for non-nullable database entries to be set.'']]

</blockquote>

===opposite reference===
<blockquote>
Lifecycle references need the specification of an opposite reference. This can be done with the <code>opposite</code> keyword.

Using the <code>opposite</code> reference, it is possible to navigate back to the original object after following the reference.

</blockquote>

===cascade===
<blockquote>
The <code>cascade</code> specifier controls the behavior of the database on delete operations. If an object with a <code>cascade</code> reference to other objects is deleted, those other objects will be removed as well.

[[File:Entity-31.png|center|frame|''Figure 31: By using the <code>cascade</code> and <code>opposite</code> keywords, bidirectional associations can be achieved.'']]

</blockquote>

==Operations==

Operations are other important features. They are based on Xbase and offer a huge set of semantic features, extending the featureset of Java. Xbase additionally offers features such as closures.
Operations can be declared by the <code>def</code> keyword followed by braces containing the inline operation.

[[File:Entity-32.png|center|frame|''Figure 32: The <code>def</code> keyword allows the inlining of custom methods in the Entity DSL code.'']]

These methods are translated into the appropriate Java methods along with the automatically generated getter and setter methods.

==Annotations==

Annotations can be added to all elements except import declarations. Specifying annotations in the Entity DSL works in a straightforward manner; content assist is available. The added annotations are taken over into the generated Java code.

[[File:Entity-33.png|center|frame|''Figure 33: Annotating elements in the Compex Entity DSL causes an annotation to be inserted into the generated Java code.'']]

These methods are translated into the appropriate Java methods along with the automatically generated getter and setter methods.

==Comments==

Comments can be added anywhere in an .entitymodel text file and are copied over into the generated Java code. Comments are enclosed in <code>/* ... */</code>.

[[File:Entity-34.png|center|frame|''Figure 34: The comments added in the Entity DSL are transformed to Java-style comments in the generated code.'']]

Comments before the <code>package</code> keyword are copied over to all generated Java classes – this is the place for copyright notices.

[[File:Entity-35.png|center|frame|''Figure 35: A comment before the package keyword ends up in all generated Java classes.'']]

==Reserved Keywords==

The keywords of the Entity DSL are syntactic features and can therefore not be used as semantic identifiers.

In order to circumvent this, it is possible to escape them with the <code>^</code> character. During the generation of the Java code, this escape character is removed.

[[File:Entity-36.png|center|frame|''Figure 36: Using the escape character '^', it is possible to achieve an identifier in the generated Java code with a name that would be a reserved word in the Entity DSL. In this case, a variable named <code>uuid</code> is generated that cannot be specified in the entity model file.'']]

Please note that you are also '''not allowed to use identifiers corresponding to reserved keywords''' of the supported databases you can find here below:

[https://db.apache.org/derby/docs/10.2/ref/rrefkeywords29722.html Derby]

[http://www.h2database.com/html/advanced.html?highlight=reserved&search=reser#firstFound H2]

[https://docs.microsoft.com/en-us/sql/odbc/reference/appendixes/reserved-keywords?view=sql-server-2017 MS SQL]

[https://dev.mysql.com/doc/refman/8.0/en/keywords.html MySQL]

[https://docs.oracle.com/database/121/SQLRF/ap_keywd001.htm#SQLRF55621 Oracle]

[https://www.postgresql.org/docs/8.2/sql-keywords-appendix.html PostgreSQL]

== Copyright Notice ==
{{Copyright Notice}}

Entity DSL

2019-02-06T10:41:40Z

Worayeno: /* Reserved Keywords */

== Purpose ==

The Entity DSL facilitates the handling of persistence entities. Defining entities using the Entity DSL efficiently creates a clean entity model that contains all relevant semantic elements of the model text file.
This semantic model is used to automatically transform the semantic information into proper Java code with the respective annotations for a persistence provider. Additionally, if the entity model is located within a project with OSBP nature, "Auto-DTOs" and services are generated as well. In this case, attributes that are added to entities will automatically be transferred to the "Auto-DTOs".

== Overview ==

The main semantic elements of the Compex Entity DSL are the following:

* "Package" - the root element that contains all the other elements. A model can contain multiple packages.

* "Import" declarations - used to import external models or even Java classes.

* "Datatype" declarations - a way to define datatypes that can be used in entities and beans.

* "Entity" - the abstraction of a business model entity. It contains further elements such as properties and references.

* "Bean" - does not compile to a JPA Entity but to a Java Bean (POJO with getter and setter and PropertyChange-Support). Beans may be used as temporary containers in entity operations or can be embedded into JPA Entities.

* "Enum" - the abstraction for Java enums.

* "Property" - a reference to an embedded Bean, an Enum, a Java class or a simple datatype (as defined in the datatype declaration). Offers multiplicity.

* "Reference" - a reference to another Entity (or to another Bean in the case of a Bean). Offers multiplicity.

* "Operations" - similar to Java methods. The Xbase expression language can be used to write high-level code.

* "Annotations" can be placed on Entity, Property and Reference.

* "Comments" can be added to all elements.

== Entity model files ==

Entity models are described in .entitymodel files. These files describe the entity model and are the basis for the code generation. Entity models may be split over several .entitymodel files containing packages in the same namespace.
An .entitymodel file may contain several packages with entities. However, from a performance point of view, a complex entity model may work better with more and smaller .entitymodel files than the same model crammed into a few large files (or even a single file).

===package===
Entity model files must start with a package declaration. Packages are the root element of the Entity DSL grammar. Everything is contained in a package: Imports, Entities, Beans and Enums have to be defined inside the Package definition. One document can contain multiple packages with unique names.
The elements a package can contain are Entities, Beans and Enums. Additionally, a package allows Import statements and the declaration of datatypes.

<syntaxhighlight lang="java">
package name {
import importStatement;
datatype datatypeDefinition;
entities/beans/enums
}
</syntaxhighlight>

[[File:entity-1.png|center|frame|''Figure 1 - Entity model file - a package is the topmost element and contains other items.'']]

Marking a DTO as abstract (before the dto keyword) generates an abstract Java class for it.

The following modifiers may be placed after the dto keyword and the DTO name:

=== import ===
The Entity DSL allows the referencing of entities defined in different packages, even in different .entitymodel files. The import statement is a way to make these elements available in the current namespace without having to address them by their fully qualified name.

Import statements allow the use of the '*' wildcard.

<syntaxhighlight lang="java">
import importStatement;
</syntaxhighlight>

[[File:entity-2.png|center|frame|''Figure 2: Items contained in another package can be addressed if the package is imported using the import keyword and its fully qualified name.'']]

=== datatype ===
The Entity DSL allows the definition of datatypes. These are translated by the inferrer into their standard Java representation. The behavior of the generator can be controlled by the datatype definitions.
Datatypes defined in an .entitymodel file are local to that file. In order to define datatypes in one place and have them available in multiple .entitymodel files, the datatypes may be defined in a ".datatypes" file containing only datatype definitions inside a package statement.
There are three types of datatype definitions:

* '''jvmTypes''': Datatype definitons that map types to '''jvmTypes''' take the basic syntax of 
<blockquote><code>datatype <name> jvmType <type> as primitive;</code>.</blockquote>
<blockquote>Specifying datatypes in this manner uses an appropriate wrapper class in the generated Java code; adding the keywords <code>as primitive</code> enforces the use of primitive datatypes where applicable:
<code>datatype foo jvmType Integer;</code> compiles to an <code>Integer</code> whereas <code>datatype foo jvmType Integer as primitive;</code> results in <code>int</code>.

[[File:entity-3.png|center|frame|''Figure 3: The defined datatype is translated to a wrapper class.'']]

[[File:Entity-4.png|center|frame|''Figure 4: By adding the <code>as primitive</code> keywords, the datatype is translated to a primitive datatype.'']]

</blockquote>
* '''dateTypes''': The datatypes for handling temporal information can be defined by the following statement:
<blockquote><code>datatype <name> datetype date—time—timestamp; </code>
Datatypes that have been defined in this manner can be used as property variables in entities and beans.

[[File:Entity-5.png|center|frame|''Figure 5: Defining datatypes for handling temporal information. Content assist is available.'']]

</blockquote>
* '''blobs''': Binary blobs can be handled by defining a datatype with the <code>as blob</code> keywords. The Java implementation of such a blob is a byte array. Appropriate persistence annotations are automatically added.
<blockquote>
<code>datatype <name> as blob;</code>

[[File:Entity-6.png|center|frame|''Figure 6: Including binary blobs by using a datatype with the <code>as blob</code> keywords.'']]
</blockquote>

 After import statements and datatype definitions, the content of the .entitymodel file is made up of <code>entity</code>, <code>bean</code> and <code>enum</code> definitions.

== Entities ==
Entities are the most complex elements in the Entity DSL. An entity is an abstraction above a business object. Entities are defined by their name, properties, references and operations. Generally, an entity is an object which can keep the state of variables and references as well as be persisted.
For each entity that is defined in a package, a Java class and the corresponding persistence structure is automatically generated. Inside a project with Compex nature, "Auto-DTOs" and services are created as well.

Entities may extend other entities. In this case, they are derived from their parent entity. That means that the properties and references of the parent entity are inherited.

Syntax:
<syntaxhighlight lang="java">
[modifiers] entity <name> extends <parentEntity> {
[entityProperties]
}
</syntaxhighlight>

[[File:Entity-7.png|center|frame|''Figure 7: Items contained in another package can be addressed if the package is imported using the <code>import</code> keyword and its fully qualified name'']]

Entities may be defined with certain modifiers that change the generated Java Code. The following modifiers are supported:

=== abstract ===

<blockquote>
<code>abstract</code> marks the entity as "abstract". This generates an abstract Java class.

[[File:Entity-8.png|center|frame|''Figure 8: The <code>abstract</code> keyword causes the translation into an abstract Java class'']]

</blockquote>

=== historized ===
<blockquote>
<code>historized</code> marks the entity as "historized". Historized entities can have several entries in a database, but only one of them may be marked as current.

The <code>historized</code> keyword adds an object ID, a version field and a flag for the current version to the entity.

[[File:Entity-9.png|center|frame|''Figure 9: The <code>historized</code> modifier triggers the creation of an object ID, an object version and a flag for marking the current version.'']]

</blockquote>

=== cacheable ===
<blockquote>
<code>cacheable</code> marks the entity as "cacheable". The appropriate annotation for the persistence provider is added to the generated Java code.

[[File:Entity-10.png|center|frame|''Figure 10: Declaring an entity to be <code>cacheable</code> adds the <code>@Cacheable</code> annotation'']]
</blockquote>

=== timedependent ===
<blockquote>
<code>timedependent</code> marks the entity as "time-dependent". An object may have several entries in the database. Which entry is valid will be determined by '''valid from''' and '''valid until''' fields that are added to the entity.
An object ID is created in order to tie the entries together. The <code>timedependent</code> keyword recognizes the modifiers <code>(DATE)</code> and <code>(TIMESTAMP)</code>. Default is <code>timedependent(DATE)</code>.

[[File:Entity-11.png|center|frame|''Figure 11: The <code>timedependent</code> keyword causes an object ID, a validFrom and a validUntil field to be created in order to support multiple database entries for an object.'']]
</blockquote>

=== mapped superclass ===
<blockquote>
<code>mapped superclass</code> marks a class that provides persistent entity state and mapping information for its subclasses, but which is not an entity itself.

Typically, the purpose of a mapped superclass is to define state and mapping information that is common to multiple entities. All the mappings from the mapped superclass are inherited by its subclasses, as if they had been defined there directly.

[[File:Entity-12.png|center|frame|''Figure 12: The <code>mapped superclass</code> keyword sets the appropriate annotation which causes the persistence provider to move the mappings to the derived subclasses.'']]
</blockquote>

===extends===
<blockquote>
The modifier <code>extends</code> may be placed after the entity keyword and the entity name, as <code>entity foo extends bar {</code>, where <code>bar</code> has already been defined as an entity.

<code>extends</code> marks an entity that is derived from another entity. That means that the properties and references of the parent entity are inherited.
</blockquote>

==Entity Persistence Settings==

Apart from the mapped superclass modifier that moves all property columns to the tables belonging to derived classes, the following settings for table inheritance can be specified within an entity definition:
* inheritance per class
* inheritance per subclass

The structure of the database created from an entity model can be controlled by the following settings:
* schemaName
* tableName
* discriminatorColumn
* discriminatorType
* discriminatorValue

===inheritance per class===
<blockquote>
<code>inheritance per class{}</code> causes a table to be created for each class; subclasses share this table using a discriminator value. This statement has to be followed by braces, inside of which further details can be specified.

[[File:Entity-13.png|center|frame|''Figure 13: A single table for entity Base is created; the generated Java code for the “Derived” class shows that the “Derived” entity is added to this table by using a discriminator.'']]
</blockquote>

===inheritance per subclass===
<blockquote>
<code>inheritance per subclass{}</code> causes a table to be created for each subclass. This statement has to be followed by braces, inside of which further details can be specified. This is the default behaviour if no inheritance strategy is specified.

[[File:Entity-14.png|center|frame|''Figure 14: An <code>@Table</code> annotation is added to the generated Java code, so that the "Derived" entity is mapped to a table of its own.'']]
</blockquote>

===schemaName===
<blockquote>
<code>schemaName</code> allows the specification of a name for the database schema to be used. This setting is translated to the appropriate JPA annotation <code>@Table(schema = <xyz>)</code>. The schema name given is converted to snake case using capitals.
</blockquote>

===tableName===
<blockquote>
<code>tableName</code> allows the specification of a name for the table (within the database schema) to which the entity is mapped. This setting is translated to the appropriate JPA annotation
<code>@Table(name = <xyz>)</code>.

The table name specified is converted to snake case using capitals. The default value is the name of the entity.

[[File:Entity-15.png|center|frame|''Figure 15: Specifying the <code>schemaName</code> and <code>tableName</code> settings in an entity determines the name of the database schema and tables used for persistence.'']]
</blockquote>

===discriminatorColumn===
<blockquote>
<code>discriminatorColumn</code> optionally allows the specification of a name for the discriminator column in the case of <code>inheritance per class</code>. It appears within the braces after the inheritance-strategy statement and must be followed by a semicolon. It defaults to <code>DISC</code>.
</blockquote>

===discriminatorType===

<blockquote>
<code>discriminatorType</code> optionally allows the definition of the datatype of the discriminator within the single table. It can be set to <code>CHAR</code>, <code>INT</code>, <code>STRING</code> or <code>INHERIT</code>. It appears within the braces after the <code>inheritance</code> statement and must be followed by a semicolon. It defaults to <code>STRING;</code>.
</blockquote>

===discriminatorValue===

<blockquote>
<code>discriminatorValue</code> allows a custom value to be used for the discriminator within the single table. It appears within the braces after the <code>inheritance</code> statement and must be followed by a semicolon. It defaults to the entity name converted to snake case.

[[File:Entity-16.png|center|frame|''Figure 16: The <code>inheritance</code> statement allows the optional specification of discriminator column, type and value to be used in the case of a single table.'']]
</blockquote>

==Beans==

'''Beans''' are objects that are embedded in other entities, inheriting their persistence and lifecycle. Similar to entities, beans are characterised by their name, their properties and their references. For each bean that is defined in a package, a Java class is automatically generated.

Beans can be embedded into entities by defining them as properties of the respective entity. The appropriate annotations (<code>@Embeddable</code>, <code>@Embedded</code>, <code>@AttributeOverrides</code> etc.) are added in order to have beans persisted with their parent entities.

[[File:Entity-17.png|center|frame|''Figure 17: Beans can be embedded in entities and are persisted with them.'']]

==Enums==

'''Enums''' are an abstraction of the Java <code>enum</code>. They compile to <code>enum</code> classes and can be used as properties in entities and beans.

[[File:Entity-18.png|center|frame|''Figure 18: Defining <code>enums</code> allows using them as variables in entities and beans.'']]

==Properties==
Properties of entities and beans are references to datatypes or enums. They can be regarded as variables and are defined by a keyword followed by a datatype (Java type or datatype defined in the <code>datatype</code> section) and a name. By defining a bean as a property of an entity, it is embedded in it.

Properties can be determined with the following keywords:

===var===
<blockquote>
The basic property <code>var</code> defines a variable that is persisted in a table column. A property must have a type and a name.

'''Multiplicity''' of properties can be controlled by the following (optional) settings:

* <code>[1]</code> defines a non-nullable property.
* <code>[0..1]</code> defines a nullable property (this is the default behavior).
* <code>[1..*]</code> defines a list of properties that must not be empty.
* <code>[0..*]</code> or simply <code>[*]</code> defines a list of properties that may be empty.

[[File:Entity-19.png|center|frame|''Figure 19: Variables can be defined using the <code>var</code> keyword.'']]

The appropriate persistence settings are generated automatically. If a multiplicity is specified, the appropriate annotations (and, if necessary, a list rather than a single variable) are generated.
</blockquote>

===derived===
<blockquote>
<code>derived</code> defines a property that is derived from other properties. The derived property must be have a type, a name and the calculation logic that derives it from the other properties, written as an Xexpression in braces.

[[File:Entity-20.png|center|frame|''Figure 20: Properties may be derived from other properties using an Xexpression.'']]

The code is automatically translated to valid Java code.
</blockquote>

===dirty===
<blockquote>
<code>dirty</code> defines a property used as a flag to track the "dirty" state of the buffered data when editing values, before the changes have been written back to the persistence entity. Only one <code>dirty</code> flag is allowed per entity. The datatype has to be boolean.

[[File:Entity-21.png|center|frame|''Figure 21: The <code>dirty</code> property is used to flag whether changes have been made to the bufered data, but not yet written back to the persistence entity. '']]

The boolean field for this property and the appropriate annotation are generated with the <code>dirty</code> keyword.
</blockquote>

===domainDescription===
<blockquote>
<code>domainDescription</code> defines a property that is used as a domain description. The appropriate annotation is added to the property. A domain description must be of type <code>String</code>. Domain descriptions may be derived from other properties.

[[File:Entity-22.png|center|frame|''Figure 22: Domain description properties can be created with the <code>domainDescription</code> keyword.'']]
</blockquote>

===domainKey===
<blockquote>
<code>domainKey</code> defines a domain key. The appropriate annotation is added to the property. Primitive datatypes may be used as domain keys.

[[File:Entity-23.png|center|frame|''Figure 23: A field containing a domain key is created with the <code>domainKey keyword</code>.'']]
</blockquote>

===id===
<blockquote>
{{Deprecated}}

'''id''' defines an ID property (used as a primary key by the JPA compiler). '''This keyword is deprecated - use uuid instead'''. If no <code>id</code> is specified, a warning is given.

'''Caution''': ID autogeneration causes problems, since the value is not set before the entity is persisted, e.g., in the database. It is therefore advised to use the <code>uuid</code> keyword instead.

[[File:Entity-24.png|center|frame|''Figure 24: Entities are supposed to have an ID property that is used as a primary key to the underlying database.'']]

'''Caution''': The generated IDs are not necessarily unique if the deprecated <code>id</code> keyword is used!
</blockquote>

===index===
<blockquote>
The <code>index</code> keyword causes an index for the table to be generated. Indexes may be based on one or more properties (primitive only) and references (one-to-one only) of the entity. An index must be given a name and, in braces, a list of the fields it is based upon. If the <code>index</code> keyword is prefixed with <code>unique</code>, a unique index is created.

[[File:Entity-25.png|center|frame|''Figure 25: Database table indexes that map entities are generated with the <code>index</code> keyword.'']]

The <code>@Table</code> annotation is supplemented with the index definition.

</blockquote>

===properties===
<blockquote>
Features (properties and references) of entities and beans can optionally be given additional information in the form of key-value pairs. This information can then be retrieved from the semantic model. The key-value pairs are defined in parentheses after the properties keyword following the feature name. Multiple pairs can be defined (comma-separated).

[[File:Entity-26.png|center|frame|''Figure 26: Additional information about features can be defined by key-value pairs. This information is then stored in the semantic model and is retrievable.'']]

</blockquote>

===uuid===
<blockquote>
<code>uuid</code> allows the use of Universally Unique IDs as primary keys. A new UUID value is generated for each object as soon as that object has been created, independently of database operations. This circumvents the problems with the <code>id</code> keyword. UUIDs have to be of type <code>String</code>.

[[File:Entity-27.png|center|frame|''Figure 27: By using the <code>uuid</code> keyword, entities are created with a reliably unique identifier.'']]

</blockquote>

===version===
<blockquote>
<code>version</code> defines a version-property (used by the JPA-Compiler).

[[File:Entity-28.png|center|frame|''Figure 28: A <code>version</code> property can be added to entities and beans.'']]

</blockquote>

===transient===
<blockquote>
<code>transient</code> marks the property as transient. Instead of a <code>@Column</code>, a <code>@Transient</code> annotation is generated, so that the property is not persisted in the database.

[[File:Entity-29.png|center|frame|''Figure 29: The <code>transient</code> keyword enables the exclusion of properties from persistence.'']]

</blockquote>

==References==

The Entity DSL tracks relationships between entities by using the concept of "references". References can exist between objects of the same nature (entities to entities, beans to beans). Where appropriate, back references ("opposite") are added.
References are defined by the <code>ref</code> keyword, a target, an optional type and a name. The exact type of the reference can be specified with the following modifiers:

===Multiplicity and nullability===
<blockquote>
The Entity DSL supports the specification of multiplicities in square brackets appended to the type:
* <code>[1]</code> defines a non-nullable, one-to-one relationship.
* <code>[0..1]</code> defines a nullable, one-to-one relationship (this is the default behavior).
* <code>[1..*]</code> defines a non-nullable, one-to-many relationship. An <code>opposite</code> reference is needed.
* <code>[0..*]</code> or simply <code>[*]</code> defines a nullable, one-to-many relationship. An <code>opposite</code> reference is needed.

[[File:Entity-30.png|center|frame|''Figure 30: Adding multiplicity "[1]" causes the annotations for non-nullable database entries to be set.'']]

</blockquote>

===opposite reference===
<blockquote>
Lifecycle references need the specification of an opposite reference. This can be done with the <code>opposite</code> keyword.

Using the <code>opposite</code> reference, it is possible to navigate back to the original object after following the reference.

</blockquote>

===cascade===
<blockquote>
The <code>cascade</code> specifier controls the behavior of the database on delete operations. If an object with a <code>cascade</code> reference to other objects is deleted, those other objects will be removed as well.

[[File:Entity-31.png|center|frame|''Figure 31: By using the <code>cascade</code> and <code>opposite</code> keywords, bidirectional associations can be achieved.'']]

</blockquote>

==Operations==

Operations are other important features. They are based on Xbase and offer a huge set of semantic features, extending the featureset of Java. Xbase additionally offers features such as closures.
Operations can be declared by the <code>def</code> keyword followed by braces containing the inline operation.

[[File:Entity-32.png|center|frame|''Figure 32: The <code>def</code> keyword allows the inlining of custom methods in the Entity DSL code.'']]

These methods are translated into the appropriate Java methods along with the automatically generated getter and setter methods.

==Annotations==

Annotations can be added to all elements except import declarations. Specifying annotations in the Entity DSL works in a straightforward manner; content assist is available. The added annotations are taken over into the generated Java code.

[[File:Entity-33.png|center|frame|''Figure 33: Annotating elements in the Compex Entity DSL causes an annotation to be inserted into the generated Java code.'']]

These methods are translated into the appropriate Java methods along with the automatically generated getter and setter methods.

==Comments==

Comments can be added anywhere in an .entitymodel text file and are copied over into the generated Java code. Comments are enclosed in <code>/* ... */</code>.

[[File:Entity-34.png|center|frame|''Figure 34: The comments added in the Entity DSL are transformed to Java-style comments in the generated code.'']]

Comments before the <code>package</code> keyword are copied over to all generated Java classes – this is the place for copyright notices.

[[File:Entity-35.png|center|frame|''Figure 35: A comment before the package keyword ends up in all generated Java classes.'']]

==Reserved Keywords==

The keywords of the Entity DSL are syntactic features and can therefore not be used as semantic identifiers.

In order to circumvent this, it is possible to escape them with the <code>^</code> character. During the generation of the Java code, this escape character is removed.

[[File:Entity-36.png|center|frame|''Figure 36: Using the escape character '^', it is possible to achieve an identifier in the generated Java code with a name that would be a reserved word in the Entity DSL. In this case, a variable named <code>uuid</code> is generated that cannot be specified in the entity model file.'']]

Please note that you are also '''not allowed to use identifiers corresponding to reserved keywords''' of the supported databases:

[https://db.apache.org/derby/docs/10.2/ref/rrefkeywords29722.html Derby]

[http://www.h2database.com/html/advanced.html?highlight=reserved&search=reser#firstFound H2]

[https://docs.microsoft.com/en-us/sql/odbc/reference/appendixes/reserved-keywords?view=sql-server-2017 MS SQL]

[https://dev.mysql.com/doc/refman/8.0/en/keywords.html MySQL]

[https://docs.oracle.com/database/121/SQLRF/ap_keywd001.htm#SQLRF55621 Oracle]

[https://www.postgresql.org/docs/8.2/sql-keywords-appendix.html PostgreSQL]

== Copyright Notice ==
{{Copyright Notice}}

AppUpIn5Extensions

2018-01-23T10:27:43Z

Worayeno:

==Purpose==

The purpose of this document is to describe the first set of functional extensions of the CSV2App module presented in the [[App up in 5 minutes]] page, which will be available with the next release version.

=== OSBP applications===

The OSBP application '''My1App''' should already have been generated before starting this app.
You can find the instructions [http://download.osbee.org/documentation/index.php/My_first_app here].

=== CSV-file ===

You may use the two following files as reference files [http://download.osbee.org/downloads/samples/documentation/BrandType.csv BrandType.csv] and [http://download.osbee.org/downloads/samples/documentation/Brand.csv Brand.csv].

== ''AppUpIn5 - Extensions 1.0'' ==

You get access to those new functionalities by opening a csv file with the CSV2App module editor of the OS.bee Software Factory, and by making a left mouse click on the column you wish to edit the metadata from.

 [[File:Brandtype.png|none|frame|''Figure 1: Brandtype.csv in CSV2 Editor'']] 

The settings dialog of the corresponding column will then appear. The several options provided in this dialog are organized in two parts: the meta data section and the sorting section.

 [[File:Settingdialog.png|frame|none|''Figure 2: Settings dialog of column "id"'']] 

The sorting options are always available to the user, whereas the meta data options are only available based on the analysis of the type of data contained in the selected column.

==Metadata options==
The metadata section allows users to set additional information related to the entity that will be created, based on the content of a csv file and existing dsl model files.

===Id===
With the option ''ID'' you are able to define the column representing the unique identifier data of an entity. An entity has always one identification key, also known as primary key, which is here a ''Universal Unique Identifier'' (UUID), a unique alphanumerical string. Only columns having this type of data can be defined by the user as ''ID''-columns.

With a left mouse click on the column named ''id'' of the csv file ''BrandType.csv'', the user opens the settings dialog of this column.

 [[File:SettingsID.png|frame|none|''Figure 3: Settings dialog column "id" of Brandtype'']] 

(1) By selecting the ''ID'' checkbox, (2) and then pressing the OK button, the user set the column ''id'' as the ''ID''-column of the entity created later on, like shown on the figure below. Each entity has always one UUID attribute. Therefore each csv file must have one ''ID''-column. The generated code later on will look like this snippet on figure 4.

 [[File:Brandtypeid.png|frame|none|''Figure 4: Entity dsl model - "id" attribute of Brandtype'']] 

===Reference===
With the reference option you are able to set column data as reference data (or foreign key) pointing to the ''Universal Unique Identifier'' (primary key) of another '''already existing entity'''. These data are also alphanumerical values, as mentioned in the section above concerning the id-option.

 [[File:RefArea.png|frame|none|''Figure 5: Reference area.'']] 

A reference column results into the creation of a 1-n relation between the new entity, which will be created on the basis of the considered csv file and the referenced entity, which already exists in the entity model file of your project. The condition of having this target entity to be referenced on already existing in the model translates into a specific '''order of execution''' of the application creation: successively pressing the button ''Create App'' in the right order to be able to choose the target entity.

For instance, we would like to create a reference between the entity ''Brandtype'' and the new entity to be created ''Brand'', whose csv file contains the ''brandTypeId'' as column. As you can see on the left side of figure 6, showing the content of the entity dsl model file, the entity ''Brandtype'' has already been created.

 [[File:RefEntBrand.png|thumb|600px|none|''Figure 6: Entity model file and Brand.csv file.'']] 

(1) By selecting the reference checkbox, (2) selecting ''Brandtype'' in the list of all existing entities, (3) and then by pressing the OK button, the user set the column ''brandTypeId'' as a reference key pointing to the UUID of the entity ''Brandtype''.

 [[File:RefBrandtypeId.png|thumb|600px|none|''Figure 7: Settings dialog column "brandTypeId" of Brand'']] 

The result of this relation at the end of the app creation would then look like this.

 [[File:Refbrandtypenormal.png|thumb|600px|none|''Figure 8: Reference result on "brandTypeId"'']] 

The optional tag <code>cascade</code> allows, when selected, the deletion of all elements of the n-side of the relation, when the one-side element is deleted. In our example, the removal of one brand type would then result to the deletion of all the brands categorized by that type. The generated relation would then look like this in contrast to last example.

 [[File:Refbrandtypecascade.png|thumb|600px|none|''Figure 9: Reference result on "brandTypeId" with cascade'']] 

Besides the fact that here 1-n relations are created between entities, a reference attribute will also be generated in each one of them. This is needed in order to show the information data of each relation graphically (here as table) in the application interface. This is characterized by the use of a <code>properties{...}</code> block.

===Domain key===
The domain key option allows the user to set a user friendly identification search field for the application instead of UUIDs, since those are too cryptic for users to clearly distinguish data from each other.

Only column data from type string allow the user to define a column as the domain key column.

In the case of the entity ''Brandtype'', an adequate candidate for the domain key is the column ''brandTypeNm'' containing the names of brand types, which are easy for users to read and identify data from in the application later on.

(1) By selecting the domain key checkbox, (2) and then pressing the OK button, the user defines the column ''brandTypeNm'' as the domain key column of the entity Brandtype.

 [[File:Brandtypenm.png|frame|none|''Figure 10: Settings dialog column "brandTypeNm" of Brandtype'']] 

The result is the creation of the domain key attribute of the entity ''Brandtype'' as shown on the figure below.

 [[File:BrandtypenmEntity.png|frame|none|''Figure 11: Domain key in entity dsl model'']] 

===Media data===
The media data option allows the user to define a column as a multimedia column. It allows user to specify from which columns information can be gathered from, in order to create the appropriate structures to store and upload any type of files in your application. This type of column contains the filenames of the multimedia files without extension. In addition to both the mime type and the extension, the user has also to define the directory path, where those files are located.

 [[File:Mediadata.png|thumb|600px|none|''Figure 12: Media data section'']] 

The currently supported mime types are the following: plain, jpg, mpeg, octetstream and pdf.
 [[File:Mediadata4.png|thumb|600px|none|''Figure 13: Mimetypes'']] 

The user can not just select one of the predefined extension formats (bmp, csv, jpg, mp3, pdf, txt, xml), but also edit an extension format on his own (java or sql ...).

 [[File:Mediadata5.png|thumb|600px|none|''Figure 14: Extensions'']] 

An optional column name can be given by the user to set the name of the multimedia column, which will be additionally created to store these files based on the OS.bee [[BlobMapping]] data type. If not defined, the media column name will consist of the actual column name followed with the suffix '''media'''.

Only columns containing text data can be defined as media data column by the user.

 [[File:Mediadata1.png|thumb|600px|none|''Figure 15: Media data on column "bsin"'']] 

The column ''bsin'' of the entity Brand contains media file name. Besides being provided with the Brand.csv file, we also have the corresponding jpg-files illustrated here in figure 16.

 [[File:Mediadata2.png|thumb|600px|none|''Figure 16: Media file location'']] 

After opening the settings dialog of the column ''bsin'', (1) the user needs first to select the media data checkbox, which allows the modification of the information needed. (2) The user sets the path directory with the help of directory chooser, which appears after pressing the Path button and then selects the directory, in which the files are located. (3) The mime type and extension of the files have to be chosen within the corresponding combo boxes. (4) After pressing the OK button, the user sets the column ''bsin'' as a multimedia column. This will then result into the creation of both attributes ''bsin'' and ''bsinmedia'' of the entity Brand later on, as shown below.

 [[File:Mediadata3.png|thumb|600px|none|''Figure 17: Blobmapping attribute in entity Brand'']] 

==General Notice==
As soon as the user press the button "Create App", an error message will eventually be displayed to inform the user to complete or adapt the meta data configuration of the considered csv file.
* '''Please note that a proper configuration of column definitions has to be done by the user as soon as id, reference or domain keys candidates have been detected.''' Candidates are columns of a csv file, which meet the criteria for either an id, a reference (both from alphanumerical string with UUID format as described above) or a domain key column. Setting the meta data of those columns is then '''mandatory'''.

*'''A universal unique identifier (UUID) will be automatically generated by the OS.bee Software Factory for an entity only in the case, in which no id-column candidates are available in a csv file.'''

* '''Please note that all configurations made by the user in one csv file are immediately lost, as soon as the user close the file from the CSV2App module editor or by restarting the eclipse IDE.'''

Further information over the usage of meta data such as '''id''', '''reference''' and '''domain key''' can be found in the [[Entity DSL]] documentation page.

==Sorting options==
The sorting section allows you to sort the csv data within the editor. The selected column data can be sorted either in an ascending or a descending order.
 [[File:Sorting.png|frame|none|''Figure 18: Sorting options'']]

The following examples show you how to use the sort functions by applying it on the column ''brandNm'' of the provided [[#files|Brand.csv]] file. After you opened it in the CSV2App module editor within your eclipse workspace (for example via drag-n-drop), (1) make a left-mouse click on the column ''brandNm'', (2) choose either the ascending (figure 19) or the descending (figure 20) option in the sorting section, (3) and then press the OK button to trigger to the sorting of the column data. (4) You can observe the resulting sorted column data on the right side of both figures below.

► '''Example 1''': [[File:Sorting1.png|thumb|600px|none|''Figure 19: Ascending sort of the column "brandNm"'']]

► '''Example 2''': [[File:Sorting2.png|thumb|600px|none|''Figure 20: Descending sort of the column "brandNm"'']]

== Copyright Notice ==
{{Copyright Notice}}

== License information ==

{{License information}}

File:Sorting2.png

2018-01-23T10:01:21Z

Worayeno: Worayeno uploaded a new version of File:Sorting2.png

File:Sorting1.png

2018-01-23T10:00:54Z

Worayeno: Worayeno uploaded a new version of File:Sorting1.png

File:Refbrandtypecascade.png

2018-01-23T09:41:05Z

Worayeno:

File:Refbrandtypenormal.png

2018-01-23T09:40:44Z

Worayeno:

AppUpIn5Extensions

2018-01-23T09:40:22Z

Worayeno: /* Reference */

==Purpose==

The purpose of this document is to describe the first set of functional extensions of the CSV2App module presented in the [[App up in 5 minutes]] page, which will be available with the next release version.

=== OSBP applications===

The OSBP application '''My1App''' should already have been generated before starting this app.
You can find the instructions [http://download.osbee.org/documentation/index.php/My_first_app here].

=== CSV-file ===

You may use the two following files as reference files [http://download.osbee.org/downloads/samples/documentation/BrandType.csv BrandType.csv] and [http://download.osbee.org/downloads/samples/documentation/Brand.csv Brand.csv].

== ''AppUpIn5 - Extensions 1.0'' ==

You get access to those new functionalities by opening a csv file with the CSV2App module editor of the OS.bee Software Factory, and by making a left mouse click on the column you wish to edit the metadata from.

 [[File:Brandtype.png|none|frame|''Figure 1: Brandtype.csv im CSV2 Editor'']] 

The settings dialog of the corresponding column will then appear. The several options provided in this dialog are organized in two parts: the meta data section and the sorting section.

 [[File:Settingdialog.png|frame|none|''Figure 2: Settings dialog of column "id"'']] 

The sorting options are always available to the user, whereas the meta data options are only available based on the analysis of the type of data contained in the selected column.

==Metadata options==
The metadata section allows users to set additional information related to the entity that will be created, based on the content of a csv file and existing dsl model files.

===Id===
With the option ''ID'' you are able to define the column representing the unique identifier data of an entity. An entity has always one identification key, also known as primary key, which is here a ''Universal Unique Identifier'' (UUID), a unique alphanumerical string. Only columns having this type of data can be defined by the user as ''ID''-columns.

With a left mouse click on the column named ''id'' of the csv file ''BrandType.csv'', the user opens the settings dialog of this column.

 [[File:SettingsID.png|frame|none|''Figure 3: Settings dialog column "id" of Brandtype'']] 

(1) By selecting the ''ID'' checkbox, (2) and then pressing the OK button, the user set the column ''id'' as the ''ID''-column of the entity created later on, like shown on the figure below. Each entity has always one UUID attribute, therefore each csv file must have one ''ID''-column. The generated code later on will look like this snippet on figure 4.

 [[File:Brandtypeid.png|frame|none|''Figure 4: Entity dsl model - "id" attribute of Brandtype'']] 

===Reference===
With the reference option you are able to set column data as reference data (or foreign key) pointing to the ''Universal Unique Identifier'' (primary key) of another '''already existing entity'''. These data are also alphanumerical values, as mentioned in the section above concerning the id-option.

 [[File:RefArea.png|frame|none|''Figure 5: Reference area.'']] 

A reference column results into the creation of a 1-n relation between the new entity, which will be created on the basis of the considered csv file and the referenced entity, which already exists in the entity model file of your project. The condition of having this target entity to be referenced on already existing in the model translates into a specific '''order of execution''' of the application creation: successively pressing the button ''Create App'' in the right order to be able to choose the target entity.

For instance, we would like to create a reference between the entity ''Brandtype'' and the new entity to be created ''Brand'', whose csv file contains the ''brandTypeId'' as column. As you can see on the left side of figure 6, showing the content of the entity dsl model file, the entity ''Brandtype'' has already been created.

 [[File:RefEntBrand.png|thumb|600px|none|''Figure 6: Entity model file and Brand.csv file.'']] 

(1) By selecting the reference checkbox, (2) selecting ''Brandtype'' in the list of all existing entities, (3) and then by pressing the OK button, the user set the column ''brandTypeId'' as a reference key pointing to the UUID of the entity ''Brandtype''.

 [[File:RefBrandtypeId.png|thumb|600px|none|''Figure 7: Settings dialog column "brandTypeId" of Brand'']] 

The result of this relation at the end of the app creation would then look like this.

 [[File:Refbrandtypenormal.png|thumb|600px|none|''Figure 8: Reference result on "brandTypeId"'']] 

The optional tag <code>cascade</code> allows, when selected, the deletion of all elements of the n-side of the relation, when the one-side element is deleted. In our example, the removal of one brand type would then result to the deletion of all the brands categorized by that type. The generated relation would then look like this in contrast to last example.

 [[File:Refbrandtypecascade.png|thumb|600px|none|''Figure 9: Reference result on "brandTypeId" with cascade'']] 

Besides the fact that here 1-n relations are created between entities, a reference attribute will also be generated in each entity. This is needed in order to show the information data of each relation graphically (here as table) in the application interface. This is characterized by the use of a <code>properties{...}</code> block.

===Domain key===
The domain key option allows the user to set a user friendly identification search field for the application instead of UUIDs, since those are too cryptic for users to clearly distinguish data from each other.

Only column data from type string allow the user to define a column as the domain key column.

In the case of the entity ''Brandtype'', an adequate candidate for the domain key is the column ''brandTypeNm'' containing the names of brand types, which are easy for users to read and identify data from in the application later on.

(1) By selecting the domain key checkbox, (2) and then pressing the OK button, the user define the column ''brandTypeNm'' as the domain key column of the entity Brandtype.

 [[File:Brandtypenm.png|frame|none|''Figure 10: Settings dialog column "brandTypeNm" of Brandtype'']] 

This results into the creation of the domain key attribute of the entity ''Brandtype'' as shown on the figure below.

 [[File:BrandtypenmEntity.png|frame|none|''Figure 11: Domain key in entity dsl model'']] 

===Media data===
The media data option allows the user to define a column as a multimedia column. It allows user to specify from which columns information can be gathered from, in order to create the appropiate structures to store and upload any type of files in your application. This type of column contains the filenames of the multimedia files without extension. In addition to both the mime type and the extension, the user has also to define the directory path, where those files are located.

 [[File:Mediadata.png|thumb|600px|none|''Figure 12: Media data section'']] 

The currently supported mime types are the following: plain, jpg, mpeg, octetstream and pdf.
 [[File:Mediadata4.png|thumb|600px|none|''Figure 13: Mimetypes'']] 

The user can not just select one of the predefined extension formats (bmp, csv, jpg, mp3, pdf, txt, xml), but also edit an extension format on his own (java or sql...).

 [[File:Mediadata5.png|thumb|600px|none|''Figure 14: Extensions'']] 

An optional column name can be given by the user to set the name of the multimedia column, which will be additionally created to store these files based on the OS.bee [[BlobMapping]] data type. If not defined, the media column name will consist of the actual column name followed with the suffix '''media'''.

Only columns containing text data can be defined as media data column by the user.

 [[File:Mediadata1.png|thumb|600px|none|''Figure 15: Media data on column "bsin"'']] 

The column ''bsin'' of the entity Brand contains media file name. Besides being provided with the Brand.csv file, we also have the corresponding jpg-files illustrated here in figure 16.

 [[File:Mediadata2.png|thumb|600px|none|''Figure 16: Media file location'']] 

After opening the settings dialog of the column ''bsin'', (1) the user needs first to select the media data checkbox, which allows the modification of the information needed. (2) The user sets the path directory with the help of directory chooser, which appears after pressing the Path button and then selects the directory, in which the files are located. (3) The mime type and extension of the files have to be chosen within the corresponding combo boxes. (4) After pressing the OK button, the user sets the column ''bsin'' as a multimedia column. This will then result into the creation of both attributes ''bsin'' and ''bsinmedia'' of the entity Brand later on, as shown below.

 [[File:Mediadata3.png|thumb|600px|none|''Figure 17: Blobmapping attribute in entity Brand'']] 

==General Notice==
As soon as the user press the button "Create App", an error message will eventually be displayed to inform the user to complete or adapt the metadata configuration of the considered csv file.
* '''Please note that a proper configuration of column definitions has to be done by the user as soon as id, reference or domain keys candidates have been detected.''' Candidates are columns of a csv file, which meet the criteria for either an id, a reference (both from alphanumerical string with UUID format as described above) or a domain key column. Setting the metadata of those columns is then '''mandatory'''.

*'''A universal unique identifier (UUID) will be automatically generated by the OS.bee Software Factory for an entity only in the case, in which no id-column candidates are available in a csv file.'''

* '''Please note that all configurations made by the user in one csv file are immediately lost, as soon as the user close the file from the CSV2App module editor or by restarting the eclipse IDE.'''

Further information over the usage of metadata such as '''id''', '''reference''' and '''domain key''' can be found in the [[Entity DSL]] documentation page.

==Sorting options==
The sorting section allows you to sort the csv data within the editor. The selected column data can be sorted either in an ascending or a descending order.
 [[File:Sorting.png|frame|none|''Figure 18: Sorting options'']]

The following examples show you how to use the sort functions by applying it on the column ''brandNm'' of the provided [[#files|Brand.csv]] file. After you opened it in the CSV2App module editor within your eclipse workspace (for example via drag-n-drop), (1) make a left-mouse click on the column ''brandNm'', (2) choose either the ascending (figure 19) or the descending (figure 20) option in the sorting section, (3) and then press the OK button to trigger to the sorting of the column data. (4) You can observe the resulting sorted column data on the right side of both figures below.

► '''Example 1''': [[File:Sorting1.png|thumb|600px|none|''Figure 19: Ascending sort of the column "brandNm"'']]

► '''Example 2''': [[File:Sorting2.png|thumb|600px|none|''Figure 20: Descending sort of the column "brandNm"'']]

== Copyright Notice ==
{{Copyright Notice}}

== License information ==

{{License information}}

File:RefBrandtypeId1.png

2018-01-23T09:38:25Z

Worayeno: Worayeno uploaded a new version of File:RefBrandtypeId1.png

File:Brandtypeid.png

2018-01-23T09:23:38Z

Worayeno: Worayeno uploaded a new version of File:Brandtypeid.png

File:RefEntBrand.png

2018-01-23T09:20:12Z

Worayeno:

AppUpIn5Extensions

2018-01-23T09:19:48Z

Worayeno: /* Reference */

==Purpose==

The purpose of this document is to describe the first set of functional extensions of the CSV2App module presented in the [[App up in 5 minutes]] page, which will be available with the next release version.

=== OSBP applications===

The OSBP application '''My1App''' should already have been generated before starting this app.
You can find the instructions [http://download.osbee.org/documentation/index.php/My_first_app here].

=== CSV-file ===

You may use the two following files as reference files [http://download.osbee.org/downloads/samples/documentation/BrandType.csv BrandType.csv] and [http://download.osbee.org/downloads/samples/documentation/Brand.csv Brand.csv].

== ''AppUpIn5 - Extensions 1.0'' ==

You get access to those new functionalities by opening a csv file with the CSV2App module editor of the OS.bee Software Factory, and by making a left mouse click on the column you wish to edit the metadata from.

 [[File:Brandtype.png|none|frame|''Figure 1: Brandtype.csv im CSV2 Editor'']] 

The settings dialog of the corresponding column will then appear. The several options provided in this dialog are organized in two parts: the meta data section and the sorting section.

 [[File:Settingdialog.png|frame|none|''Figure 2: Settings dialog of column "id"'']] 

The sorting options are always available to the user, whereas the meta data options are only available based on the analysis of the type of data contained in the selected column.

==Metadata options==
The metadata section allows users to set additional information related to the entity that will be created, based on the content of a csv file and existing dsl model files.

===Id===
With the option ''ID'' you are able to define the column representing the unique identifier data of an entity. An entity has always one identification key, also known as primary key, which is here a ''Universal Unique Identifier'' (UUID), a unique alphanumerical string. Only columns having this type of data can be defined by the user as ''ID''-columns.

With a left mouse click on the column named ''id'' of the csv file ''BrandType.csv'', the user opens the settings dialog of this column.

 [[File:SettingsID.png|frame|none|''Figure 3: Settings dialog column "id" of Brandtype'']] 

(1) By selecting the ''ID'' checkbox, (2) and then pressing the OK button, the user set the column ''id'' as the ''ID''-column of the entity created later on, like shown on the figure below. Each entity has always one UUID attribute, therefore each csv file must have one ''ID''-column. The generated code later on will look like this snippet on figure 4.

 [[File:Brandtypeid.png|frame|none|''Figure 4: Entity dsl model - "id" attribute of Brandtype'']] 

===Reference===
With the reference option you are able to set column data as reference data (or foreign key) pointing to the ''Universal Unique Identifier'' (primary key) of another '''already existing entity'''. These data are also alphanumerical values, as mentioned in the section above concerning the id-option.

 [[File:RefArea.png|frame|none|''Figure 5: Reference area.'']] 

A reference column results into the creation of a 1-n relation between the new entity, which will be created on the basis of the considered csv file and the referenced entity, which already exists in the entity model file of your project. The condition of having this target entity to be referenced on already existing in the model translates into a specific '''order of execution''' of the application creation: successively pressing the button ''Create App'' in the right order to be able to choose the target entity.

For instance, we would like to create a reference between the entity ''Brandtype'' and the new entity to be created ''Brand'', whose csv file contains the ''brandTypeId'' as column. As you can see on the left side of figure 6, showing the content of the entity dsl model file, the entity ''Brandtype'' has already been created.

 [[File:RefEntBrand.png|thumb|600px|none|''Figure 6: Entity model file and Brand.csv file.'']] 

(1) By selecting the reference checkbox, (2) selecting ''Brandtype'' in the list of all existing entities, (3) and then by pressing the OK button, the user set the column ''brandTypeId'' as a reference key pointing to the UUID of the entity ''Brandtype''.

 [[File:RefBrandtypeId.png|thumb|600px|none|''Figure 7: Settings dialog column "brandTypeId" of Brand'']] 

The result of this relation at the end of the app creation would then look like this.

 [[File:RefBrandtypeId1.png|thumb|600px|none|''Figure 8: Reference result on "brandTypeId"'']] 

The optional tag <code>cascade</code> allows, when selected, the deletion of all elements of the n-side of the relation, when the one-side element is deleted. In our example, the removal of one brand type would then result to the deletion of all the brands categorized by that type. The generated relation would then look like this in contrast to last example.

 [[File:RefBrandtypeId2.png|thumb|600px|none|''Figure 9: Reference result on "brandTypeId"'']] 

Besides the fact that here 1-n relations are created between entities, a reference attribute will also be generated in each entity. This is needed in order to show the information data of each relation graphically (here as table) in the application interface. This is characterized by the use of a <code>properties{...}</code> block.

===Domain key===
The domain key option allows the user to set a user friendly identification search field for the application instead of UUIDs, since those are too cryptic for users to clearly distinguish data from each other.

Only column data from type string allow the user to define a column as the domain key column.

In the case of the entity ''Brandtype'', an adequate candidate for the domain key is the column ''brandTypeNm'' containing the names of brand types, which are easy for users to read and identify data from in the application later on.

(1) By selecting the domain key checkbox, (2) and then pressing the OK button, the user define the column ''brandTypeNm'' as the domain key column of the entity Brandtype.

 [[File:Brandtypenm.png|frame|none|''Figure 10: Settings dialog column "brandTypeNm" of Brandtype'']] 

This results into the creation of the domain key attribute of the entity ''Brandtype'' as shown on the figure below.

 [[File:BrandtypenmEntity.png|frame|none|''Figure 11: Domain key in entity dsl model'']] 

===Media data===
The media data option allows the user to define a column as a multimedia column. It allows user to specify from which columns information can be gathered from, in order to create the appropiate structures to store and upload any type of files in your application. This type of column contains the filenames of the multimedia files without extension. In addition to both the mime type and the extension, the user has also to define the directory path, where those files are located.

 [[File:Mediadata.png|thumb|600px|none|''Figure 12: Media data section'']] 

The currently supported mime types are the following: plain, jpg, mpeg, octetstream and pdf.
 [[File:Mediadata4.png|thumb|600px|none|''Figure 13: Mimetypes'']] 

The user can not just select one of the predefined extension formats (bmp, csv, jpg, mp3, pdf, txt, xml), but also edit an extension format on his own (java or sql...).

 [[File:Mediadata5.png|thumb|600px|none|''Figure 14: Extensions'']] 

An optional column name can be given by the user to set the name of the multimedia column, which will be additionally created to store these files based on the OS.bee [[BlobMapping]] data type. If not defined, the media column name will consist of the actual column name followed with the suffix '''media'''.

Only columns containing text data can be defined as media data column by the user.

 [[File:Mediadata1.png|thumb|600px|none|''Figure 15: Media data on column "bsin"'']] 

The column ''bsin'' of the entity Brand contains media file name. Besides being provided with the Brand.csv file, we also have the corresponding jpg-files illustrated here in figure 16.

 [[File:Mediadata2.png|thumb|600px|none|''Figure 16: Media file location'']] 

After opening the settings dialog of the column ''bsin'', (1) the user needs first to select the media data checkbox, which allows the modification of the information needed. (2) The user sets the path directory with the help of directory chooser, which appears after pressing the Path button and then selects the directory, in which the files are located. (3) The mime type and extension of the files have to be chosen within the corresponding combo boxes. (4) After pressing the OK button, the user sets the column ''bsin'' as a multimedia column. This will then result into the creation of both attributes ''bsin'' and ''bsinmedia'' of the entity Brand later on, as shown below.

 [[File:Mediadata3.png|thumb|600px|none|''Figure 17: Blobmapping attribute in entity Brand'']] 

==General Notice==
As soon as the user press the button "Create App", an error message will eventually be displayed to inform the user to complete or adapt the metadata configuration of the considered csv file.
* '''Please note that a proper configuration of column definitions has to be done by the user as soon as id, reference or domain keys candidates have been detected.''' Candidates are columns of a csv file, which meet the criteria for either an id, a reference (both from alphanumerical string with UUID format as described above) or a domain key column. Setting the metadata of those columns is then '''mandatory'''.

*'''A universal unique identifier (UUID) will be automatically generated by the OS.bee Software Factory for an entity only in the case, in which no id-column candidates are available in a csv file.'''

* '''Please note that all configurations made by the user in one csv file are immediately lost, as soon as the user close the file from the CSV2App module editor or by restarting the eclipse IDE.'''

Further information over the usage of metadata such as '''id''', '''reference''' and '''domain key''' can be found in the [[Entity DSL]] documentation page.

==Sorting options==
The sorting section allows you to sort the csv data within the editor. The selected column data can be sorted either in an ascending or a descending order.
 [[File:Sorting.png|frame|none|''Figure 18: Sorting options'']]

The following examples show you how to use the sort functions by applying it on the column ''brandNm'' of the provided [[#files|Brand.csv]] file. After you opened it in the CSV2App module editor within your eclipse workspace (for example via drag-n-drop), (1) make a left-mouse click on the column ''brandNm'', (2) choose either the ascending (figure 19) or the descending (figure 20) option in the sorting section, (3) and then press the OK button to trigger to the sorting of the column data. (4) You can observe the resulting sorted column data on the right side of both figures below.

► '''Example 1''': [[File:Sorting1.png|thumb|600px|none|''Figure 19: Ascending sort of the column "brandNm"'']]

► '''Example 2''': [[File:Sorting2.png|thumb|600px|none|''Figure 20: Descending sort of the column "brandNm"'']]

== Copyright Notice ==
{{Copyright Notice}}

== License information ==

{{License information}}

File:RefEntityBrand.png

2018-01-23T09:17:28Z

Worayeno: Worayeno uploaded a new version of File:RefEntityBrand.png

AppUpIn5Extensions

2018-01-23T09:13:32Z

Worayeno: /* Metadata options */

==Purpose==

The purpose of this document is to describe the first set of functional extensions of the CSV2App module presented in the [[App up in 5 minutes]] page, which will be available with the next release version.

=== OSBP applications===

The OSBP application '''My1App''' should already have been generated before starting this app.
You can find the instructions [http://download.osbee.org/documentation/index.php/My_first_app here].

=== CSV-file ===

You may use the two following files as reference files [http://download.osbee.org/downloads/samples/documentation/BrandType.csv BrandType.csv] and [http://download.osbee.org/downloads/samples/documentation/Brand.csv Brand.csv].

== ''AppUpIn5 - Extensions 1.0'' ==

You get access to those new functionalities by opening a csv file with the CSV2App module editor of the OS.bee Software Factory, and by making a left mouse click on the column you wish to edit the metadata from.

 [[File:Brandtype.png|none|frame|''Figure 1: Brandtype.csv im CSV2 Editor'']] 

The settings dialog of the corresponding column will then appear. The several options provided in this dialog are organized in two parts: the meta data section and the sorting section.

 [[File:Settingdialog.png|frame|none|''Figure 2: Settings dialog of column "id"'']] 

The sorting options are always available to the user, whereas the meta data options are only available based on the analysis of the type of data contained in the selected column.

==Metadata options==
The metadata section allows users to set additional information related to the entity that will be created, based on the content of a csv file and existing dsl model files.

===Id===
With the option ''ID'' you are able to define the column representing the unique identifier data of an entity. An entity has always one identification key, also known as primary key, which is here a ''Universal Unique Identifier'' (UUID), a unique alphanumerical string. Only columns having this type of data can be defined by the user as ''ID''-columns.

With a left mouse click on the column named ''id'' of the csv file ''BrandType.csv'', the user opens the settings dialog of this column.

 [[File:SettingsID.png|frame|none|''Figure 3: Settings dialog column "id" of Brandtype'']] 

(1) By selecting the ''ID'' checkbox, (2) and then pressing the OK button, the user set the column ''id'' as the ''ID''-column of the entity created later on, like shown on the figure below. Each entity has always one UUID attribute, therefore each csv file must have one ''ID''-column. The generated code later on will look like this snippet on figure 4.

 [[File:Brandtypeid.png|frame|none|''Figure 4: Entity dsl model - "id" attribute of Brandtype'']] 

===Reference===
With the reference option you are able to set column data as reference data (or foreign key) pointing to the ''Universal Unique Identifier'' (primary key) of another '''already existing entity'''. These data are also alphanumerical values, as mentioned in the section above concerning the id-option.

 [[File:RefArea.png|frame|none|''Figure 5: Reference area.'']] 

A reference column results into the creation of a 1-n relation between the new entity, which will be created on the basis of the considered csv file and the referenced entity, which already exists in the entity model file of your project. The condition of having this target entity to be referenced on already existing in the model translates into a specific '''order of execution''' of the application creation: successively pressing the button ''Create App'' in the right order to be able to choose the target entity.

For instance, we would like to create a reference between the entity ''Brandtype'' and the new entity to be created ''Brand'', whose csv file contains the ''brandTypeId'' as column. As you can see on the left side of figure 6, showing the content of the entity dsl model file, the entity ''Brandtype'' has already been created.

 [[File:RefEntityBrand.png|thumb|600px|none|''Figure 6: Entity model file and Brand.csv file.'']] 

(1) By selecting the reference checkbox, (2) selecting ''Brandtype'' in the list of all existing entities, (3) and then by pressing the OK button, the user set the column ''brandTypeId'' as a reference key pointing to the UUID of the entity ''Brandtype''.

 [[File:RefBrandtypeId.png|thumb|600px|none|''Figure 7: Settings dialog column "brandTypeId" of Brand'']] 

The result of this relation at the end of the app creation would then look like this.

 [[File:RefBrandtypeId1.png|thumb|600px|none|''Figure 8: Reference result on "brandTypeId"'']] 

The optional tag <code>cascade</code> allows, when selected, the deletion of all elements of the n-side of the relation, when the one-side element is deleted. In our example, the removal of one brand type would then result to the deletion of all the brands categorized by that type. The generated relation would then look like this in contrast to last example.

 [[File:RefBrandtypeId2.png|thumb|600px|none|''Figure 9: Reference result on "brandTypeId"'']] 

Besides the fact that here 1-n relations are created between entities, a reference attribute will also be generated in each entity. This is needed in order to show the information data of each relation graphically (here as table) in the application interface. This is characterized by the use of a <code>properties{...}</code> block.

===Domain key===
The domain key option allows the user to set a user friendly identification search field for the application instead of UUIDs, since those are too cryptic for users to clearly distinguish data from each other.

Only column data from type string allow the user to define a column as the domain key column.

In the case of the entity ''Brandtype'', an adequate candidate for the domain key is the column ''brandTypeNm'' containing the names of brand types, which are easy for users to read and identify data from in the application later on.

(1) By selecting the domain key checkbox, (2) and then pressing the OK button, the user define the column ''brandTypeNm'' as the domain key column of the entity Brandtype.

 [[File:Brandtypenm.png|frame|none|''Figure 10: Settings dialog column "brandTypeNm" of Brandtype'']] 

This results into the creation of the domain key attribute of the entity ''Brandtype'' as shown on the figure below.

 [[File:BrandtypenmEntity.png|frame|none|''Figure 11: Domain key in entity dsl model'']] 

===Media data===
The media data option allows the user to define a column as a multimedia column. It allows user to specify from which columns information can be gathered from, in order to create the appropiate structures to store and upload any type of files in your application. This type of column contains the filenames of the multimedia files without extension. In addition to both the mime type and the extension, the user has also to define the directory path, where those files are located.

 [[File:Mediadata.png|thumb|600px|none|''Figure 12: Media data section'']] 

The currently supported mime types are the following: plain, jpg, mpeg, octetstream and pdf.
 [[File:Mediadata4.png|thumb|600px|none|''Figure 13: Mimetypes'']] 

The user can not just select one of the predefined extension formats (bmp, csv, jpg, mp3, pdf, txt, xml), but also edit an extension format on his own (java or sql...).

 [[File:Mediadata5.png|thumb|600px|none|''Figure 14: Extensions'']] 

An optional column name can be given by the user to set the name of the multimedia column, which will be additionally created to store these files based on the OS.bee [[BlobMapping]] data type. If not defined, the media column name will consist of the actual column name followed with the suffix '''media'''.

Only columns containing text data can be defined as media data column by the user.

 [[File:Mediadata1.png|thumb|600px|none|''Figure 15: Media data on column "bsin"'']] 

The column ''bsin'' of the entity Brand contains media file name. Besides being provided with the Brand.csv file, we also have the corresponding jpg-files illustrated here in figure 16.

 [[File:Mediadata2.png|thumb|600px|none|''Figure 16: Media file location'']] 

After opening the settings dialog of the column ''bsin'', (1) the user needs first to select the media data checkbox, which allows the modification of the information needed. (2) The user sets the path directory with the help of directory chooser, which appears after pressing the Path button and then selects the directory, in which the files are located. (3) The mime type and extension of the files have to be chosen within the corresponding combo boxes. (4) After pressing the OK button, the user sets the column ''bsin'' as a multimedia column. This will then result into the creation of both attributes ''bsin'' and ''bsinmedia'' of the entity Brand later on, as shown below.

 [[File:Mediadata3.png|thumb|600px|none|''Figure 17: Blobmapping attribute in entity Brand'']] 

==General Notice==
As soon as the user press the button "Create App", an error message will eventually be displayed to inform the user to complete or adapt the metadata configuration of the considered csv file.
* '''Please note that a proper configuration of column definitions has to be done by the user as soon as id, reference or domain keys candidates have been detected.''' Candidates are columns of a csv file, which meet the criteria for either an id, a reference (both from alphanumerical string with UUID format as described above) or a domain key column. Setting the metadata of those columns is then '''mandatory'''.

*'''A universal unique identifier (UUID) will be automatically generated by the OS.bee Software Factory for an entity only in the case, in which no id-column candidates are available in a csv file.'''

* '''Please note that all configurations made by the user in one csv file are immediately lost, as soon as the user close the file from the CSV2App module editor or by restarting the eclipse IDE.'''

Further information over the usage of metadata such as '''id''', '''reference''' and '''domain key''' can be found in the [[Entity DSL]] documentation page.

==Sorting options==
The sorting section allows you to sort the csv data within the editor. The selected column data can be sorted either in an ascending or a descending order.
 [[File:Sorting.png|frame|none|''Figure 18: Sorting options'']]

The following examples show you how to use the sort functions by applying it on the column ''brandNm'' of the provided [[#files|Brand.csv]] file. After you opened it in the CSV2App module editor within your eclipse workspace (for example via drag-n-drop), (1) make a left-mouse click on the column ''brandNm'', (2) choose either the ascending (figure 19) or the descending (figure 20) option in the sorting section, (3) and then press the OK button to trigger to the sorting of the column data. (4) You can observe the resulting sorted column data on the right side of both figures below.

► '''Example 1''': [[File:Sorting1.png|thumb|600px|none|''Figure 19: Ascending sort of the column "brandNm"'']]

► '''Example 2''': [[File:Sorting2.png|thumb|600px|none|''Figure 20: Descending sort of the column "brandNm"'']]

== Copyright Notice ==
{{Copyright Notice}}

== License information ==

{{License information}}

AppUpIn5Extensions

2018-01-23T09:11:13Z

Worayeno: /* AppUpIn5 - Extensions 1.0 */

==Purpose==

The purpose of this document is to describe the first set of functional extensions of the CSV2App module presented in the [[App up in 5 minutes]] page, which will be available with the next release version.

=== OSBP applications===

The OSBP application '''My1App''' should already have been generated before starting this app.
You can find the instructions [http://download.osbee.org/documentation/index.php/My_first_app here].

=== CSV-file ===

You may use the two following files as reference files [http://download.osbee.org/downloads/samples/documentation/BrandType.csv BrandType.csv] and [http://download.osbee.org/downloads/samples/documentation/Brand.csv Brand.csv].

== ''AppUpIn5 - Extensions 1.0'' ==

You get access to those new functionalities by opening a csv file with the CSV2App module editor of the OS.bee Software Factory, and by making a left mouse click on the column you wish to edit the metadata from.

 [[File:Brandtype.png|none|frame|''Figure 1: Brandtype.csv im CSV2 Editor'']] 

The settings dialog of the corresponding column will then appear. The several options provided in this dialog are organized in two parts: the meta data section and the sorting section.

 [[File:Settingdialog.png|frame|none|''Figure 2: Settings dialog of column "id"'']] 

The sorting options are always available to the user, whereas the meta data options are only available based on the analysis of the type of data contained in the selected column.

==Metadata options==
The metadata section allows users to set additional information related to the entity that will be created, based on the content of a csv file and existing dsl model files.

===Id===
With the option ''ID'' you are able to define the column representing the unique identifier data of an entity. An entity has always one identification key, also known as primary key, which is here a ''Universal Unique Identifier'' (UUID), a unique alphanumerical string. Only columns having this type of data can be defined by the user as ''ID''-columns.

With a left mouse click on the column named ''id'' of the csv file ''BrandType.csv'', the user opens the settings dialog of this column.

 [[File:SettingsID.png|frame|none|''Figure 3: Settings dialog column "id" of Brandtype'']]

(1) By selecting the ''ID'' checkbox, (2) and then pressing the OK button, the user set the column ''id'' as the ''ID''-column of the entity created later on, like shown on the figure below. Each entity has always one UUID attribute, therefore each csv file must have one ''ID''-column. The generated code later on will look like this snippet on figure 4.

 [[File:Brandtypeid.png|frame|none|''Figure 4: Entity dsl model - "id" attribute of Brandtype'']]

===Reference===
With the reference option you are able to set column data as reference data (or foreign key) pointing to the ''Universal Unique Identifier'' (primary key) of another '''already existing entity'''. These data are also alphanumerical values, as mentioned in the section above concerning the id-option.

 [[File:RefArea.png|frame|none|''Figure 5: Reference area.'']]

A reference column results into the creation of a 1-n relation between the new entity, which will be created on the basis of the considered csv file and the referenced entity, which already exists in the entity model file of your project. The condition of having this target entity to be referenced on already existing in the model translates into a specific '''order of execution''' of the application creation: successively pressing the button ''Create App'' in the right order to be able to choose the target entity.

For instance, we would like to create a reference between the entity ''Brandtype'' and the new entity to be created ''Brand'', whose csv file contains the ''brandTypeId'' as column. As you can see on the left side of figure 6, showing the content of the entity dsl model file, the entity ''Brandtype'' has already been created.

 [[File:RefEntityBrand.png|thumb|600px|none|''Figure 6: Entity model file and Brand.csv file.'']]

(1) By selecting the reference checkbox, (2) selecting ''Brandtype'' in the list of all existing entities, (3) and then by pressing the OK button, the user set the column ''brandTypeId'' as a reference key pointing to the UUID of the entity ''Brandtype''.

 [[File:RefBrandtypeId.png|thumb|600px|none|''Figure 7: Settings dialog column "brandTypeId" of Brand'']]

The result of this relation at the end of the app creation would then look like this.

 [[File:RefBrandtypeId1.png|thumb|600px|none|''Figure 8: Reference result on "brandTypeId"'']]

The optional tag <code>cascade</code> allows, when selected, the deletion of all elements of the n-side of the relation, when the one-side element is deleted. In our example, the removal of one brand type would then result to the deletion of all the brands categorized by that type. The generated relation would then look like this in contrast to last example.

 [[File:RefBrandtypeId2.png|thumb|600px|none|''Figure 9: Reference result on "brandTypeId"'']]

Besides the fact that here 1-n relations are created between entities, a reference attribute will also be generated in each entity. This is needed in order to show the information data of each relation graphically (here as table) in the application interface. This is characterized by the use of a <code>properties{...}</code> block.

===Domain key===
The domain key option allows the user to set a user friendly identification search field for the application instead of UUIDs, since those are too cryptic for users to clearly distinguish data from each other.

Only column data from type string allow the user to define a column as the domain key column.

In the case of the entity ''Brandtype'', an adequate candidate for the domain key is the column ''brandTypeNm'' containing the names of brand types, which are easy for users to read and identify data from in the application later on.

(1) By selecting the domain key checkbox, (2) and then pressing the OK button, the user define the column ''brandTypeNm'' as the domain key column of the entity Brandtype.

 [[File:Brandtypenm.png|frame|none|''Figure 10: Settings dialog column "brandTypeNm" of Brandtype'']]

This results into the creation of the domain key attribute of the entity ''Brandtype'' as shown on the figure below.

 [[File:BrandtypenmEntity.png|frame|none|''Figure 11: Domain key in entity dsl model'']]

===Media data===
The media data option allows the user to define a column as a multimedia column. It allows user to specify from which columns information can be gathered from, in order to create the appropiate structures to store and upload any type of files in your application. This type of column contains the filenames of the multimedia files without extension. In addition to both the mime type and the extension, the user has also to define the directory path, where those files are located.

 [[File:Mediadata.png|thumb|600px|none|''Figure 12: Media data section'']]

The currently supported mime types are the following: plain, jpg, mpeg, octetstream and pdf.
 [[File:Mediadata4.png|thumb|600px|none|''Figure 13: Mimetypes'']]

The user can not just select one of the predefined extension formats (bmp, csv, jpg, mp3, pdf, txt, xml), but also edit an extension format on his own (java or sql...).
 [[File:Mediadata5.png|thumb|600px|none|''Figure 14: Extensions'']]

An optional column name can be given by the user to set the name of the multimedia column, which will be additionally created to store these files based on the OS.bee [[BlobMapping]] data type. If not defined, the media column name will consist of the actual column name followed with the suffix '''media'''.

Only columns containing text data can be defined as media data column by the user.

 [[File:Mediadata1.png|thumb|600px|none|''Figure 15: Media data on column "bsin"'']]

The column ''bsin'' of the entity Brand contains media file name. Besides being provided with the Brand.csv file, we also have the corresponding jpg-files illustrated here in figure 16.

 [[File:Mediadata2.png|thumb|600px|none|''Figure 16: Media file location'']]

After opening the settings dialog of the column ''bsin'', (1) the user needs first to select the media data checkbox, which allows the modification of the information needed. (2) The user sets the path directory with the help of directory chooser, which appears after pressing the Path button and then selects the directory, in which the files are located. (3) The mime type and extension of the files have to be chosen within the corresponding combo boxes. (4) After pressing the OK button, the user sets the column ''bsin'' as a multimedia column. This will then result into the creation of both attributes ''bsin'' and ''bsinmedia'' of the entity Brand later on, as shown below.

 [[File:Mediadata3.png|thumb|600px|none|''Figure 17: Blobmapping attribute in entity Brand'']]

==General Notice==
As soon as the user press the button "Create App", an error message will eventually be displayed to inform the user to complete or adapt the metadata configuration of the considered csv file.
* '''Please note that a proper configuration of column definitions has to be done by the user as soon as id, reference or domain keys candidates have been detected.''' Candidates are columns of a csv file, which meet the criteria for either an id, a reference (both from alphanumerical string with UUID format as described above) or a domain key column. Setting the metadata of those columns is then '''mandatory'''.

*'''A universal unique identifier (UUID) will be automatically generated by the OS.bee Software Factory for an entity only in the case, in which no id-column candidates are available in a csv file.'''

* '''Please note that all configurations made by the user in one csv file are immediately lost, as soon as the user close the file from the CSV2App module editor or by restarting the eclipse IDE.'''

Further information over the usage of metadata such as '''id''', '''reference''' and '''domain key''' can be found in the [[Entity DSL]] documentation page.

==Sorting options==
The sorting section allows you to sort the csv data within the editor. The selected column data can be sorted either in an ascending or a descending order.
 [[File:Sorting.png|frame|none|''Figure 18: Sorting options'']]

The following examples show you how to use the sort functions by applying it on the column ''brandNm'' of the provided [[#files|Brand.csv]] file. After you opened it in the CSV2App module editor within your eclipse workspace (for example via drag-n-drop), (1) make a left-mouse click on the column ''brandNm'', (2) choose either the ascending (figure 19) or the descending (figure 20) option in the sorting section, (3) and then press the OK button to trigger to the sorting of the column data. (4) You can observe the resulting sorted column data on the right side of both figures below.

► '''Example 1''': [[File:Sorting1.png|thumb|600px|none|''Figure 19: Ascending sort of the column "brandNm"'']]

► '''Example 2''': [[File:Sorting2.png|thumb|600px|none|''Figure 20: Descending sort of the column "brandNm"'']]

== Copyright Notice ==
{{Copyright Notice}}

== License information ==

{{License information}}

AppUpIn5Extensions

2018-01-23T09:10:29Z

Worayeno: /* AppUpIn5 - Extensions 1.0 */

==Purpose==

The purpose of this document is to describe the first set of functional extensions of the CSV2App module presented in the [[App up in 5 minutes]] page, which will be available with the next release version.

=== OSBP applications===

The OSBP application '''My1App''' should already have been generated before starting this app.
You can find the instructions [http://download.osbee.org/documentation/index.php/My_first_app here].

=== CSV-file ===

You may use the two following files as reference files [http://download.osbee.org/downloads/samples/documentation/BrandType.csv BrandType.csv] and [http://download.osbee.org/downloads/samples/documentation/Brand.csv Brand.csv].

== ''AppUpIn5 - Extensions 1.0'' ==

You get access to those new functionalities by opening a csv file with the CSV2App module editor of the OS.bee Software Factory, and by making a left mouse click on the column you wish to edit the metadata from.

 [[File:Brandtype.png|none|frame|''Figure 1: Brandtype.csv im CSV2 Editor'']]

The settings dialog of the corresponding column will then appear. The several options provided in this dialog are organized in two parts: the meta data section and the sorting section.

 [[File:Settingdialog.png|frame|none|''Figure 2: Settings dialog of column "id"'']]

The sorting options are always available to the user, whereas the meta data options are only available based on the analysis of the type of data contained in the selected column.

==Metadata options==
The metadata section allows users to set additional information related to the entity that will be created, based on the content of a csv file and existing dsl model files.

===Id===
With the option ''ID'' you are able to define the column representing the unique identifier data of an entity. An entity has always one identification key, also known as primary key, which is here a ''Universal Unique Identifier'' (UUID), a unique alphanumerical string. Only columns having this type of data can be defined by the user as ''ID''-columns.

With a left mouse click on the column named ''id'' of the csv file ''BrandType.csv'', the user opens the settings dialog of this column.

 [[File:SettingsID.png|frame|none|''Figure 3: Settings dialog column "id" of Brandtype'']]

(1) By selecting the ''ID'' checkbox, (2) and then pressing the OK button, the user set the column ''id'' as the ''ID''-column of the entity created later on, like shown on the figure below. Each entity has always one UUID attribute, therefore each csv file must have one ''ID''-column. The generated code later on will look like this snippet on figure 4.

 [[File:Brandtypeid.png|frame|none|''Figure 4: Entity dsl model - "id" attribute of Brandtype'']]

===Reference===
With the reference option you are able to set column data as reference data (or foreign key) pointing to the ''Universal Unique Identifier'' (primary key) of another '''already existing entity'''. These data are also alphanumerical values, as mentioned in the section above concerning the id-option.

 [[File:RefArea.png|frame|none|''Figure 5: Reference area.'']]

A reference column results into the creation of a 1-n relation between the new entity, which will be created on the basis of the considered csv file and the referenced entity, which already exists in the entity model file of your project. The condition of having this target entity to be referenced on already existing in the model translates into a specific '''order of execution''' of the application creation: successively pressing the button ''Create App'' in the right order to be able to choose the target entity.

For instance, we would like to create a reference between the entity ''Brandtype'' and the new entity to be created ''Brand'', whose csv file contains the ''brandTypeId'' as column. As you can see on the left side of figure 6, showing the content of the entity dsl model file, the entity ''Brandtype'' has already been created.

 [[File:RefEntityBrand.png|thumb|600px|none|''Figure 6: Entity model file and Brand.csv file.'']]

(1) By selecting the reference checkbox, (2) selecting ''Brandtype'' in the list of all existing entities, (3) and then by pressing the OK button, the user set the column ''brandTypeId'' as a reference key pointing to the UUID of the entity ''Brandtype''.

 [[File:RefBrandtypeId.png|thumb|600px|none|''Figure 7: Settings dialog column "brandTypeId" of Brand'']]

The result of this relation at the end of the app creation would then look like this.

 [[File:RefBrandtypeId1.png|thumb|600px|none|''Figure 8: Reference result on "brandTypeId"'']]

The optional tag <code>cascade</code> allows, when selected, the deletion of all elements of the n-side of the relation, when the one-side element is deleted. In our example, the removal of one brand type would then result to the deletion of all the brands categorized by that type. The generated relation would then look like this in contrast to last example.

 [[File:RefBrandtypeId2.png|thumb|600px|none|''Figure 9: Reference result on "brandTypeId"'']]

Besides the fact that here 1-n relations are created between entities, a reference attribute will also be generated in each entity. This is needed in order to show the information data of each relation graphically (here as table) in the application interface. This is characterized by the use of a <code>properties{...}</code> block.

===Domain key===
The domain key option allows the user to set a user friendly identification search field for the application instead of UUIDs, since those are too cryptic for users to clearly distinguish data from each other.

Only column data from type string allow the user to define a column as the domain key column.

In the case of the entity ''Brandtype'', an adequate candidate for the domain key is the column ''brandTypeNm'' containing the names of brand types, which are easy for users to read and identify data from in the application later on.

(1) By selecting the domain key checkbox, (2) and then pressing the OK button, the user define the column ''brandTypeNm'' as the domain key column of the entity Brandtype.

 [[File:Brandtypenm.png|frame|none|''Figure 10: Settings dialog column "brandTypeNm" of Brandtype'']]

This results into the creation of the domain key attribute of the entity ''Brandtype'' as shown on the figure below.

 [[File:BrandtypenmEntity.png|frame|none|''Figure 11: Domain key in entity dsl model'']]

===Media data===
The media data option allows the user to define a column as a multimedia column. It allows user to specify from which columns information can be gathered from, in order to create the appropiate structures to store and upload any type of files in your application. This type of column contains the filenames of the multimedia files without extension. In addition to both the mime type and the extension, the user has also to define the directory path, where those files are located.

 [[File:Mediadata.png|thumb|600px|none|''Figure 12: Media data section'']]

The currently supported mime types are the following: plain, jpg, mpeg, octetstream and pdf.
 [[File:Mediadata4.png|thumb|600px|none|''Figure 13: Mimetypes'']]

The user can not just select one of the predefined extension formats (bmp, csv, jpg, mp3, pdf, txt, xml), but also edit an extension format on his own (java or sql...).
 [[File:Mediadata5.png|thumb|600px|none|''Figure 14: Extensions'']]

An optional column name can be given by the user to set the name of the multimedia column, which will be additionally created to store these files based on the OS.bee [[BlobMapping]] data type. If not defined, the media column name will consist of the actual column name followed with the suffix '''media'''.

Only columns containing text data can be defined as media data column by the user.

 [[File:Mediadata1.png|thumb|600px|none|''Figure 15: Media data on column "bsin"'']]

The column ''bsin'' of the entity Brand contains media file name. Besides being provided with the Brand.csv file, we also have the corresponding jpg-files illustrated here in figure 16.

 [[File:Mediadata2.png|thumb|600px|none|''Figure 16: Media file location'']]

After opening the settings dialog of the column ''bsin'', (1) the user needs first to select the media data checkbox, which allows the modification of the information needed. (2) The user sets the path directory with the help of directory chooser, which appears after pressing the Path button and then selects the directory, in which the files are located. (3) The mime type and extension of the files have to be chosen within the corresponding combo boxes. (4) After pressing the OK button, the user sets the column ''bsin'' as a multimedia column. This will then result into the creation of both attributes ''bsin'' and ''bsinmedia'' of the entity Brand later on, as shown below.

 [[File:Mediadata3.png|thumb|600px|none|''Figure 17: Blobmapping attribute in entity Brand'']]

==General Notice==
As soon as the user press the button "Create App", an error message will eventually be displayed to inform the user to complete or adapt the metadata configuration of the considered csv file.
* '''Please note that a proper configuration of column definitions has to be done by the user as soon as id, reference or domain keys candidates have been detected.''' Candidates are columns of a csv file, which meet the criteria for either an id, a reference (both from alphanumerical string with UUID format as described above) or a domain key column. Setting the metadata of those columns is then '''mandatory'''.

*'''A universal unique identifier (UUID) will be automatically generated by the OS.bee Software Factory for an entity only in the case, in which no id-column candidates are available in a csv file.'''

* '''Please note that all configurations made by the user in one csv file are immediately lost, as soon as the user close the file from the CSV2App module editor or by restarting the eclipse IDE.'''

Further information over the usage of metadata such as '''id''', '''reference''' and '''domain key''' can be found in the [[Entity DSL]] documentation page.

==Sorting options==
The sorting section allows you to sort the csv data within the editor. The selected column data can be sorted either in an ascending or a descending order.
 [[File:Sorting.png|frame|none|''Figure 18: Sorting options'']]

The following examples show you how to use the sort functions by applying it on the column ''brandNm'' of the provided [[#files|Brand.csv]] file. After you opened it in the CSV2App module editor within your eclipse workspace (for example via drag-n-drop), (1) make a left-mouse click on the column ''brandNm'', (2) choose either the ascending (figure 19) or the descending (figure 20) option in the sorting section, (3) and then press the OK button to trigger to the sorting of the column data. (4) You can observe the resulting sorted column data on the right side of both figures below.

► '''Example 1''': [[File:Sorting1.png|thumb|600px|none|''Figure 19: Ascending sort of the column "brandNm"'']]

► '''Example 2''': [[File:Sorting2.png|thumb|600px|none|''Figure 20: Descending sort of the column "brandNm"'']]

== Copyright Notice ==
{{Copyright Notice}}

== License information ==

{{License information}}

File:Brandtypeid.png

2018-01-23T08:51:41Z

Worayeno:

AppUpIn5Extensions

2018-01-23T08:51:23Z

Worayeno: /* Id */

==Purpose==

The purpose of this document is to describe the first set of functional extensions of the CSV2App module presented in the [[App up in 5 minutes]] page, which will be available with the next release version.

=== OSBP applications===

The OSBP application '''My1App''' should already have been generated before starting this app.
You can find the instructions [http://download.osbee.org/documentation/index.php/My_first_app here].

=== CSV-file ===

You may use the two following files as reference files [http://download.osbee.org/downloads/samples/documentation/BrandType.csv BrandType.csv] and [http://download.osbee.org/downloads/samples/documentation/Brand.csv Brand.csv].

== ''AppUpIn5 - Extensions 1.0'' ==

You get access to those new functionalities by opening a csv file with the CSV2App module editor of the OS.bee Software Factory, and by making a left mouse click on the column you wish to edit the metadata from.
 [[File:Brandtype.png|none|frame|''Figure 1: Brandtype.csv im CSV2 Editor'']]

The setting dialog of the corresponding column will appear and several options will be available for you to choose, based on the analysis of the type of data contained in this column and the configurations you would have made so far.
 [[File:Settingdialog.png|frame|none|''Figure 2: Settings dialog of column "id"'']]

==Metadata options==
The metadata section allows users to set additional information related to the entity that will be created, based on the content of a csv file and existing dsl model files.

===Id===
With the option ''ID'' you are able to define the column representing the unique identifier data of an entity. An entity has always one identification key, also known as primary key, which is here a ''Universal Unique Identifier'' (UUID), a unique alphanumerical string. Only columns having this type of data can be defined by the user as ''ID''-columns.

With a left mouse click on the column named ''id'' of the csv file ''BrandType.csv'', the user opens the settings dialog of this column.

 [[File:SettingsID.png|frame|none|''Figure 3: Settings dialog column "id" of Brandtype'']]

(1) By selecting the ''ID'' checkbox, (2) and then pressing the OK button, the user set the column ''id'' as the ''ID''-column of the entity created later on, like shown on the figure below. Each entity has always one UUID attribute, therefore each csv file must have one ''ID''-column. The generated code later on will look like this snippet on figure 4.

 [[File:Brandtypeid.png|frame|none|''Figure 4: Entity dsl model - "id" attribute of Brandtype'']]

===Reference===
With the reference option you are able to set column data as reference data (or foreign key) pointing to the ''Universal Unique Identifier'' (primary key) of another '''already existing entity'''. These data are also alphanumerical values, as mentioned in the section above concerning the id-option.

 [[File:RefArea.png|frame|none|''Figure 5: Reference area.'']]

A reference column results into the creation of a 1-n relation between the new entity, which will be created on the basis of the considered csv file and the referenced entity, which already exists in the entity model file of your project. The condition of having this target entity to be referenced on already existing in the model translates into a specific '''order of execution''' of the application creation: successively pressing the button ''Create App'' in the right order to be able to choose the target entity.

For instance, we would like to create a reference between the entity ''Brandtype'' and the new entity to be created ''Brand'', whose csv file contains the ''brandTypeId'' as column. As you can see on the left side of figure 6, showing the content of the entity dsl model file, the entity ''Brandtype'' has already been created.

 [[File:RefEntityBrand.png|thumb|600px|none|''Figure 6: Entity model file and Brand.csv file.'']]

(1) By selecting the reference checkbox, (2) selecting ''Brandtype'' in the list of all existing entities, (3) and then by pressing the OK button, the user set the column ''brandTypeId'' as a reference key pointing to the UUID of the entity ''Brandtype''.

 [[File:RefBrandtypeId.png|thumb|600px|none|''Figure 7: Settings dialog column "brandTypeId" of Brand'']]

The result of this relation at the end of the app creation would then look like this.

 [[File:RefBrandtypeId1.png|thumb|600px|none|''Figure 8: Reference result on "brandTypeId"'']]

The optional tag <code>cascade</code> allows, when selected, the deletion of all elements of the n-side of the relation, when the one-side element is deleted. In our example, the removal of one brand type would then result to the deletion of all the brands categorized by that type. The generated relation would then look like this in contrast to last example.

 [[File:RefBrandtypeId2.png|thumb|600px|none|''Figure 9: Reference result on "brandTypeId"'']]

Besides the fact that here 1-n relations are created between entities, a reference attribute will also be generated in each entity. This is needed in order to show the information data of each relation graphically (here as table) in the application interface. This is characterized by the use of a <code>properties{...}</code> block.

===Domain key===
The domain key option allows the user to set a user friendly identification search field for the application instead of UUIDs, since those are too cryptic for users to clearly distinguish data from each other.

Only column data from type string allow the user to define a column as the domain key column.

In the case of the entity ''Brandtype'', an adequate candidate for the domain key is the column ''brandTypeNm'' containing the names of brand types, which are easy for users to read and identify data from in the application later on.

(1) By selecting the domain key checkbox, (2) and then pressing the OK button, the user define the column ''brandTypeNm'' as the domain key column of the entity Brandtype.

 [[File:Brandtypenm.png|frame|none|''Figure 10: Settings dialog column "brandTypeNm" of Brandtype'']]

This results into the creation of the domain key attribute of the entity ''Brandtype'' as shown on the figure below.

 [[File:BrandtypenmEntity.png|frame|none|''Figure 11: Domain key in entity dsl model'']]

===Media data===
The media data option allows the user to define a column as a multimedia column. It allows user to specify from which columns information can be gathered from, in order to create the appropiate structures to store and upload any type of files in your application. This type of column contains the filenames of the multimedia files without extension. In addition to both the mime type and the extension, the user has also to define the directory path, where those files are located.

 [[File:Mediadata.png|thumb|600px|none|''Figure 12: Media data section'']]

The currently supported mime types are the following: plain, jpg, mpeg, octetstream and pdf.
 [[File:Mediadata4.png|thumb|600px|none|''Figure 13: Mimetypes'']]

The user can not just select one of the predefined extension formats (bmp, csv, jpg, mp3, pdf, txt, xml), but also edit an extension format on his own (java or sql...).
 [[File:Mediadata5.png|thumb|600px|none|''Figure 14: Extensions'']]

An optional column name can be given by the user to set the name of the multimedia column, which will be additionally created to store these files based on the OS.bee [[BlobMapping]] data type. If not defined, the media column name will consist of the actual column name followed with the suffix '''media'''.

Only columns containing text data can be defined as media data column by the user.

 [[File:Mediadata1.png|thumb|600px|none|''Figure 15: Media data on column "bsin"'']]

The column ''bsin'' of the entity Brand contains media file name. Besides being provided with the Brand.csv file, we also have the corresponding jpg-files illustrated here in figure 16.

 [[File:Mediadata2.png|thumb|600px|none|''Figure 16: Media file location'']]

After opening the settings dialog of the column ''bsin'', (1) the user needs first to select the media data checkbox, which allows the modification of the information needed. (2) The user sets the path directory with the help of directory chooser, which appears after pressing the Path button and then selects the directory, in which the files are located. (3) The mime type and extension of the files have to be chosen within the corresponding combo boxes. (4) After pressing the OK button, the user sets the column ''bsin'' as a multimedia column. This will then result into the creation of both attributes ''bsin'' and ''bsinmedia'' of the entity Brand later on, as shown below.

 [[File:Mediadata3.png|thumb|600px|none|''Figure 17: Blobmapping attribute in entity Brand'']]

==General Notice==
As soon as the user press the button "Create App", an error message will eventually be displayed to inform the user to complete or adapt the metadata configuration of the considered csv file.
* '''Please note that a proper configuration of column definitions has to be done by the user as soon as id, reference or domain keys candidates have been detected.''' Candidates are columns of a csv file, which meet the criteria for either an id, a reference (both from alphanumerical string with UUID format as described above) or a domain key column. Setting the metadata of those columns is then '''mandatory'''.

*'''A universal unique identifier (UUID) will be automatically generated by the OS.bee Software Factory for an entity only in the case, in which no id-column candidates are available in a csv file.'''

* '''Please note that all configurations made by the user in one csv file are immediately lost, as soon as the user close the file from the CSV2App module editor or by restarting the eclipse IDE.'''

Further information over the usage of metadata such as '''id''', '''reference''' and '''domain key''' can be found in the [[Entity DSL]] documentation page.

==Sorting options==
The sorting section allows you to sort the csv data within the editor. The selected column data can be sorted either in an ascending or a descending order.
 [[File:Sorting.png|frame|none|''Figure 18: Sorting options'']]

The following examples show you how to use the sort functions by applying it on the column ''brandNm'' of the provided [[#files|Brand.csv]] file. After you opened it in the CSV2App module editor within your eclipse workspace (for example via drag-n-drop), (1) make a left-mouse click on the column ''brandNm'', (2) choose either the ascending (figure 19) or the descending (figure 20) option in the sorting section, (3) and then press the OK button to trigger to the sorting of the column data. (4) You can observe the resulting sorted column data on the right side of both figures below.

► '''Example 1''': [[File:Sorting1.png|thumb|600px|none|''Figure 19: Ascending sort of the column "brandNm"'']]

► '''Example 2''': [[File:Sorting2.png|thumb|600px|none|''Figure 20: Descending sort of the column "brandNm"'']]

== Copyright Notice ==
{{Copyright Notice}}

== License information ==

{{License information}}

File:Settingdialog.png

2018-01-23T08:49:40Z

Worayeno:

AppUpIn5Extensions

2018-01-23T08:49:20Z

Worayeno: /* AppUpIn5 - Extensions 1.0 */

==Purpose==

The purpose of this document is to describe the first set of functional extensions of the CSV2App module presented in the [[App up in 5 minutes]] page, which will be available with the next release version.

=== OSBP applications===

The OSBP application '''My1App''' should already have been generated before starting this app.
You can find the instructions [http://download.osbee.org/documentation/index.php/My_first_app here].

=== CSV-file ===

You may use the two following files as reference files [http://download.osbee.org/downloads/samples/documentation/BrandType.csv BrandType.csv] and [http://download.osbee.org/downloads/samples/documentation/Brand.csv Brand.csv].

== ''AppUpIn5 - Extensions 1.0'' ==

You get access to those new functionalities by opening a csv file with the CSV2App module editor of the OS.bee Software Factory, and by making a left mouse click on the column you wish to edit the metadata from.
 [[File:Brandtype.png|none|frame|''Figure 1: Brandtype.csv im CSV2 Editor'']]

The setting dialog of the corresponding column will appear and several options will be available for you to choose, based on the analysis of the type of data contained in this column and the configurations you would have made so far.
 [[File:Settingdialog.png|frame|none|''Figure 2: Settings dialog of column "id"'']]

==Metadata options==
The metadata section allows users to set additional information related to the entity that will be created, based on the content of a csv file and existing dsl model files.

===Id===
With the option ''ID'' you are able to define the column representing the unique identifier data of an entity. An entity has always one identification key, also known as primary key, which is here a ''Universal Unique Identifier'' (UUID), a unique alphanumerical string. Only columns having this type of data can be defined by the user as ''ID''-columns.

With a left mouse click on the column named ''id'' of the csv file ''BrandType.csv'', the user opens the settings dialog of this column.

 [[File:SettingsID.png|frame|none|''Figure 3: Settings dialog column "id" of Brandtype'']]

(1) By selecting the ''ID'' checkbox, (2) and then pressing the OK button, the user set the column ''id'' as the ''ID''-column of the entity created later on, like shown on the figure below. Each entity has always one UUID attribute, therefore each csv file must have one ''ID''-column. The generated code later on will look like this snippet on figure 4.

 [[File:ID.png|frame|none|''Figure 4: Entity dsl model - "id" attribute of Brandtype'']]

===Reference===
With the reference option you are able to set column data as reference data (or foreign key) pointing to the ''Universal Unique Identifier'' (primary key) of another '''already existing entity'''. These data are also alphanumerical values, as mentioned in the section above concerning the id-option.

 [[File:RefArea.png|frame|none|''Figure 5: Reference area.'']]

A reference column results into the creation of a 1-n relation between the new entity, which will be created on the basis of the considered csv file and the referenced entity, which already exists in the entity model file of your project. The condition of having this target entity to be referenced on already existing in the model translates into a specific '''order of execution''' of the application creation: successively pressing the button ''Create App'' in the right order to be able to choose the target entity.

For instance, we would like to create a reference between the entity ''Brandtype'' and the new entity to be created ''Brand'', whose csv file contains the ''brandTypeId'' as column. As you can see on the left side of figure 6, showing the content of the entity dsl model file, the entity ''Brandtype'' has already been created.

 [[File:RefEntityBrand.png|thumb|600px|none|''Figure 6: Entity model file and Brand.csv file.'']]

(1) By selecting the reference checkbox, (2) selecting ''Brandtype'' in the list of all existing entities, (3) and then by pressing the OK button, the user set the column ''brandTypeId'' as a reference key pointing to the UUID of the entity ''Brandtype''.

 [[File:RefBrandtypeId.png|thumb|600px|none|''Figure 7: Settings dialog column "brandTypeId" of Brand'']]

The result of this relation at the end of the app creation would then look like this.

 [[File:RefBrandtypeId1.png|thumb|600px|none|''Figure 8: Reference result on "brandTypeId"'']]

The optional tag <code>cascade</code> allows, when selected, the deletion of all elements of the n-side of the relation, when the one-side element is deleted. In our example, the removal of one brand type would then result to the deletion of all the brands categorized by that type. The generated relation would then look like this in contrast to last example.

 [[File:RefBrandtypeId2.png|thumb|600px|none|''Figure 9: Reference result on "brandTypeId"'']]

Besides the fact that here 1-n relations are created between entities, a reference attribute will also be generated in each entity. This is needed in order to show the information data of each relation graphically (here as table) in the application interface. This is characterized by the use of a <code>properties{...}</code> block.

===Domain key===
The domain key option allows the user to set a user friendly identification search field for the application instead of UUIDs, since those are too cryptic for users to clearly distinguish data from each other.

Only column data from type string allow the user to define a column as the domain key column.

In the case of the entity ''Brandtype'', an adequate candidate for the domain key is the column ''brandTypeNm'' containing the names of brand types, which are easy for users to read and identify data from in the application later on.

(1) By selecting the domain key checkbox, (2) and then pressing the OK button, the user define the column ''brandTypeNm'' as the domain key column of the entity Brandtype.

 [[File:Brandtypenm.png|frame|none|''Figure 10: Settings dialog column "brandTypeNm" of Brandtype'']]

This results into the creation of the domain key attribute of the entity ''Brandtype'' as shown on the figure below.

 [[File:BrandtypenmEntity.png|frame|none|''Figure 11: Domain key in entity dsl model'']]

===Media data===
The media data option allows the user to define a column as a multimedia column. It allows user to specify from which columns information can be gathered from, in order to create the appropiate structures to store and upload any type of files in your application. This type of column contains the filenames of the multimedia files without extension. In addition to both the mime type and the extension, the user has also to define the directory path, where those files are located.

 [[File:Mediadata.png|thumb|600px|none|''Figure 12: Media data section'']]

The currently supported mime types are the following: plain, jpg, mpeg, octetstream and pdf.
 [[File:Mediadata4.png|thumb|600px|none|''Figure 13: Mimetypes'']]

The user can not just select one of the predefined extension formats (bmp, csv, jpg, mp3, pdf, txt, xml), but also edit an extension format on his own (java or sql...).
 [[File:Mediadata5.png|thumb|600px|none|''Figure 14: Extensions'']]

An optional column name can be given by the user to set the name of the multimedia column, which will be additionally created to store these files based on the OS.bee [[BlobMapping]] data type. If not defined, the media column name will consist of the actual column name followed with the suffix '''media'''.

Only columns containing text data can be defined as media data column by the user.

 [[File:Mediadata1.png|thumb|600px|none|''Figure 15: Media data on column "bsin"'']]

The column ''bsin'' of the entity Brand contains media file name. Besides being provided with the Brand.csv file, we also have the corresponding jpg-files illustrated here in figure 16.

 [[File:Mediadata2.png|thumb|600px|none|''Figure 16: Media file location'']]

After opening the settings dialog of the column ''bsin'', (1) the user needs first to select the media data checkbox, which allows the modification of the information needed. (2) The user sets the path directory with the help of directory chooser, which appears after pressing the Path button and then selects the directory, in which the files are located. (3) The mime type and extension of the files have to be chosen within the corresponding combo boxes. (4) After pressing the OK button, the user sets the column ''bsin'' as a multimedia column. This will then result into the creation of both attributes ''bsin'' and ''bsinmedia'' of the entity Brand later on, as shown below.

 [[File:Mediadata3.png|thumb|600px|none|''Figure 17: Blobmapping attribute in entity Brand'']]

==General Notice==
As soon as the user press the button "Create App", an error message will eventually be displayed to inform the user to complete or adapt the metadata configuration of the considered csv file.
* '''Please note that a proper configuration of column definitions has to be done by the user as soon as id, reference or domain keys candidates have been detected.''' Candidates are columns of a csv file, which meet the criteria for either an id, a reference (both from alphanumerical string with UUID format as described above) or a domain key column. Setting the metadata of those columns is then '''mandatory'''.

*'''A universal unique identifier (UUID) will be automatically generated by the OS.bee Software Factory for an entity only in the case, in which no id-column candidates are available in a csv file.'''

* '''Please note that all configurations made by the user in one csv file are immediately lost, as soon as the user close the file from the CSV2App module editor or by restarting the eclipse IDE.'''

Further information over the usage of metadata such as '''id''', '''reference''' and '''domain key''' can be found in the [[Entity DSL]] documentation page.

==Sorting options==
The sorting section allows you to sort the csv data within the editor. The selected column data can be sorted either in an ascending or a descending order.
 [[File:Sorting.png|frame|none|''Figure 18: Sorting options'']]

The following examples show you how to use the sort functions by applying it on the column ''brandNm'' of the provided [[#files|Brand.csv]] file. After you opened it in the CSV2App module editor within your eclipse workspace (for example via drag-n-drop), (1) make a left-mouse click on the column ''brandNm'', (2) choose either the ascending (figure 19) or the descending (figure 20) option in the sorting section, (3) and then press the OK button to trigger to the sorting of the column data. (4) You can observe the resulting sorted column data on the right side of both figures below.

► '''Example 1''': [[File:Sorting1.png|thumb|600px|none|''Figure 19: Ascending sort of the column "brandNm"'']]

► '''Example 2''': [[File:Sorting2.png|thumb|600px|none|''Figure 20: Descending sort of the column "brandNm"'']]

== Copyright Notice ==
{{Copyright Notice}}

== License information ==

{{License information}}

File:Brandtype1.png

2018-01-23T08:48:06Z

Worayeno: Worayeno uploaded a new version of File:Brandtype1.png

File:ID.png

2018-01-23T08:43:10Z

Worayeno: Worayeno uploaded a new version of File:ID.png

File:ID.png

2018-01-23T08:42:48Z

Worayeno: Worayeno uploaded a new version of File:ID.png

File:Brandtype1.png

2018-01-23T08:41:10Z

Worayeno: Worayeno uploaded a new version of File:Brandtype1.png

File:ID.png

2018-01-23T08:40:40Z

Worayeno: Worayeno uploaded a new version of File:ID.png

File:Brandtype1.png

2018-01-23T08:35:14Z

Worayeno: Worayeno uploaded a new version of File:Brandtype1.png

File:Brandtype1.png

2018-01-23T08:34:17Z

Worayeno: Worayeno uploaded a new version of File:Brandtype1.png

File:Brandtype1.png

2018-01-23T08:33:43Z

Worayeno: Worayeno uploaded a new version of File:Brandtype1.png

File:Brandtype.png

2018-01-23T08:29:50Z

Worayeno: Worayeno uploaded a new version of File:Brandtype.png

AppUpIn5Extensions

2018-01-22T16:51:33Z

Worayeno:

==Purpose==

The purpose of this document is to describe the first set of functional extensions of the CSV2App module presented in the [[App up in 5 minutes]] page, which will be available with the next release version.

=== OSBP applications===

The OSBP application '''My1App''' should already have been generated before starting this app.
You can find the instructions [http://download.osbee.org/documentation/index.php/My_first_app here].

=== CSV-file ===

You may use the two following files as reference files [http://download.osbee.org/downloads/samples/documentation/BrandType.csv BrandType.csv] and [http://download.osbee.org/downloads/samples/documentation/Brand.csv Brand.csv].

== ''AppUpIn5 - Extensions 1.0'' ==

You get access to those new functionalities by opening a csv file with the CSV2App module editor of the OS.bee Software Factory, and by making a left mouse click on the column you wish to edit the metadata from.
 [[File:Brandtype.png|none|frame|''Figure 1: Brandtype.csv im CSV2 Editor'']]

The setting dialog of the corresponding column will appear and several options will be available for you to choose, based on the analysis of the type of data contained in this column and the configurations you would have made so far.
 [[File:Brandtype1.png|frame|none|''Figure 2: Settings dialog of column "id"'']]

==Metadata options==
The metadata section allows users to set additional information related to the entity that will be created, based on the content of a csv file and existing dsl model files.

===Id===
With the option ''ID'' you are able to define the column representing the unique identifier data of an entity. An entity has always one identification key, also known as primary key, which is here a ''Universal Unique Identifier'' (UUID), a unique alphanumerical string. Only columns having this type of data can be defined by the user as ''ID''-columns.

With a left mouse click on the column named ''id'' of the csv file ''BrandType.csv'', the user opens the settings dialog of this column.

 [[File:SettingsID.png|frame|none|''Figure 3: Settings dialog column "id" of Brandtype'']]

(1) By selecting the ''ID'' checkbox, (2) and then pressing the OK button, the user set the column ''id'' as the ''ID''-column of the entity created later on, like shown on the figure below. Each entity has always one UUID attribute, therefore each csv file must have one ''ID''-column. The generated code later on will look like this snippet on figure 4.

 [[File:ID.png|frame|none|''Figure 4: Entity dsl model - "id" attribute of Brandtype'']]

===Reference===
With the reference option you are able to set column data as reference data (or foreign key) pointing to the ''Universal Unique Identifier'' (primary key) of another '''already existing entity'''. These data are also alphanumerical values, as mentioned in the section above concerning the id-option.

 [[File:RefArea.png|frame|none|''Figure 5: Reference area.'']]

A reference column results into the creation of a 1-n relation between the new entity, which will be created on the basis of the considered csv file and the referenced entity, which already exists in the entity model file of your project. The condition of having this target entity to be referenced on already existing in the model translates into a specific '''order of execution''' of the application creation: successively pressing the button ''Create App'' in the right order to be able to choose the target entity.

For instance, we would like to create a reference between the entity ''Brandtype'' and the new entity to be created ''Brand'', whose csv file contains the ''brandTypeId'' as column. As you can see on the left side of figure 6, showing the content of the entity dsl model file, the entity ''Brandtype'' has already been created.

 [[File:RefEntityBrand.png|thumb|600px|none|''Figure 6: Entity model file and Brand.csv file.'']]

(1) By selecting the reference checkbox, (2) selecting ''Brandtype'' in the list of all existing entities, (3) and then by pressing the OK button, the user set the column ''brandTypeId'' as a reference key pointing to the UUID of the entity ''Brandtype''.

 [[File:RefBrandtypeId.png|thumb|600px|none|''Figure 7: Settings dialog column "brandTypeId" of Brand'']]

The result of this relation at the end of the app creation would then look like this.

 [[File:RefBrandtypeId1.png|thumb|600px|none|''Figure 8: Reference result on "brandTypeId"'']]

The optional tag <code>cascade</code> allows, when selected, the deletion of all elements of the n-side of the relation, when the one-side element is deleted. In our example, the removal of one brand type would then result to the deletion of all the brands categorized by that type. The generated relation would then look like this in contrast to last example.

 [[File:RefBrandtypeId2.png|thumb|600px|none|''Figure 9: Reference result on "brandTypeId"'']]

Besides the fact that here 1-n relations are created between entities, a reference attribute will also be generated in each entity. This is needed in order to show the information data of each relation graphically (here as table) in the application interface. This is characterized by the use of a <code>properties{...}</code> block.

===Domain key===
The domain key option allows the user to set a user friendly identification search field for the application instead of UUIDs, since those are too cryptic for users to clearly distinguish data from each other.

Only column data from type string allow the user to define a column as the domain key column.

In the case of the entity ''Brandtype'', an adequate candidate for the domain key is the column ''brandTypeNm'' containing the names of brand types, which are easy for users to read and identify data from in the application later on.

(1) By selecting the domain key checkbox, (2) and then pressing the OK button, the user define the column ''brandTypeNm'' as the domain key column of the entity Brandtype.

 [[File:Brandtypenm.png|frame|none|''Figure 10: Settings dialog column "brandTypeNm" of Brandtype'']]

This results into the creation of the domain key attribute of the entity ''Brandtype'' as shown on the figure below.

 [[File:BrandtypenmEntity.png|frame|none|''Figure 11: Domain key in entity dsl model'']]

===Media data===
The media data option allows the user to define a column as a multimedia column. It allows user to specify from which columns information can be gathered from, in order to create the appropiate structures to store and upload any type of files in your application. This type of column contains the filenames of the multimedia files without extension. In addition to both the mime type and the extension, the user has also to define the directory path, where those files are located.

 [[File:Mediadata.png|thumb|600px|none|''Figure 12: Media data section'']]

The currently supported mime types are the following: plain, jpg, mpeg, octetstream and pdf.
 [[File:Mediadata4.png|thumb|600px|none|''Figure 13: Mimetypes'']]

The user can not just select one of the predefined extension formats (bmp, csv, jpg, mp3, pdf, txt, xml), but also edit an extension format on his own (java or sql...).
 [[File:Mediadata5.png|thumb|600px|none|''Figure 14: Extensions'']]

An optional column name can be given by the user to set the name of the multimedia column, which will be additionally created to store these files based on the OS.bee [[BlobMapping]] data type. If not defined, the media column name will consist of the actual column name followed with the suffix '''media'''.

Only columns containing text data can be defined as media data column by the user.

 [[File:Mediadata1.png|thumb|600px|none|''Figure 15: Media data on column "bsin"'']]

The column ''bsin'' of the entity Brand contains media file name. Besides being provided with the Brand.csv file, we also have the corresponding jpg-files illustrated here in figure 16.

 [[File:Mediadata2.png|thumb|600px|none|''Figure 16: Media file location'']]

After opening the settings dialog of the column ''bsin'', (1) the user needs first to select the media data checkbox, which allows the modification of the information needed. (2) The user sets the path directory with the help of directory chooser, which appears after pressing the Path button and then selects the directory, in which the files are located. (3) The mime type and extension of the files have to be chosen within the corresponding combo boxes. (4) After pressing the OK button, the user sets the column ''bsin'' as a multimedia column. This will then result into the creation of both attributes ''bsin'' and ''bsinmedia'' of the entity Brand later on, as shown below.

 [[File:Mediadata3.png|thumb|600px|none|''Figure 17: Blobmapping attribute in entity Brand'']]

==General Notice==
As soon as the user press the button "Create App", an error message will eventually be displayed to inform the user to complete or adapt the metadata configuration of the considered csv file.
* '''Please note that a proper configuration of column definitions has to be done by the user as soon as id, reference or domain keys candidates have been detected.''' Candidates are columns of a csv file, which meet the criteria for either an id, a reference (both from alphanumerical string with UUID format as described above) or a domain key column. Setting the metadata of those columns is then '''mandatory'''.

*'''A universal unique identifier (UUID) will be automatically generated by the OS.bee Software Factory for an entity only in the case, in which no id-column candidates are available in a csv file.'''

* '''Please note that all configurations made by the user in one csv file are immediately lost, as soon as the user close the file from the CSV2App module editor or by restarting the eclipse IDE.'''

Further information over the usage of metadata such as '''id''', '''reference''' and '''domain key''' can be found in the [[Entity DSL]] documentation page.

==Sorting options==
The sorting section allows you to sort the csv data within the editor. The selected column data can be sorted either in an ascending or a descending order.
 [[File:Sorting.png|frame|none|''Figure 18: Sorting options'']]

The following examples show you how to use the sort functions by applying it on the column ''brandNm'' of the provided [[#files|Brand.csv]] file. After you opened it in the CSV2App module editor within your eclipse workspace (for example via drag-n-drop), (1) make a left-mouse click on the column ''brandNm'', (2) choose either the ascending (figure 19) or the descending (figure 20) option in the sorting section, (3) and then press the OK button to trigger to the sorting of the column data. (4) You can observe the resulting sorted column data on the right side of both figures below.

► '''Example 1''': [[File:Sorting1.png|thumb|600px|none|''Figure 19: Ascending sort of the column "brandNm"'']]

► '''Example 2''': [[File:Sorting2.png|thumb|600px|none|''Figure 20: Descending sort of the column "brandNm"'']]

== Copyright Notice ==
{{Copyright Notice}}

== License information ==

{{License information}}

AppUpIn5Extensions

2018-01-22T16:22:25Z

Worayeno: /* AppUpIn5 - Extensions 1.0 */

==Purpose==

The purpose of this document is to describe the first set of functional extensions of the CSV2App module presented in the [[App up in 5 minutes]] page, which will be available with the next release version.

=== OSBP applications===

The OSBP application '''My1App''' should already have been generated before starting this app.
You can find the instructions [http://download.osbee.org/documentation/index.php/My_first_app here].

=== CSV-file ===

You may use the two following files as reference files [http://download.osbee.org/downloads/samples/documentation/BrandType.csv BrandType.csv] and [http://download.osbee.org/downloads/samples/documentation/Brand.csv Brand.csv].

== ''AppUpIn5 - Extensions 1.0'' ==

You get access to those new functionalities by opening a csv file with the CSV2App module editor of the OS.bee Software Factory, and by making a left mouse click on the column you wish to edit the metadata from. [[File:Brandtype.png|left|frame|''Figure 1: Brandtype.csv im CSV2 Editor'']] 

The setting dialog of the corresponding column will appear and several options will be available for you to choose, based on the analysis of the type of data contained in this column and the configurations you would have made so far. [[File:Brandtype1.png|frame|left|''Figure 2: Settings dialog of column "id"'']] 

==Metadata options==
The metadata section allows users to set additional information related to the entity that will be created, based on the content of a csv file and existing dsl model files.

===Id===
With the option ''ID'' you are able to define the column representing the unique identifier data of an entity. An entity has always one identification key, also known as primary key, which is here a ''Universal Unique Identifier'' (UUID), a unique alphanumerical string. Only columns having this type of data can be defined by the user as ''ID''-columns.

With a left mouse click on the column named ''id'' of the csv file ''BrandType.csv'', the user opens the settings dialog of this column.

[[File:SettingsID.png|frame|center|''Figure 3: Settings dialog column "id" of Brandtype'']]

(1) By selecting the ''ID'' checkbox, (2) and then pressing the OK button, the user set the column ''id'' as the ''ID''-column of the entity created later on, like shown on the figure below. Each entity has always one UUID attribute, therefore each csv file must have one ''ID''-column. The generated code later on will look like this snippet on figure 4.

[[File:ID.png|frame|center|''Figure 4: Entity dsl model - "id" attribute of Brandtype'']]

===Reference===
With the reference option you are able to set column data as reference data (or foreign key) pointing to the ''Universal Unique Identifier'' (primary key) of another '''already existing entity'''. These data are also alphanumerical values, as mentioned in the section above concerning the id-option.

[[File:RefArea.png|frame|center|''Figure 5: Reference area.'']]

A reference column results into the creation of a 1-n relation between the new entity, which will be created on the basis of the considered csv file and the referenced entity, which already exists in the entity model file of your project. The condition of having this target entity to be referenced on already existing in the model translates into a specific '''order of execution''' of the application creation: successively pressing the button ''Create App'' in the right order to be able to choose the target entity.

For instance, we would like to create a reference between the entity ''Brandtype'' and the new entity to be created ''Brand'', whose csv file contains the ''brandTypeId'' as column. As you can see on the left side of figure 6, showing the content of the entity dsl model file, the entity ''Brandtype'' has already been created.

[[File:RefEntityBrand.png|thumb|600px|center|''Figure 6: Entity model file and Brand.csv file.'']]

(1) By selecting the reference checkbox, (2) selecting ''Brandtype'' in the list of all existing entities, (3) and then by pressing the OK button, the user set the column ''brandTypeId'' as a reference key pointing to the UUID of the entity ''Brandtype''.

[[File:RefBrandtypeId.png|thumb|600px|center|''Figure 7: Settings dialog column "brandTypeId" of Brand'']]

The result of this relation at the end of the app creation would then look like this.

[[File:RefBrandtypeId1.png|thumb|600px|center|''Figure 8: Reference result on "brandTypeId"'']]

The optional tag <code>cascade</code> allows, when selected, the deletion of all elements of the n-side of the relation, when the one-side element is deleted. In our example, the removal of one brand type would then result to the deletion of all the brands categorized by that type. The generated relation would then look like this in contrast to last example.

[[File:RefBrandtypeId2.png|thumb|600px|center|''Figure 9: Reference result on "brandTypeId"'']]

Besides the fact that here 1-n relations are created between entities, a reference attribute will also be generated in each entity. This is needed in order to show the information data of each relation graphically (here as table) in the application interface. This is characterized by the use of a <code>properties{...}</code> block.

===Domain key===
The domain key option allows the user to set a user friendly identification search field for the application instead of UUIDs, since those are too cryptic for users to clearly distinguish data from each other.

Only column data from type string allow the user to define a column as the domain key column.

In the case of the entity ''Brandtype'', an adequate candidate for the domain key is the column ''brandTypeNm'' containing the names of brand types, which are easy for users to read and identify data from in the application later on.

(1) By selecting the domain key checkbox, (2) and then pressing the OK button, the user define the column ''brandTypeNm'' as the domain key column of the entity Brandtype.

[[File:Brandtypenm.png|frame|center|''Figure 10: Settings dialog column "brandTypeNm" of Brandtype'']]

This results into the creation of the domain key attribute of the entity ''Brandtype'' as shown on the figure below.

[[File:BrandtypenmEntity.png|frame|center|''Figure 11: Domain key in entity dsl model'']]

===Media data===
The media data option allows the user to define a column as a multimedia column. It allows user to specify from which columns information can be gathered from, in order to create the appropiate structures to store and upload any type of files in your application. This type of column contains the filenames of the multimedia files without extension. In addition to both the mime type and the extension, the user has also to define the directory path, where those files are located.

[[File:Mediadata.png|thumb|600px|center|''Figure 12: Media data section'']]

The currently supported mime types are the following: plain, jpg, mpeg, octetstream and pdf.
[[File:Mediadata4.png|thumb|600px|center|''Figure 13: Mimetypes'']]

The user can not just select one of the predefined extension formats (bmp, csv, jpg, mp3, pdf, txt, xml), but also edit an extension format on his own (java or sql...).
[[File:Mediadata5.png|thumb|600px|center|''Figure 14: Extensions'']]

An optional column name can be given by the user to set the name of the multimedia column, which will be additionally created to store these files based on the OS.bee [[BlobMapping]] data type. If not defined, the media column name will consist of the actual column name followed with the suffix '''media'''.

Only columns containing text data can be defined as media data column by the user.

[[File:Mediadata1.png|thumb|600px|center|''Figure 15: Media data on column "bsin"'']]

The column ''bsin'' of the entity Brand contains media file name. Besides being provided with the Brand.csv file, we also have the corresponding jpg-files illustrated here in figure 16.

[[File:Mediadata2.png|thumb|600px|center|''Figure 16: Media file location'']]

After opening the settings dialog of the column ''bsin'', (1) the user needs first to select the media data checkbox, which allows the modification of the information needed. (2) The user sets the path directory with the help of directory chooser, which appears after pressing the Path button and then selects the directory, in which the files are located. (3) The mime type and extension of the files have to be chosen within the corresponding combo boxes. (4) After pressing the OK button, the user sets the column ''bsin'' as a multimedia column. This will then result into the creation of both attributes ''bsin'' and ''bsinmedia'' of the entity Brand later on, as shown below.

[[File:Mediadata3.png|thumb|600px|center|''Figure 17: Blobmapping attribute in entity Brand'']]

==General Notice==
As soon as the user press the button "Create App", an error message will eventually be displayed to inform the user to complete or adapt the metadata configuration of the considered csv file.
* '''Please note that a proper configuration of column definitions has to be done by the user as soon as id, reference or domain keys candidates have been detected.''' Candidates are columns of a csv file, which meet the criteria for either an id, a reference (both from alphanumerical string with UUID format as described above) or a domain key column. Setting the metadata of those columns is then '''mandatory'''.

*'''A universal unique identifier (UUID) will be automatically generated by the OS.bee Software Factory for an entity only in the case, in which no id-column candidates are available in a csv file.'''

* '''Please note that all configurations made by the user in one csv file are immediately lost, as soon as the user close the file from the CSV2App module editor or by restarting the eclipse IDE.'''

Further information over the usage of metadata such as '''id''', '''reference''' and '''domain key''' can be found in the [[Entity DSL]] documentation page.

==Sorting options==
The sorting section allows you to sort the csv data within the editor. The selected column data can be sorted either in an ascending or a descending order.
[[File:Sorting.png|frame|center|''Figure 18: Sorting options'']]

The following examples show you how to use the sort functions by applying it on the column ''brandNm'' of the provided [[#files|Brand.csv]] file. After you opened it in the CSV2App module editor within your eclipse workspace (for example via drag-n-drop), (1) make a left-mouse click on the column ''brandNm'', (2) choose either the ascending (figure 19) or the descending (figure 20) option in the sorting section, (3) and then press the OK button to trigger to the sorting of the column data. (4) You can observe the resulting sorted column data on the right side of both figures below.

► '''Example 1''':
[[File:Sorting1.png|thumb|600px|center|''Figure 19: Ascending sort of the column "brandNm"'']]

► '''Example 2''':
[[File:Sorting2.png|thumb|600px|center|''Figure 20: Descending sort of the column "brandNm"'']]

== Copyright Notice ==
{{Copyright Notice}}

== License information ==

{{License information}}

AppUpIn5Extensions

2018-01-22T16:20:38Z

Worayeno: /* AppUpIn5 - Extensions 1.0 */

==Purpose==

The purpose of this document is to describe the first set of functional extensions of the CSV2App module presented in the [[App up in 5 minutes]] page, which will be available with the next release version.

=== OSBP applications===

The OSBP application '''My1App''' should already have been generated before starting this app.
You can find the instructions [http://download.osbee.org/documentation/index.php/My_first_app here].

=== CSV-file ===

You may use the two following files as reference files [http://download.osbee.org/downloads/samples/documentation/BrandType.csv BrandType.csv] and [http://download.osbee.org/downloads/samples/documentation/Brand.csv Brand.csv].

== ''AppUpIn5 - Extensions 1.0'' ==

You get access to those new functionalities by opening a csv file with the CSV2App module editor of the OS.bee Software Factory, and by making a left mouse click on the column you wish to edit the metadata from.[[File:Brandtype.png|left|frame|''Figure 1: Brandtype.csv im CSV2 Editor'']] 

The setting dialog of the corresponding column will appear and several options will be available for you to choose, based on the analysis of the type of data contained in this column and the configurations you would have made so far.[[File:Brandtype1.png|frame|left|''Figure 2: Settings dialog of column "id"'']] 

==Metadata options==
The metadata section allows users to set additional information related to the entity that will be created, based on the content of a csv file and existing dsl model files.

===Id===
With the option ''ID'' you are able to define the column representing the unique identifier data of an entity. An entity has always one identification key, also known as primary key, which is here a ''Universal Unique Identifier'' (UUID), a unique alphanumerical string. Only columns having this type of data can be defined by the user as ''ID''-columns.

With a left mouse click on the column named ''id'' of the csv file ''BrandType.csv'', the user opens the settings dialog of this column.

[[File:SettingsID.png|frame|center|''Figure 3: Settings dialog column "id" of Brandtype'']]

(1) By selecting the ''ID'' checkbox, (2) and then pressing the OK button, the user set the column ''id'' as the ''ID''-column of the entity created later on, like shown on the figure below. Each entity has always one UUID attribute, therefore each csv file must have one ''ID''-column. The generated code later on will look like this snippet on figure 4.

[[File:ID.png|frame|center|''Figure 4: Entity dsl model - "id" attribute of Brandtype'']]

===Reference===
With the reference option you are able to set column data as reference data (or foreign key) pointing to the ''Universal Unique Identifier'' (primary key) of another '''already existing entity'''. These data are also alphanumerical values, as mentioned in the section above concerning the id-option.

[[File:RefArea.png|frame|center|''Figure 5: Reference area.'']]

A reference column results into the creation of a 1-n relation between the new entity, which will be created on the basis of the considered csv file and the referenced entity, which already exists in the entity model file of your project. The condition of having this target entity to be referenced on already existing in the model translates into a specific '''order of execution''' of the application creation: successively pressing the button ''Create App'' in the right order to be able to choose the target entity.

For instance, we would like to create a reference between the entity ''Brandtype'' and the new entity to be created ''Brand'', whose csv file contains the ''brandTypeId'' as column. As you can see on the left side of figure 6, showing the content of the entity dsl model file, the entity ''Brandtype'' has already been created.

[[File:RefEntityBrand.png|thumb|600px|center|''Figure 6: Entity model file and Brand.csv file.'']]

(1) By selecting the reference checkbox, (2) selecting ''Brandtype'' in the list of all existing entities, (3) and then by pressing the OK button, the user set the column ''brandTypeId'' as a reference key pointing to the UUID of the entity ''Brandtype''.

[[File:RefBrandtypeId.png|thumb|600px|center|''Figure 7: Settings dialog column "brandTypeId" of Brand'']]

The result of this relation at the end of the app creation would then look like this.

[[File:RefBrandtypeId1.png|thumb|600px|center|''Figure 8: Reference result on "brandTypeId"'']]

The optional tag <code>cascade</code> allows, when selected, the deletion of all elements of the n-side of the relation, when the one-side element is deleted. In our example, the removal of one brand type would then result to the deletion of all the brands categorized by that type. The generated relation would then look like this in contrast to last example.

[[File:RefBrandtypeId2.png|thumb|600px|center|''Figure 9: Reference result on "brandTypeId"'']]

Besides the fact that here 1-n relations are created between entities, a reference attribute will also be generated in each entity. This is needed in order to show the information data of each relation graphically (here as table) in the application interface. This is characterized by the use of a <code>properties{...}</code> block.

===Domain key===
The domain key option allows the user to set a user friendly identification search field for the application instead of UUIDs, since those are too cryptic for users to clearly distinguish data from each other.

Only column data from type string allow the user to define a column as the domain key column.

In the case of the entity ''Brandtype'', an adequate candidate for the domain key is the column ''brandTypeNm'' containing the names of brand types, which are easy for users to read and identify data from in the application later on.

(1) By selecting the domain key checkbox, (2) and then pressing the OK button, the user define the column ''brandTypeNm'' as the domain key column of the entity Brandtype.

[[File:Brandtypenm.png|frame|center|''Figure 10: Settings dialog column "brandTypeNm" of Brandtype'']]

This results into the creation of the domain key attribute of the entity ''Brandtype'' as shown on the figure below.

[[File:BrandtypenmEntity.png|frame|center|''Figure 11: Domain key in entity dsl model'']]

===Media data===
The media data option allows the user to define a column as a multimedia column. It allows user to specify from which columns information can be gathered from, in order to create the appropiate structures to store and upload any type of files in your application. This type of column contains the filenames of the multimedia files without extension. In addition to both the mime type and the extension, the user has also to define the directory path, where those files are located.

[[File:Mediadata.png|thumb|600px|center|''Figure 12: Media data section'']]

The currently supported mime types are the following: plain, jpg, mpeg, octetstream and pdf.
[[File:Mediadata4.png|thumb|600px|center|''Figure 13: Mimetypes'']]

The user can not just select one of the predefined extension formats (bmp, csv, jpg, mp3, pdf, txt, xml), but also edit an extension format on his own (java or sql...).
[[File:Mediadata5.png|thumb|600px|center|''Figure 14: Extensions'']]

An optional column name can be given by the user to set the name of the multimedia column, which will be additionally created to store these files based on the OS.bee [[BlobMapping]] data type. If not defined, the media column name will consist of the actual column name followed with the suffix '''media'''.

Only columns containing text data can be defined as media data column by the user.

[[File:Mediadata1.png|thumb|600px|center|''Figure 15: Media data on column "bsin"'']]

The column ''bsin'' of the entity Brand contains media file name. Besides being provided with the Brand.csv file, we also have the corresponding jpg-files illustrated here in figure 16.

[[File:Mediadata2.png|thumb|600px|center|''Figure 16: Media file location'']]

After opening the settings dialog of the column ''bsin'', (1) the user needs first to select the media data checkbox, which allows the modification of the information needed. (2) The user sets the path directory with the help of directory chooser, which appears after pressing the Path button and then selects the directory, in which the files are located. (3) The mime type and extension of the files have to be chosen within the corresponding combo boxes. (4) After pressing the OK button, the user sets the column ''bsin'' as a multimedia column. This will then result into the creation of both attributes ''bsin'' and ''bsinmedia'' of the entity Brand later on, as shown below.

[[File:Mediadata3.png|thumb|600px|center|''Figure 17: Blobmapping attribute in entity Brand'']]

==General Notice==
As soon as the user press the button "Create App", an error message will eventually be displayed to inform the user to complete or adapt the metadata configuration of the considered csv file.
* '''Please note that a proper configuration of column definitions has to be done by the user as soon as id, reference or domain keys candidates have been detected.''' Candidates are columns of a csv file, which meet the criteria for either an id, a reference (both from alphanumerical string with UUID format as described above) or a domain key column. Setting the metadata of those columns is then '''mandatory'''.

*'''A universal unique identifier (UUID) will be automatically generated by the OS.bee Software Factory for an entity only in the case, in which no id-column candidates are available in a csv file.'''

* '''Please note that all configurations made by the user in one csv file are immediately lost, as soon as the user close the file from the CSV2App module editor or by restarting the eclipse IDE.'''

Further information over the usage of metadata such as '''id''', '''reference''' and '''domain key''' can be found in the [[Entity DSL]] documentation page.

==Sorting options==
The sorting section allows you to sort the csv data within the editor. The selected column data can be sorted either in an ascending or a descending order.
[[File:Sorting.png|frame|center|''Figure 18: Sorting options'']]

The following examples show you how to use the sort functions by applying it on the column ''brandNm'' of the provided [[#files|Brand.csv]] file. After you opened it in the CSV2App module editor within your eclipse workspace (for example via drag-n-drop), (1) make a left-mouse click on the column ''brandNm'', (2) choose either the ascending (figure 19) or the descending (figure 20) option in the sorting section, (3) and then press the OK button to trigger to the sorting of the column data. (4) You can observe the resulting sorted column data on the right side of both figures below.

► '''Example 1''':
[[File:Sorting1.png|thumb|600px|center|''Figure 19: Ascending sort of the column "brandNm"'']]

► '''Example 2''':
[[File:Sorting2.png|thumb|600px|center|''Figure 20: Descending sort of the column "brandNm"'']]

== Copyright Notice ==
{{Copyright Notice}}

== License information ==

{{License information}}

AppUpIn5Extensions

2018-01-22T16:19:07Z

Worayeno: /* AppUpIn5 - Extensions 1.0 */

==Purpose==

The purpose of this document is to describe the first set of functional extensions of the CSV2App module presented in the [[App up in 5 minutes]] page, which will be available with the next release version.

=== OSBP applications===

The OSBP application '''My1App''' should already have been generated before starting this app.
You can find the instructions [http://download.osbee.org/documentation/index.php/My_first_app here].

=== CSV-file ===

You may use the two following files as reference files [http://download.osbee.org/downloads/samples/documentation/BrandType.csv BrandType.csv] and [http://download.osbee.org/downloads/samples/documentation/Brand.csv Brand.csv].

== ''AppUpIn5 - Extensions 1.0'' ==

You get access to those new functionalities by opening a csv file with the CSV2App module editor of the OS.bee Software Factory, and by making a left mouse click on the column you wish to edit the metadata from.
[[File:Brandtype.png|left|frame|''Figure 1: Brandtype.csv im CSV2 Editor'']] 
The setting dialog of the corresponding column will appear and several options will be available for you to choose, based on the analysis of the type of data contained in this column and the configurations you would have made so far.

[[File:Brandtype1.png|thumb|left|''Figure 2: Settings dialog of column "id"'']]

==Metadata options==
The metadata section allows users to set additional information related to the entity that will be created, based on the content of a csv file and existing dsl model files.

===Id===
With the option ''ID'' you are able to define the column representing the unique identifier data of an entity. An entity has always one identification key, also known as primary key, which is here a ''Universal Unique Identifier'' (UUID), a unique alphanumerical string. Only columns having this type of data can be defined by the user as ''ID''-columns.

With a left mouse click on the column named ''id'' of the csv file ''BrandType.csv'', the user opens the settings dialog of this column.

[[File:SettingsID.png|frame|center|''Figure 3: Settings dialog column "id" of Brandtype'']]

(1) By selecting the ''ID'' checkbox, (2) and then pressing the OK button, the user set the column ''id'' as the ''ID''-column of the entity created later on, like shown on the figure below. Each entity has always one UUID attribute, therefore each csv file must have one ''ID''-column. The generated code later on will look like this snippet on figure 4.

[[File:ID.png|frame|center|''Figure 4: Entity dsl model - "id" attribute of Brandtype'']]

===Reference===
With the reference option you are able to set column data as reference data (or foreign key) pointing to the ''Universal Unique Identifier'' (primary key) of another '''already existing entity'''. These data are also alphanumerical values, as mentioned in the section above concerning the id-option.

[[File:RefArea.png|frame|center|''Figure 5: Reference area.'']]

A reference column results into the creation of a 1-n relation between the new entity, which will be created on the basis of the considered csv file and the referenced entity, which already exists in the entity model file of your project. The condition of having this target entity to be referenced on already existing in the model translates into a specific '''order of execution''' of the application creation: successively pressing the button ''Create App'' in the right order to be able to choose the target entity.

For instance, we would like to create a reference between the entity ''Brandtype'' and the new entity to be created ''Brand'', whose csv file contains the ''brandTypeId'' as column. As you can see on the left side of figure 6, showing the content of the entity dsl model file, the entity ''Brandtype'' has already been created.

[[File:RefEntityBrand.png|thumb|600px|center|''Figure 6: Entity model file and Brand.csv file.'']]

(1) By selecting the reference checkbox, (2) selecting ''Brandtype'' in the list of all existing entities, (3) and then by pressing the OK button, the user set the column ''brandTypeId'' as a reference key pointing to the UUID of the entity ''Brandtype''.

[[File:RefBrandtypeId.png|thumb|600px|center|''Figure 7: Settings dialog column "brandTypeId" of Brand'']]

The result of this relation at the end of the app creation would then look like this.

[[File:RefBrandtypeId1.png|thumb|600px|center|''Figure 8: Reference result on "brandTypeId"'']]

The optional tag <code>cascade</code> allows, when selected, the deletion of all elements of the n-side of the relation, when the one-side element is deleted. In our example, the removal of one brand type would then result to the deletion of all the brands categorized by that type. The generated relation would then look like this in contrast to last example.

[[File:RefBrandtypeId2.png|thumb|600px|center|''Figure 9: Reference result on "brandTypeId"'']]

Besides the fact that here 1-n relations are created between entities, a reference attribute will also be generated in each entity. This is needed in order to show the information data of each relation graphically (here as table) in the application interface. This is characterized by the use of a <code>properties{...}</code> block.

===Domain key===
The domain key option allows the user to set a user friendly identification search field for the application instead of UUIDs, since those are too cryptic for users to clearly distinguish data from each other.

Only column data from type string allow the user to define a column as the domain key column.

In the case of the entity ''Brandtype'', an adequate candidate for the domain key is the column ''brandTypeNm'' containing the names of brand types, which are easy for users to read and identify data from in the application later on.

(1) By selecting the domain key checkbox, (2) and then pressing the OK button, the user define the column ''brandTypeNm'' as the domain key column of the entity Brandtype.

[[File:Brandtypenm.png|frame|center|''Figure 10: Settings dialog column "brandTypeNm" of Brandtype'']]

This results into the creation of the domain key attribute of the entity ''Brandtype'' as shown on the figure below.

[[File:BrandtypenmEntity.png|frame|center|''Figure 11: Domain key in entity dsl model'']]

===Media data===
The media data option allows the user to define a column as a multimedia column. It allows user to specify from which columns information can be gathered from, in order to create the appropiate structures to store and upload any type of files in your application. This type of column contains the filenames of the multimedia files without extension. In addition to both the mime type and the extension, the user has also to define the directory path, where those files are located.

[[File:Mediadata.png|thumb|600px|center|''Figure 12: Media data section'']]

The currently supported mime types are the following: plain, jpg, mpeg, octetstream and pdf.
[[File:Mediadata4.png|thumb|600px|center|''Figure 13: Mimetypes'']]

The user can not just select one of the predefined extension formats (bmp, csv, jpg, mp3, pdf, txt, xml), but also edit an extension format on his own (java or sql...).
[[File:Mediadata5.png|thumb|600px|center|''Figure 14: Extensions'']]

An optional column name can be given by the user to set the name of the multimedia column, which will be additionally created to store these files based on the OS.bee [[BlobMapping]] data type. If not defined, the media column name will consist of the actual column name followed with the suffix '''media'''.

Only columns containing text data can be defined as media data column by the user.

[[File:Mediadata1.png|thumb|600px|center|''Figure 15: Media data on column "bsin"'']]

The column ''bsin'' of the entity Brand contains media file name. Besides being provided with the Brand.csv file, we also have the corresponding jpg-files illustrated here in figure 16.

[[File:Mediadata2.png|thumb|600px|center|''Figure 16: Media file location'']]

After opening the settings dialog of the column ''bsin'', (1) the user needs first to select the media data checkbox, which allows the modification of the information needed. (2) The user sets the path directory with the help of directory chooser, which appears after pressing the Path button and then selects the directory, in which the files are located. (3) The mime type and extension of the files have to be chosen within the corresponding combo boxes. (4) After pressing the OK button, the user sets the column ''bsin'' as a multimedia column. This will then result into the creation of both attributes ''bsin'' and ''bsinmedia'' of the entity Brand later on, as shown below.

[[File:Mediadata3.png|thumb|600px|center|''Figure 17: Blobmapping attribute in entity Brand'']]

==General Notice==
As soon as the user press the button "Create App", an error message will eventually be displayed to inform the user to complete or adapt the metadata configuration of the considered csv file.
* '''Please note that a proper configuration of column definitions has to be done by the user as soon as id, reference or domain keys candidates have been detected.''' Candidates are columns of a csv file, which meet the criteria for either an id, a reference (both from alphanumerical string with UUID format as described above) or a domain key column. Setting the metadata of those columns is then '''mandatory'''.

*'''A universal unique identifier (UUID) will be automatically generated by the OS.bee Software Factory for an entity only in the case, in which no id-column candidates are available in a csv file.'''

* '''Please note that all configurations made by the user in one csv file are immediately lost, as soon as the user close the file from the CSV2App module editor or by restarting the eclipse IDE.'''

Further information over the usage of metadata such as '''id''', '''reference''' and '''domain key''' can be found in the [[Entity DSL]] documentation page.

==Sorting options==
The sorting section allows you to sort the csv data within the editor. The selected column data can be sorted either in an ascending or a descending order.
[[File:Sorting.png|frame|center|''Figure 18: Sorting options'']]

The following examples show you how to use the sort functions by applying it on the column ''brandNm'' of the provided [[#files|Brand.csv]] file. After you opened it in the CSV2App module editor within your eclipse workspace (for example via drag-n-drop), (1) make a left-mouse click on the column ''brandNm'', (2) choose either the ascending (figure 19) or the descending (figure 20) option in the sorting section, (3) and then press the OK button to trigger to the sorting of the column data. (4) You can observe the resulting sorted column data on the right side of both figures below.

► '''Example 1''':
[[File:Sorting1.png|thumb|600px|center|''Figure 19: Ascending sort of the column "brandNm"'']]

► '''Example 2''':
[[File:Sorting2.png|thumb|600px|center|''Figure 20: Descending sort of the column "brandNm"'']]

== Copyright Notice ==
{{Copyright Notice}}

== License information ==

{{License information}}

AppUpIn5Extensions

2018-01-22T16:18:32Z

Worayeno: /* AppUpIn5 - Extensions 1.0 */

==Purpose==

The purpose of this document is to describe the first set of functional extensions of the CSV2App module presented in the [[App up in 5 minutes]] page, which will be available with the next release version.

=== OSBP applications===

The OSBP application '''My1App''' should already have been generated before starting this app.
You can find the instructions [http://download.osbee.org/documentation/index.php/My_first_app here].

=== CSV-file ===

You may use the two following files as reference files [http://download.osbee.org/downloads/samples/documentation/BrandType.csv BrandType.csv] and [http://download.osbee.org/downloads/samples/documentation/Brand.csv Brand.csv].

== ''AppUpIn5 - Extensions 1.0'' ==

You get access to those new functionalities by opening a csv file with the CSV2App module editor of the OS.bee Software Factory, and by making a left mouse click on the column you wish to edit the metadata from.
[[File:Brandtype.png|left|frame|''Figure 1: Brandtype.csv im CSV2 Editor'']] 
The setting dialog of the corresponding column will appear and several options will be available for you to choose, based on the analysis of the type of data contained in this column and the configurations you would have made so far.

[[File:Brandtype1.png|frame|left|''Figure 2: Settings dialog of column "id"'']]

==Metadata options==
The metadata section allows users to set additional information related to the entity that will be created, based on the content of a csv file and existing dsl model files.

===Id===
With the option ''ID'' you are able to define the column representing the unique identifier data of an entity. An entity has always one identification key, also known as primary key, which is here a ''Universal Unique Identifier'' (UUID), a unique alphanumerical string. Only columns having this type of data can be defined by the user as ''ID''-columns.

With a left mouse click on the column named ''id'' of the csv file ''BrandType.csv'', the user opens the settings dialog of this column.

[[File:SettingsID.png|frame|center|''Figure 3: Settings dialog column "id" of Brandtype'']]

(1) By selecting the ''ID'' checkbox, (2) and then pressing the OK button, the user set the column ''id'' as the ''ID''-column of the entity created later on, like shown on the figure below. Each entity has always one UUID attribute, therefore each csv file must have one ''ID''-column. The generated code later on will look like this snippet on figure 4.

[[File:ID.png|frame|center|''Figure 4: Entity dsl model - "id" attribute of Brandtype'']]

===Reference===
With the reference option you are able to set column data as reference data (or foreign key) pointing to the ''Universal Unique Identifier'' (primary key) of another '''already existing entity'''. These data are also alphanumerical values, as mentioned in the section above concerning the id-option.

[[File:RefArea.png|frame|center|''Figure 5: Reference area.'']]

A reference column results into the creation of a 1-n relation between the new entity, which will be created on the basis of the considered csv file and the referenced entity, which already exists in the entity model file of your project. The condition of having this target entity to be referenced on already existing in the model translates into a specific '''order of execution''' of the application creation: successively pressing the button ''Create App'' in the right order to be able to choose the target entity.

For instance, we would like to create a reference between the entity ''Brandtype'' and the new entity to be created ''Brand'', whose csv file contains the ''brandTypeId'' as column. As you can see on the left side of figure 6, showing the content of the entity dsl model file, the entity ''Brandtype'' has already been created.

[[File:RefEntityBrand.png|thumb|600px|center|''Figure 6: Entity model file and Brand.csv file.'']]

(1) By selecting the reference checkbox, (2) selecting ''Brandtype'' in the list of all existing entities, (3) and then by pressing the OK button, the user set the column ''brandTypeId'' as a reference key pointing to the UUID of the entity ''Brandtype''.

[[File:RefBrandtypeId.png|thumb|600px|center|''Figure 7: Settings dialog column "brandTypeId" of Brand'']]

The result of this relation at the end of the app creation would then look like this.

[[File:RefBrandtypeId1.png|thumb|600px|center|''Figure 8: Reference result on "brandTypeId"'']]

The optional tag <code>cascade</code> allows, when selected, the deletion of all elements of the n-side of the relation, when the one-side element is deleted. In our example, the removal of one brand type would then result to the deletion of all the brands categorized by that type. The generated relation would then look like this in contrast to last example.

[[File:RefBrandtypeId2.png|thumb|600px|center|''Figure 9: Reference result on "brandTypeId"'']]

Besides the fact that here 1-n relations are created between entities, a reference attribute will also be generated in each entity. This is needed in order to show the information data of each relation graphically (here as table) in the application interface. This is characterized by the use of a <code>properties{...}</code> block.

===Domain key===
The domain key option allows the user to set a user friendly identification search field for the application instead of UUIDs, since those are too cryptic for users to clearly distinguish data from each other.

Only column data from type string allow the user to define a column as the domain key column.

In the case of the entity ''Brandtype'', an adequate candidate for the domain key is the column ''brandTypeNm'' containing the names of brand types, which are easy for users to read and identify data from in the application later on.

(1) By selecting the domain key checkbox, (2) and then pressing the OK button, the user define the column ''brandTypeNm'' as the domain key column of the entity Brandtype.

[[File:Brandtypenm.png|frame|center|''Figure 10: Settings dialog column "brandTypeNm" of Brandtype'']]

This results into the creation of the domain key attribute of the entity ''Brandtype'' as shown on the figure below.

[[File:BrandtypenmEntity.png|frame|center|''Figure 11: Domain key in entity dsl model'']]

===Media data===
The media data option allows the user to define a column as a multimedia column. It allows user to specify from which columns information can be gathered from, in order to create the appropiate structures to store and upload any type of files in your application. This type of column contains the filenames of the multimedia files without extension. In addition to both the mime type and the extension, the user has also to define the directory path, where those files are located.

[[File:Mediadata.png|thumb|600px|center|''Figure 12: Media data section'']]

The currently supported mime types are the following: plain, jpg, mpeg, octetstream and pdf.
[[File:Mediadata4.png|thumb|600px|center|''Figure 13: Mimetypes'']]

The user can not just select one of the predefined extension formats (bmp, csv, jpg, mp3, pdf, txt, xml), but also edit an extension format on his own (java or sql...).
[[File:Mediadata5.png|thumb|600px|center|''Figure 14: Extensions'']]

An optional column name can be given by the user to set the name of the multimedia column, which will be additionally created to store these files based on the OS.bee [[BlobMapping]] data type. If not defined, the media column name will consist of the actual column name followed with the suffix '''media'''.

Only columns containing text data can be defined as media data column by the user.

[[File:Mediadata1.png|thumb|600px|center|''Figure 15: Media data on column "bsin"'']]

The column ''bsin'' of the entity Brand contains media file name. Besides being provided with the Brand.csv file, we also have the corresponding jpg-files illustrated here in figure 16.

[[File:Mediadata2.png|thumb|600px|center|''Figure 16: Media file location'']]

After opening the settings dialog of the column ''bsin'', (1) the user needs first to select the media data checkbox, which allows the modification of the information needed. (2) The user sets the path directory with the help of directory chooser, which appears after pressing the Path button and then selects the directory, in which the files are located. (3) The mime type and extension of the files have to be chosen within the corresponding combo boxes. (4) After pressing the OK button, the user sets the column ''bsin'' as a multimedia column. This will then result into the creation of both attributes ''bsin'' and ''bsinmedia'' of the entity Brand later on, as shown below.

[[File:Mediadata3.png|thumb|600px|center|''Figure 17: Blobmapping attribute in entity Brand'']]

==General Notice==
As soon as the user press the button "Create App", an error message will eventually be displayed to inform the user to complete or adapt the metadata configuration of the considered csv file.
* '''Please note that a proper configuration of column definitions has to be done by the user as soon as id, reference or domain keys candidates have been detected.''' Candidates are columns of a csv file, which meet the criteria for either an id, a reference (both from alphanumerical string with UUID format as described above) or a domain key column. Setting the metadata of those columns is then '''mandatory'''.

*'''A universal unique identifier (UUID) will be automatically generated by the OS.bee Software Factory for an entity only in the case, in which no id-column candidates are available in a csv file.'''

* '''Please note that all configurations made by the user in one csv file are immediately lost, as soon as the user close the file from the CSV2App module editor or by restarting the eclipse IDE.'''

Further information over the usage of metadata such as '''id''', '''reference''' and '''domain key''' can be found in the [[Entity DSL]] documentation page.

==Sorting options==
The sorting section allows you to sort the csv data within the editor. The selected column data can be sorted either in an ascending or a descending order.
[[File:Sorting.png|frame|center|''Figure 18: Sorting options'']]

The following examples show you how to use the sort functions by applying it on the column ''brandNm'' of the provided [[#files|Brand.csv]] file. After you opened it in the CSV2App module editor within your eclipse workspace (for example via drag-n-drop), (1) make a left-mouse click on the column ''brandNm'', (2) choose either the ascending (figure 19) or the descending (figure 20) option in the sorting section, (3) and then press the OK button to trigger to the sorting of the column data. (4) You can observe the resulting sorted column data on the right side of both figures below.

► '''Example 1''':
[[File:Sorting1.png|thumb|600px|center|''Figure 19: Ascending sort of the column "brandNm"'']]

► '''Example 2''':
[[File:Sorting2.png|thumb|600px|center|''Figure 20: Descending sort of the column "brandNm"'']]

== Copyright Notice ==
{{Copyright Notice}}

== License information ==

{{License information}}

File:Sorting2.png

2018-01-17T15:56:02Z

Worayeno:

File:Sorting1.png

2018-01-17T15:55:47Z

Worayeno:

File:Sorting.png

2018-01-17T15:55:22Z

Worayeno:

File:Mediadata3.png

2018-01-17T15:55:01Z

Worayeno:

File:Mediadata2.png

2018-01-17T15:54:38Z

Worayeno:

File:Mediadata1.png

2018-01-17T15:54:08Z

Worayeno:

File:Mediadata5.png

2018-01-17T15:53:03Z

Worayeno:

File:Mediadata4.png

2018-01-17T15:52:40Z

Worayeno:

File:Mediadata.png

2018-01-17T15:52:16Z

Worayeno:

File:BrandtypenmEntity.png

2018-01-17T15:51:51Z

Worayeno:

File:Brandtypenm.png

2018-01-17T15:51:15Z

Worayeno:

File:RefBrandtypeId2.png

2018-01-17T15:50:43Z

Worayeno:

File:RefBrandtypeId1.png

2018-01-17T15:50:18Z

Worayeno: