DTO DSL

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 DTO DSL facilitates the creation and handling of data transfer objects (DTOs) in order to carry data between processes. Communication between processes is usually done by calls to remote interfaces and services where each call is a computationally expensive and time-consuming operation. The use of DTOs that aggregate the data that would have been transferred separately reduces the number of calls that are necessary, thus speeding up the operation. Furthermore, DTOs are decoupled from the JPA, thus eliminating burdensome dependencies.

Using the DTO DSL, it is easy to create DTOs and the mapper classes that link them to the respective persistence entities. Property change support is automatically included in order to have current data without direct dependencies on the persistence layer.

Overview

The main semantic elements of the DTO 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 other DTO models or the entity model files that are covered by the DTOs.
• Datatype declarations - a way to define datatypes that can be used (only within the package - private scope).
• DTO - the model of a DTO that wraps an entity. It contains further elements such as properties and references. Appropriate mapper methods can be specified.
• Property - a reference to an enum, a Java class or a “simple datatype" (as defined in the datatype declaration). Can be inherited from the wrapped entity and offers multiplicity.
• Reference - a reference to another DTO. Can be inherited from the wrapped entity and offers multiplicity.
• Operations - similar to Java methods. The Xbase expression language can be used to write high-level code.
• Comments can be added to all elements.

► Caveat: In order to make use of the DTO DSL, one has to make sure that the OSBP builder is executed after the Xtext builder.

DTO model files

DTO models are described in .dtos files. These files describe the DTO model and are the basis for the code generation. DTO models may be split over several .dtos files containing packages in the same namespace.

A .dtos file may contain several packages with DTOs.

package

Packages are the root element of the DTO DSL grammar. Everything is contained in a package: Imports, datatypes, DTOs 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 DTOs and enums. Additionally, a package allows import statements and the declaration of datatypes.

► Syntax:

 package name {
    import importStatement;
    datatype datatypeDefinition;
    DTOs
 }

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

import

In order to wrap entities into DTOs, the DTO DSL has to reference entities defined in entity model files. Furthermore, it is possible to reference DTOs in other packages. The import statement is a way to address these elements by their fully qualified name.

Import statements allow the use of the *-wildcard.

► Syntax:

package name {
    import importStatement;
    datatype datatypeDefinition;
    DTOs
}

Figure 2: Items contained in another package can be accessed and handled if the package is imported.

datatype

The DTO DSL allows the definition of datatypes. These are translated by the inferrer into their standard Java presentation. The behaviour of the generator can be controlled by the datatype definitions. There are three types of datatype definitions:

jvmTypes

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

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

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.
datatype <name> as blob;

After import statements and datatype definitions, the content of the .dtos file is made up of DTO definitions.