Datatype DSL

Purpose

The Datatype DSL is, beside the Entity DSL, one of the most basic DSL for the Software Factory. It provides you with the most common used basic (atomic) datatypes by mapping them. It also allows you to define new simple and complex datatypes, to be used in all your projects. You will find here a couple of informations to help you understand how to use it.

Overview

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

• "Import" declarations - used to import external Java classes.

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

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

• "Enum" declarations - the abstraction for Java enums.

The Datatype DSL as such is working under the hood of your application's entity model by providing acces to datatypes (Number, String, Boolean...). The figure below represents straightforward how the grammar was designed in order to make it possible for you to use and also create your own datatypes. This is the structural foundation, on which the Datatype DSL model is based on.

Figure 1: Grammar Definition

Figure 2: Grammar Definition - Detailed View 1

Figure 3: Grammar Definition - Detailed View 2

Datatypes Model Files

Datatype DSL model files end with the .datatype extension. Datatype models may be split into several .datatype files, as long as they have the same package declaration.

Reserved Keywords

In the following we will dive deeper into the description and the usage of datatype related and reserved keywords.

package

Datatype model files must start with a package declaration. Packages are the root element of the Datatype DSL grammar. Everything is contained in a package: Datatypes and Enums have to be defined inside the Package definition. One document can contain multiple packages with unique names.

  import importStatement

  package name {
     datatype datatypeDefinition
     enums enumDefinition
  }

File:DatatypePackage.png

Figure 4 - Datatype model file

import

Although Import-Statements are located above the package declaration, they are optional as you may not necessarely need to reference any external Java Classes to extend the your datatype definitions. Using an 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

File:DatatypeImport.png

Figure 5: Items (Java Classes) contained in another package can be addressed if the package is imported using the import keyword and its fully qualified name.

datatype

The Datatype 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 .datatype file are local to that file.

There are three types of datatype definitions:

jvmType

Datatype definitons that map types to jvmType take the basic syntax of

 datatype <name> jvmType <type> asPrimitive

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

Example 1:

datatype foo jvmType Integer

compiles to an Integer whereas

Example 2:

datatype foo jvmType Integer asPrimitive

results in int.

Figure 6: The defined datatype is translated to a wrapper class

Figure 7: By adding the asPrimitive keywords, the datatype is translated to a primitive datatype

Example 3:

datatype boolean jvmType java.lang.Boolean asPrimitive 
datatype short jvmType java.lang.Short asPrimitive
datatype int jvmType java.lang.Integer asPrimitive
datatype long jvmType java.lang.Long asPrimitive
datatype double jvmType java.lang.Double asPrimitive
datatype character jvmType java.lang.Character asPrimitive
datatype byte jvmType java.lang.Byte asPrimitive

datatype Boolean jvmType java.lang.Boolean
datatype Short jvmType java.lang.Short
datatype Int jvmType java.lang.Integer
datatype Long jvmType java.lang.Long
datatype Double jvmType java.lang.Double
datatype Character jvmType java.lang.Character
datatype Byte jvmType java.lang.Byte
datatype BigDecimal jvmType java.math.BigDecimal
 
datatype String jvmType java.lang.String

dateType

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

datatype <name> dateType {date|time|timestamp} [options]*

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

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

Example 1:

datatype MyDate dateType date

Example 2:

datatype MyDate dateType time

Example 3:

datatype MyDate dateType timestamp

You can also extend or constraint the datetype definition by adding one or more of the following options:

[options]: 
   <isPast>    specifies that every object of this datetype can only accept value prior its creation.
   <isFuture>  specifies that every object of this datetype can only accept value after its creation.
   <isNull>    specifies that any   object of this datetype can have the value null.
   <isNotNull> specifies that the every object of this datetype can not have the value null.

   <'['severity =  {error|info|warn} ']'> sets the severity level of a non valid value.

Figure 9: Severity Level Error

File:DatatypeIconSeverity2.png

Figure 10: Severity Level Info

File:DatatypeIconSeverity3.png

Figure 11: Severity Level Warning

Please note that setting the severity level has the effect of showing context based information (here non valid data) in the UI on the corresponding field by displaying either a red exclamation point(error) or a small yellow triangle(info) or blue triangle(info). This depends of course on the set of options you would have chosen in your datetype definition.

Example 4:

datatype BirthDate dateType date isNotNull isPast[severity=error]

File:DatatypeIconSeverity4.png

Figure 12: Birthdate - Severity Level Error

asBlob

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

datatype <name> asBlob

File:DatatypeBlob.png

Figure 9: Including binary blobs by using a datatype with the asBlob keywords

enum

Enumerations can be handled by defining a slightly different datatype with the enum keywords. The Java implementation of such a enum is exactly the same.

enum <name>  { <Value1> [, <Value2>]* }

Example:

enum LayoutingStrategies {
    Form2, Form3, Horizontal, Vertical, Grid, Css
}

enum ItemClassification {
    Class_A, Class_B, Class_C
}

File:DatatypeEnum.png

Figure 10: Defining an Enumeration with enum keyword.

Custom Datatypes

In this section you will find some informations about the available custom datatypes (OSBEE).

BlobMapping

This is a custom datatypes that allows the use of big data as blob.

Example 1:

	datatype BlobMapping jvmType java.lang.String 
	properties (
		key="Blob" value="2"
		/**
		 * value="0" name="unnormalized" resolution="unknown"
		 * value="1" name="small" resolution="16x16"
		 * value="2" name="mid" resolution="64x64"
		 * value="3" name="portrait" resolution="64x128"
		 * value="4" name="landscape" resolution="128x64"
		 * value="5" name="big" resolution="200x-1"
		 * 			 
		 */
	);

Example 2:

File:DatatypeBlobMapping.png

Figure 11: BlobMapping For Employee images.

Disclaimer / Notice

A small notice/disclaimer about the how it is used in other DSLs...

How to use existing and newly created Datatypes? => The same way it is used in the Entity DSL, Entitymock DSL and the Function Library DSL with the import keyword.

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