View source for Datatype DSL

==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. 
<br/>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...). 


==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.
 
► '''Syntax''':
<syntaxhighlight lang="java">
import importStatement

package name {
    datatype datatypeDefinition
    enum enumDefinition
}
</syntaxhighlight>


► '''Example''':
<syntaxhighlight lang="java">
package net.osbee.sample.foodmart.datatypes {
   ...
}
</syntaxhighlight>


===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.<br/> 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. 


► '''Syntax''':
<syntaxhighlight lang="java">
import importStatement
</syntaxhighlight>



► '''Example 1''':
<syntaxhighlight lang="java">
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 {
   ...
}
</syntaxhighlight>



Import statements also allow the use of the '*' wildcard.


► '''Example 2''':
<syntaxhighlight lang="java">
import java.lang.*

import java.math.BigDecimal
...

package net.osbee.sample.foodmart.datatypes {
   ...
}</syntaxhighlight>


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

► '''Syntax''':
<syntaxhighlight lang="java">
 datatype <name> jvmType <type> asPrimitive
</syntaxhighlight>


Specifying datatypes in this manner uses an appropriate wrapper class in the generated Java code. Adding the keywords <code>asPrimitive</code> enforces the use of primitive datatypes where applicable.


► '''Example 1''':
<syntaxhighlight lang="java">
datatype foo jvmType Integer
</syntaxhighlight>


compiles to an <code>Integer</code> whereas 

► '''Example 2''':
<syntaxhighlight lang="java">
datatype foo jvmType Integer asPrimitive
</syntaxhighlight> 


results in <code>int</code>.


[[File:entity-3.png|center|frame|''Figure 1: The defined datatype is translated to a wrapper class'']]
[[File:Entity-4.png|center|frame|''Figure 2: By adding the <code>asPrimitive</code> keywords, the datatype is translated to a primitive datatype'']]



► '''Example 3''':
<syntaxhighlight lang="java">
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
</syntaxhighlight>

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

► '''Syntax''':
<syntaxhighlight lang="java">
datatype <name> dateType {date|time|timestamp} [options]*
</syntaxhighlight>

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

[[File:Entity-5.png|center|frame|''Figure 3: Defining datatypes for handling temporal information. Content assist is available.'']]

► '''Example 1''':
<syntaxhighlight lang="java">datatype MyDate dateType date</syntaxhighlight>

► '''Example 2''':
<syntaxhighlight lang="java">datatype MyDate dateType time</syntaxhighlight>

► '''Example 3''':
<syntaxhighlight lang="java">datatype MyDate dateType timestamp</syntaxhighlight>


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

► '''Syntax''':
<syntaxhighlight lang="java">

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

</syntaxhighlight>


Please note that setting the <code>severity</code> 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''':
<syntaxhighlight lang="java">
datatype BirthDate dateType date isNotNull isPast[severity=error]</syntaxhighlight>

[[File:DatatypeIconSeverity1.png|center|frame|''Figure 4:  Birthdate - Severity Level 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 <code>asBlob</code>. The Java implementation of such a blob is a byte array. Appropriate persistence annotations are automatically added.

► '''Syntax''':
<syntaxhighlight lang="java">datatype <name> asBlob</syntaxhighlight> 


► '''Example''':
<syntaxhighlight lang="java">
datatype blobtype asBlob
datatype clobtype asBlob
</syntaxhighlight>

====properties====
With the <code>properties</code> 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''':
<syntaxhighlight lang="java">properties '(' key="AKey" value="AValue" [, key="AnotherKey" value="AnotherValue"]* ')'</syntaxhighlight>

► '''Example 1''':
<syntaxhighlight lang="java">
key="age"  value="15"
key="name" value="Joe"
</syntaxhighlight>


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.<br/>

► '''Example 2''':
<syntaxhighlight lang="java">
datatype RichText_Long asBlob properties(key = "type" value = "richTextArea")
datatype Password jvmType String properties(key = "type" value = "password")
</syntaxhighlight>


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

► '''Example''':
<syntaxhighlight lang="java">datatype TextArea jvmType java.lang.String properties(key = "textarea" value = "5")</syntaxhighlight>

in [projectname] .entitymodel:

► '''Example''':
<syntaxhighlight lang="java">var TextArea description</syntaxhighlight>

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:

► '''Example''':
<syntaxhighlight lang="java">
datatype SmartImagejvmType java.lang.String properties(key="Blob" value="2")
</syntaxhighlight>

in *.entitymodel:

► '''Example''':
<syntaxhighlight lang="java">
/** portrait of person */
var SmartImage portrait 
</syntaxhighlight>

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

► '''Example''':
<syntaxhighlight lang="java">
datatype Price jvmType java.lang.Double asPrimitive properties (key="decimalformat" value="¤ ###,###.##")
</syntaxhighlight>

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.

► '''Example''':
<syntaxhighlight lang="java">
datatype Price jvmType java.lang.Double asPrimitive properties (key="decimalformat" value="&curren; ###,###.##")
</syntaxhighlight>

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:
<blockquote>
<table class="wikitable">
 <tr><th>Pattern</th><td colspan="2" align="center">PositivePattern</td><td colspan="2" align="center">PositivePattern</td><td align="center">;</td><td align="center">NegativePattern</td></tr>
 <tr> <th>PositivePattern</th><td colspan="2" align="center">Prefixopt</td><td colspan="2" align="center">Number</td><td colspan="2" align="center">Suffixopt</td></tr>
 <tr> <th>NegativePattern</th><td colspan="2" align="center">Prefixopt</td><td colspan="2" align="center">Number</td><td colspan="2" align="center">Suffixopt</td></tr>
 <tr> <th>Prefix</th><td colspan="6" align="center">any Unicode characters except \uFFFE, \uFFFF, and special characters</td></tr>
 <tr> <th>Suffix</th><td colspan="6" align="center">any Unicode characters except \uFFFE, \uFFFF, and special characters</td></tr>
 <tr> <th>Number</th><td>Integer</td><td>Exponentopt</td><td>Integer</td><td align="center">.</td><td>Fraction</td><td>Exponentopt</td></tr>
 <tr> <th>Integer</th><td>MinimumInteger</td><td align="center"># #</td><td>Integer</td><td align="center">#</td><td align="center">,</td><td>Integer</td></tr>
 <tr> <th>MinimumInteger</th><td align="center">0 0</td><td>MinimumInteger</td><td align="center">0</td><td align="center" colspan="2">,</td><td>MinimumInteger</td></tr>
 <tr> <th>Fraction</th><td colspan="3" align="center">MinimumFractionopt</td><td colspan="3" align="center">OptionalFractionopt</td></tr>
 <tr> <th>MinimumFraction</th><td colspan="3" align="center">0</td><td colspan="3" align="center">MinimumFractionopt</td></tr>
 <tr> <th>OptionalFraction</th><td colspan="3" align="center">#</td><td colspan="3" align="center">OptionalFractionopt</td></tr>
 <tr> <th>Exponent</th><td colspan="3" align="center">E</td><td colspan="3" align="center">MinimumExponent</td></tr>
 <tr> <th>MinimumExponent</th><td colspan="3" align="center">0</td><td colspan="3" align="center">MinimumExponentopt</td></tr>
</table>
</blockquote>


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. 

<blockquote>
<table class="wikitable">
<tr><td><strong>Symbol</strong></td><td><strong>HTML encoded</strong></td><td><strong>Location</strong></td><td><strong>Localized?</strong></td><td><strong>Meaning</strong>
</td></tr><tr><td>0</td><td>0</td><td>Number</td><td>Yes</td><td>Digit
</td></tr><tr><td>#</td><td>#</td><td>Number</td><td>Yes</td><td>Digit, zero shows as absent
</td></tr><tr><td>.</td><td>.</td><td>Number</td><td>Yes</td><td>Decimal separator or monetary decimal separator
</td></tr><tr><td>-</td><td>-</td><td>Number</td><td>Yes</td><td>Minus sign
</td></tr><tr><td>,</td><td>,</td><td>Number</td><td>Yes</td><td>Grouping separator
</td></tr><tr><td>E</td><td>E</td><td>Number</td><td>Yes</td><td>Separates mantissa and exponent in scientific notation. Need not be quoted in prefix or suffix.
</td></tr><tr><td>;</td><td>;</td><td>Subpattern boundary</td><td>Yes</td><td>Separates positive and negative sub patterns
</td></tr><tr><td>%</td><td>%</td><td>Prefix or suffix</td><td>Yes</td><td>Multiply by 100 and show as percentage
</td></tr><tr><td>\u2030</td><td>&amp;permil;</td><td>Prefix or suffix</td><td>Yes</td><td>Multiply by 1000 and show as per mille value
</td></tr><tr><td>¤ (\u00A4)</td><td>&amp;curren;</td><td>Prefix or suffix</td><td>No</td><td>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.
</td></tr>
<tr><td>'</td><td>'</td><td>Prefix or suffix</td><td>No</td><td>Used to quote special characters in a prefix or suffix, for example, "'#'#" formats 123 to <tt>"#123"</tt>. To create a single quote itself, use two in a row: "# o<em>clock</em>".</td></tr></table>
</blockquote>

=====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.<br/>
If the key is '''time''', then the date fraction of the Date datatype will be omitted.<br/>
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: 
<blockquote>
<table class="wikitable">
<tr><td><strong>value</strong></td><td><strong>resolution pattern</strong></td><td><strong>meaning</strong>
</td></tr><tr><td>YEAR</td><td>yyyy</td><td>only display the 4 digit year
</td></tr><tr><td>MONTH</td><td>yyyy.MM</td><td>display year and month
</td></tr><tr><td>DAY</td><td>yyyy.MM.dd</td><td>display day month and year
</td></tr><tr><td>HOUR</td><td>yyyy.MM.dd HH</td><td>complete date with hour
</td></tr><tr><td>MINUTE</td><td>yyyy.MM.dd HH:mm</td><td>complete date with hour and minute
</td></tr><tr><td>SECOND</td><td>yyyy.MM.dd HH:mm:ss</td><td>complete date and time
</td></tr></table>
</blockquote>

===enum=== 
Enumerations can be handled by defining a slightly different datatype with the <code>enum</code> keyword. The Java implementation of such a enum is exactly the same.

► '''Syntax''':
<syntaxhighlight lang="java">enum <name>  { <Value1> [, <Value2>]* }</syntaxhighlight>

► '''Example''':
<syntaxhighlight lang="java">
enum LayoutingStrategies {
    Form2, Form3, Horizontal, Vertical, Grid, Css
}

enum ItemClassification {
    Class_A, Class_B, Class_C
}
</syntaxhighlight>

===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''':
<syntaxhighlight lang="xtend">
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"
		 * 			 
		 */
);
</syntaxhighlight>



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''':
<syntaxhighlight lang="java">
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
	...
}
</syntaxhighlight>

[[File:DatatypeBlobMappingImage.png|center|frame|''Figure 5: BlobMapping For Employee images.'']]


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.


[[File:DatatypeBlobMappingPDF.png|center|frame|''Figure 6: Report For Employee PDF.'']]


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|''Entity DSL Model'']] with '''import'''-statements.


== Copyright Notice ==
{{Copyright Notice}}