3 The plugin was designed with three main goals in mind:
5 * It should be easy to use.
7 * It should be maximal unlikely, to erase a producation-database by
10 * It should not slow down the development cycle.
12 To achieve the first goal, the convention-over-configuration paradigma
13 was applied and the plugin was stuffed with usefull logging-messages.
14 So, if in doubt, just turn on the {{Debug-Output}} with the <<<mvn -X ...>>>.
16 To achieve the second goal, the precedence in which the configuration
17 locations are consulted was layouted in a way that makes it possible, to
18 prevent overwrites of the wrong database by accident.
20 Last but not least, in order to not slow down the development cycle, the
21 hibernate4-maven-plugin only executes the schema-export, if the mapping
22 or the dialect changes (or if you force it to do so).
24 Configuration through a hibernate.properties-File
26 The most simple way to configure the plugin is, to put all the
27 hibernate-configuration in a <<hibernate.properties>>-file on your
28 classpath. Put the file in the <<<resources>>>-folder. Maven will put
29 it in the <<<class>>>-folder of your webapp, where it will be picked up
30 by this plugin as well as by Hibernate 4.
32 Doing so, the only additionally configuration needed, to activat the plugin
33 is the following entry in the <<<plugins>>>-section of your <<<pom.xml>>>:
37 <groupId>de.juplo</groupId>
38 <artifactId>hibernate4-maven-plugin</artifactId>
39 <version>${project.version}</version>
50 But be aware, that in this case the database-url, that is
51 build in the application is the same that is used while testing, where
52 the database is droped and recreated by the plugin.
53 <<<So, you should never fire up this configuration on your production
54 system, or your database might be erased!>>>
56 Hence, you should specify a different url for testing like in the
61 <groupId>de.juplo</groupId>
62 <artifactId>hibernate4-maven-plugin</artifactId>
63 <version>${project.version}</version>
72 <url><![CDATA[jdbc:mysql://localhost/test-db]]></url>
77 Configuration properties, that are set in the <<<configuration>>>-section
78 of the plugin-configuration cannnot be overwritten elsewere (for details
79 see {{Configuration-Method-Precedence}}).
80 You never can overwrite them by accident when specifying a property on
81 the commandline or in your <<<settings.xml>>>.
83 Configuration through maven-properties
85 Alternatively, it is possible, to configure the plugin via maven-properties.
86 Each relevant configuration-option has a corresponding maven-property
87 (for a full list see the {{{./export-mojo.html} Documentation of the export-Mojo}}).
88 These are named after the
89 {{{http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-hibernatejdbc} Hibernate JDBC Properties}}:
91 * <<<hibernate.connection.driver_class>>>
93 * <<<hibernate.dialect>>>
95 * <<<hibernate.connection.url>>>
97 * <<<hibernate.connection.username>>>
99 * <<<hibernate.connection.password>>>
101 So, instead of writing the hibernate-configuration in the properties-file,
102 like above, you could put it in the <<<properties>>>-section of your
105 Thogether with the plugin-definition from above, the following would
106 be a complete configuration (again, the database-url was overwritten in
107 the plugin-configuration, to be sure to have a separate database for
112 <hibernate.connection.driver_class>org.hsqldb.jdbcDriver</hibernate.connection.driver_class>
113 <hibernate.dialect>org.hibernate.dialect.HSQLDialect</hibernate.dialect>
114 <hibernate.connection.url><![CDATA[jdbc:hsqldb:res:org.my.path.production_db]]></hibernate.connection.url>
115 <hibernate.connection.username>sa</hibernate.connection.username>
116 <hibernate.connection.password></hibernate.connection.password>
126 <groupId>de.juplo</groupId>
127 <artifactId>hibernate4-maven-plugin</artifactId>
128 <version>${project.version}</version>
137 <url><![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]></url>
144 Configuration through the plugin-configuration
146 A third way for configuring the plugin is the plugin-configuration.
147 The relevant configuration-parameters are:
149 * <<<driverClassName>>>
151 * <<<hibernateDialect>>>
159 The equivalent of the configuration from the last section would look
164 <groupId>de.juplo</groupId>
165 <artifactId>hibernate4-maven-plugin</artifactId>
166 <version>${project.version}</version>
175 <driverClassName>org.hsqldb.jdbcDriver</driverClassName>
176 <hibernateDialect>org.hibernate.dialect.HSQLDialect</hibernateDialect>
177 <url><![CDATA[jdbc:hsqldb:target/db/fotos;shutdown=true]]></url>
178 <username>sa</username>
179 <password></password>
184 There are some seldom used parameters, that can only be configured throug
187 * <<delimiter>> the delimiter used in the generated sql-script
189 * <<format>> wether the generated sql-script is formatted, or not
191 * <<hibernateProperties>> name of the hibernate-properties-file
193 * <<outputFile>> name of the generated sql-script
195 * <<target>> create database or generate sql-script or both
197 * <<type>> create or drop the database or do both or nothing
198 (just validate the annotation-configuration)
200 For explanations, see the
201 {{{./export-mojo.html} Documentation of the export-Mojo}}.
203 {Configuration-Method-Precedence}
205 The configuration is gathered in a fix order:
207 [[1]] <<<hibernate.properties>>>
209 [[2]] maven-properties
211 [[3]] plugin-configuration
213 If you are in doubt about where a configuration-value comes from, run
214 maven with the {{Debug-Output}} enabled: <<<mvn -X hibernate4:export>>>
215 and be aware, that maven-properties can be overwitten on the command-line,
216 in your <<<~/.m2/settings.xml>>> and in a profile.
218 The plugin-configuration comes last and overwrites everything else.
219 That way, you can be sure, that a configuration-value, that is
220 specified in the plugin-configuration will never be overwritten by any
221 other configuration-method.
224 If you realy need to overwrite plugin-configuration-values with
225 maven-properties, you can use maven-properties in the plugin-configuration:
229 <groupId>de.juplo</groupId>
230 <artifactId>hibernate4-maven-plugin</artifactId>
231 <version>${project.version}</version>
240 <password>${my-password-property}</password>
245 Enabling {Debug-Output}
247 If you are new to <<<hibernate4-maven-plugin>>>, in many cases, the
248 {Configuration-Method-Precedence} may be the source of configuration
250 To solve this problem, you should run maven with the debugging output
252 For example, by executing:
255 mvn -X compile hibernate4:export
258 (The <<<compile>>> might be necessary, because <<<hibernate4-maven-plugin>>>
259 has to scan the compiled classes for annotations!)
261 Unlike the majority of the maven-plugins, <<<hibernate4-maven-plugin>>> was
262 designed to give a good many hints, when debugging is enabled.
263 Because, if you do not know, what went wrong, you can't fix it!
265 <<But be warned:>> <<<hibernate4-maven-plugin>>> tends to be very chatty ;)
269 The hibernate4-maven-plugin computes MD5-sums for all found annotated
270 classes and stores them together with the generated schema.
271 If no classes were changed or added and the dialect wasn't changed too, it
272 automatically skips the configured schema-export, to speed up the development
275 The plugin signals, that the execution was skipped by setting the maven
276 property <<<${hibernate.export.skipped}>>> to <<<true>>>.
277 This may be helpful, because other plugins like
278 {{{http://mojo.codehaus.org/dbunit-maven-plugin/}dbunit-plugin}}
279 {{{DBUnit fails}may fail}}, when the execution is skipped.
281 If you need the hibernate4-maven-plugin to <never skip automatically>
282 execution, you can force it to do so, if you set the parameter <<<force>>> to
287 <groupId>de.juplo</groupId>
288 <artifactId>hibernate4-maven-plugin</artifactId>
289 <version>${project.version}</version>
296 Or you may specify <<<-Dhibernate.export.force=true>>> at the command line,
297 if you want to force hibernate4-maven-plugin only once.
301 * Dependency for driver-class XYZ is missing
303 One regular problem is the scope of the jdbc-driver-dependency.
304 It is very unlikely, that this dependency is needed at compile-time.
305 So a tidy maven-developer would usually scope it for <<<runtime>>>.
307 But this will break the execution of the <<<hibernate4-maven-plugin>>>.
308 Since it will not be able to see the needed dependency, it will fail with
309 an error-message like:
312 [INFO] Gathered hibernate-configuration (turn on debugging for details):
313 [INFO] hibernate.connection.username = sa
314 [INFO] hibernate.connection.password =
315 [INFO] hibernate.dialect = org.hibernate.dialect.HSQLDialect
316 [INFO] hibernate.connection.url = jdbc:hsqldb:/home/kai/mmf/target/mmf;shutdown=true
317 [INFO] hibernate.connection.driver_class = org.hsqldb.jdbcDriver
318 [ERROR] Dependency for driver-class org.hsqldb.jdbcDriver is missing!
319 [INFO] ------------------------------------------------------------------------
321 [INFO] ------------------------------------------------------------------------
322 [INFO] org.hsqldb.jdbcDriver
323 [INFO] ------------------------------------------------------------------------
324 [INFO] For more information, run Maven with the -e switch
325 [INFO] ------------------------------------------------------------------------
326 [INFO] Total time: 2 seconds
327 [INFO] Finished at: Thu Nov 29 11:31:14 CET 2012
328 [INFO] Final Memory: 32M/342M
329 [INFO] ------------------------------------------------------------------------
332 A quick workaround for this error would be, to delete the runtime-constraint
333 for the jdbc-driver-dependency.
335 A much cleaner way is, to (additionally) ad the dependency, to the
340 <groupId>de.juplo</groupId>
341 <artifactId>hibernate4-maven-plugin</artifactId>
342 <version>${project.version}</version>
352 <groupId>org.hsqldb</groupId>
353 <artifactId>hsqldb</artifactId>
354 <version>2.2.8</version>
360 This is also the best way, if you use a different jdbc-driver for
361 testing, than in production.
362 Because otherwise, this dependency will unnecessarily bloat the
363 runtime-dependencies of your project.
365 * {DBUnit fails} after execution of hibernate4 was skipped because nothing has changed
367 If hibernate4-maven-plugin skips its excecution, this may lead to errors in
369 For example, when importing sample-data in the automatically created database
370 with the help of the {{{http://mojo.codehaus.org/dbunit-maven-plugin/}dbunit-plugin}},
371 the <<<CLEAN_INSERT>>>-operation may fail because of foreign-key-constraints,
372 if the database was not recreated, because the hibernate4-maven-plugin has
373 skipped its excecution.
375 A quick fix to this problem is, to {{{Force execution}force}}
376 hibernate4-maven-plugin to export the schema every time it is running.
377 But to recreate the database on every testrun may noticeable slow down your
378 development cycle, if you have to wait for slow IO.
380 To circumvent this problem, hibernate4-maven-plugin signals a skipped
381 excecution by setting the maven property <<<${hibernate.export.skipped}>>> to
383 You can configure other plugins to react on this signal.
384 For example, the dbunit-plugin can be configured to skip its excecution, if
385 hibernate4-maven-plugin was skipped like this:
389 <groupId>org.codehaus.mojo</groupId>
390 <artifactId>dbunit-maven-plugin</artifactId>
392 <skip>${hibernate.export.skipped}</skip>