Datatype DSL
Contents
Purpose
The Datatype DSL is, beside the Entity DSL, one of the most basic DSL of 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 information 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 access to data types (Number, String, Boolean...).
Grammar Definition
The figures below represent how the grammar was designed, in order to make it possible for you to use and also create your own data types. This is the structural foundation on which the Datatype DSL model is based on.
Further information will be provided in upcoming releases.
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 elements 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 enum enumDefinition }
Example:
package net.osbee.sample.foodmart.datatypes { ... }
import
Although import statements are located above the package declaration, they are optional as you may not necessarily need to reference any external Java Classes to extend 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 importStatement
Example 1:
import java.lang.Double import java.lang.Boolean import java.lang.Long import java.lang.Character import java.lang.String import java.math.BigDecimal ... package net.osbee.sample.foodmart.datatypes { ... }
Import statements also allow the use of the '*' wildcard.
Example 2:
import java.lang.* import java.math.BigDecimal ... package net.osbee.sample.foodmart.datatypes { ... }
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 a .datatype file are local to that file.
There are three types of datatype definitions: jvmType, dateType and asBlob (blobs).
jvmType
Datatype definitions that map types to jvmType (Java Virtual Machine Types) 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.
asPrimitive keywords, the datatype is translated to a primitive datatypeExample 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.
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 the current date. <isFuture> specifies that every object of this datetype can only accept value after the current date. <isNull> specifies that any object of this datetype can have the value null. <isNotNull> specifies that every object of this datetype cannot have the value null. <'['severity = {error|info|warn} ']'> sets the severity level of a non valid value.
Please note that setting the severity level has the effect of showing in the application if a data is not valid. This happens as soon as you leave the concerned field and after the validation of its content by displaying at the moment an exclamation point and the value both in red (error). This depends of course on the set of options you would have chosen to be checked in your datetype-definition.
Example 4:
datatype BirthDate dateType date isNotNull isPast[severity=error]
In the example shown above only dates (values) from the past (current editing date included) are allowed.
asBlob
Binary blobs can be handled by defining a datatype followed by the keyword asBlob. The Java implementation of such a blob is a byte array. Appropriate persistence annotations are automatically added.
datatype <name> asBlob
Example:
datatype blobtype asBlob datatype clobtype asBlob
properties
With the properties keyword you are able to influence the visualization of UI components in extending the datatype definitions with additional metadata. The properties take effect whenever the data type is used in entity models, which are respectively inherited DTO DSL models. Changes on the datatype property therefore effect all visualizations depending on this datatype.
All these properties are required to achieve different behaviors on the visualization of information. Some of them are used by the AutowireHelper, other are used by the AbstractLayoutingStrategy to create varying UI elements based on the same data type.
Properties are a set of definitions each consisting of a pair of terms called key and value. A name–value pair, key–value pair, field–value pair or attribute–value pair is a fundamental data representation in computing systems and applications. Designers often desire an open-ended data structure that allows for future extension without modifying existing code or data. In such situations, all or part of the data model may be expressed as a collection of tuples <attribute name, value>; each element is an attribute–value pair. Depending on the particular application and the implementation chosen by programmers, attribute names may or may not be unique.
Syntax:
properties '(' key="AKey" value="AValue" [, key="AnotherKey" value="AnotherValue"]* ')'
Example 1:
key="age" value="15" key="name" value="Joe"
Please note that in this context the key is case-insensitive whereas the value is not. Key and value are always enclosed by quotation marks.
Example 2:
datatype RichText_Long asBlob properties(key = "type" value = "richTextArea")
Textarea
Let's consider the UI element known as Textarea. The key is textarea and the value determines the number of rows that will be created. The datatype is String.
Within a Sample application you will probably find:
in [projectname] .datatypes:
datatype TextArea jvmType java.lang.String properties(key = "textarea" value = "5")
in [projectname] .entitymodel:
var TextArea description
This construct creates a new datatype for project [projectname] which can be used in entitymodels, defining a textarea with 5 rows.
Images of a specified resolution
For performance reasons, images are stored in the database as base64 encoded strings. If uploaded, all resolutions defined in the blob-model are calculated and the resulting variants are stored in the database. As images are more often retrieved from database as stored, this approach helps the performance with the cost of an increased database storage space.
The key is blob and the value determines the resolution that will be created. The datatype is String.
Within a Sample application you will probably find:
in *.datatypes:
datatype SmartImagejvmType java.lang.String properties(key="Blob" value="2")
in *.entitymodel:
/** portrait of person */ var SmartImage portrait
Monetary and other decimal fields
To display fields formatted in a specified way there is the following construction: The key is decimalformat and the value determines the format pattern that will be created. The datatype is Double. Please note that Float is no longer supported in this context.
To display a double value with preceding currency sign, you could use this sample:
datatype Price jvmType java.lang.Double asPrimitive properties (key="decimalformat" value="¤ ###,###.##")
Note that ¤ the ASCII character 164 can be HTML encoded to avoid codepage problems in your editor. This also works for all other special characters.
datatype Price jvmType java.lang.Double asPrimitive properties (key="decimalformat" value="¤ ###,###.##")
The format pattern has a variety of features designed to make it possible to format numbers in any locale, including support for Western, Arabic, and Indic digits. It also supports different kinds of numbers, including integers (123), fixed-point numbers (123.4), scientific notation (1.23E4), percentages (12%), and currency amounts ($123). All of these can be localized.
A decimalformat comprises a pattern and a set of symbols.
Patterns
Patterns have the following syntax:
Pattern PositivePattern PositivePattern ; NegativePattern PositivePattern Prefixopt Number Suffixopt NegativePattern Prefixopt Number Suffixopt Prefix any Unicode characters except \uFFFE, \uFFFF, and special characters Suffix any Unicode characters except \uFFFE, \uFFFF, and special characters Number Integer Exponentopt Integer . Fraction Exponentopt Integer MinimumInteger # # Integer # , Integer MinimumInteger 0 0 MinimumInteger 0 , MinimumInteger Fraction MinimumFractionopt OptionalFractionopt MinimumFraction 0 MinimumFractionopt OptionalFraction # OptionalFractionopt Exponent E MinimumExponent MinimumExponent 0 MinimumExponentopt
A decimalformat pattern contains a positive and negative sub pattern, for example, "#,##0.00;(#,##0.00)". Each sub pattern has a prefix, numeric part, and suffix. The negative sub pattern is optional; if absent, then the positive sub pattern prefixed with the localized minus sign ('-' in most locales) is used as the negative sub pattern. That is, "0.00" alone is equivalent to "0.00;-0.00". If there is an explicit negative sub pattern, it serves only to specify the negative prefix and suffix; the number of digits, minimal digits, and other characteristics are all the same as the positive pattern. That means that "#,##0.0#;(#)" produces precisely the same behavior as "#,##0.0#;(#,##0.0#)".
The prefixes, suffixes, and various symbols used for infinity, digits, thousands separators, decimal separators, etc. may be set to arbitrary values, and they will appear properly during formatting. However, care must be taken that the symbols and strings do not conflict. For example, either the positive and negative prefixes or the suffixes must be distinct to be able to distinguish positive from negative values. (If they are identical, then decimalformat will behave as if no negative sub pattern was specified.) Another example is that the decimal separator and thousands separator should be distinct characters.
The grouping separator is commonly used for thousands, but in some countries it separates ten-thousands. The grouping size is a constant number of digits between the grouping characters, such as 3 for 100,000,000 or 4 for 1,0000,0000. If you supply a pattern with multiple grouping characters, the interval between the last one and the end of the integer is the one that is used. So "#,##,###,####" == "######,####" == "##,####,####".
Special Pattern Characters
Many characters in a pattern are taken literally; they are matched during parsing and output unchanged during formatting. Special characters, on the other hand, stand for other characters, strings, or classes of characters. They must be quoted, unless noted otherwise, if they are to appear in the prefix or suffix as literals.
The characters listed here are used in non-localized patterns. Localized patterns use the corresponding characters instead, and these characters lose their special status. Two exceptions are the currency sign and quote, which are not localized. In OS.bee you can use the HTML encoded name instead to avoid code page problems.
Symbol HTML encoded Location Localized? Meaning 0 0 Number Yes Digit # # Number Yes Digit, zero shows as absent . . Number Yes Decimal separator or monetary decimal separator - - Number Yes Minus sign , , Number Yes Grouping separator E E Number Yes Separates mantissa and exponent in scientific notation. Need not be quoted in prefix or suffix. ; ; Subpattern boundary Yes Separates positive and negative sub patterns % % Prefix or suffix Yes Multiply by 100 and show as percentage \u2030 ‰ Prefix or suffix Yes Multiply by 1000 and show as per mille value ¤ (\u00A4) ¤ Prefix or suffix No Currency sign, replaced by currency symbol. If doubled, replaced by international currency symbol. If present in a pattern, the monetary decimal separator is used instead of the decimal separator. ' ' Prefix or suffix No Used to quote special characters in a prefix or suffix, for example, "'#'#" formats 123 to "#123". To create a single quote itself, use two in a row: "# oclock".
Date and time fields
To display defined fractions of a date and time value you can use the following construct. The key is date, time or date_time. The value determines the resolution that will be created. The datatype is Date.
If the key is date, then the time fraction of the Date datatype will be omitted.
If the key is time, then the date fraction of the Date datatype will be omitted.
If the key is date_time, then all parts are displayed.
The value represents the resolution of the respective key. All components of the resolution pattern (divided by dots) are arranged in the order of the currently selected locale. Some resolutions only make sense with the appropriate key. E.g. with the key date, the resolution SECOND is not working. Resolutions are following a coarse-to-fine sequence and must be used in capitals:
value resolution pattern meaning YEAR yyyy only display the 4 digit year MONTH yyyy.MM display year and month DAY yyyy.MM.dd display day month and year HOUR yyyy.MM.dd HH complete date with hour MINUTE yyyy.MM.dd HH:mm complete date with hour and minute SECOND yyyy.MM.dd HH:mm:ss complete date and time
enum
Enumerations can be handled by defining a slightly different datatype with the enum keyword. The Java implementation of such a enum is exactly the same.
Syntax:
enum <name> { <Value1> [, <Value2>]* }
Example:
enum LayoutingStrategies { Form2, Form3, Horizontal, Vertical, Grid, Css } enum ItemClassification { Class_A, Class_B, Class_C }
Custom Datatypes
In this section you will find some informations about the available custom datatypes (OSBEE).
BlobMapping
This is a custom datatype that allows you to store media files, such as .PDF files, .TXT files and images (.PNG, .JPG, .GIF) in form of binary large files (blob). The implementation of this datatype allows you to save for instance an image file in several resolutions (here 6 as shown below) with a single line of code.
Syntax:
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" * */ );
In the following example you can see how to store pictures, by simply defining a variable from (data-)type Blobmapping in one Entity. In the application the user will get to chose an image with a Filepicker and upload it. A small image preview will be shown, if the file was successfully uploaded.
Example:
entity Memployee extends BaseID { persistenceUnit "businessdata" domainKey unique String full_name var String first_name var filter String last_name var range BirthDate birth_date var Date hire_date var Date end_date var range double salary var BlobMapping profileimage var String education_level var String marital_status ... }
If you selected a PDF file rather than an image based on the same code excerpt, as shown in the example above, you would see an small PDF icon, instead of an image preview.
As of now you can also store audio and video files as well as file from other formats. As show on the figure above, you will get an additional button for you to download the file you would have saved earlier.
Further information will be provided in upcoming releases.
Notice
You have created several new datatypes from scratch or defined some by referencing already existing Java classes. One of the logical next steps would be to make use of them inside your project as it is similarly done within the Entity DSL Model with import-statements.
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
