<?xml version="1.0"?>

<document>

  <properties>
    <title>Melati - Java SQL Website Development Engine</title>
    <author email="timp@paneris.org">Tim Pizey</author>
    <keywords>
      Persistence, Java, SQL, Database, Templates, Object Relational Mapping,
      ORM, Objects, Object Oriented, J2EE replacement
    </keywords>
  </properties>

  <body>


<!--
<p align="center">
 <font size="-1"><i>
This page last updated: $Date: 2007/01/18 16:40:03 $ $Author: timp $
 </i></font>
</p>
-->
  
<!-- menu -->

<section name=" Unification ">
<p>
Melati is based upon holding rich metadata about database objects.
This metadata is held in three locations and three different formats:
the database metadata tables, the JDBC metadata and generated java files.
</p>
<p>
The unique feature of Melati is that it does a three way 
unification between these three potentially conflicting sets of metadata.
</p>

<subsection name=" What is Unification ">
<p>
We are talking about <a href='http://en.wikipedia.org/wiki/Unification'>Unification</a> 
as in Prolog, ie a procedure for making sets of variables with attributes equivalent.
</p>
<p>
If you have two lists of assigned variables then all those that occur in both
and are equivalent unify, any which only occur in one are copied to the other
and so unify. If a variable occurs in both but does not have equivalent attributes 
then unification fails.
</p>
<p>
In a three way unification one needs in theory to unify 
<b><tt>A</tt></b> with <b><tt>B</tt></b>, unify the resultant 
(<b><tt>A</tt></b> or <b><tt>B</tt></b>) with 
<b><tt>C</tt></b> and then unify the resultant (<b><tt>B</tt></b> or <b><tt>C</tt></b>) 
with <b><tt>A</tt></b> again, though we will see below that this last step is not 
required in our case.
</p>
</subsection>
<subsection name=" Metadata ">
<p>
A PoemDatabase has an <a href='http://en.wikipedia.org/wiki/Codds_twelve_rules' 
title="Codd's 12 rules">
Active online catalog based on the relational model</a> 
that is to say it has system tables called <a
href="/melati/Admin/contacts/tableinfo/Main">tableInfo</a> and <a 
href="/melati/Admin/contacts/columninfo/Main">columnInfo</a> which are used to store 
metadata about the tables and fields in the database.
</p>
<p>
All JDBC databases contain and can supply metadata about their contents
through the <a
href="http://java.sun.com/j2se/1.3/docs/api/java/sql/DatabaseMetaData.html">DatabaseMetaData</a>
class of the <a
href="http://java.sun.com/j2se/1.3/docs/guide/jdbc/index.html">JDBC API</a>.
</p>
<p>
A Poem Table can support all SQL datatypes as columns, but Poem holds more
metadata about a column than SQL does, for instance how to display the 
field.
</p>
</subsection>
<subsection name=" Unification Rules ">
<p>
In the abstract, Prolog, sense unification between two trees is 
bi-directional, with no precedence, but our case is limited:
</p>
<ol>
<li>
Metadata in the database tables takes precedence over metadata in the java code.
</li>
<li>The java code is compiled so cannot change, however see Iterating below.</li>
<li>The existing jdbc metadata cannot be changed only added to.</li>
</ol>
<p>
The equivalence function between Poem's datatypes and SQL datatypes (called 
<a 
href="/melati/apidocs/org/melati/poem/dbms/AnsiStandard.html#canRepresent(org.melati.poem.PoemType,
org.melati.poem.PoemType)">canRepresent</a>) determines whether a JDBC column 
is allowed to unify with a columnn in the <tt>columnInfo</tt> table.
</p>
</subsection>
<subsection name=" Example ">
<p>
If you point melati at an empty database it will unify with a 
<a href="/melati/apidocs/org/melati/poem/PoemDatabse.html">PoemDatabase</a> 
creating tables and populating the metadata tables with results shown below:
</p>
<table>
<caption>Unifying with empty database</caption>
<tr>
<th>
Poem
</th>
<th>
Info
</th>
<th>
JDBC
</th>
</tr>
<tr>
<td bgcolor="lime">
<a href="/melati/apidocs/org/melati/poem/TableInfoTable.html">TableInfoTable</a>
</td>
<td  bgcolor="cyan">
tableinfo
</td>
<td bgcolor="cyan">
TABLEINFO
</td>
</tr>
<tr>
<td  bgcolor="lime">
<a href="/melati/apidocs/org/melati/poem/ColumnInfoTable.html">ColumnInfoTable</a>
</td>
<td bgcolor="cyan">
columninfo
</td>
<td bgcolor="cyan">
COLUMNINFO
</td>
</tr>
<tr>
<td  bgcolor="lime">
<a href="/melati/apidocs/org/melati/poem/TableCategoryTable.html">TableCategoryTable</a>
</td>
<td bgcolor="cyan">
tablecategory
</td>
<td bgcolor="cyan">
TABLECATEGORY
</td>
</tr>
</table>
<p>
If you point it at your database, then the Poem metadata tables are 
created and the information about them and your table is stored in them
(the metadata tables hold information about themselves as per Codd's rule).
</p>
<table>
<caption>Unifying with populated database</caption>
<tr>
<th>
Poem
</th>
<th>
Info
</th>
<th>
JDBC
</th>
</tr>
<tr>
<td bgcolor="cyan">
 
</td>
<td  bgcolor="cyan">
yourtable
</td>
<td bgcolor="lime">
YOURTABLE
</td>
</tr>
<tr>
<td bgcolor="cyan">
<a href="/melati/apidocs/org/melati/poem/TableInfoTable.html">TableInfoTable</a>
</td>
<td  bgcolor="cyan">
tableinfo
</td>
<td bgcolor="cyan">
TABLEINFO
</td>
</tr>
<tr>
<td  bgcolor="cyan">
<a href="/melati/apidocs/org/melati/poem/ColumnInfoTable.html">ColumnInfoTable</a>
</td>
<td bgcolor="cyan">
columninfo
</td>
<td bgcolor="cyan">
COLUMNINFO
</td>
</tr>
<tr>
<td  bgcolor="cyan">
<a href="/melati/apidocs/org/melati/poem/TableCategoryTable.html">TableCategoryTable</a>
</td>
<td bgcolor="cyan">
tablecategory
</td>
<td bgcolor="cyan">
TABLECATEGORY
</td>
</tr>
</table>
</subsection>
<subsection name=" Use case - Generating classes from a database ">
<p>
You have a database, which is normalised and has a numeric primary key called
<tt>id</tt> 
in each table and you want to represent this in java.
</p>
<p>
The unification process takes the following steps:
<ol>
<li>
Look for database metadata tables (tableinfo, columninfo, tablecategory) - not found, so created
</li>
<li>
Use the java definitions of a PoemDatabase to create tables the user management 
and settings table and populate tableinfo and columninfo with details of these tables.
</li>
<li>
Read the JDBC metadata to populate tableinfo and columninfo with details of 
your tables.
</li>
</ol>
You can now view your database in the Admin system.
You can generate a Data Structure Definition file using the Admin system 
<a href="/melati/Admin/melatitest/DSD?comments=true">DSD Report</a> from which 
you can generate your java files.
</p>
</subsection>
<subsection name=" Use case - Generating a database from a data definition">
<p>
You have defined the database structure you want in a DSD file.
</p>
<p>
Depending upon your DBMS you may need to create an empty database, then point 
Melati at that database and the unification process will create the tables
themselves and populate the tableinfo and columninfo tables for you.
If your application requires that some tables are populated with default
values, type tables for example, then you can add an <tt>ensure</tt> method to 
your table initialisation method to create these values if absent.
</p>
</subsection>
<subsection name=" Iterating ">
<p>
Once you have a functioning Poem database you can create a DSD using the 
Admin system <a href="/melati-webapp/Admin/contacts/DSD?comments=true">DSD Report</a>.
</p>
<p>
This can be fed back into the start of the process, enabling you to add meta
data, such as verbose descriptions of fields and tables, using the Admin
interface, and then recreate your data definition and hence your java source.
</p>
<p>
This feature is particularly powerful in a situation where you are capturing
requirements with a customer, as you can add and delete tables and columns, 
reorder them and change their characteristics on the fly in real time, 
then export your DSD and capture the metadata in your java files.
</p>
</subsection>
</section>
</body>
</document>












