1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
\r
2 <!-- Generated by Apache Maven Doxia at Nov 29, 2012 -->
\r
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
\r
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
\r
6 <title>Hibernate 4 Maven Plugin - </title>
\r
7 <style type="text/css" media="all">
\r
8 @import url("./css/maven-base.css");
\r
9 @import url("./css/maven-theme.css");
\r
10 @import url("./css/site.css");
\r
12 <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
\r
13 <meta name="Date-Revision-yyyymmdd" content="20121129" />
\r
14 <meta http-equiv="Content-Language" content="en" />
\r
17 <body class="composite">
\r
19 <div id="bannerLeft">
\r
20 Hibernate 4 Maven Plugin
\r
26 <div id="breadcrumbs">
\r
30 <span id="publishDate">Last Published: 2012-11-29</span>
\r
31 | <span id="projectVersion">Version: 1.0</span>
\r
33 <div class="xright">
\r
40 <div id="leftColumn">
\r
41 <div id="navcolumn">
\r
47 <a href="index.html" title="Introduction">Introduction</a>
\r
50 <strong>Examples</strong>
\r
53 <a href="plugin-info.html" title="Documentation">Documentation</a>
\r
56 <h5>Project Documentation</h5>
\r
58 <li class="collapsed">
\r
59 <a href="project-info.html" title="Project Information">Project Information</a>
\r
61 <li class="collapsed">
\r
62 <a href="project-reports.html" title="Project Reports">Project Reports</a>
\r
65 <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
\r
66 <img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
\r
72 <div id="bodyColumn">
\r
73 <div id="contentBox">
\r
74 <div class="section"><h2>Configuration Examples<a name="Configuration_Examples"></a></h2><p>The plugin was designed with two main goals in mind:</p><ul><li>It should be easy to use.</li><li>It should be maximal unlikely, to erase a producation-database by accident.</li></ul><p>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 <a href="#Debug-Output">Debug-Output</a> with the <tt>mvn -X ...</tt>. </p><p>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.</p></div><div class="section"><h2>Configuration through a hibernate.properties-File<a name="Configuration_through_a_hibernate.properties-File"></a></h2><p>The most simple way to configure the plugin is, to put all the hibernate-configuration in a <b>hibernate.properties</b>-file on your classpath. Put the file in the <tt>resources</tt>-folder. Maven will put it in the <tt>class</tt>-folder of your webapp, where it will be picked up by this plugin as well as by Hibernate 4.</p><p>Doing so, the only additionally configuration needed, to activat the plugin is the following entry in the <tt>plugins</tt>-section of your <tt>pom.xml</tt>:</p><div><pre><plugin>
75 <groupId>de.juplo</groupId>
76 <artifactId>hibernate4-maven-plugin</artifactId>
77 <version>1.0</version>
81 <goal>export</goal>
85 </plugin></pre></div><p>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. <tt>So, you should never fire up this configuration on your production system, or your database might be erased!</tt></p><p>Hence, you should specify a different url for testing like in the following snippet:</p><div><pre><plugin>
86 <groupId>de.juplo</groupId>
87 <artifactId>hibernate4-maven-plugin</artifactId>
88 <version>1.0</version>
92 <goal>export</goal>
97 <url><![CDATA[jdbc:mysql://localhost/test-db]]></url>
98 </configuration>
99 </plugin></pre></div><p>Configuration properties, that are set in the <tt>configuration</tt>-section of the plugin-configuration cannnot be overwritten elsewere (for details see <a href="#Configuration-Method-Precedence">Configuration-Method-Precedence</a>). You never can overwrite them by accident when specifying a property on the commandline or in your <tt>settings.xml</tt>.</p></div><div class="section"><h2>Configuration through maven-properties<a name="Configuration_through_maven-properties"></a></h2><p>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 <a href="./export-mojo.html"> Documentation of the export-Mojo</a>). These are named after the <a class="externalLink" href="http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-hibernatejdbc"> Hibernate JDBC Properties</a>:</p><ul><li><tt>hibernate.connection.driver_class</tt></li><li><tt>hibernate.dialect</tt></li><li><tt>hibernate.connection.url</tt></li><li><tt>hibernate.connection.username</tt></li><li><tt>hibernate.connection.password</tt></li></ul><p>So, instead of writing the hibernate-configuration in the properties-file, like above, you could put it in the <tt>properties</tt>-section of your <tt>pom.xml</tt>.</p><p>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):</p><div><pre><properties>
100 <hibernate.connection.driver_class>org.hsqldb.jdbcDriver</hibernate.connection.driver_class>
101 <hibernate.dialect>org.hibernate.dialect.HSQLDialect</hibernate.dialect>
102 <hibernate.connection.url><![CDATA[jdbc:hsqldb:res:org.my.path.production_db]]></hibernate.connection.url>
103 <hibernate.connection.username>sa</hibernate.connection.username>
104 <hibernate.connection.password></hibernate.connection.password>
114 <groupId>de.juplo</groupId>
115 <artifactId>hibernate4-maven-plugin</artifactId>
116 <version>1.0</version>
120 <goal>export</goal>
124 <configuration>
125 <url><![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]></url>
126 </configuration>
129 <plugins></pre></div></div><div class="section"><h2>Configuration through the plugin-configuration<a name="Configuration_through_the_plugin-configuration"></a></h2><p>A third way for configuring the plugin is the plugin-configuration. The relevant configuration-parameters are:</p><ul><li><tt>driverClassName</tt></li><li><tt>hibernateDialect</tt></li><li><tt>url</tt></li><li><tt>username</tt></li><li><tt>password</tt></li></ul><p>The equivalent of the configuration from the last section would look like this:</p><div><pre><plugin>
130 <groupId>de.juplo</groupId>
131 <artifactId>hibernate4-maven-plugin</artifactId>
132 <version>1.0</version>
136 <goal>export</goal>
140 <configuration>
141 <driverClassName>org.hsqldb.jdbcDriver</driverClassName>
142 <hibernateDialect>org.hibernate.dialect.HSQLDialect</hibernateDialect>
143 <url><![CDATA[jdbc:hsqldb:target/db/fotos;shutdown=true]]></url>
144 <username>sa</username>
145 <password></password>
146 </configuration>
147 </plugin></pre></div><p>There are some seldom used parameters, that can only be configured throug this method:</p><ul><li><b>delimiter</b> the delimiter used in the generated sql-script</li><li><b>format</b> wether the generated sql-script is formatted, or not</li><li><b>hibernateProperties</b> name of the hibernate-properties-file</li><li><b>outputFile</b> name of the generated sql-script</li><li><b>target</b> create database or generate sql-script or both</li><li><b>type</b> create or drop the database or do both or nothing (just validate the annotation-configuration)</li></ul><p>For explanations, see the <a href="./export-mojo.html"> Documentation of the export-Mojo</a>.</p></div><div class="section"><h2><a name="Configuration-Method-Precedence">Configuration-Method-Precedence</a><a name="Configuration-Method-Precedence"></a></h2><p>The configuration is gathered in a fix order:</p><ol style="list-style-type: decimal"><li><tt>hibernate.properties</tt></li><li>maven-properties</li><li>plugin-configuration</li></ol><p>If you are in doubt about where a configuration-value comes from, run maven with the <a href="#Debug-Output">Debug-Output</a> enabled: <tt>mvn -X hibernate4:export</tt> and be aware, that maven-properties can be overwitten on the command-line, in your <tt>~/.m2/settings.xml</tt> and in a profile.</p><p>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.</p><p>If you realy need to overwrite plugin-configuration-values with maven-properties, you can use maven-properties in the plugin-configuration:</p><div><pre><plugin>
148 <groupId>de.juplo</groupId>
149 <artifactId>hibernate4-maven-plugin</artifactId>
150 <version>1.0</version>
154 <goal>export</goal>
158 <configuration>
159 <password>${my-password-property}</password>
160 </configuration>
161 </plugin></pre></div></div><div class="section"><h2>Enabling <a name="Debug-Output">Debug-Output</a><a name="Enabling_Debug-Output"></a></h2><p>If you are new to <tt>hibernate4-maven-plugin</tt>, in many cases, the <a name="Configuration-Method-Precedence">Configuration-Method-Precedence</a> may be the source of configuration errors. To solve this problem, you should run maven with the debugging output enabled. For example, by executing:</p><div><pre>mvn -X compile hibernate4:export </pre></div><p>(The <tt>compile</tt> might be necessary, because <tt>hibernate4-maven-plugin</tt> has to scan the compiled classes for annotations!)</p><p>Unlike the majority of the maven-plugins, <tt>hibernate4-maven-plugin</tt> 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!</p><p><b>But be warned:</b> <tt>hibernate4-maven-plugin</tt> tends to be very chatty ;)</p></div><div class="section"><h2>Known Pitfalls<a name="Known_Pitfalls"></a></h2><p>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 <tt>runtime</tt>.</p><p>But this will break the execution of the <tt>hibernate4-maven-plugin</tt>. Since it will not be able to see the needed dependency, it will fail with an error-message like:</p><div><pre>[INFO] Gathered hibernate-configuration (turn on debugging for details):
162 [INFO] hibernate.connection.username = sa
163 [INFO] hibernate.connection.password =
164 [INFO] hibernate.dialect = org.hibernate.dialect.HSQLDialect
165 [INFO] hibernate.connection.url = jdbc:hsqldb:/home/kai/mmf/target/mmf;shutdown=true
166 [INFO] hibernate.connection.driver_class = org.hsqldb.jdbcDriver
167 [ERROR] Dependency for driver-class org.hsqldb.jdbcDriver is missing!
168 [INFO] ------------------------------------------------------------------------
170 [INFO] ------------------------------------------------------------------------
171 [INFO] org.hsqldb.jdbcDriver
172 [INFO] ------------------------------------------------------------------------
173 [INFO] For more information, run Maven with the -e switch
174 [INFO] ------------------------------------------------------------------------
175 [INFO] Total time: 2 seconds
176 [INFO] Finished at: Thu Nov 29 11:31:14 CET 2012
177 [INFO] Final Memory: 32M/342M
178 [INFO] ------------------------------------------------------------------------</pre></div><p>A quick workaround for this error would be, to delete the runtime-constraint for the jdbc-driver-dependency.</p><p>A much cleaner way is, to (additionally) ad the dependency, to the plugin-definition:</p><div><pre><plugin>
179 <groupId>de.juplo</groupId>
180 <artifactId>hibernate4-maven-plugin</artifactId>
181 <version>1.0</version>
185 <goal>export</goal>
191 <groupId>org.hsqldb</groupId>
192 <artifactId>hsqldb</artifactId>
193 <version>2.2.8</version>
195 </dependencies>
196 </plugin></pre></div><p>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.</p></div>
\r
199 <div class="clear">
\r
203 <div class="xright">Copyright © 2012.
\r
204 All Rights Reserved.
\r
207 <div class="clear">
\r