+++ /dev/null
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\r
-<!-- Generated by Apache Maven Doxia at Nov 29, 2012 -->\r
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">\r
- <head>\r
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />\r
- <title>Hibernate 4 Maven Plugin - </title>\r
- <style type="text/css" media="all">\r
- @import url("./css/maven-base.css");\r
- @import url("./css/maven-theme.css");\r
- @import url("./css/site.css");\r
- </style>\r
- <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />\r
- <meta name="Date-Revision-yyyymmdd" content="20121129" />\r
- <meta http-equiv="Content-Language" content="en" />\r
- \r
- </head>\r
- <body class="composite">\r
- <div id="banner">\r
- <div id="bannerLeft">\r
- Hibernate 4 Maven Plugin\r
- </div>\r
- <div class="clear">\r
- <hr/>\r
- </div>\r
- </div>\r
- <div id="breadcrumbs">\r
- \r
- \r
- <div class="xleft">\r
- <span id="publishDate">Last Published: 2012-11-29</span>\r
- | <span id="projectVersion">Version: 1.0</span>\r
- </div>\r
- <div class="xright"> \r
- \r
- </div>\r
- <div class="clear">\r
- <hr/>\r
- </div>\r
- </div>\r
- <div id="leftColumn">\r
- <div id="navcolumn">\r
- \r
- \r
- <h5>Overview</h5>\r
- <ul>\r
- <li class="none">\r
- <a href="index.html" title="Introduction">Introduction</a>\r
- </li>\r
- <li class="none">\r
- <strong>Examples</strong>\r
- </li>\r
- <li class="none">\r
- <a href="plugin-info.html" title="Documentation">Documentation</a>\r
- </li>\r
- </ul>\r
- <h5>Project Documentation</h5>\r
- <ul>\r
- <li class="collapsed">\r
- <a href="project-info.html" title="Project Information">Project Information</a>\r
- </li>\r
- <li class="collapsed">\r
- <a href="project-reports.html" title="Project Reports">Project Reports</a>\r
- </li>\r
- </ul>\r
- <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">\r
- <img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />\r
- </a>\r
- \r
- \r
- </div>\r
- </div>\r
- <div id="bodyColumn">\r
- <div id="contentBox">\r
- <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>
- <groupId>de.juplo</groupId>
- <artifactId>hibernate4-maven-plugin</artifactId>
- <version>1.0</version>
- <executions>
- <execution>
- <goals>
- <goal>export</goal>
- </goals>
- </execution>
- </executions>
-</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>
- <groupId>de.juplo</groupId>
- <artifactId>hibernate4-maven-plugin</artifactId>
- <version>1.0</version>
- <executions>
- <execution>
- <goals>
- <goal>export</goal>
- </goals>
- </execution>
- </executions>
- <configuration>
- <url><![CDATA[jdbc:mysql://localhost/test-db]]></url>
- </configuration>
-</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>
- <hibernate.connection.driver_class>org.hsqldb.jdbcDriver</hibernate.connection.driver_class>
- <hibernate.dialect>org.hibernate.dialect.HSQLDialect</hibernate.dialect>
- <hibernate.connection.url><![CDATA[jdbc:hsqldb:res:org.my.path.production_db]]></hibernate.connection.url>
- <hibernate.connection.username>sa</hibernate.connection.username>
- <hibernate.connection.password></hibernate.connection.password>
-</properties>
-
-...
-
-<plugins>
-
- ...
-
- <plugin>
- <groupId>de.juplo</groupId>
- <artifactId>hibernate4-maven-plugin</artifactId>
- <version>1.0</version>
- <executions>
- <execution>
- <goals>
- <goal>export</goal>
- </goals>
- </execution>
- </executions>
- <configuration>
- <url><![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]></url>
- </configuration>
- </plugin>
-
-<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>
- <groupId>de.juplo</groupId>
- <artifactId>hibernate4-maven-plugin</artifactId>
- <version>1.0</version>
- <executions>
- <execution>
- <goals>
- <goal>export</goal>
- </goals>
- </execution>
- </executions>
- <configuration>
- <driverClassName>org.hsqldb.jdbcDriver</driverClassName>
- <hibernateDialect>org.hibernate.dialect.HSQLDialect</hibernateDialect>
- <url><![CDATA[jdbc:hsqldb:target/db/fotos;shutdown=true]]></url>
- <username>sa</username>
- <password></password>
- </configuration>
-</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>
- <groupId>de.juplo</groupId>
- <artifactId>hibernate4-maven-plugin</artifactId>
- <version>1.0</version>
- <executions>
- <execution>
- <goals>
- <goal>export</goal>
- </goals>
- </execution>
- </executions>
- <configuration>
- <password>${my-password-property}</password>
- </configuration>
-</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):
-[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] ------------------------------------------------------------------------</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>
- <groupId>de.juplo</groupId>
- <artifactId>hibernate4-maven-plugin</artifactId>
- <version>1.0</version>
- <executions>
- <execution>
- <goals>
- <goal>export</goal>
- </goals>
- </execution>
- </executions>
- <dependencies>
- <dependency>
- <groupId>org.hsqldb</groupId>
- <artifactId>hsqldb</artifactId>
- <version>2.2.8</version>
- </dependency>
- </dependencies>
-</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
- </div>\r
- </div>\r
- <div class="clear">\r
- <hr/>\r
- </div>\r
- <div id="footer">\r
- <div class="xright">Copyright © 2012.\r
- All Rights Reserved. \r
- \r
- </div>\r
- <div class="clear">\r
- <hr/>\r
- </div>\r
- </div>\r
- </body>\r
-</html>\r
projects / website / blobdiff