juplo.de Git - hibernate4-maven-plugin/blob - src/site/apt/examples.apt

   1 Configuration Examples
   2
   3   The plugin was designed with two main goals in mind:
   4
   5     * It should be easy to use.
   6
   7     * It should be maximal unlikely, to erase a producation-database by
   8       accident.
   9
  10   To achieve the first goal, the convention-over-configuration paradigma
  11   was applied and the plugin was stuffed with usefull logging-messages.
  12   So, if in doubt, just turn on the {{Debug-Output}} with the <<<mvn -X ...>>>.
  13
  14   To achieve the second goal, the precedence in which the configuration
  15   locations are consulted was layouted in a way that makes it possible, to
  16   prevent overwrites of the wrong database by accident.
  17
  18 Configuration through a hibernate.properties-File
  19
  20   The most simple way to configure the plugin is, to put all the
  21   hibernate-configuration in a <<hibernate.properties>>-file on your
  22   classpath. Put the file in the <<<resources>>>-folder. Maven will put
  23   it in the <<<class>>>-folder of your webapp, where it will be picked up
  24   by this plugin as well as by Hibernate 4.
  25
  26   Doing so, the only additionally configuration needed, to activat the plugin
  27   is the following entry in the <<<plugins>>>-section of your <<<pom.xml>>>:
  28
  29 ---------------
  30 <plugin>
  31   <groupId>de.juplo</groupId>
  32   <artifactId>hibernate4-maven-plugin</artifactId>
  33   <version>1.0-SNAPSHOT</version>
  34   <executions>
  35     <execution>
  36       <goals>
  37         <goal>export</goal>
  38       </goals>
  39     </execution>
  40   </executions>
  41 </plugin>
  42 ---------------
  43
  44   But be aware, that in this case the database-url, that is
  45   build in the application is the same that is used while testing, where
  46   the database is droped and recreated by the plugin.
  47   <<<So, you should never fire up this configuration on your production
  48   system, or your database might be erased!>>>
  49
  50   Hence, you should specify a different url for testing like in the
  51   following snippet:
  52
  53 ---------------
  54 <plugin>
  55   <groupId>de.juplo</groupId>
  56   <artifactId>hibernate4-maven-plugin</artifactId>
  57   <version>1.0-SNAPSHOT</version>
  58   <executions>
  59     <execution>
  60       <goals>
  61         <goal>export</goal>
  62       </goals>
  63     </execution>
  64   </executions>
  65   <configuration>
  66     <url><![CDATA[jdbc:mysql://localhost/test-db]]></url>
  67   </configuration>
  68 </plugin>
  69 ---------------
  70
  71   Configuration properties, that are set in the <<<configuration>>>-section
  72   of the plugin-configuration cannnot be overwritten elsewere (for details
  73   see {{Configuration-Method-Precedence}}).
  74   You never can overwrite them by accident when specifying a property on
  75   the commandline or in your <<<settings.xml>>>.
  76
  77 Configuration through maven-properties
  78
  79   Alternatively, it is possible, to configure the plugin via maven-properties.
  80   Each relevant configuration-option has a corresponding maven-property
  81   (for a full list see the {{{./export-mojo.html} Documentation of the export-Mojo}}).
  82   These are named after the
  83   {{{http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-hibernatejdbc} Hibernate JDBC Properties}}:
  84
  85     * <<<hibernate.connection.driver_class>>>
  86
  87     * <<<hibernate.dialect>>>
  88
  89     * <<<hibernate.connection.url>>>
  90
  91     * <<<hibernate.connection.username>>>
  92
  93     * <<<hibernate.connection.password>>>
  94
  95   So, instead of writing the hibernate-configuration in the properties-file,
  96   like above, you could put it in the <<<properties>>>-section of your
  97   <<<pom.xml>>>.
  98
  99   Thogether with the plugin-definition from above, the following would
 100   be a complete configuration (again, the database-url was overwritten in
 101   the plugin-configuration, to be sure to have a separate database for
 102   testing):
 103
 104 ---------------
 105 <properties>
 106   <hibernate.connection.driver_class>org.hsqldb.jdbcDriver</hibernate.connection.driver_class>
 107   <hibernate.dialect>org.hibernate.dialect.HSQLDialect</hibernate.dialect>
 108   <hibernate.connection.url><![CDATA[jdbc:hsqldb:res:org.my.path.production_db]]></hibernate.connection.url>
 109   <hibernate.connection.username>sa</hibernate.connection.username>
 110   <hibernate.connection.password></hibernate.connection.password>
 111 </properties>
 112
 113 ...
 114
 115 <plugins>
 116
 117   ...
 118
 119   <plugin>
 120     <groupId>de.juplo</groupId>
 121     <artifactId>hibernate4-maven-plugin</artifactId>
 122     <version>1.0-SNAPSHOT</version>
 123     <executions>
 124       <execution>
 125         <goals>
 126           <goal>export</goal>
 127         </goals>
 128       </execution>
 129     </executions>
 130     <configuration>
 131       <url><![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]></url>
 132     </configuration>
 133   </plugin>
 134
 135 <plugins>
 136 ---------------
 137
 138 Configuration through the plugin-configuration
 139
 140   A third way for configuring the plugin is the plugin-configuration.
 141   The relevant configuration-parameters are:
 142
 143     * <<<driverClassName>>>
 144
 145     * <<<hibernateDialect>>>
 146
 147     * <<<url>>>
 148
 149     * <<<username>>>
 150
 151     * <<<password>>>
 152
 153   The equivalent of the configuration from the last section would look
 154   like this:
 155
 156 ---------------
 157 <plugin>
 158   <groupId>de.juplo</groupId>
 159   <artifactId>hibernate4-maven-plugin</artifactId>
 160   <version>1.0-SNAPSHOT</version>
 161   <executions>
 162     <execution>
 163       <goals>
 164         <goal>export</goal>
 165       </goals>
 166     </execution>
 167   </executions>
 168   <configuration>
 169     <driverClassName>org.hsqldb.jdbcDriver</driverClassName>
 170     <hibernateDialect>org.hibernate.dialect.HSQLDialect</hibernateDialect>
 171     <url><![CDATA[jdbc:hsqldb:target/db/fotos;shutdown=true]]></url>
 172     <username>sa</username>
 173     <password></password>
 174   </configuration>
 175 </plugin>
 176 ---------------
 177
 178   There are some seldom used parameters, that can only be configured throug
 179   this method:
 180
 181     * <<delimiter>> the delimiter used in the generated sql-script
 182
 183     * <<format>> wether the generated sql-script is formatted, or not
 184
 185     * <<hibernateProperties>> name of the hibernate-properties-file
 186
 187     * <<outputFile>> name of the generated sql-script
 188
 189     * <<target>> create database or generate sql-script or both
 190
 191     * <<type>> create or drop the database or do both or nothing
 192       (just validate the annotation-configuration)
 193
 194   For explanations, see the
 195   {{{./export-mojo.html} Documentation of the export-Mojo}}.
 196
 197 {Configuration-Method-Precedence}
 198
 199   The configuration is gathered in a fix order:
 200
 201     [[1]] <<<hibernate.properties>>>
 202
 203     [[2]] maven-properties
 204
 205     [[3]] plugin-configuration
 206
 207   If you are in doubt about where a configuration-value comes from, run
 208   maven with the {{Debug-Output}} enabled: <<<mvn -X hibernate4:export>>>
 209   and be aware, that maven-properties can be overwitten on the command-line,
 210   in your <<<~/.m2/settings.xml>>> and in a profile.
 211
 212   The plugin-configuration comes last and overwrites everything else.
 213   That way, you can be sure, that a configuration-value, that is
 214   specified in the plugin-configuration will never be overwritten by any
 215   other configuration-method.
 216
 217
 218   If you realy need to overwrite plugin-configuration-values with
 219   maven-properties, you can use maven-properties in the plugin-configuration:
 220
 221 ----------------
 222 <plugin>
 223   <groupId>de.juplo</groupId>
 224   <artifactId>hibernate4-maven-plugin</artifactId>
 225   <version>1.0-SNAPSHOT</version>
 226   <executions>
 227     <execution>
 228       <goals>
 229         <goal>export</goal>
 230       </goals>
 231     </execution>
 232   </executions>
 233   <configuration>
 234     <password>${my-password-property}</password>
 235   </configuration>
 236 </plugin>
 237 ----------------
 238
 239 Enabling {Debug-Output}
 240
 241   If you are new to <<<hibernate4-maven-plugin>>>, in many cases, the
 242   {Configuration-Method-Precedence} may be the source of configuration
 243   errors.
 244   To solve this problem, you should run maven with the debugging output
 245   enabled.
 246   For example, by executing:
 247
 248 -------------
 249 mvn -X compile hibernate4:export
 250 -------------
 251
 252   (The <<<compile>>> might be necessary, because <<<hibernate4-maven-plugin>>>
 253   has to scan the compiled classes for annotations!)
 254
 255   Unlike the majority of the maven-plugins, <<<hibernate4-maven-plugin>>> was
 256   designed to give a good many hints, when debugging is enabled.
 257   Because, if you do not know, what went wrong, you can't fix it!
 258
 259   <<But be warned:>> <<<hibernate4-maven-plugin>>> tends to be very chatty ;)
 260
 261 Known Pitfalls
 262
 263   One regular problem is the scope of the jdbc-driver-dependency.
 264   It is very unlikely, that this dependency is needed at compile-time.
 265   So a tidy maven-developer would usually scope it for <<<runtime>>>.
 266
 267   But this will break the execution of the <<<hibernate4-maven-plugin>>>.
 268   Since it will not be able to see the needed dependency, it will fail with
 269   an error-message like:
 270
 271 ---------------
 272 [INFO] Gathered hibernate-configuration (turn on debugging for details):
 273 [INFO]   hibernate.connection.username = sa
 274 [INFO]   hibernate.connection.password =
 275 [INFO]   hibernate.dialect = org.hibernate.dialect.HSQLDialect
 276 [INFO]   hibernate.connection.url = jdbc:hsqldb:/home/kai/mmf/target/mmf;shutdown=true
 277 [INFO]   hibernate.connection.driver_class = org.hsqldb.jdbcDriver
 278 [ERROR] Dependency for driver-class org.hsqldb.jdbcDriver is missing!
 279 [INFO] ------------------------------------------------------------------------
 280 [ERROR] BUILD ERROR
 281 [INFO] ------------------------------------------------------------------------
 282 [INFO] org.hsqldb.jdbcDriver
 283 [INFO] ------------------------------------------------------------------------
 284 [INFO] For more information, run Maven with the -e switch
 285 [INFO] ------------------------------------------------------------------------
 286 [INFO] Total time: 2 seconds
 287 [INFO] Finished at: Thu Nov 29 11:31:14 CET 2012
 288 [INFO] Final Memory: 32M/342M
 289 [INFO] ------------------------------------------------------------------------
 290 ---------------
 291
 292   A quick workaround for this error would be, to delete the runtime-constraint
 293   for the jdbc-driver-dependency.
 294
 295   A much cleaner way is, to (additionally) ad the dependency, to the
 296   plugin-definition:
 297
 298 ---------------
 299 <plugin>
 300   <groupId>de.juplo</groupId>
 301   <artifactId>hibernate4-maven-plugin</artifactId>
 302   <version>1.0-SNAPSHOT</version>
 303   <executions>
 304     <execution>
 305       <goals>
 306         <goal>export</goal>
 307       </goals>
 308     </execution>
 309   </executions>
 310   <dependencies>
 311   <dependency>
 312     <groupId>org.hsqldb</groupId>
 313     <artifactId>hsqldb</artifactId>
 314     <version>2.2.8</version>
 315   </dependency>
 316   </dependencies>
 317 </plugin>
 318 ---------------
 319
 320   This is also the best way, if you use a different jdbc-driver for
 321   testing, than in production.
 322   Because otherwise, this dependency will unnecessarily bloat the
 323   runtime-dependencies of your project.