Difference between revisions of "Entity DSL"

Revision as of 11:22, 3 August 2016

Copyright Notice

All rights are reserved by Compex Systemhaus GmbH. In particular, duplications, translations, microfilming, saving and processing in electronic systems are protected by copyright. Use of this manual is only authorized with the permission of Compex Systemhaus GmbH. Infringements of the law shall be punished in accordance with civil and penal laws. We have taken utmost care in putting together texts and images. Nevertheless, the possibility of errors cannot be completely ruled out. The Figures and information in this manual are only given as approximations unless expressly indicated as binding. Amendments to the manual due to amendments to the standard software remain reserved. Please note that the latest amendments to the manual can be accessed through our helpdesk at any time. The contractually agreed regulations of the licensing and maintenance of the standard software shall apply with regard to liability for any errors in the documentation. Guarantees, particularly guarantees of quality or durability can only be assumed for the manual insofar as its quality or durability are expressly stipulated as guaranteed. If you would like to make a suggestion, the Compex Team would be very pleased to hear from you.

(c) 2016 Compex Systemhaus GmbH

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 .entityodel 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 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.

 package name {
    import importStatement;
    datatype datatypeDefinition;
    entities/beans/enums
 } align alignment

Figure 1 - Entity model file - a package is the topmost element and contains other items.

import

The Entity DSL allows to reference entities defined in different packages, even in different .entitymodel files. The import statement is a way to make these elements available by their fully qualified name.

Import statements allow the use of the "*"-wildcard.

 import importStatement;

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 behaviour of the generator can be controlled by the datatype definitions. Datatypes defined in an .entitymodel file are local to this 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 datatype <name> jvmType <type> as primitive;.

Specifying datatypes in this manner uses an appropriate wrapper class in the generated Java code; adding the keyword as primitive enforces the use of primitive datatypes where applicable:

datatype foo jvmType Integer; compiles to an Integer whereas datatype foo jvmType Integer as primitive; results in int.

---

Figure 3: The defined datatype is translated to a wrapper class.

---

Figure 4: By adding the as primitive keyword, the datatype is translated to a primitive datatype.

---

• dateTypes: The datatypes for handling temporal information can be defined by the following statement:

datatype <name> datetype date—time—timestamp;

Datatypes that have been defined in this manner can be used as property variables in entities and beans.

---

Figure 5: Defining datatypes for handling temporal information. Content assist is available.

---

• blobs: Binary blobs can be handled by defining a datatype with the as blob keyword. The Java implementation of such a blob is a byte array. Appropriate persistence annotations are automatically added.

datatype <name> as blob;

---

Figure 6: Including binary blobs by using a datatype with the as blob keyword.

---

After import statements and datatype definitions, the content of the .entitymodel file is made up of entity, bean and enum 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 its name and properties, references and operations. Generally, an entity is an object which can keep a state about variables and references and can 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:

[modifiers] entity <name> extends <parentEntity> {
    [entityProperties]
}

Figure 7: Items contained in another package can be addressed if the package is imported using the import 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

abstract marks the entity to be abstract. This generates an abstract Java class.

Figure 8: The abstract keyword causes the translation into an abstract Java class

historized

historized marks the entity to be historized. Historized entities can have several entries in a database, but only one of them may be marked as current.

The historized keyword adds an object ID (OID), a version field and a flag for the current version to the entity.

Figure 9: The historized modifier triggers the creation of an OID, an object version and a flag for marking the current version.

cacheable

timedependent

mapped superclass