# org.melati.poem.prepro User Guide

## Introduction

### Melati and the POEM preprocessor

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.

### Outline

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.

- Think about your schema.

  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.

- Write your data structure definition.

  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.

- Run the DSD preprocessor.

  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.

- Compile and inspect your schema.

  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.

- Add Java methods.

  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)

- Review your DSD by exporting it

  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.

## The data structure definition file

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

## Invoking the preprocessor

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

## Compiling your application

    javac -d /usr/local/packages/inst/paneris `find . -path .*java`

## Running your application

Attributes only find their way in the first time. Incompatibilities => startup aborts. How to fix problems.

## About this document

### Readership and purpose

- Users using Melati should understand how to use the system and how it fits in to its broader contex.

This document is also intended to give the wider open source community an insight into Melati's preprocessor, so that they can give us feedback pre-release and understand the finished product.

### History

The important points in the life of this document are listed below.

The CVS log for this document is:
$Log: PoemPreproUserGuide.html,v $
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?)