Difference between revisions of "Entity DSL"

Revision as of 23:35, 8 January 2017

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

  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.

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.

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

datatype <name> jvmType <type> as primitive;.

Specifying datatypes in this manner uses an appropriate wrapper class in the generated Java code; adding the keywords 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 keywords, 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 keywords. 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 keywords.

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 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:

 [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 as "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 as "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, a version field and a flag for the current version to the entity.

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

cacheable

cacheable marks the entity as "cacheable". The appropriate annotation for the persistence provider is added to the generated Java code.

Figure 10: Declaring an entity to be cacheable adds the @Cacheable annotation

timedependent

timedependent 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 timedependent keyword recognizes the modifiers (DATE) and (TIMESTAMP). Default is timedependent(DATE).

Figure 11: The timedependent keyword causes an object ID, a validFrom and a validUntil field to be created in order to support multiple database entries for an object.

mapped superclass

mapped superclass 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.

Figure 12: The mapped superclass keyword sets the appropriate annotation which causes the persistence provider to move the mappings to the derived subclasses.

extends

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

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

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

inheritance per class{} 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.

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.

inheritance per subclass

inheritance per subclass{} 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.

Figure 14: An @Table annotation is added to the generated Java code, so that the "Derived" entity is mapped to a table of its own.

schemaName

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

tableName

tableName 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 @Table(name = <xyz>).

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

Figure 15: Specifying the schemaName and tableName settings in an entity determines the name of the database schema and tables used for persistence.

discriminatorColumn

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

discriminatorType

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

discriminatorValue

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

Figure 16: The inheritance statement allows the optional specification of discriminator column, type and value to be used in the case of a single table.

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 (@Embeddable, @Embedded, @AttributeOverrides etc.) are added in order to have beans persisted with their parent entities.

Figure 17: Beans can be embedded in entities and are persisted with them.

Enums

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

Figure 18: Defining enums 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 datatype 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

The basic property var 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:

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

Figure 19: Variables can be defined using the var 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.

derived

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

Figure 20: Properties may be derived from other properties using an Xexpression.

The code is automatically translated to valid Java code.

dirty

dirty 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 dirty flag is allowed per entity. The datatype has to be boolean.

Figure 21: The dirty property is used to flag whether changes have been made to the bufered data, but not yet written back to the database.

The boolean field for this property and the appropriate annotation are generated with the dirty keyword.

domainDescription

domainDescription 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 String. Domain descriptions may be derived from other properties.

Figure 22: Domain description properties can be created with the domainDescription keyword.

domainKey

domainKey defines a domain key. The appropriate annotation is added to the property. Primitive datatypes may be used as domain keys.

Figure 23: A field containing a domain key is created with the domainKey keyword.

id

► -- deprecated -- deprecated -- deprecated -- deprecated -- deprecated -- deprecated -- deprecated -- deprecated --

id defines an id-property (used as primary key by the JPA compiler). This keyword is deprecated. If no id is given, a warning is shown.

Caution: ID autogeneration causes problems since the value is not set before the entity is persisted in the database. It is advised to use the uuid keyword instead.

Figure 24: Entities are supposed to have an ID property that is used as primary key in the database.

Caution: The generated IDs are not necessarily unique if the deprecated id keyword is used!

index

index causes an index for the table to be calculated. Indices 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 on. If the index keyword is prefixed with unique, a unique index is generated.

Figure 25: Indices for the database tables that map entities are generated with the index keyword.

The @Table annotation is supplemented with the index definition.

properties

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

Figure 26: Additional information about features can be defined by key-value pairs. This information is then stored in the semantic model.

uuid

uuid allows the use of Universally Unique IDs as primary keys. A new UUID value is created for each object as soon as it is created, independently of database operations. This circumvents the problems with the id keyword. UUIDs have to be strings.

Figure 27: By using the uuid keyword, entities are created with a reliably unique identifier.

version

version defines a version-property (used by the JPA-Compiler).

Figure 28: A version property can be added to entities and beans.

transient

transient marks the property to be transient. Instead of @Column, an @Transient annotation is generated so the property is not persisted in the database.

Figure 29: The transient keyword allows properties to be excluded from persistence.

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 ref keyword, a type and a name. The exact type of reference can be specified with the following modifiers:

Multiplicity and nullability

The Entity DSL supports the specification of multiplicities in square brackets appended to the type:

• [1] defines a non-nullable one-to-one relationship.
• [0..1] defines a nullable one-to-one relationship (Default behavior).
• [1..*] defines a non-nullable one-to-many relationship. Needs an opposite reference.
• [0..*] or simply [*] defines a nullable one-to-many relationship. Needs an opposite reference.

Figure 30: Adding multiplicity [1] causes the annotations for non-nullable database entries to be set.

opposite reference

Lifecycle references need the specification of an opposite reference. This can be done with the opposite keyword.

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

cascade

The cascade specifier controls the behaviour of the database on delete operations. If an object with a ref cascade reference to other objects is deleted, those will be removed as well.

Figure 31: By using the cascade and opposite keywords, bidirectional associations can be achieved.

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 like closures. Operations can be declared by the def keyword followed by braces containing the inlined operation.

Figure 32: The def keyword allows the inlining of custom methods in the Entity DSL code.

These methods are translated to the appropriate Java methods along with the auto-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.

Figure 33: Annotating elements in the Compex Entity DSL causes an annotation to be inserted into the generated Java code.

These methods are translated to the appropriate Java methods along with the auto-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 /* ... */.

Figure 34: The comments added in the Entity DSL are transformed to Java-style comments in the generated code.

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

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 ^ character. During the generation of the Java code, this escape character is removed.

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 name uuid is generated that cannot be specified in the entity model file.