Makumba Specification

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.

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.

Fields

Every data definition file contains field definitions, separated by newline.

A field definition looks like:

fieldname= [attributes] fieldtype [parameters] [; description]

(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. male female )

real

A read number with double precision with (2-2^-52)·2¹⁰²³ 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.

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)

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

address= ptr{
    street= char[80]; Street
    number= int; Number}; address

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

addresses: set{
    street: char[80]; Street
    number: int; Number }; Addresses

The set can contain enumerated int values :

place= set int {"home"=1, "away"=0} ; Home or away

DEPRECATED: The set can contain enumerated char values :

place= set char {"home", "away"} ; Home or away

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)

Object title

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

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.