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} ------------