Makumba uses so-called Makumba Data Definitions (MDDs) in order to represent objects. These definitions are also referred to as type of an object. This section provides a short overview of MDDs and illustrates them with some examples, check the reference documentation for more details on MDDs.
This documentation does not give any guidelines regarding data model design. We assume that you already has some knowledge of general data model design concepts.
General principles#
MDDs are stored as files that are located in the WEB-INF/classes/dataDefinitions folder of your webapp. Their file extensions are .mdd and the resulting Makumba type name is using the same naming principle of Java packages, i.e. the MDD stored in WEB-INF/classes/dataDefinitions/company/Employee.mdd will have as type name company.Employee.
MDDs contain following elements:
- the field definitions
- validation rules referring to one or more fields
- MDD functions
We will further explain those type of fields by using the following example of a company that has employees, each working in a department and assigned to several projects:
 |
Let's take a look at the Makumba Data Definitions that fit this example:
company.Company (company/Company.mdd)
name = char[50] turnover = real suppliers = set company.Company targetMarkets = set general.Country logo = file
company.Department (company/Department.mdd)
name = char[50] company = ptr company.Company manager = ptr company.Employee
company.Employee (company/Employee.mdd)
name = char[200]
surname = char[200]
gender = int{"Male" = 10, "Female" = 20}
birthdate = date
salary = real
department = ptr company.Department
projects = set
projects->project = ptr company.Project
projects->timePercentage = int ;percentage assigned
company.Project (company/Project.mdd)
name = char[255] leader = ptr company.Employee description = text
Field definitions#
This section gives a short overview of the different types of field types that exist in Makumba:Primitive types#
| Field definition type | Description | Default edit user interface |
|---|---|---|
| int | a simple integer | text field |
| int{} | Integer enumeration, allowing for a set of predefined values | dropdown choice or radio button |
| real | a real number | text field |
| date | a date | date |
| char | a limited text (maximum length is 255) | text field |
| text | an unlimited text | text area |
| binary | a binary content, e.g. an image | binary area |
| file | a file including its meta-data (content type, size, ...) | file upload |
Relational types and collections#
| Field definition type | Description | Default edit user interface |
|---|---|---|
| ptr | a pointer to another type record | dropdown select of record titles. |
| set | a set of records of another type (which could be re-used in another type) TODO: set chooser link | multiple choice of record titles. |
| fieldName=set fieldName-> ... |
an internal set that relates to one specific record | multiple choice of record titles |
| set int{} | a set of predefined values | multiple choice from values |
Validation rules#
Validation rules make it possible to automatically ensure the validity of the data entered by the user in forms. These rules take place at the client level (if client-side validation is enabled) and at the server level.
If we wanted to ensure that employees have to be at least 16 years old, we could add the following line to the company.Employee MDD:
compare(birthdate) {birthdate <= date($now, $now, $now - 16)} : An employee has to be at least 16 years old!
Additionally to these explicit validation rules, the type of a field and/or the field attributes generate automatic checks that reflect on validation. For example name = not null char[255] will lead to a client and server-side check that makes sure this field is not empty, and salary=real will trigger a check for the input actually containing a number.
For a complete list of these implicit rules, please refer to the reference documentation on validation rules.
MDD functions#
MDD functions are functions defined in a Makumba Data Definition and can be used in all kind of Makumba queries (in business logic, on the JSP level or in other functions).If we want to often print the name and surname of one employee, we can define the following function in company.Employee:
nameSurname() { concat(name, ' ', surname }
You can read more about MDD functions in the reference documentation or in the MDD function usage documentation.
Interaction with the database schema#
One powerful feature of Makumba is that it takes care of the interaction with the database. This means that once you correctly configured the database, Makumba will create and maintain the table structure for you, as well as indexes and foreign keys. Allowing the alteration of specific types
In order to allow Makumba to create the necessary tables related to a type, it is necessary to declare this in the data source configuration in Makumba.conf.
When using the Makumba database layer, this is done by using the alter#typeName=tue/false parameter in the data source section it should apply to (it may be that you don't want to allow schema update in your production environment whilst it's not a problem in a test environment).
alter#company.Employee=true
will allow Makumba to alter the table structure of the company.Employee type.
alter#=true
will allow Makumba to alter all the types in the database.
Make sure you allow Makumba to modify a type after creating or updating it, or these changes won't reflect in the database and you will get an error.
Changes in the MDD structure require a webapp restart in order to reflect in the database.
When using the Hibernate database layer, the parameter makumba.schemaUpdate=true|false has to be used in order to allow the database layer to alter the database schema.
Makumba table and field names#
Makumba generates table and field names in a specific manner:
- company.Employee will be kept in the table company_Employee_
- the primitive field company.Employee#name will be called name_ in the database
- the internal set company.Employee#projects will be hold in the table company_Employee__projects_
- the external set company.Company#suppliers will be hold in the table company_Company_ (since it is a set of companies) and the intermediary table general_Company__suppliers_ will hold the references to its members
This mechanism can be modified to some extent by using a number of parameters in the data source configuration in Makumba.conf:
- company.Company = company means that Makumba will look for the type company.Company in the database table company instead of company_Company_
- company.Company->name = companyName means that Makumba will look for the field name in the database field companyName instead of name_
- the parameter addUnderscore=true|false makes it possible to control whether underscores are appended to the database name of tables and fields