From bf5e8c39287713b9eb236ca441473f723059357a Mon Sep 17 00:00:00 2001 From: Kai Moritz Date: Tue, 18 Dec 2012 00:14:08 +0100 Subject: [PATCH] Reworked documentation: added documentation for new features etc. --- .../juplo/plugins/hibernate4/Hbm2DdlMojo.java | 26 +++++-- src/site/apt/examples.apt | 74 ++++++++++++++++++- src/site/apt/index.apt | 4 +- 3 files changed, 96 insertions(+), 8 deletions(-) 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. + *

+ * Only needed internally. * * @parameter expression="${project}" * @required @@ -91,8 +93,12 @@ public class Hbm2DdlMojo extends AbstractMojo /** * Build-directory. + *

+ * Only needed internally. * * @parameter expression="${project.build.directory}" + * @required + * @readonly */ private String buildDirectory; @@ -131,6 +137,14 @@ public class Hbm2DdlMojo extends AbstractMojo /** * Skip execution + *

+ * If set to true, the execution is skipped. + *

+ * A skipped excecution is signaled via the maven-property + * ${hibernate.export.skipped}. + *

+ * 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 *

* Force execution, even if no modified or newly added annotated classes - * where found. skip takes precedence over force. + * where found and the dialect was not changed. + *

+ * skip takes precedence over force. * * @parameter expression="${hibernate.export.force}" default-value="false" */ @@ -191,8 +207,8 @@ public class Hbm2DdlMojo extends AbstractMojo /** * Target of execution: *

@@ -201,12 +217,12 @@ public class Hbm2DdlMojo extends AbstractMojo private String target; /** - * Type of export. + * Type of execution. * * @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 <<>>. @@ -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 <> <<>> 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 <<>>. + 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 + execution, you can force it to do so, if you set the parameter <<>> to + <<>>: + +---------------- + + de.juplo + hibernate4-maven-plugin + ${project.version} + + true + + +---------------- + + 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 <<>>. @@ -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 <<>>-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 + <<>>. + 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: + +------------ + + org.codehaus.mojo + dbunit-maven-plugin + + ${hibernate.export.skipped} + + +------------ 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 -- 2.20.1