<?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,
      Objects, Object Oriented, J2EE replacement
    </keywords>
  </properties>

  <body>


<!--
<p align="center">
 <font size="-1"><i>
This page last updated: $Date: 2008/06/03 12:24:35 $ $Author: timp $
 </i></font>
</p>
-->
  
<section name=" Usage ">
<p>
The DSD processor is used to generate java code from a Data Structure Definition file. 
</p>
<p>
  The preprocessor's task is to map a
  succinct Java-style &quot;Data Structure Definition&quot; 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.
</p>
<subsection name=" Outline ">

<UL>
  <LI> <B>Think about your schema.</B>
       <P>
         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.
       </P>
       <P>
          If you database SQL definition contains repetition,
          say every table contains the fields <tt>changetime</tt> and
          <tt>changedbyuser</tt> these fields can be separated out into a
          an abstract table which all your other tables extend.
       </P>
  </LI>
  <LI> <B>Write your data structure definition.</B>
       <P>
          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.
       </P>
  </LI>
  <LI> <B>Run the DSD preprocessor.</B>
       <P>
         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.
       </P>
  </LI>
  <LI> <B>Compile and inspect your schema.</B>
       <P>
         Before going any further you can look at your schema using the
         Melati Admin system.
       </P>
       <P>
         Use the Admin system to fill in data in your schema.
       </P>
  </LI>
  <LI> <B>Add Java methods.</B>
       <P>
         The DSD also outputs stub classes to which you can add any special
         Java methods you wish to attach to your row-objects.
       </P>
       <P>
         It is a good idea to use <tt>ensure</tt> methods to prepopulate
         code tables with values which are essential to the working of the
         system;
         see for example <a href="/melati/apidocs/org/melati/poem/CapabilityTable.html#ensure(java.lang.String)">CapabilityTable.ensure(java.lang.String)</a>
       </P>
  </LI>
  <LI> <B>Review you DSD by exporting it</B>
       <P>
         You may wish to use the DSD export function to review your DSD,
         <A href="/db/org.melati.admin.Admin/melatitest/DSD?comments">
         http://www.melati.org/db/org.melati.admin.Admin/melatitest/DSD?comments</A>
         though be aware that this function does not preserve abstract tables
         and enforces the <b>only first letter capitalised</b> rule for table
         names.
       </P>
  </LI>
</UL>

</subsection>
<subsection name=" Notes ">
<P>
  You might like to look at <a href="/melati-static/poem/Poem.dsd">POEM's own DSD</a>.
</P>
<P>
  The <tt>package</tt> statement should be changed to the name of your
  package eg <tt>org.paneris.myproj.model</tt>.
  <br/>
  <strong>Note</strong> that this should also be reflected in
  <tt>LogicalDatabase.Properties</tt>
<pre>
<tt>
org.melati.LogicalDatabase.myproj.class=org.paneris.myproj.model.MyprojDatabase
</tt>
</pre>

</P>

<P>
  It will only overwrite files in the generated directory, once it has created a stub 
  it will not overwrite it.
</P>

</subsection>
<subsection name=" Command line ">
<p>
At the command line type:
<pre>
mvn org.melati:maven-dsd-plugin:1.0-SNAPSHOT:generate
</pre>
</p>
</subsection>
<subsection name=" Forcing regeneration ">
<p>
The plugin compares the file timestamps of the DSD and the generated database base file 
(<tt>generated/MyProjectDatabaseBase.java</tt>). If the generated file is younger than the 
DSD then the plugin does not run.
</p>
<p>
To override this behaviour, when there is a new version of the plugin for example, 
add the following:
</p>
<pre>
mvn -DcheckUptodate=false org.melati:maven-dsd-plugin:1.0-SNAPSHOT:generate
</pre>

</subsection>
<subsection name=" Shortening the Command Line ">
<p>
In order to shorten the amount of typing needed on the command line, 
you need to add the plugin's group ID to the list of group IDs 
searched by default. 
</p>
<p>
To do this, you need to add the following to your 
<tt>\${user.home}/.m2/settings.xml</tt> file:
<pre>
&lt;pluginGroups&gt;
  &lt;pluginGroup>org.melati&lt;/pluginGroup&gt;
&lt;/pluginGroups&gt;
</pre>
</p>
<p>
At this point, you can run the plugin with:
<pre>
mvn dsd:generate
</pre>
</p>
</subsection>
<subsection name=" Lifecycle Configuration ">
<p>
If you use the Melati archetype or wish to retrofit the 
plugin then you need to add  it to the build section of your POM:
<pre>
   &lt;plugins&gt;
    &lt;plugin&gt;
     &lt;groupId&gt;org.melati&lt;/groupId&gt;
     &lt;artifactId&gt;maven-dsd-plugin&lt;/artifactId&gt;
     &lt;executions&gt;
       &lt;execution&gt;
         &lt;phase&gt;process-sources&lt;/phase&gt;
         &lt;goals&gt;
           &lt;goal&gt;generate&lt;/goal&gt;
         &lt;/goals&gt;
       &lt;/execution&gt;
     &lt;/executions&gt;
     &lt;configuration&gt;
       &lt;dsdPackage&gt;your-groupId.your-artifactId.model&lt;/dsdPackage&gt;
       &lt;dsdFile&gt;your-artifactId.dsd&lt;/dsdFile&gt;
     &lt;/configuration&gt;
    &lt;/plugin&gt;
   &lt;/plugins&gt;
</pre>
</p>
The plugin will look for your DSD at the <tt>groupId</tt> level, 
a directory called <tt>model</tt> or <tt>poem</tt> under that, at the <tt>artifactId</tt> 
level or a directory called <tt>model</tt> or <tt>poem</tt> under that.
Or, as above, you can configure it by giving the package name and/or the the file name of the 
DSD.

</subsection>

<subsection name=" Classpath Configuration ">
<p>
Maven plugins run with their own classpath, defined by their own POM. 
</p>
<p>
If you need to import a dsd from another project, such as <a href="http:boards.paneris.net">MelatiBoards</a>, 
it is not sufficient to add MelatiBoards as a dependency in your main POM, you also have to add it to 
the plugin invocation section:
<pre>

   &lt;plugins&gt;
    &lt;plugin&gt;
     &lt;groupId&gt;org.melati&lt;/groupId&gt;
     &lt;artifactId&gt;maven-dsd-plugin&lt;/artifactId&gt;
     &lt;executions&gt;
       &lt;execution&gt;
         &lt;phase&gt;generate-sources&lt;/phase&gt;
         &lt;goals&gt;
           &lt;goal&gt;generate&lt;/goal&gt;
         &lt;/goals&gt;
       &lt;/execution&gt;
     &lt;/executions&gt;
     &lt;configuration&gt;
       &lt;dsdPackage&gt;org.paneris.rimauresq.model&lt;/dsdPackage&gt;
       &lt;dsdFile&gt;rimauresq.dsd&lt;/dsdFile&gt;
       &lt;classpath refid="maven.compile.classpath"/&gt;
     &lt;/configuration&gt;
     &lt;dependencies&gt;
      &lt;dependency&gt;
       &lt;groupId&gt;org.melati&lt;/groupId&gt;
       &lt;artifactId>MelatiSite&lt;/artifactId&gt;
       &lt;version&gt;0.1&lt;/version&gt;
       &lt;scope&gt;runtime&lt;/scope&gt;
      &lt;/dependency&gt;
     &lt;/dependencies&gt;
    &lt;/plugin&gt;
   &lt;/plugins&gt;

</pre>
</p>
</subsection>
</section>
</body>
</document>












