Melati is an open source, Java-based infrastructure for the rapid and convenient development of web-based database applications. This guide describes a preprocessor facility which forms part of Melati POEM (Persistent Object Engine for Melati), the layer which provides Melati with its object-oriented view of the underlying relational database. The preprocessor's task is to map a succinct Java-style "Data Structure Definition" file, in which the application programmer describes the schema of the database to which they expect their code to be attached, into a set of boilerplate Java source files implementing a statically-typed object-oriented API for that schema.
This document describes each of the stages involved in setting up a statically-typed application-specific object-oriented view of an RDBMS database using Melati POEM.
Melati POEM encourages you to think about your relational database in an object-oriented way. A table row corresponds to a Java object and can be given Java methods.
If you database SQL definition contains repetition, say every table contains the fields changetime and changedbyuser these fields can be separated out into a an abstract table which all your other tables extend.
POEM's DSD grammar is simple (similar to Java's syntax for defining class fields) and provides a convenient way of specifying display attributes for your objects' fields.
The DSD processor turns your DSD file into boilerplate classes which implement a type-safe API for your schema, and automatically create/validate your database at application startup time.
Before going any further you can look at your schema using the Melati Admin system.
Use the Admin system to fill in data in your schema.
The DSD also outputs stub classes to which you can add any special Java methods you wish to attach to your row-objects.
It is a good idea to use ensure methods to prepopulate code tables with values which are essential to the working of the system; see for example CapabilityTable.ensure(java.lang.String)
You may wish to use the DSD export function to review your DSD, http://www.melati.org/db/org.melati.admin.Admin/melatitest/DSD?comments though be aware that this function does not preserve abstract tables and enforces the only first letter capitalised rule for table names.
Attributes are "factory defaults" and are not applied to existing tables/columns. DSD is not exclusive.
You might like to look at POEM's own DSD.
The package statement should be changed to the name of your
package eg org.paneris.myproj.model.
Note that this should also be reflected in
LogicalDatabase.Properties
org.melati.LogicalDatabase.myproj.class=org.paneris.myproj.model.MyprojDatabase
It will only overwrite files with a tag at the top, and it doesn't try to overwrite stubs.
java org.melati.poem.prepro.DSD myproj.dsd
javac -d /usr/local/packages/inst/paneris `find . -path .*java`
Attributes only find their way in the first time. Incompatibilities => startup aborts. How to fix problems.
The important points in the life of this document are listed below.
The CVS log for this document is:
$Log$
Revision 1.3 2008/02/22 14:00:47 timp
Typo
Revision 1.2 2006/12/13 11:41:52 timp
New javadoc and db mount points
Revision 1.1 2005/11/21 22:01:49 timp
Moved from site/doc
Revision 1.12 2003/07/11 23:47:41 timp
remove a few broken links
Revision 1.11 2003/03/04 22:01:47 jimw
Removed some broken links and a few misleading historical details.
Revision 1.10 2000/07/04 16:13:31 timp
Add examples
Revision 1.9 2000/03/18 10:29:46 williamc
Beginnings of some text (not clear where it's going)
Revision 1.8 2000/03/06 11:51:52 williamc
Add missing files (why did it ever work?)