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