From 4b507b15b0122ac180e44b8418db8d9143ae9c3a Mon Sep 17 00:00:00 2001 From: Kai Moritz Date: Tue, 15 Jan 2013 23:09:01 +0100 Subject: [PATCH] Reworked documentation: splited and reorderd pages and menu --- src/site/apt/configuration.apt | 222 ++++++++++++++++++ src/site/apt/debugging.apt | 21 ++ src/site/apt/examples.apt | 395 --------------------------------- src/site/apt/force.apt | 31 +++ src/site/apt/index.apt | 45 ++-- src/site/apt/pitfalls.apt | 97 ++++++++ src/site/site.xml | 7 +- 7 files changed, 408 insertions(+), 410 deletions(-) create mode 100644 src/site/apt/configuration.apt create mode 100644 src/site/apt/debugging.apt delete mode 100644 src/site/apt/examples.apt create mode 100644 src/site/apt/force.apt create mode 100644 src/site/apt/pitfalls.apt diff --git a/src/site/apt/configuration.apt b/src/site/apt/configuration.apt new file mode 100644 index 00000000..ea11db0c --- /dev/null +++ b/src/site/apt/configuration.apt @@ -0,0 +1,222 @@ +Configuration Examples + +* Configuration through a hibernate.properties-File + + The most simple way to configure the plugin is, to put all the + hibernate-configuration in a <>-file on your + classpath. Put the file in the <<>>-folder. Maven will put + it in the <<>>-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 <<>>-section of your <<>>: + +--------------- + + de.juplo + hibernate4-maven-plugin + ${project.version} + + + + export + + + + +--------------- + + 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. + <<>> + + Hence, you should specify a different url for testing like in the + following snippet: + +--------------- + + de.juplo + hibernate4-maven-plugin + ${project.version} + + + + export + + + + + + + +--------------- + + Configuration properties, that are set in the <<>>-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 <<>>. + +* 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}}: + + * <<>> + + * <<>> + + * <<>> + + * <<>> + + * <<>> + + So, instead of writing the hibernate-configuration in the properties-file, + like above, you could put it in the <<>>-section of your + <<>>. + + 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): + +--------------- + + org.hsqldb.jdbcDriver + org.hibernate.dialect.HSQLDialect + + sa + + + +... + + + + ... + + + de.juplo + hibernate4-maven-plugin + ${project.version} + + + + export + + + + + + + + + +--------------- + +* Configuration through the plugin-configuration + + A third way for configuring the plugin is the plugin-configuration. + The relevant configuration-parameters are: + + * <<>> + + * <<>> + + * <<>> + + * <<>> + + * <<>> + + The equivalent of the configuration from the last section would look + like this: + +--------------- + + de.juplo + hibernate4-maven-plugin + ${project.version} + + + + export + + + + + org.hsqldb.jdbcDriver + org.hibernate.dialect.HSQLDialect + + sa + + + +--------------- + + There are some seldom used parameters, that can only be configured throug + this method: + + * <> the delimiter used in the generated sql-script + + * <> wether the generated sql-script is formatted, or not + + * <> name of the hibernate-properties-file + + * <> name of the generated sql-script + + * <> create database or generate sql-script or both + + * <> 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]] <<>> + + [[2]] maven-properties + + [[3]] plugin-configuration + + If you are in doubt about where a configuration-value comes from, run + maven with the {{{./debugging.html}debug-output}} enabled: <<>> + 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: + +---------------- + + de.juplo + hibernate4-maven-plugin + ${project.version} + + + + export + + + + + ${my-password-property} + + +---------------- diff --git a/src/site/apt/debugging.apt b/src/site/apt/debugging.apt new file mode 100644 index 00000000..5e3d5ab6 --- /dev/null +++ b/src/site/apt/debugging.apt @@ -0,0 +1,21 @@ +Enabling Debug-Output + + If you are new to <<>>, 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 <<>> might be necessary, because <<>> + has to scan the compiled classes for annotations!) + + Unlike the majority of the maven-plugins, <<>> 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! + + <> <<>> tends to be very chatty ;) diff --git a/src/site/apt/examples.apt b/src/site/apt/examples.apt deleted file mode 100644 index 360b5b5e..00000000 --- a/src/site/apt/examples.apt +++ /dev/null @@ -1,395 +0,0 @@ -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 <<>>. - - 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 <>-file on your - classpath. Put the file in the <<>>-folder. Maven will put - it in the <<>>-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 <<>>-section of your <<>>: - ---------------- - - de.juplo - hibernate4-maven-plugin - ${project.version} - - - - export - - - - ---------------- - - 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. - <<>> - - Hence, you should specify a different url for testing like in the - following snippet: - ---------------- - - de.juplo - hibernate4-maven-plugin - ${project.version} - - - - export - - - - - - - ---------------- - - Configuration properties, that are set in the <<>>-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 <<>>. - -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}}: - - * <<>> - - * <<>> - - * <<>> - - * <<>> - - * <<>> - - So, instead of writing the hibernate-configuration in the properties-file, - like above, you could put it in the <<>>-section of your - <<>>. - - 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): - ---------------- - - org.hsqldb.jdbcDriver - org.hibernate.dialect.HSQLDialect - - sa - - - -... - - - - ... - - - de.juplo - hibernate4-maven-plugin - ${project.version} - - - - export - - - - - - - - - ---------------- - -Configuration through the plugin-configuration - - A third way for configuring the plugin is the plugin-configuration. - The relevant configuration-parameters are: - - * <<>> - - * <<>> - - * <<>> - - * <<>> - - * <<>> - - The equivalent of the configuration from the last section would look - like this: - ---------------- - - de.juplo - hibernate4-maven-plugin - ${project.version} - - - - export - - - - - org.hsqldb.jdbcDriver - org.hibernate.dialect.HSQLDialect - - sa - - - ---------------- - - There are some seldom used parameters, that can only be configured throug - this method: - - * <> the delimiter used in the generated sql-script - - * <> wether the generated sql-script is formatted, or not - - * <> name of the hibernate-properties-file - - * <> name of the generated sql-script - - * <> create database or generate sql-script or both - - * <> 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]] <<>> - - [[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: <<>> - 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: - ----------------- - - de.juplo - hibernate4-maven-plugin - ${project.version} - - - - export - - - - - ${my-password-property} - - ----------------- - -Enabling {Debug-Output} - - If you are new to <<>>, 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 <<>> might be necessary, because <<>> - has to scan the compiled classes for annotations!) - - Unlike the majority of the maven-plugins, <<>> 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! - - <> <<>> 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 <<>>. - - But this will break the execution of the <<>>. - 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: - ---------------- - - de.juplo - hibernate4-maven-plugin - ${project.version} - - - - export - - - - - - org.hsqldb - hsqldb - 2.2.8 - - - ---------------- - - 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 <<>>-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/force.apt b/src/site/apt/force.apt new file mode 100644 index 00000000..26554d1a --- /dev/null +++ b/src/site/apt/force.apt @@ -0,0 +1,31 @@ +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}} + {{{./pitfalls.html#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. diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt index f33e325d..ffe27dd5 100644 --- a/src/site/apt/index.apt +++ b/src/site/apt/index.apt @@ -4,26 +4,45 @@ A simple Plugin for generating a Database-Schema from Hibernate 4 Mapping-Annota from your Hibernate-4-Mappings and create or update your database accordingly. - 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 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}}. + The plugin was designed with three main goals in mind: -Releases + * It should be easy to use. - * {{{http://juplo.de/hibernate4-maven-plugin} current version}} + * It should be maximal unlikely, to erase a producation-database by + accident. - * ${project.version} (this version) + * It should not slow down the development cycle. - * {{{http://juplo.de/hibernate4-maven-plugin-1.0} 1.0}} + 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 {{{./debugging.html} debugging output}} with the <<>>. -Documentation and Examples + 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). + + 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}}. - * See {{{./examples.html} Examples}} for Usage-Explanations and simple - examples of how to use this plugin. +* Documentation - * See {{{./plugin-info.html} Plugin Documentation}} for the full + * See {{{./configuration.html} Configuration Examples}} for Usage-Explanations + and simple examples of how to use this plugin. + + * See {{{./export-mojo.html}hibernate4:export}} and + {{{./plugin-info.html} Plugin Documentation}} for the full autogenerated documentation. These are mostly configuration-options of the Hibernate-Tools <<>> and <<>>, that do the work in the background. + +* Releases + + * {{{http://juplo.de/hibernate4-maven-plugin} current version}} + + * ${project.version} (this version) + + * {{{http://juplo.de/hibernate4-maven-plugin-1.0} 1.0}} diff --git a/src/site/apt/pitfalls.apt b/src/site/apt/pitfalls.apt new file mode 100644 index 00000000..5bbbff12 --- /dev/null +++ b/src/site/apt/pitfalls.apt @@ -0,0 +1,97 @@ +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 <<>>. + + But this will break the execution of the <<>>. + 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: + +--------------- + + de.juplo + hibernate4-maven-plugin + ${project.version} + + + + export + + + + + + org.hsqldb + hsqldb + 2.2.8 + + + +--------------- + + 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 <<>>-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.html}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/site.xml b/src/site/site.xml index a7f9e176..a8a3bef2 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -18,8 +18,11 @@ - - + + + + + -- 2.20.1