3 The plugin was designed with two main goals in mind:
5 * It should be easy to use.
7 * It should be maximal unlikely, to erase a producation-database by
10 To achieve the first goal, the convention-over-configuration paradigma
11 was applied and the plugin was stuffed with usefull logging-messages.
12 So, if in doubt, just turn on the {{Debug-Output}} with the <<<mvn -X ...>>>.
14 To achieve the second goal, the precedence in which the configuration
15 locations are consulted was layouted in a way that makes it possible, to
16 prevent overwrites of the wrong database by accident.
18 Configuration through a hibernate.properties-File
20 The most simple way to configure the plugin is, to put all the
21 hibernate-configuration in a <<hibernate.properties>>-file on your
22 classpath. Put the file in the <<<resources>>>-folder. Maven will put
23 it in the <<<class>>>-folder of your webapp, where it will be picked up
24 by this plugin as well as by Hibernate 4.
26 Doing so, the only additionally configuration needed, to activat the plugin
27 is the following entry in the <<<plugins>>>-section of your <<<pom.xml>>>:
31 <groupId>de.juplo</groupId>
32 <artifactId>hibernate4-maven-plugin</artifactId>
33 <version>${project.version}</version>
44 But be aware, that in this case the database-url, that is
45 build in the application is the same that is used while testing, where
46 the database is droped and recreated by the plugin.
47 <<<So, you should never fire up this configuration on your production
48 system, or your database might be erased!>>>
50 Hence, you should specify a different url for testing like in the
55 <groupId>de.juplo</groupId>
56 <artifactId>hibernate4-maven-plugin</artifactId>
57 <version>${project.version}</version>
66 <url><![CDATA[jdbc:mysql://localhost/test-db]]></url>
71 Configuration properties, that are set in the <<<configuration>>>-section
72 of the plugin-configuration cannnot be overwritten elsewere (for details
73 see {{Configuration-Method-Precedence}}).
74 You never can overwrite them by accident when specifying a property on
75 the commandline or in your <<<settings.xml>>>.
77 Configuration through maven-properties
79 Alternatively, it is possible, to configure the plugin via maven-properties.
80 Each relevant configuration-option has a corresponding maven-property
81 (for a full list see the {{{./export-mojo.html} Documentation of the export-Mojo}}).
82 These are named after the
83 {{{http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-hibernatejdbc} Hibernate JDBC Properties}}:
85 * <<<hibernate.connection.driver_class>>>
87 * <<<hibernate.dialect>>>
89 * <<<hibernate.connection.url>>>
91 * <<<hibernate.connection.username>>>
93 * <<<hibernate.connection.password>>>
95 So, instead of writing the hibernate-configuration in the properties-file,
96 like above, you could put it in the <<<properties>>>-section of your
99 Thogether with the plugin-definition from above, the following would
100 be a complete configuration (again, the database-url was overwritten in
101 the plugin-configuration, to be sure to have a separate database for
106 <hibernate.connection.driver_class>org.hsqldb.jdbcDriver</hibernate.connection.driver_class>
107 <hibernate.dialect>org.hibernate.dialect.HSQLDialect</hibernate.dialect>
108 <hibernate.connection.url><![CDATA[jdbc:hsqldb:res:org.my.path.production_db]]></hibernate.connection.url>
109 <hibernate.connection.username>sa</hibernate.connection.username>
110 <hibernate.connection.password></hibernate.connection.password>
120 <groupId>de.juplo</groupId>
121 <artifactId>hibernate4-maven-plugin</artifactId>
122 <version>${project.version}</version>
131 <url><![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]></url>
138 Configuration through the plugin-configuration
140 A third way for configuring the plugin is the plugin-configuration.
141 The relevant configuration-parameters are:
143 * <<<driverClassName>>>
145 * <<<hibernateDialect>>>
153 The equivalent of the configuration from the last section would look
158 <groupId>de.juplo</groupId>
159 <artifactId>hibernate4-maven-plugin</artifactId>
160 <version>${project.version}</version>
169 <driverClassName>org.hsqldb.jdbcDriver</driverClassName>
170 <hibernateDialect>org.hibernate.dialect.HSQLDialect</hibernateDialect>
171 <url><![CDATA[jdbc:hsqldb:target/db/fotos;shutdown=true]]></url>
172 <username>sa</username>
173 <password></password>
178 There are some seldom used parameters, that can only be configured throug
181 * <<delimiter>> the delimiter used in the generated sql-script
183 * <<format>> wether the generated sql-script is formatted, or not
185 * <<hibernateProperties>> name of the hibernate-properties-file
187 * <<outputFile>> name of the generated sql-script
189 * <<target>> create database or generate sql-script or both
191 * <<type>> create or drop the database or do both or nothing
192 (just validate the annotation-configuration)
194 For explanations, see the
195 {{{./export-mojo.html} Documentation of the export-Mojo}}.
197 {Configuration-Method-Precedence}
199 The configuration is gathered in a fix order:
201 [[1]] <<<hibernate.properties>>>
203 [[2]] maven-properties
205 [[3]] plugin-configuration
207 If you are in doubt about where a configuration-value comes from, run
208 maven with the {{Debug-Output}} enabled: <<<mvn -X hibernate4:export>>>
209 and be aware, that maven-properties can be overwitten on the command-line,
210 in your <<<~/.m2/settings.xml>>> and in a profile.
212 The plugin-configuration comes last and overwrites everything else.
213 That way, you can be sure, that a configuration-value, that is
214 specified in the plugin-configuration will never be overwritten by any
215 other configuration-method.
218 If you realy need to overwrite plugin-configuration-values with
219 maven-properties, you can use maven-properties in the plugin-configuration:
223 <groupId>de.juplo</groupId>
224 <artifactId>hibernate4-maven-plugin</artifactId>
225 <version>${project.version}</version>
234 <password>${my-password-property}</password>
239 Enabling {Debug-Output}
241 If you are new to <<<hibernate4-maven-plugin>>>, in many cases, the
242 {Configuration-Method-Precedence} may be the source of configuration
244 To solve this problem, you should run maven with the debugging output
246 For example, by executing:
249 mvn -X compile hibernate4:export
252 (The <<<compile>>> might be necessary, because <<<hibernate4-maven-plugin>>>
253 has to scan the compiled classes for annotations!)
255 Unlike the majority of the maven-plugins, <<<hibernate4-maven-plugin>>> was
256 designed to give a good many hints, when debugging is enabled.
257 Because, if you do not know, what went wrong, you can't fix it!
259 <<But be warned:>> <<<hibernate4-maven-plugin>>> tends to be very chatty ;)
263 One regular problem is the scope of the jdbc-driver-dependency.
264 It is very unlikely, that this dependency is needed at compile-time.
265 So a tidy maven-developer would usually scope it for <<<runtime>>>.
267 But this will break the execution of the <<<hibernate4-maven-plugin>>>.
268 Since it will not be able to see the needed dependency, it will fail with
269 an error-message like:
272 [INFO] Gathered hibernate-configuration (turn on debugging for details):
273 [INFO] hibernate.connection.username = sa
274 [INFO] hibernate.connection.password =
275 [INFO] hibernate.dialect = org.hibernate.dialect.HSQLDialect
276 [INFO] hibernate.connection.url = jdbc:hsqldb:/home/kai/mmf/target/mmf;shutdown=true
277 [INFO] hibernate.connection.driver_class = org.hsqldb.jdbcDriver
278 [ERROR] Dependency for driver-class org.hsqldb.jdbcDriver is missing!
279 [INFO] ------------------------------------------------------------------------
281 [INFO] ------------------------------------------------------------------------
282 [INFO] org.hsqldb.jdbcDriver
283 [INFO] ------------------------------------------------------------------------
284 [INFO] For more information, run Maven with the -e switch
285 [INFO] ------------------------------------------------------------------------
286 [INFO] Total time: 2 seconds
287 [INFO] Finished at: Thu Nov 29 11:31:14 CET 2012
288 [INFO] Final Memory: 32M/342M
289 [INFO] ------------------------------------------------------------------------
292 A quick workaround for this error would be, to delete the runtime-constraint
293 for the jdbc-driver-dependency.
295 A much cleaner way is, to (additionally) ad the dependency, to the
300 <groupId>de.juplo</groupId>
301 <artifactId>hibernate4-maven-plugin</artifactId>
302 <version>${project.version}</version>
312 <groupId>org.hsqldb</groupId>
313 <artifactId>hsqldb</artifactId>
314 <version>2.2.8</version>
320 This is also the best way, if you use a different jdbc-driver for
321 testing, than in production.
322 Because otherwise, this dependency will unnecessarily bloat the
323 runtime-dependencies of your project.