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