From: Kai Moritz <kai@coolibri.de>
Date: Mon, 17 Dec 2012 23:14:08 +0000 (+0100)
Subject: Reworked documentation: added documentation for new features etc.
X-Git-Tag: hibernate4-maven-plugin-1.0.1~5
X-Git-Url: http://juplo.de/gitweb/?a=commitdiff_plain;h=bf5e8c39287713b9eb236ca441473f723059357a;p=hibernate-maven-plugin
Reworked documentation: added documentation for new features etc.
---
diff --git a/src/main/java/de/juplo/plugins/hibernate4/Hbm2DdlMojo.java b/src/main/java/de/juplo/plugins/hibernate4/Hbm2DdlMojo.java
index 91b589d8..3b3a72b7 100644
--- a/src/main/java/de/juplo/plugins/hibernate4/Hbm2DdlMojo.java
+++ b/src/main/java/de/juplo/plugins/hibernate4/Hbm2DdlMojo.java
@@ -82,6 +82,8 @@ public class Hbm2DdlMojo extends AbstractMojo
/**
* The maven project.
+ * <p>
+ * Only needed internally.
*
* @parameter expression="${project}"
* @required
@@ -91,8 +93,12 @@ public class Hbm2DdlMojo extends AbstractMojo
/**
* Build-directory.
+ * <p>
+ * Only needed internally.
*
* @parameter expression="${project.build.directory}"
+ * @required
+ * @readonly
*/
private String buildDirectory;
@@ -131,6 +137,14 @@ public class Hbm2DdlMojo extends AbstractMojo
/**
* Skip execution
+ * <p>
+ * If set to <code>true</code>, the execution is skipped.
+ * <p>
+ * A skipped excecution is signaled via the maven-property
+ * <code>${hibernate.export.skipped}</code>.
+ * <p>
+ * The excecution is skipped automatically, if no modified or newly added
+ * annotated classes are found and the dialect was not changed.
*
* @parameter expression="${maven.test.skip}" default-value="false"
*/
@@ -140,7 +154,9 @@ public class Hbm2DdlMojo extends AbstractMojo
* Force execution
* <p>
* Force execution, even if no modified or newly added annotated classes
- * where found. <code>skip</code> takes precedence over <code>force</code>.
+ * where found and the dialect was not changed.
+ * <p>
+ * <code>skip</code> takes precedence over <code>force</code>.
*
* @parameter expression="${hibernate.export.force}" default-value="false"
*/
@@ -191,8 +207,8 @@ public class Hbm2DdlMojo extends AbstractMojo
/**
* Target of execution:
* <ul>
- * <li><strong>NONE</strong> do nothing - just validate the configuration</li>
- * <li><strong>EXPORT</strong> create database <strong>(DEFAULT!)</strong></li>
+ * <li><strong>NONE</strong> do nothing - just validate the configuration (forces excecution, signals skip)</li>
+ * <li><strong>EXPORT</strong> create database (<strong>DEFAULT!</strong>. forces excecution, signals skip)</li>
* <li><strong>SCRIPT</strong> export schema to SQL-script</li>
* <li><strong>BOTH</strong></li>
* </ul>
@@ -201,12 +217,12 @@ public class Hbm2DdlMojo extends AbstractMojo
private String target;
/**
- * Type of export.
+ * Type of execution.
* <ul>
* <li><strong>NONE</strong> do nothing - just validate the configuration</li>
* <li><strong>CREATE</strong> create database-schema</li>
* <li><strong>DROP</strong> drop database-schema</li>
- * <li><strong>BOTH</strong> <strong>(DEFAULT!)</strong></li>
+ * <li><strong>BOTH</strong> (<strong>DEFAULT!</strong>)</li>
* </ul>
* @parameter expression="${hibernate.export.type}" default-value="BOTH"
*/
diff --git a/src/site/apt/examples.apt b/src/site/apt/examples.apt
index 1c28320c..360b5b5e 100644
--- a/src/site/apt/examples.apt
+++ b/src/site/apt/examples.apt
@@ -1,12 +1,14 @@
Configuration Examples
- The plugin was designed with two main goals in mind:
+ 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 ...>>>.
@@ -15,6 +17,10 @@ Configuration Examples
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
@@ -258,8 +264,42 @@ mvn -X compile hibernate4:export
<<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>>>.
@@ -321,3 +361,35 @@ Known Pitfalls
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>
+------------
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
index 3698529b..f9949256 100644
--- a/src/site/apt/index.apt
+++ b/src/site/apt/index.apt
@@ -7,12 +7,12 @@ A simple Plugin for generating a Database-Schema from Hibernate 4 Mapping-Annota
The plugin was designed to be easy and safe to use, because it must not
never, never happen, that you blow away your production database when
firering a maven-build of your webapp on your production-machine!
- For more information about the insiration to write this tiny plugin,
+ For more information about the inspiration to write this tiny plugin,
{{{/hibernate4-maven-plugin-a-simple-plugin-for-generating-a-database-schema-from-hibernate-4-mapping-annotations/} read our blog-article about the hibernate4-maven-plugin}}.
Documentation and Examples
- * See {{{./examples.html} Examples}} for Usage-Eplanations and simple
+ * See {{{./examples.html} Examples}} for Usage-Explanations and simple
examples of how to use this plugin.
* See {{{./plugin-info.html} Plugin Documentation}} for the full