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 Configuration-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>- or
  12   a <strong>hibernate.cfg.xml</strong>-file on your classpath or in the
  13   <strong>persistence.xml</strong>-file of your JPA-configuration, just
  14   like you would do, if you are not using the
  15   <code>hibernate-maven-plugin</code>.
  16   </p>
  17   <p>
  18   Doing so, the only additionally configuration needed, to activat the plugin
  19   is the following entry in the <code>plugins</code>-section of your <code>pom.xml</code>:
  20   </p>
  21   <pre class="prettyprint linenums lang-html">
  22 &lt;plugin&gt;
  23   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
  24   &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
  25   &lt;version&gt;${project.version}&lt;/version&gt;
  26   &lt;executions&gt;
  27     &lt;execution&gt;
  28       &lt;goals&gt;
  29         &lt;goal&gt;create&lt;/goal&gt;
  30       &lt;/goals&gt;
  31     &lt;/execution&gt;
  32   &lt;/executions&gt;
  33 &lt;/plugin&gt;</pre>
  34   <p>
  35   This would create the configured database.
  36   If you want it to be droped beforehand, you have to add the goal
  37   <code>drop</code>:
  38   </p>
  39   <pre class="prettyprint linenums lang-html">
  40 &lt;plugin&gt;
  41   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
  42   &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
  43   &lt;version&gt;${project.version}&lt;/version&gt;
  44   &lt;executions&gt;
  45     &lt;execution&gt;
  46       &lt;goals&gt;
  47         &lt;goal&gt;drop&lt;/goal&gt;
  48         &lt;goal&gt;create&lt;/goal&gt;
  49       &lt;/goals&gt;
  50     &lt;/execution&gt;
  51   &lt;/executions&gt;
  52 &lt;/plugin&gt;</pre>
  53   <p>
  54   A correspondin goal for the command <code>update</code> is missing in this
  55   version, but we are planning to implement it in near feature.
  56   </p>
  57   <p>
  58   In order to let this configuration work, your configuration file must
  59   contain a complete valid configuration for the database, that you want
  60   to use.
  61   A simple example <code>hibernate.properties</code>-file may look like this:
  62   </p>
  63   <pre class="prettyprint linenums lang-properties">
  64 hibernate.dialect=org.hibernate.dialect.H2Dialect
  65 hibernate.connection.url=jdbc:h2:file:./target/db
  66 hibernate.connection.driver_class=org.h2.Driver
  67 hibernate.connection.username=sa
  68 hibernate.connection.password=</pre>
  69   <p>
  70   But be aware, that using this configuration-approach the database-url,
  71   that is build in the application is the same that is used while testing,
  72   where the database is droped and recreated by the plugin.
  73   Because of that,
  74   <strong>
  75     you should never fire up this configuration on your production
  76     system, or your database might be erased!
  77   </strong>
  78   </p>
  79   <p>
  80   A better approach is, to specify a different url for testing like in the
  81   following snippet:
  82   </p>
  83   <pre class="prettyprint linenums lang-html">
  84 &lt;plugin&gt;
  85   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
  86   &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
  87   &lt;version&gt;${project.version}&lt;/version&gt;
  88   &lt;executions&gt;
  89     &lt;execution&gt;
  90       &lt;goals&gt;
  91         &lt;goal&gt;drop&lt;/goal&gt;
  92         &lt;goal&gt;create&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>
 100   <p>
 101   Configuration properties, that are set in the <code>configuration</code>-section
 102   of the plugin-configuration cannnot be overwritten elsewere (for details
 103   see <a href="#precedence">Configuration-Method-Precedence</a>).
 104   You never can overwrite them by accident when specifying a property on
 105   the commandline or in your <code>settings.xml</code>.
 106   </p>
 107   <h2>Configuration through maven-properties</h2>
 108   <p>
 109   Alternatively, it is possible, to configure the plugin via maven-properties.
 110   Each relevant configuration-option has a corresponding maven-property
 111   (for a full list see the <a href="./create-mojo.html">Documentation of the goal create</a>).
 112   These are named after the
 113   <a href="http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-hibernatejdbc">Hibernate JDBC Properties</a>:
 114   </p>
 115   <ul>
 116     <li><code>hibernate.connection.driver_class</code></li>
 117     <li><code>hibernate.dialect</code></li>
 118     <li><code>hibernate.connection.url</code></li>
 119     <li><code>hibernate.connection.username</code></li>
 120     <li><code>hibernate.connection.password</code></li>
 121   </ul>
 122   <p>
 123   So, instead of writing the hibernate-configuration in the properties-file,
 124   like above, you could put it in the <code>properties</code>-section of your
 125   <code>pom.xml</code>.
 126   </p>
 127   <p>
 128   Thogether with the plugin-definition from above, the following would
 129   be a complete configuration (again, the database-url was overwritten in
 130   the plugin-configuration, to be sure to have a separate database for
 131   testing):
 132   </p>
 133   <pre class="prettyprint linenums lang-html">
 134 &lt;properties&gt;
 135   &lt;hibernate.connection.driver_class&gt;org.hsqldb.jdbcDriver&lt;/hibernate.connection.driver_class&gt;
 136   &lt;hibernate.dialect&gt;org.hibernate.dialect.HSQLDialect&lt;/hibernate.dialect&gt;
 137   &lt;hibernate.connection.url&gt;&lt;![CDATA[jdbc:hsqldb:res:org.my.path.production_db]]&gt;&lt;/hibernate.connection.url&gt;
 138   &lt;hibernate.connection.username&gt;sa&lt;/hibernate.connection.username&gt;
 139   &lt;hibernate.connection.password&gt;&lt;/hibernate.connection.password&gt;
 140 &lt;/properties&gt;
 141
 142 ...
 143
 144 &lt;plugins&gt;
 145
 146   ...
 147
 148   &lt;plugin&gt;
 149     &lt;groupId&gt;de.juplo&lt;/groupId&gt;
 150     &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
 151     &lt;version&gt;${project.version}&lt;/version&gt;
 152     &lt;executions&gt;
 153       &lt;execution&gt;
 154         &lt;goals&gt;
 155           &lt;goal&gt;drop&lt;/goal&gt;
 156           &lt;goal&gt;create&lt;/goal&gt;
 157         &lt;/goals&gt;
 158       &lt;/execution&gt;
 159     &lt;/executions&gt;
 160     &lt;configuration&gt;
 161       &lt;url&gt;&lt;![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]&gt;&lt;/url&gt;
 162     &lt;/configuration&gt;
 163   &lt;/plugin&gt;
 164
 165 &lt;plugins&gt;</pre>
 166   <p>
 167   This way, you can reuse the same properties to provide a
 168   default-configurationthe, that is build into your application, and
 169   overwrite the database-url, that is used during testing to prevent
 170   accidential drops of your production database.
 171   </p>
 172   <h2>Configuration through the plugin-configuration</h2>
 173   <p>
 174   A third way for configuring the plugin is the plugin-configuration.
 175   The relevant configuration-parameters are:
 176   </p>
 177   <ul>
 178     <li><code>driver</code></li>
 179     <li><code>dialect</code></li>
 180     <li><code>url</code></li>
 181     <li><code>username</code></li>
 182     <li><code>password</code></li>
 183   </ul>
 184   <p>
 185   The equivalent of the configuration from the last section would look
 186   like this:
 187   </p>
 188   <pre class="prettyprint linenums lang-html">
 189 &lt;plugin&gt;
 190   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
 191   &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
 192   &lt;version&gt;${project.version}&lt;/version&gt;
 193   &lt;executions&gt;
 194     &lt;execution&gt;
 195       &lt;goals&gt;
 196         &lt;goal&gt;drop&lt;/goal&gt;
 197         &lt;goal&gt;create&lt;/goal&gt;
 198       &lt;/goals&gt;
 199     &lt;/execution&gt;
 200   &lt;/executions&gt;
 201   &lt;configuration&gt;
 202     &lt;driver&gt;org.hsqldb.jdbcDriver&lt;/driver&gt;
 203     &lt;dialect&gt;org.hibernate.dialect.HSQLDialect&lt;/dialect&gt;
 204     &lt;url&gt;&lt;![CDATA[jdbc:hsqldb:target/db/fotos;shutdown=true]]&gt;&lt;/url&gt;
 205     &lt;username&gt;sa&lt;/username&gt;
 206     &lt;password&gt;&lt;/password&gt;
 207   &lt;/configuration&gt;
 208 &lt;/plugin&gt;</pre>
 209   <p>
 210   The parameter <strong>hibernateProperties</strong> (name of the hibernate-properties-file
 211   to use, defaults to <strong>hibernate.properties</strong>) can only be configured through
 212   this approach.
 213   </p>
 214   <p>
 215   For more explanations, see the
 216   <a href="./create-mojo.html">Documentation of the goal create</a>.
 217   </p>
 218   <h2 id="precedence">Configuration-Method-Precedence</h2>
 219   <p>
 220   The configuration is gathered in a fix order:
 221   </p>
 222   <ol>
 223     <li><code>hibernate.properties</code></li>
 224     <li><code>hibernate.cfg.xml</code></li>
 225     <li><code>persistence.xml</code></li>
 226     <li>maven-properties</li>
 227     <li>plugin-configuration</li>
 228   </ol>
 229   <p>
 230   If you are in doubt about where a configuration-value comes from, run
 231   maven with the <a href="./debugging.html">debug-output</a> enabled: <code>mvn -X hibernate:create</code>
 232   and be aware, that maven-properties can be overwitten on the command-line,
 233   in your <code>~/.m2/settings.xml</code> and in a profile.
 234   </p>
 235   <p>
 236   The plugin-configuration comes last and overwrites everything else.
 237   That way, you can be sure, that a configuration-value, that is
 238   specified in the plugin-configuration will never be overwritten by any
 239   other configuration-method.
 240   </p>
 241   <p>
 242   If you need to overwrite plugin-configuration-values with
 243   maven-properties, you can use maven-properties in the plugin-configuration:
 244   </p>
 245   <pre class="prettyprint linenums lang-html">
 246 &lt;plugin&gt;
 247   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
 248   &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
 249   &lt;version&gt;${project.version}&lt;/version&gt;
 250   &lt;executions&gt;
 251     &lt;execution&gt;
 252       &lt;goals&gt;
 253         &lt;goal&gt;drop&lt;/goal&gt;
 254         &lt;goal&gt;create&lt;/goal&gt;
 255       &lt;/goals&gt;
 256     &lt;/execution&gt;
 257   &lt;/executions&gt;
 258   &lt;configuration&gt;
 259     &lt;password&gt;${my-password-property}&lt;/password&gt;
 260   &lt;/configuration&gt;
 261 &lt;/plugin&gt;</pre>
 262  </body>
 263 </html>