User Guide

This section provides a quick usage guide to the Maven ORM Generator Plugin.

At the present time, the plugin uses Hibernate to map the database to ORM. Hibernate is in itself an abstraction layer that provides connection to a great number of database back ends.

A Simple usage to generate ORM files

Basic Requirements

There are some requirements that should be met before plugin usage.

First of all we need to have the following three files in "src/main/config" folder:

  • hibernate.cfg.xml: This file defines the connection to the database and some hibernate configurations. This file is documented in this section of the Hibernate documentation.
  • hibernate.reveng.xml This file specifies the reverse engineering rules. This file is documented in this section of the Hibernate documentation.
  • orm.generation.xml This file specifies the rules of service generation. This file is documented here.

Having these files well configured will provide a successful code generation.

IMPORTANT: The name of the hibernate.cfg.xml file must use the datasource name instead of hibernate. By convention hibernate is used only if no dataSourceName parameter value is specified.

Maven dependencies

ORM Generator is a Maven plugin. As such, it has its own dependencies that must be present to ensure proper plugin functioning.

Here's the list:

  • hibernate - the ORM engine.
  • database JDBC - The driver JDBC for the database that was specified in the hibernate.cfg.xml file.
  • ioc-utils - ORM Generator creates a set of services that are IoC contributions.

Note: See more on IoC on the support IoC Utils project

Sample Maven pom.xml dependencies:

    <dependencies>
        <dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate</artifactId>
            <version>3.2.0.cr4</version>
        </dependency>
        <dependency>
            <groupId>postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <version>8.2-504.jdbc3</version>
        </dependency>
        <dependency>
            <groupId>pt.digitalis</groupId>
            <artifactId>ioc-utils</artifactId>
            <version>1.0.1</version>
        </dependency>
    </dependencies>

Plugin invocation

The ORM layer code generation will be attached to the Maven generate-sources phase. This means that we need to provide our Maven project pom.xml with the plugin declaration and phase/goal attachment.

See the example bellow. Ignore the configuration for the time being:

    <build>
        <plugins>
            <plugin>
                <groupId>pt.digitalis</groupId>
                <artifactId>maven-orm-generator-plugin</artifactId>
                <configuration>
                    <dataSourceName>dif</dataSourceName>
                    <packageName>pt.digitalis.dif.model</packageName>
                </configuration>
                <executions>
                    <execution>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>run</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
Configuration

The plugin configuration uses the following parameters:

  • dataSourceName: The name of this dataSource. This is important to bind the datasource configurations to a given name and to name the factory to be created.
  • packageName: The base package name for the generated ORM files.
  • splitSchemas: Indicates if the generated classes should be schema separated in packages.
  • multiInstance: Indicates if the generated classes should implement access to multiple instances of the same database model.
  • hibernateConfig: The path for the Hibernate config file (Optional, defaults to "/src/main/config/hibernate.cfg.xml")
  • hibernateReveng: The path for the Hibernate reveng file (Optional, defaults to "/src/main/config/hibernate.reveng.xml")
  • ormGenerationConfig: The path for the generation process configuration file (Optional, defaults to "/src/main/config/orm.generation.xml")

Note that the first two parameters are mandatory. All other parameters have default values and the configuration files revert to the "src/main/config" folder for every file.

In the example above all the files will be saved at the package "pt.digitalis.dif.model". The folder structure will be generated automatically too. As explained before, these configuration files must be placed in the "src/main/config" folder.

Folder/Package Structure of the generated DAOs

This is the folder structure for the DAOs created created bellow.

<packageName>
       |
       |- impl
       |
       |- data
       |
       \- dao
            |
            |- impl
            |
            \- auto
                  |
                  \-impl
  • packageName - the base package name where the Services interfaces, the Module specification and the Factory files will be placed.
    • impl - This will be the package where all the services interfaces implementations are stored.
    • data - This package is where all the data information, the POJOs (src/main/java) and the hbm.xml (src/main/resources) will be created.
    • dao - This package is where the DAO interfaces will be placed. These interfaces extend the interfaces in the package packageName.dao.auto. These files can be customized by the programmer. As such, they are only created if they don't already exist.
      • impl - This package is where all the DAO implementations will be inserted. These classes will extend the files in the package packageName.dao.auto.impl and implements the interface packageName.dao. As the interfaces this implementations can be costumized and so they are only generated if they don't exist.
      • auto - The automatically generated DAO interface files. These interfaces will have all the basic methods to fetch the data from the DB.
        • impl - This package is where all the automatic DAO implementations will be placed. These classes implements the interfaces in package packageName.dao.auto.

    Note that if schemaSeparated is activated in each of the previous folders a new package with each schema name will be created for it's classes.

    This structure can be customized. To do so, you must define the desired structure in orm.generation.xml. Read the details in this dedicated section.

ORM Generator in action

To run the ORM Generator open a shell, browse to the project folder and type:

mvn generate-sources

The plugin will read all configuration files and place them in the specified package.

This phase runs before the compilation phase, so if you call the compile or package goal the output will include the updated generated code from the ORM Generator.

A sample model structure generated by the ORM Generator

A simple use case, with a couple of tables: Answers and Options.

The Answers table
                     Table "public.answers"
          Column           |          Type          | Modifiers
---------------------------+------------------------+-----------
 id                        | integer                | not null
 presentation_knowledge    | integer                | not null
 presentation_demo         | integer                | not null
 dif_opinion               | integer                | not null
 presentation_content      | integer                | not null
 presentation_presentation | integer                | not null
 presentation_interest     | integer                | not null
 presentation_clarity      | integer                | not null
 dif_technology            | integer                | not null
 name                      | character varying(100) |
 recomend_presentation     | boolean                | not null
 recomend_dif              | boolean                | not null
 will_use_dif              | boolean                | not null
Indexes:
    "answers_pkey" PRIMARY KEY, btree (id)
Foreign-key constraints:
    "fkcd7db8751c5d2797" FOREIGN KEY (presentation_interest) REFERENCES options(id)
    "fkcd7db8754213ba81" FOREIGN KEY (presentation_knowledge) REFERENCES options(id)
    "fkcd7db87549e7cd7" FOREIGN KEY (presentation_clarity) REFERENCES options(id)
    "fkcd7db87580d1c72" FOREIGN KEY (dif_technology) REFERENCES options(id)
    "fkcd7db8759e6308d0" FOREIGN KEY (presentation_demo) REFERENCES options(id)
    "fkcd7db875a75113c" FOREIGN KEY (presentation_content) REFERENCES options(id)
    "fkcd7db875bb5b3507" FOREIGN KEY (presentation_presentation) REFERENCES options(id)
    "fkcd7db875bc55beac" FOREIGN KEY (dif_opinion) REFERENCES options(id)
The Options table
demos-# \d options;
              Table "public.options"
   Column    |          Type          | Modifiers
-------------+------------------------+-----------
 id          | integer                | not null
 keyword     | character varying(10)  |
 description | character varying(200) |
Indexes:
    "options_pkey" PRIMARY KEY, btree (id)
The generated sources structure
src
`-- main
    |-- config
    |   |-- demo.cfg.xml
    |   |-- hibernate.reveng.xml
    |   `-- orm.generation.xml
    |-- java
    |   `-- pt
    |       `-- digitalis
    |           `-- difsurvey
    |               `-- model
    |                   |-- DIFModelModule.java
    |                   |-- IDemoService.java
    |                   |-- dao
    |                   |   |-- IAnswersDAO.java
    |                   |   |-- IOptionsDAO.java
    |                   |   |-- auto
    |                   |   |   |-- IAutoAnswersDAO.java
    |                   |   |   |-- IAutoOptionsDAO.java
    |                   |   |   `-- impl
    |                   |   |       |-- AutoAnswersDAOImpl.java
    |                   |   |       `-- AutoOptionsDAOImpl.java
    |                   |   `-- impl
    |                   |       |-- AnswersDAOImpl.java
    |                   |       `-- OptionsDAOImpl.java
    |                   |-- data
    |                   |   |-- Answers.java
    |                   |   `-- Options.java
    |                   |-- demoFactory.java
    |                   |-- hibernateFactory.java
    |                   `-- impl
    |                       `-- DemoServiceImpl.java
    `-- resources
        |-- demo.cfg.xml
        |-- modules.properties
        `-- pt
            `-- digitalis
                `-- difsurvey
                    `-- model
                        `-- data
                            |-- Answers.hbm.xml
                            `-- Options.hbm.xml

How to retain custom code in our DOAs

A very common need is to implement new code in the DAOs that the ORM Generator creates. Often, these modifications should persist between model generations. To avoid having the ORM Generator overwriting your custom code please proceed as is described below.

Use the "impl" folder to place your DAOs. The "auto" package will contain all generated code. The "impl" package is intended to receive your custom code in the form of classes that extend the auto-generated ones.

The ORM Generator will pick this up on generation time and link the IoC service to the right extended class on a new generation, thus you will receive through inheritance all new generated code while maintaining your custom code in place.