Fork me on GitHub

Usage

The DSD processor is used to generate java code from a Data Structure Definition file.

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

  • 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 you 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.

Notes

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 in the generated directory, once it has created a stub it will not overwrite it.

Command line

At the command line type: 

mvn org.melati:dsd-maven-plugin:0.7.9-SNAPSHOT:generate

Forcing regeneration

The plugin compares the file timestamps of the DSD and the generated database base file (generated/MyProjectDatabaseBase.java). If the generated file is younger than the DSD then the plugin does not run.

To override this behaviour, when there is a new version of the plugin for example, add the following: 

mvn -DcheckUptodate=false org.melati:maven-dsd-plugin:1.0-SNAPSHOT:generate

Shortening the Command Line

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.

To do this, you need to add the following to your \${user.home}/.m2/settings.xml file: 

<pluginGroups>
  <pluginGroup>org.melati</pluginGroup>
</pluginGroups>

At this point, you can run the plugin with: 

mvn dsd:generate

Lifecycle Configuration

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: 

   <plugins>
    <plugin>
     <groupId>org.melati</groupId>
     <artifactId>maven-dsd-plugin</artifactId>
     <executions>
       <execution>
         <phase>process-sources</phase>
         <goals>
           <goal>generate</goal>
         </goals>
       </execution>
     </executions>
     <configuration>
       <dsdPackage>your-groupId.your-artifactId.model</dsdPackage>
       <dsdFile>your-artifactId.dsd</dsdFile>
     </configuration>
    </plugin>
   </plugins>
The plugin will look for your DSD at the groupId level, a directory called model or poem under that, at the artifactId level or a directory called model or poem under that. Or, as above, you can configure it by giving the package name and/or the the file name of the DSD.

Classpath Configuration

Maven plugins run with their own classpath, defined by their own POM.

If you need to import a dsd from another project, such as MelatiBoards, 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: 


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