<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE document PUBLIC "-//MAKUMBA//DTD Documentation V2.0//EN" "document-v20-mak.dtd">

<document>
	<header>
		<title>Data Definition Language</title>
		<subtitle>(the Makumba abstract level)</subtitle>
	</header>
	<body>


		<section id="Types_objects_databases">
			<title>Types, objects, databases</title>

			<p>Data definitions describe <strong>data types (or classes)</strong>. 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 <strong>the file
					company/Employee.mdd </strong>describes <strong>the type general.Person</strong>.
				Type names can contain letters, digits, underscores and dashes and cannot contain
				slashes and
				dots.<!-- MDD max size 255 : http://bugs.best.eu.org/show_bug.cgi?id=639 -->
				Usually, the directories are used to separate organisations and projects.</p>

			<p>Current Java implementation finds the data definition files as follows:</p>
			<ul>
				<li>the designated file extension is <code>.mdd</code> (Makumba Data
					Definition)</li>
				<li>relative to CLASSPATH (e.g. <code>classes/company/Employee.mdd</code>)</li>
				<li>in a directory called "<strong>dataDefinitions/</strong>" in the CLASSPATH (e.g.
						<code>classes/dataDefinitions/company/Employee.mdd</code>)</li>
			</ul>

			<p><strong>Data objects (records)</strong> are stored in <strong>databases</strong>.</p>
			<p><strong>Data can be copied and/or replicated between different databases</strong>,
				even between different DB engine types.</p>
			<note>Replication is not yet implemented, but the design is prepared for it. Copying
				works.</note>
		</section>

		<section id="Fields">
			<title>Fields</title>

			<p>Every data definition file contains <strong>field definitions</strong>, separated by
				newline.</p>
			<p>A field definition looks like:</p>
			<source><![CDATA[fieldname= [attributes] fieldtype [parameters] [; description] ]]></source>

			<note>Default values are supported internally, but not by the MDD parser</note>

			<p>As an implementation guideline, field names tend to stay approximately the same
				in:</p>
			<!-- Put this <p> inside the list -->
			<ul class="internalnote">
				<li>HTTP requests</li>
				<li>Record instances (<a
						href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Dictionary.html"
						>java.util.Dictionary</a> in the current Java API)</li>
				<li>Database columns</li>
				<li>etc</li>
			</ul>

			<p>The field description is used by the code generator 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.</p>
			<p><strong>Comment lines</strong> can be inserted in the data definition files as
				follows:</p>
			<source><![CDATA[# your comment... ]]></source>
		</section>

		<section id="DefaultFields">
			<title>Default fields</title>

			<p>Every datatype has some additional fields by default, as follows:</p>
			<ul>
				<li><strong>Primary Key field</strong>. When using the Makumba database layer, it
					consists of two parts [DBSV with 8 bits | UID with 24 bits]: <ul>
						<li>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.</li>
						<li>Object identifier (UID): unique id for the object in the given
							database.</li>
					</ul>
					<br/> This combination ensures that no two objects of one type have the same
					primary key field. See <a
						href="/configuration/configuration.html#datasource_configuration">how to
						configure</a> this.<br/> 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.</li>
				<li><strong>Object creation time</strong> Can be accessed as <code>TS_create</code>. </li>
				<li><strong>Last modification time</strong>. Updates whenever the object is changed.
					The initicial value is <code>TS_create</code>. Can be accessed as <code>TS_modify</code>.
				</li>
			</ul>
		</section>

		<section id="SimpleFieldTypes">
			<title>Simple field types</title>
			<section id="int">
				<title>int</title>

				<p>A 32-bit integer. For example</p>
				<source>shoeSize= int; Shoe size</source>
				<p>If the int can have a limited number of values, it can be described as
					follows</p>
				<source>gender = int{ "Male" = 10, "Female" = 20 }</source>
				<p>This will help the presentation layer to present a suitable input control such as:</p>

				<ihtml>
    	<![CDATA[<select> 
      	<option value="0">male</option>
      	<option value="1">female</option>
    	</select> ]]>
				</ihtml>

				<note>"deprecated" can be used in this way to denote a deprecated option:<br/>
					userType = int{"type1"=10, "type2"=10,"old"=0 deprecated}</note>
				<note class="internal">In the present implementation, this type is called "intEnum"
					internally.<br/> Negative numbers are supported (e.g. int { "aa"=5, "bb"=2,
					"cc"=-10}).</note>
			</section>

			<section id="real">
				<title>real</title>
				<!-- http://bugs.best.eu.org/show_bug.cgi?id=430 -->
				<!-- http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Double.html -->
				<p>A real number with double precision with
						(2-2<sup>-52</sup>)&middot;2<sup>1023</sup> as max value and
						2<sup>-1074</sup> as min value. For example:</p>
				<source>turnover = real; turnover of the company</source>
			</section>

			<section id="char">
				<title>char</title>
				<p>A char field contains a number of characters. Maximal width must be specified and
					is limited to 255. <em class="future">(Optionally a minimal number of characters
						(lesser than max) can be indicated).</em> Both must be positive integers.
					For example:</p>
				<source>
<![CDATA[fieldName= char[maxWidth]
name= unique char[80];]]></source>
				<p><code>unique</code> is a <a href="#FieldAttributes"
						>field attribute</a>, explained below.</p>
				<note>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.</note>

			</section>

			<section id="boolean">
				<title>boolean</title>
				<p>A boolean, that can take as values true or false. For example:</p>
				<source>
<![CDATA[currentlyEmployed= true; whether this employee is currently employed]]></source>
			</section>

			<section id="text">
				<title>text</title>

				<p>An unlimited-length string of characters. This type is designed to accommodate
					large text content. It is implemented with LONGTEXT or its counterparts,
					depending on the underlying DB engine. The text data-type is ready for accepting
					data in UTF-8 encoding.</p>
				<source>
<![CDATA[description=text ; Description of the project ]]></source>
			</section>

			<section id="binary">
				<title>binary</title>

				<p>An unlimited-length field designed for binary content. In contrast to the
						<code>text</code> data type, binary will always be of 8 bit length. It is
					implemented with LONGTEXT or its counterparts, depending on the underlying DB
					engine. This type is meant for storing only raw binary data, for storing files
					along with meta-data like a file name, content type, etc., you should rather use
					the <a href="#file">file data type</a>.</p>
				<source>
					<![CDATA[signature= binary ; a binary digital signature ]]></source>
			</section>

			<section id="date">
				<title>date</title>

				<p>A date and/or time.</p>
				<source>
<![CDATA[birthdate = date; Date of birth
arrivalTime = date; Arrival time]]></source>
				<!-- FIXME. (fred, 2003-10-13) bug 606

    	 Should there be a warning about "time".

    	 Because it really isn't a "time", it would be a "date" where d/m/y fields

    	 are not set explicitly... but they are filled in with 'random'/'current'

     	values. So comparison as "time" < 9am or so is not possible?

         -->
			</section>
		</section>


		<section id="StructuralTypes">
			<title>Structural (relational) types</title>

			<section id="ptr">
				<title>ptr</title>

				<p>Pointers define a reference to an object of a certain type. For example</p>
				<source><![CDATA[manager = ptr company.Employee; The manager of the department]]></source>
				</section>

			<section id="set">
				<title>set</title>

				<p>Sets define a number of references to multiple objects of a certain type. For
					example:</p>
				<source>
<![CDATA[suppliers= set company.Company; Suppliers of this company]]></source>
				<p>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.</p>
				<p>The type which the set is made of can be defined on the spot:</p>
				<source>
<![CDATA[projects = set
projects->project = ptr company.Project
projects->timePercentage = int ;percentage assigned]]></source>
				<note>The main difference between sets of external types and internal sets is that
					when the host object (e.g. Employee.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).</note>
				<note class="internal">This type is known internally as setComplex</note>
				<p>The set can contain enumerated int values :</p>
				<source>
<![CDATA[ place= set int {"home"=1, "away"=0} ; Home or away ]]></source>
				<note class="internal">This is currently known internally as setintEnum</note>
				
			</section>

			<section id="file">
				<title>file</title>

				<p>A file data-type is a kind-of record containing several fields needed when
					wanting to store files. These fields are:</p>
				<ul>
					<li>content (<a href="#binary">binary</a>): the actual binary data of the
						file.</li>
					<li>name (<a href="#char">char</a>): the file name.</li>
					<li>originalName (<a href="#char">char</a>): the original file name.</li>
					<li>contentType (<a href="#char">char</a>): the MIME content-type of the
						file.</li>
					<li>contentLength (<a href="#int">int</a>): the content length in byte.</li>
					<li>imageWidth (<a href="#int">int</a>): (only for images) the image width.</li>
					<li>imageHeight (<a href="#int">int</a>): (only for images) the image
						height.</li>
				</ul>
				<source>
<![CDATA[ logo = file ; Picture attachment ]]></source>
				<p>All fields are automatically set by Makumba, all needed to do is to make a
					&lt;mak:input&gt; on the field name.</p>
				<p>This type should be used in favour of the <a href="#binary">binary data type</a>
					when you don't want to store only the raw binary data, but also meta-data as in
					the fields above.</p>

			</section>
		</section>


		<section id="MacroTypes">
			<title>Macro types</title>

			<p>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</p>
			<source>
<![CDATA[!type.rank = int{"Neutral"=0, "Very good"=5, "Very bad"=-5}

happyInLife = rank]]></source>
		</section>

		<section id="FieldAttributes">
			<title>Field attributes</title>
			<ul>
				<li><strong>fixed</strong> fields can only set during the record's insertion in the
					database. The subsequent updates will not update the field</li>
				<li><strong>not null</strong> fields will produce a exception if an attempt is made
					to insert/update without them being initialized</li>
                <li><strong>not empty</strong> fields will produce a exception if an attempt is made
                    to insert/update an empty string value</li>
				<li><strong>unique</strong> fields have a unique value in the respective object, for
					the respective type</li>
			</ul>
        <p>These attributes are used by makumba in order to perform <strong>implicit validation</strong> at form submission time, i.e., the fields of submitted forms will automatically be checked for coherence against the defined field attributes.</p>
        <p>It is possible to customise the error message that will be displayed in case an implicit field validation fails:</p>
        <source><![CDATA[login.unique = "This login is already taken, please choose another one"
surname.notEmpty = "Please fill in your surname"
age.notNull = "Please fill in your age"
age.NaN = "Please enter a valid number"
age.notInt = "Please enter a valid integer"
amount.notReal = "Please enter a valid real"]]></source>

<note>The NaN (Not A Number), notInt (not an integer) and notReal (not a real) error message is part of implicit, type-dependent validation and is performed by makumba automatically, without the need of adding a field attribute.</note>
		</section>

		<section id="ObjectTitle">
			<title>Object title</title>

			<note>The object title is used for <em>set</em> and <em>ptr</em> choosers</note>
			<p>One of the fields is always the <em>object title</em>, 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 <em>mak:input</em> on that field, Makumba will
				automatically create a list with all the items in the set and it will use the
					<em>object title</em> 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</p>
			<source>!title=gender</source>
			<note>for the on-the spot types in the current implementation, the following notation works:<br/>
				<code> address-&gt;!title= street</code></note>
		</section>

		<section id="Include">
			<title>Include mechanism</title>

			<p>A record description can include text from one or more files. This is declared as</p>
			<source>
<![CDATA[!include=name_of_included_type ]]></source>
			<p>The included file has the idd extension and is found in a similar way like the data
				definitions.</p>
			<p>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</p>
			<source>
<![CDATA[fieldname =]]></source>
			<p>it means that it does not actually exist. This can be used to cancel an included
				field.</p>
			<note class="future">Include might be replaced by more advanced concepts such as
				inheritance and type inclusion (rather than reference in foreign table)</note>
		</section>

	</body>
</document>