Added breadcrumb to site

[hibernate4-maven-plugin] / src / site / apt / examples.apt

Configuration Examples

  The plugin was designed with three main goals in mind:

    * It should be easy to use.

    * It should be maximal unlikely, to erase a producation-database by
      accident.

    * It should not slow down the development cycle.

  To achieve the first goal, the convention-over-configuration paradigma
  was applied and the plugin was stuffed with usefull logging-messages.
  So, if in doubt, just turn on the {{Debug-Output}} with the <<<mvn -X ...>>>. 

  To achieve the second goal, the precedence in which the configuration
  locations are consulted was layouted in a way that makes it possible, to
  prevent overwrites of the wrong database by accident.

  Last but not least, in order to not slow down the development cycle, the
  hibernate4-maven-plugin only executes the schema-export, if the mapping
  or the dialect changes (or if you force it to do so).

Configuration through a hibernate.properties-File

  The most simple way to configure the plugin is, to put all the
  hibernate-configuration in a <<hibernate.properties>>-file on your
  classpath. Put the file in the <<<resources>>>-folder. Maven will put
  it in the <<<class>>>-folder of your webapp, where it will be picked up
  by this plugin as well as by Hibernate 4.

  Doing so, the only additionally configuration needed, to activat the plugin
  is the following entry in the <<<plugins>>>-section of your <<<pom.xml>>>:

---------------
<plugin>
  <groupId>de.juplo</groupId>
  <artifactId>hibernate4-maven-plugin</artifactId>
  <version>${project.version}</version>
  <executions>
    <execution>
      <goals>
        <goal>export</goal>
      </goals>
    </execution>
  </executions>
</plugin>
---------------

  But be aware, that in this case the database-url, that is
  build in the application is the same that is used while testing, where
  the database is droped and recreated by the plugin.
  <<<So, you should never fire up this configuration on your production
  system, or your database might be erased!>>>

  Hence, you should specify a different url for testing like in the
  following snippet:

---------------
<plugin>
  <groupId>de.juplo</groupId>
  <artifactId>hibernate4-maven-plugin</artifactId>
  <version>${project.version}</version>
  <executions>
    <execution>
      <goals>
        <goal>export</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <url><![CDATA[jdbc:mysql://localhost/test-db]]></url>
  </configuration>
</plugin>
---------------

  Configuration properties, that are set in the <<<configuration>>>-section
  of the plugin-configuration cannnot be overwritten elsewere (for details
  see {{Configuration-Method-Precedence}}).
  You never can overwrite them by accident when specifying a property on
  the commandline or in your <<<settings.xml>>>.

Configuration through maven-properties

  Alternatively, it is possible, to configure the plugin via maven-properties.
  Each relevant configuration-option has a corresponding maven-property
  (for a full list see the {{{./export-mojo.html} Documentation of the export-Mojo}}).
  These are named after the
  {{{http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-hibernatejdbc} Hibernate JDBC Properties}}:

    * <<<hibernate.connection.driver_class>>>

    * <<<hibernate.dialect>>>

    * <<<hibernate.connection.url>>>

    * <<<hibernate.connection.username>>>

    * <<<hibernate.connection.password>>>

  So, instead of writing the hibernate-configuration in the properties-file,
  like above, you could put it in the <<<properties>>>-section of your
  <<<pom.xml>>>.

  Thogether with the plugin-definition from above, the following would
  be a complete configuration (again, the database-url was overwritten in
  the plugin-configuration, to be sure to have a separate database for
  testing):

---------------
<properties>
  <hibernate.connection.driver_class>org.hsqldb.jdbcDriver</hibernate.connection.driver_class>
  <hibernate.dialect>org.hibernate.dialect.HSQLDialect</hibernate.dialect>
  <hibernate.connection.url><![CDATA[jdbc:hsqldb:res:org.my.path.production_db]]></hibernate.connection.url>
  <hibernate.connection.username>sa</hibernate.connection.username>
  <hibernate.connection.password></hibernate.connection.password>
</properties>

...

<plugins>

  ...

  <plugin>
    <groupId>de.juplo</groupId>
    <artifactId>hibernate4-maven-plugin</artifactId>
    <version>${project.version}</version>
    <executions>
      <execution>
        <goals>
          <goal>export</goal>
        </goals>
      </execution>
    </executions>
    <configuration>
      <url><![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]></url>
    </configuration>
  </plugin>

<plugins>
---------------

Configuration through the plugin-configuration

  A third way for configuring the plugin is the plugin-configuration.
  The relevant configuration-parameters are:

    * <<<driverClassName>>>

    * <<<hibernateDialect>>>

    * <<<url>>>

    * <<<username>>>

    * <<<password>>>

  The equivalent of the configuration from the last section would look
  like this:

---------------
<plugin>
  <groupId>de.juplo</groupId>
  <artifactId>hibernate4-maven-plugin</artifactId>
  <version>${project.version}</version>
  <executions>
    <execution>
      <goals>
        <goal>export</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <driverClassName>org.hsqldb.jdbcDriver</driverClassName>
    <hibernateDialect>org.hibernate.dialect.HSQLDialect</hibernateDialect>
    <url><![CDATA[jdbc:hsqldb:target/db/fotos;shutdown=true]]></url>
    <username>sa</username>
    <password></password>
  </configuration>
</plugin>
---------------

  There are some seldom used parameters, that can only be configured throug
  this method:

    * <<delimiter>> the delimiter used in the generated sql-script

    * <<format>> wether the generated sql-script is formatted, or not

    * <<hibernateProperties>> name of the hibernate-properties-file

    * <<outputFile>> name of the generated sql-script

    * <<target>> create database or generate sql-script or both

    * <<type>> create or drop the database or do both or nothing
      (just validate the annotation-configuration)

  For explanations, see the
  {{{./export-mojo.html} Documentation of the export-Mojo}}.

{Configuration-Method-Precedence}

  The configuration is gathered in a fix order:

    [[1]] <<<hibernate.properties>>>

    [[2]] maven-properties

    [[3]] plugin-configuration

  If you are in doubt about where a configuration-value comes from, run
  maven with the {{Debug-Output}} enabled: <<<mvn -X hibernate4:export>>>
  and be aware, that maven-properties can be overwitten on the command-line,
  in your <<<~/.m2/settings.xml>>> and in a profile.

  The plugin-configuration comes last and overwrites everything else.
  That way, you can be sure, that a configuration-value, that is
  specified in the plugin-configuration will never be overwritten by any
  other configuration-method.


  If you realy need to overwrite plugin-configuration-values with
  maven-properties, you can use maven-properties in the plugin-configuration:

----------------
<plugin>
  <groupId>de.juplo</groupId>
  <artifactId>hibernate4-maven-plugin</artifactId>
  <version>${project.version}</version>
  <executions>
    <execution>
      <goals>
        <goal>export</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <password>${my-password-property}</password>
  </configuration>
</plugin>
----------------

Enabling {Debug-Output}

  If you are new to <<<hibernate4-maven-plugin>>>, in many cases, the
  {Configuration-Method-Precedence} may be the source of configuration
  errors.
  To solve this problem, you should run maven with the debugging output
  enabled.
  For example, by executing:

-------------
mvn -X compile hibernate4:export 
-------------

  (The <<<compile>>> might be necessary, because <<<hibernate4-maven-plugin>>>
  has to scan the compiled classes for annotations!)

  Unlike the majority of the maven-plugins, <<<hibernate4-maven-plugin>>> was
  designed to give a good many hints, when debugging is enabled.
  Because, if you do not know, what went wrong, you can't fix it!

  <<But be warned:>> <<<hibernate4-maven-plugin>>> tends to be very chatty ;)

{Force execution}

  The hibernate4-maven-plugin computes MD5-sums for all found annotated
  classes and stores them together with the generated schema.
  If no classes were changed or added and the dialect wasn't changed too, it
  automatically skips the configured schema-export, to speed up the development
  cycle.

  The plugin signals, that the execution was skipped by setting the maven
  property <<<${hibernate.export.skipped}>>> to <<<true>>>.
  This may be helpful, because other plugins like
  {{{http://mojo.codehaus.org/dbunit-maven-plugin/}dbunit-plugin}}
  {{{DBUnit fails}may fail}}, when the execution is skipped.

  If you need the hibernate4-maven-plugin to <never skip automatically>
  execution, you can force it to do so, if you set the parameter <<<force>>> to
  <<<true>>>:

----------------
<plugin>
  <groupId>de.juplo</groupId>
  <artifactId>hibernate4-maven-plugin</artifactId>
  <version>${project.version}</version>
  <configuration>
    <force>true</force>
  </configuration>
</plugin>
----------------

  Or you may specify <<<-Dhibernate.export.force=true>>> at the command line,
  if you want to force hibernate4-maven-plugin only once.

Known Pitfalls

* Dependency for driver-class XYZ is missing

  One regular problem is the scope of the jdbc-driver-dependency.
  It is very unlikely, that this dependency is needed at compile-time.
  So a tidy maven-developer would usually scope it for <<<runtime>>>.

  But this will break the execution of the <<<hibernate4-maven-plugin>>>.
  Since it will not be able to see the needed dependency, it will fail with
  an error-message like:

---------------
[INFO] Gathered hibernate-configuration (turn on debugging for details):
[INFO]   hibernate.connection.username = sa
[INFO]   hibernate.connection.password = 
[INFO]   hibernate.dialect = org.hibernate.dialect.HSQLDialect
[INFO]   hibernate.connection.url = jdbc:hsqldb:/home/kai/mmf/target/mmf;shutdown=true
[INFO]   hibernate.connection.driver_class = org.hsqldb.jdbcDriver
[ERROR] Dependency for driver-class org.hsqldb.jdbcDriver is missing!
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] org.hsqldb.jdbcDriver
[INFO] ------------------------------------------------------------------------
[INFO] For more information, run Maven with the -e switch
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 seconds
[INFO] Finished at: Thu Nov 29 11:31:14 CET 2012
[INFO] Final Memory: 32M/342M
[INFO] ------------------------------------------------------------------------
---------------

  A quick workaround for this error would be, to delete the runtime-constraint
  for the jdbc-driver-dependency.

  A much cleaner way is, to (additionally) ad the dependency, to the
  plugin-definition:

---------------
<plugin>
  <groupId>de.juplo</groupId>
  <artifactId>hibernate4-maven-plugin</artifactId>
  <version>${project.version}</version>
  <executions>
    <execution>
      <goals>
        <goal>export</goal>
      </goals>
    </execution>
  </executions>
  <dependencies>
  <dependency>
    <groupId>org.hsqldb</groupId>
    <artifactId>hsqldb</artifactId>
    <version>2.2.8</version>
  </dependency>
  </dependencies>
</plugin>
---------------

  This is also the best way, if you use a different jdbc-driver for
  testing, than in production.
  Because otherwise, this dependency will unnecessarily bloat the
  runtime-dependencies of your project.

* {DBUnit fails} after execution of hibernate4 was skipped because nothing has changed

  If hibernate4-maven-plugin skips its excecution, this may lead to errors in
  other plugins.
  For example, when importing sample-data in the automatically created database
  with the help of the {{{http://mojo.codehaus.org/dbunit-maven-plugin/}dbunit-plugin}},
  the <<<CLEAN_INSERT>>>-operation may fail because of foreign-key-constraints,
  if the database was not recreated, because the hibernate4-maven-plugin has
  skipped its excecution.

  A quick fix to this problem is, to {{{Force execution}force}}
  hibernate4-maven-plugin to export the schema every time it is running.
  But to recreate the database on every testrun may noticeable slow down your
  development cycle, if you have to wait for slow IO.

  To circumvent this problem, hibernate4-maven-plugin signals a skipped
  excecution by setting the  maven property <<<${hibernate.export.skipped}>>> to
  <<<true>>>.
  You can configure other plugins to react on this signal.
  For example, the dbunit-plugin can be configured to skip its excecution, if
  hibernate4-maven-plugin was skipped like this:

------------
<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>dbunit-maven-plugin</artifactId>
  <configuration>
    <skip>${hibernate.export.skipped}</skip>
  </configuration>
</plugin>
------------