# Makumba Specification

[Data Definitions] | [Query Languages] | [JSP tag library: Intro | Listing | Forms] | [Business Logics] | [Summary]

## Data Definition Language

Types, objects, databases Fields Default fields Simple field types int real char text date Structural (relational) types ptr set Macro types Field attributes Object title Include mechanism | (the Makumba abstract level) ### Types, objects, databases Data definitions describe data types (or classes). They are placed in files contained in directory hierarchies, and the directory name is part of the type name (similar to Java packages). For example the file best/Student.mdd describes the type best.Student. Type names can contain letters, digits, underscores and dashes and cannot contain slashes and dots. Usually, the directories are used to separate organisations and projects. Current Java implementation finds the data definition files as follows: the designated file extension is `.mdd` (Makumba Data Definition) relative to CLASSPATH (e.g. `classes/best/Student.mdd`) in a directory called "dataDefinitions/" in the CLASSPATH (e.g. `classes/dataDefinitions/best/Student.mdd`) OLDSTYLE: if no mdd file is present, the no-extension file (i.e. best/Student) is looked up Data objects (records) are stored in databases. The actual implementation of the database is not part of this specification but implementation suggestions will be made. Data can be copied and/or replicated between different databases, even between different DB engine types. Replication is not yet implemented, but the design is prepared for it. Copying works. ### Fields Every data definition file contains field definitions, separated by newline. A field definition looks like:
    fieldname= [attributes] fieldtype [parameters] [; description]
default values are supported internally, but not by the mdd parser As an implementation guideline, field names tend to stay approximately the same in: http requests Record instances (java.util.Dictionary in the current Java API) database columns etc (Automatic labeling: The field description might be used at interface levels to present that field. It is typically shown at the left of, or somewhere near to, the input control (text box, radio button, chooser, etc) that allows for data input in that field. If a field description is not present, its field name stands for its description by default.) Comment lines can be inserted in the data definition files as follows:
    # your comment...
### Default fields Every datatype has some additional fields by default, as follows: Primary Key field, consisting of two parts [DBSV with 8 bits | UID with 24 bits]: Database identifier (DBSV). It is unique (within the webapp) per database. All objects created thru that webapp and in that database get the same value. It is set by property dbsv in the database config file. Object identifier (UID): unique id for the object in the given database. This combination ensures that no two objects of one type have the same primary key field. See how to configure this. The name of the primary key field is the same with the last part of the type name. If another field by that name is defined by the makumba user, this field will be renamed in the database. Object creation time Can be accessed as TS_create. Last modification time. Updates whenever the object is changed. The initicial value is TS_create. Can be accessed as TS_modify. ### Simple field types #### int A 32-bit integer. For example
    shoeSize= int; Shoe size
If the int can have a limited number of values, it can be described as follows
    gender= int{ "male"=0, "female"=1 }; Sex
This will help the presentation layer to present a suitable input control (e.g. ) "deprecated" can be used in this way to denote a deprecated option: userType = int{"type1"=10, "type2"=10,"old"=0 deprecated} In the present implementation, this type is called "intEnum" internally. Negative numbers are supported (e.g. int { "aa"=5, "bb"=2, "cc"=-10}). #### real A read number with double precision with (2-2-52)·21023 as max value and 2-1074 as min value. For example:
    high= real; high of a person
#### char A char field contains a number of characters. Maximal width must be specified and is limited to 255. (Optionally a minimal number of characters (lesser than max) can be indicated). Both must be positive integers. For example:
    #fieldName= char[maxWidth]
    name= unique char[80]; Username
    #fieldName= char[minWidth..maxWidth]
    password= encrypted char[6..10]; Secret password
"`unique`" and "`encrypted`" are field attributes, explained below. Pay close attention to the character set (charset) for encoding the characters. In Java the charset is Unicode, but the JSP/HTML pages have their own encoding settings, as well as the database, etc. DEPRECATED (use int{...} instead): If the char can have a limited number of value, it can be described as follows
    gender= char{ "male", "female" }; Sex
This will help the presentation layer to present a suitable input control (e.g. a HTML SELECT) in the present implementation, this type is called "charEnum" internally #### text An unlimited-length string of bytes or characters. This type was designed to accomodate large text or binary content. It is implemented with LONGVARBINARY or its counterparts, depending on the underlying DB engine.
    application= text ; Application letter
    description=text  ; Description of object
    image= text	  ; Picture attachment
#### date A date and/or time.
    birthdate= date; Date of birth
    arrivalTime= date; Arrival time
### Structural (relational) types #### Pointers (ptr) Pointers define a reference to an object of a certain type. For example
    citizenship= ptr general.Country; Citizenship
the `ptr` keyword might be ommitted in future parsers The type can be defined on-the-spot for a single usage. For example
    addres= ptr ; Address
    address->street= char[80]; Street
    address->number= int; Number
The main difference between sets of external types and internal sets is that when the host object (e.g. Person.mdd that has the above field "address") is deleted from the database (DB), also all elements of the set (addresses) are deleted automatically, so there is no orphans (addresses) in the DB. Elements (addresses) of an internal set of some host object (Person X) also can't be used in a set of some other host object (Company Y). future parsers might read this:
    address= ptr{
        street= char[80]; Street
        number= int; Number}; address
this type is known internally as ptrOne #### Sets (set, bag, list) Sets define a number of references to multiple objects of a certain type. For example:
    language= set general.Language; Spoken languages
This type accomodates sets, bags and lists. The set and list constraints (sets have to contain only one element of a certain value and lists have to be ordered) have to be cared for by the programmer. Lists are easy to represent, just having an integer field, for the order. The type which the set is made of can be defined on the spot:
    addresses= set; Addresses
      addresses->street= char[80]; Street
      addresses-> number= int; Number
the future parser might recognize this form:
    addresses: set{
        street: char[80]; Street
        number: int; Number }; Addresses
this type is known internally as setComplex The set can contain enumerated int values :
    place= set int {"home"=1, "away"=0} ; Home or away
this is currently known internally as setintEnum DEPRECATED: The set can contain enumerated char values :
    place= set char {"home", "away"} ; Home or away
It means that place is a set that can take only the "home" and "away" values. This is currently known internally as setcharEnum ### Macro types A name can be defined for a more complex type and it can be reused in the file. This can be done with a !type directive
    !type.yesno= int{"yes"=1, "no"=0}
    !type.rank= int{"neutral"=0, "very good"=5, "very bad"=-5}
    married=yesno
    happyInLife=rank
### Field attributes fixed fields can only set during the record's insertion in the database. The subsequent updates will not update the field not null fields will produce a exception if an attempt is made to insert/update without them being initialized unique fields have a unique value in the respective object, for the respective type (encrypted fields are encrypted when written to the database and decrypted when read) Currently only fixed and not null field attributes are working, while support for unique is in progress. ### Object title The object title is used for set and ptr choosers One of the fields is always the object title, and is normally presented differently from other fields in user interface. For example, when you have a field that is a set and you use a mak:input on that field, Makumba will automatically create a list with all the items in the set and it will use the object title to know what field to display. The default is the field called "name" if that exists, otherwise it is the first non-pointer field in the record description. If another field needs to be title, it can be specified like
    !title=gender
for the on-the spot types in the current implementation, the following notation works:
    address->!title= street
### Include mechanism A record description can include text from one or more files. This is declared as
    !include=name_of_included_type
The included file has the idd extension and is found in a similar way like the data definitions. The included file is inserted instead of the !include line. There can be more include lines in a record description file. If a field is defined that exists also in the included metadata, the defined field takes precedence. If
    fieldname=
it means that it does not actually exist. this can be used to cancel an included field. include might be replaced by more advanced concepts such as inheritance and type inclusion (rather than reference in foreign table)