X-Git-Url: http://juplo.de/gitweb/?p=hibernate4-maven-plugin;a=blobdiff_plain;f=src%2Fsite%2Fapt%2Fexamples.apt;fp=src%2Fsite%2Fapt%2Fexamples.apt;h=0000000000000000000000000000000000000000;hp=360b5b5ece252304af553d9f5ea1153a81dd3a3d;hb=4b507b15b0122ac180e44b8418db8d9143ae9c3a;hpb=65bbbdbaa7df1edcc92a3869122ff06a3895fe57 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} - - -------------