Generate java objects from a database

1. Ensure your database conforms to POEM's expectations
   • Every table has a unique, meaningless, unchanging key called id
   • Cross reference fields use the id field as the foreign key into referenced table
   • Your database should not include tables with the following names
     • table
     • column
     • type
     • setting
     • user
     • group
     • capability
     • membership
     • capability
     if they do consider renaming or extending the POEM tables.
   • Table and field names should ideally be lowercase to get pretty java code.
2. Set up your org.melati.LogicalDatabase.properties file.
3. Check all is well by pointing at http://127.0.0.1:8081/Admin/<yourdbname>/Main
4. Generate a Data Structure Definition (DSD) by pointing at http://127.0.0.1:8081/Admin/<yourdbname>/DSD?comments=true
5. Save resultant DSD to your model directory (eg org.yourorg.yourproject.model)
6. Edit DSD to reflect your package name (eg org.yourorg.yourproject.model) instead of org.melati.poem
7. Note that as the default database is org.melati.poem.PoemDatabase, from which all POEM databases inherit, this DSD will include the system tables
   • Table
   • Column
   • Table type
   • Setting
   and the User tables
   • User
   • Group
   • Capability
   • Group Membership
   • Group Capability
   You should delete these definitions unless you intend to extend these tables. These tables are created for all POEM databases, so they do not need to be in your DSD.
8. The generated DSD shows, commented out, the defaults and whatever default descriptions and display names that could be generated. You should try to make them more meaningful.
9. When you are happy with the DSD:

      cd <model directory>
      java -cp c:\melati\src\main;c:\melati\target\melati.jar org.melati.poem.prepro.DSD <yourproject>.dsd
      

   This will generate your java files, the getters and setters are in a subdirectory called generated, the files you should elaborate are in your model directory.
10. Compile the java files, modify your org.melati.LogicalDatabase.properties file to reflect the new class name of your database.
11. You can iterate this process, by recreating the DSD, but this time you will not need to delete the poem table definitions.
12. More details of the preprocessor can be found in the Poem Prepro User Guide.

Extend Melati's metadata

In your DSD extend the TableInfo and/or ColumnInfo tables.

For example to add a FileNumber to every table and a FieldNumber to every column:

// ===========================
// Extend Poem metadata tables
// ===========================


table TableInfo extends org.melati.poem.TableInfo 
  (displayorder = 3010)
{
    Integer fileNumber
      (displayname = "File Number")
      (description = "My File Number")
      (nullable)
      ;
}

table ColumnInfo extends org.melati.poem.ColumnInfo 
  (displayorder = 3020)
{
    Integer fieldNumber
      (displayname = "Field Number")
      (description = "My Field Number")
      (nullable)
      ;
}

Note that you need to specify the displayorder or the table will be given a sequential displayorder.

You will need to add something like the following to your generated files

TableInfo

  public TableInfo(Table table) {
    org.melati.poem.TableInfo poemTableInfo = new org.melati.poem.TableInfo(table);
    setName_unsafe(poemTableInfo.getName());
    setDisplayname_unsafe(poemTableInfo.getDisplayname());
    setDisplayorder_unsafe(poemTableInfo.getDisplayorder());
    setDescription_unsafe(poemTableInfo.getDescription());
    setCachelimit_unsafe(poemTableInfo.getCachelimit());
    setSeqcached_unsafe(poemTableInfo.getSeqcached());
    setCategory_unsafe(poemTableInfo.getCategory_unsafe());
  }

TableInfoTable

  protected org.melati.poem.TableInfo defaultTableInfoFor(Table table) {
    return new TableInfo(table);
  }

Use a different primary key name

Melati needs an Integer representation of a table's primary key.

If you have a suitable candidate but its name is not id but intkey then subclass your chosen dbms class, such as SQLServer and provide a pair of methods:

  public String melatiName(String name) {
    if (name.equalsIgnoreCase("intkey"))
      return "id";
    return super.melatiName(name);
  }


  public String unreservedName(String name) {
    if (name.equalsIgnoreCase("id"))
      return "intkey";
    return super.unreservedName(name);
  }

Use an Access database

1. Register with EasySoft
2. Download and install the JDBC-ODBC bridge software
3. If you are not using an existing Access DB then create an empty one
4. Register your DB as an ODBC Datasource with a System DSN
5. Update your org.melati.LogicalDatabase.properties file to select the MSAccess DbmsClass
6. In the build directory type

      ant go
    

7. point your browser at http://127.0.0.1:8081/Admin/contacts/Main