juplo.de Git - hibernate4-maven-plugin/blob - src/site/xhtml/configuration.xhtml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   3  <head>
   4  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5  </head>
   6  <body>
   7   <header><h1>Configuration Examples</h1></header>
   8   <h2>Configuration through a hibernate.properties-File</h2>
   9   <p>
  10   The most simple way to configure the plugin is, to put all the
  11   hibernate-configuration in a <strong>hibernate.properties</strong>-file on your
  12   classpath. Put the file in the <code>resources</code>-folder. Maven will put
  13   it in the <code>class</code>-folder of your webapp, where it will be picked up
  14   by this plugin as well as by Hibernate 4.
  15   </p>
  16   <p>
  17   Doing so, the only additionally configuration needed, to activat the plugin
  18   is the following entry in the <code>plugins</code>-section of your <code>pom.xml</code>:
  19   </p>
  20   <pre class="prettyprint linenums lang-html">
  21 &lt;plugin&gt;
  22   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
  23   &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
  24   &lt;version&gt;${project.version}&lt;/version&gt;
  25   &lt;executions&gt;
  26     &lt;execution&gt;
  27       &lt;goals&gt;
  28         &lt;goal&gt;export&lt;/goal&gt;
  29       &lt;/goals&gt;
  30     &lt;/execution&gt;
  31   &lt;/executions&gt;
  32 &lt;/plugin&gt;</pre>
  33   <p>
  34   But be aware, that in this case the database-url, that is
  35   build in the application is the same that is used while testing, where
  36   the database is droped and recreated by the plugin.
  37   Because of that,
  38   <strong>
  39     you should never fire up this configuration on your production
  40     system, or your database might be erased!
  41   </strong>
  42   </p>
  43   <p>
  44   A better approach is, to specify a different url for testing like in the
  45   following snippet:
  46   </p>
  47   <pre class="prettyprint linenums lang-html">
  48 &lt;plugin&gt;
  49   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
  50   &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
  51   &lt;version&gt;${project.version}&lt;/version&gt;
  52   &lt;executions&gt;
  53     &lt;execution&gt;
  54       &lt;goals&gt;
  55         &lt;goal&gt;export&lt;/goal&gt;
  56       &lt;/goals&gt;
  57     &lt;/execution&gt;
  58   &lt;/executions&gt;
  59   &lt;configuration&gt;
  60     &lt;url&gt;&lt;![CDATA[jdbc:mysql://localhost/test-db]]&gt;&lt;/url&gt;
  61   &lt;/configuration&gt;
  62 &lt;/plugin&gt;</pre>
  63   <p>
  64   Configuration properties, that are set in the <code>configuration</code>-section
  65   of the plugin-configuration cannnot be overwritten elsewere (for details
  66   see <a href="#precedence">Configuration-Method-Precedence</a>).
  67   You never can overwrite them by accident when specifying a property on
  68   the commandline or in your <code>settings.xml</code>.
  69   </p>
  70   <h2>Configuration through maven-properties</h2>
  71   <p>
  72   Alternatively, it is possible, to configure the plugin via maven-properties.
  73   Each relevant configuration-option has a corresponding maven-property
  74   (for a full list see the <a href="./export-mojo.html">Documentation of the export-Mojo</a>).
  75   These are named after the
  76   <a href="http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-hibernatejdbc">Hibernate JDBC Properties</a>:
  77   </p>
  78   <ul>
  79     <li><code>hibernate.connection.driver_class</code></li>
  80     <li><code>hibernate.dialect</code></li>
  81     <li><code>hibernate.connection.url</code></li>
  82     <li><code>hibernate.connection.username</code></li>
  83     <li><code>hibernate.connection.password</code></li>
  84   </ul>
  85   <p>
  86   So, instead of writing the hibernate-configuration in the properties-file,
  87   like above, you could put it in the <code>properties</code>-section of your
  88   <code>pom.xml</code>.
  89   </p>
  90   <p>
  91   Thogether with the plugin-definition from above, the following would
  92   be a complete configuration (again, the database-url was overwritten in
  93   the plugin-configuration, to be sure to have a separate database for
  94   testing):
  95   </p>
  96   <pre class="prettyprint linenums lang-html">
  97 &lt;properties&gt;
  98   &lt;hibernate.connection.driver_class&gt;org.hsqldb.jdbcDriver&lt;/hibernate.connection.driver_class&gt;
  99   &lt;hibernate.dialect&gt;org.hibernate.dialect.HSQLDialect&lt;/hibernate.dialect&gt;
 100   &lt;hibernate.connection.url&gt;&lt;![CDATA[jdbc:hsqldb:res:org.my.path.production_db]]&gt;&lt;/hibernate.connection.url&gt;
 101   &lt;hibernate.connection.username&gt;sa&lt;/hibernate.connection.username&gt;
 102   &lt;hibernate.connection.password&gt;&lt;/hibernate.connection.password&gt;
 103 &lt;/properties&gt;
 104
 105 ...
 106
 107 &lt;plugins&gt;
 108
 109   ...
 110
 111   &lt;plugin&gt;
 112     &lt;groupId&gt;de.juplo&lt;/groupId&gt;
 113     &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
 114     &lt;version&gt;${project.version}&lt;/version&gt;
 115     &lt;executions&gt;
 116       &lt;execution&gt;
 117         &lt;goals&gt;
 118           &lt;goal&gt;export&lt;/goal&gt;
 119         &lt;/goals&gt;
 120       &lt;/execution&gt;
 121     &lt;/executions&gt;
 122     &lt;configuration&gt;
 123       &lt;url&gt;&lt;![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]&gt;&lt;/url&gt;
 124     &lt;/configuration&gt;
 125   &lt;/plugin&gt;
 126
 127 &lt;plugins&gt;</pre>
 128   <h2>Configuration through the plugin-configuration</h2>
 129   <p>
 130   A third way for configuring the plugin is the plugin-configuration.
 131   The relevant configuration-parameters are:
 132   </p>
 133   <ul>
 134     <li><code>driverClassName</code></li>
 135     <li><code>hibernateDialect</code></li>
 136     <li><code>url</code></li>
 137     <li><code>username</code></li>
 138     <li><code>password</code></li>
 139   </ul>
 140   <p>
 141   The equivalent of the configuration from the last section would look
 142   like this:
 143   </p>
 144   <pre class="prettyprint linenums lang-html">
 145 &lt;plugin&gt;
 146   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
 147   &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
 148   &lt;version&gt;${project.version}&lt;/version&gt;
 149   &lt;executions&gt;
 150     &lt;execution&gt;
 151       &lt;goals&gt;
 152         &lt;goal&gt;export&lt;/goal&gt;
 153       &lt;/goals&gt;
 154     &lt;/execution&gt;
 155   &lt;/executions&gt;
 156   &lt;configuration&gt;
 157     &lt;driverClassName&gt;org.hsqldb.jdbcDriver&lt;/driverClassName&gt;
 158     &lt;hibernateDialect&gt;org.hibernate.dialect.HSQLDialect&lt;/hibernateDialect&gt;
 159     &lt;url&gt;&lt;![CDATA[jdbc:hsqldb:target/db/fotos;shutdown=true]]&gt;&lt;/url&gt;
 160     &lt;username&gt;sa&lt;/username&gt;
 161     &lt;password&gt;&lt;/password&gt;
 162   &lt;/configuration&gt;
 163 &lt;/plugin&gt;</pre>
 164   <p>
 165   The parameter <strong>hibernateProperties</strong> (name of the hibernate-properties-file
 166   to use, defaults to <strong>hibernate.properties</strong>) can only be configured through
 167   this approach.
 168   </p>
 169   <p>
 170   For more explanations, see the
 171   <a href="./export-mojo.html">Documentation of the export-Mojo</a>.
 172   </p>
 173   <h2 id="precedence">Configuration-Method-Precedence</h2>
 174   <p>
 175   The configuration is gathered in a fix order:
 176   </p>
 177   <ol>
 178     <li><code>hibernate.properties</code></li>
 179     <li>maven-properties</li>
 180     <li>plugin-configuration</li>
 181   </ol>
 182   <p>
 183   If you are in doubt about where a configuration-value comes from, run
 184   maven with the <a href="./debugging.html">debug-output</a> enabled: <code>mvn -X hibernate4:export</code>
 185   and be aware, that maven-properties can be overwitten on the command-line,
 186   in your <code>~/.m2/settings.xml</code> and in a profile.
 187   </p>
 188   <p>
 189   The plugin-configuration comes last and overwrites everything else.
 190   That way, you can be sure, that a configuration-value, that is
 191   specified in the plugin-configuration will never be overwritten by any
 192   other configuration-method.
 193   </p>
 194   <p>
 195   If you need to overwrite plugin-configuration-values with
 196   maven-properties, you can use maven-properties in the plugin-configuration:
 197   </p>
 198   <pre class="prettyprint linenums lang-html">
 199 &lt;plugin&gt;
 200   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
 201   &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
 202   &lt;version&gt;${project.version}&lt;/version&gt;
 203   &lt;executions&gt;
 204     &lt;execution&gt;
 205       &lt;goals&gt;
 206         &lt;goal&gt;export&lt;/goal&gt;
 207       &lt;/goals&gt;
 208     &lt;/execution&gt;
 209   &lt;/executions&gt;
 210   &lt;configuration&gt;
 211     &lt;password&gt;${my-password-property}&lt;/password&gt;
 212   &lt;/configuration&gt;
 213 &lt;/plugin&gt;</pre>
 214  </body>
 215 </html>