juplo.de Git - website/blob - dist/hibernate4-maven-plugin-1.0/examples.html

   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
   4   <head>\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
  11     </style>\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
  15         \r
  16   </head>\r
  17   <body class="composite">\r
  18     <div id="banner">\r
  19                     <div id="bannerLeft">\r
  20                 Hibernate 4 Maven Plugin\r
  21                 </div>\r
  22                     <div class="clear">\r
  23         <hr/>\r
  24       </div>\r
  25     </div>\r
  26     <div id="breadcrumbs">\r
  27             \r
  28         \r
  29                 <div class="xleft">\r
  30         <span id="publishDate">Last Published: 2012-11-29</span>\r
  31                   &nbsp;| <span id="projectVersion">Version: 1.0</span>\r
  32                       </div>\r
  33             <div class="xright">        \r
  34         \r
  35       </div>\r
  36       <div class="clear">\r
  37         <hr/>\r
  38       </div>\r
  39     </div>\r
  40     <div id="leftColumn">\r
  41       <div id="navcolumn">\r
  42              \r
  43         \r
  44                                 <h5>Overview</h5>\r
  45                   <ul>\r
  46                   <li class="none">\r
  47                           <a href="index.html" title="Introduction">Introduction</a>\r
  48             </li>\r
  49                   <li class="none">\r
  50             <strong>Examples</strong>\r
  51           </li>\r
  52                   <li class="none">\r
  53                           <a href="plugin-info.html" title="Documentation">Documentation</a>\r
  54             </li>\r
  55           </ul>\r
  56                        <h5>Project Documentation</h5>\r
  57                   <ul>\r
  58                                                                                                                                                                                                                                                         <li class="collapsed">\r
  59                           <a href="project-info.html" title="Project Information">Project Information</a>\r
  60                   </li>\r
  61                                                                                                                                             <li class="collapsed">\r
  62                           <a href="project-reports.html" title="Project Reports">Project Reports</a>\r
  63                   </li>\r
  64           </ul>\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
  67       </a>\r
  68                    \r
  69         \r
  70             </div>\r
  71     </div>\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>&lt;plugin&gt;
  75   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
  76   &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
  77   &lt;version&gt;1.0&lt;/version&gt;
  78   &lt;executions&gt;
  79     &lt;execution&gt;
  80       &lt;goals&gt;
  81         &lt;goal&gt;export&lt;/goal&gt;
  82       &lt;/goals&gt;
  83     &lt;/execution&gt;
  84   &lt;/executions&gt;
  85 &lt;/plugin&gt;</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>&lt;plugin&gt;
  86   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
  87   &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
  88   &lt;version&gt;1.0&lt;/version&gt;
  89   &lt;executions&gt;
  90     &lt;execution&gt;
  91       &lt;goals&gt;
  92         &lt;goal&gt;export&lt;/goal&gt;
  93       &lt;/goals&gt;
  94     &lt;/execution&gt;
  95   &lt;/executions&gt;
  96   &lt;configuration&gt;
  97     &lt;url&gt;&lt;![CDATA[jdbc:mysql://localhost/test-db]]&gt;&lt;/url&gt;
  98   &lt;/configuration&gt;
  99 &lt;/plugin&gt;</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>&lt;properties&gt;
 100   &lt;hibernate.connection.driver_class&gt;org.hsqldb.jdbcDriver&lt;/hibernate.connection.driver_class&gt;
 101   &lt;hibernate.dialect&gt;org.hibernate.dialect.HSQLDialect&lt;/hibernate.dialect&gt;
 102   &lt;hibernate.connection.url&gt;&lt;![CDATA[jdbc:hsqldb:res:org.my.path.production_db]]&gt;&lt;/hibernate.connection.url&gt;
 103   &lt;hibernate.connection.username&gt;sa&lt;/hibernate.connection.username&gt;
 104   &lt;hibernate.connection.password&gt;&lt;/hibernate.connection.password&gt;
 105 &lt;/properties&gt;
 106
 107 ...
 108
 109 &lt;plugins&gt;
 110
 111   ...
 112
 113   &lt;plugin&gt;
 114     &lt;groupId&gt;de.juplo&lt;/groupId&gt;
 115     &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
 116     &lt;version&gt;1.0&lt;/version&gt;
 117     &lt;executions&gt;
 118       &lt;execution&gt;
 119         &lt;goals&gt;
 120           &lt;goal&gt;export&lt;/goal&gt;
 121         &lt;/goals&gt;
 122       &lt;/execution&gt;
 123     &lt;/executions&gt;
 124     &lt;configuration&gt;
 125       &lt;url&gt;&lt;![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]&gt;&lt;/url&gt;
 126     &lt;/configuration&gt;
 127   &lt;/plugin&gt;
 128
 129 &lt;plugins&gt;</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>&lt;plugin&gt;
 130   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
 131   &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
 132   &lt;version&gt;1.0&lt;/version&gt;
 133   &lt;executions&gt;
 134     &lt;execution&gt;
 135       &lt;goals&gt;
 136         &lt;goal&gt;export&lt;/goal&gt;
 137       &lt;/goals&gt;
 138     &lt;/execution&gt;
 139   &lt;/executions&gt;
 140   &lt;configuration&gt;
 141     &lt;driverClassName&gt;org.hsqldb.jdbcDriver&lt;/driverClassName&gt;
 142     &lt;hibernateDialect&gt;org.hibernate.dialect.HSQLDialect&lt;/hibernateDialect&gt;
 143     &lt;url&gt;&lt;![CDATA[jdbc:hsqldb:target/db/fotos;shutdown=true]]&gt;&lt;/url&gt;
 144     &lt;username&gt;sa&lt;/username&gt;
 145     &lt;password&gt;&lt;/password&gt;
 146   &lt;/configuration&gt;
 147 &lt;/plugin&gt;</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>&lt;plugin&gt;
 148   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
 149   &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
 150   &lt;version&gt;1.0&lt;/version&gt;
 151   &lt;executions&gt;
 152     &lt;execution&gt;
 153       &lt;goals&gt;
 154         &lt;goal&gt;export&lt;/goal&gt;
 155       &lt;/goals&gt;
 156     &lt;/execution&gt;
 157   &lt;/executions&gt;
 158   &lt;configuration&gt;
 159     &lt;password&gt;${my-password-property}&lt;/password&gt;
 160   &lt;/configuration&gt;
 161 &lt;/plugin&gt;</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] ------------------------------------------------------------------------
 169 [ERROR] BUILD ERROR
 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>&lt;plugin&gt;
 179   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
 180   &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
 181   &lt;version&gt;1.0&lt;/version&gt;
 182   &lt;executions&gt;
 183     &lt;execution&gt;
 184       &lt;goals&gt;
 185         &lt;goal&gt;export&lt;/goal&gt;
 186       &lt;/goals&gt;
 187     &lt;/execution&gt;
 188   &lt;/executions&gt;
 189   &lt;dependencies&gt;
 190   &lt;dependency&gt;
 191     &lt;groupId&gt;org.hsqldb&lt;/groupId&gt;
 192     &lt;artifactId&gt;hsqldb&lt;/artifactId&gt;
 193     &lt;version&gt;2.2.8&lt;/version&gt;
 194   &lt;/dependency&gt;
 195   &lt;/dependencies&gt;
 196 &lt;/plugin&gt;</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
 197       </div>\r
 198     </div>\r
 199     <div class="clear">\r
 200       <hr/>\r
 201     </div>\r
 202     <div id="footer">\r
 203       <div class="xright">Copyright &#169;                   2012.\r
 204           All Rights Reserved.      \r
 205         \r
 206       </div>\r
 207       <div class="clear">\r
 208         <hr/>\r
 209       </div>\r
 210     </div>\r
 211   </body>\r
 212 </html>\r