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

   1 Known Pitfalls
   2
   3 * hibernate4-maven-plugin always needs a database-connection
   4
   5   The default-configuration uses the EXPORT-target of the SchemaExport-Tool.
   6   If you do not need to create a database with the evaluated schema, you can
   7   use the NONE- or the SCRIPT-target.
   8   This can be achieved with the commandline-parameter
   9   <<<-Dhibernate.export.target=SCRIPT>>> or with the following configuration:
  10
  11 ------------
  12 <configuration>
  13   <target>SCRIPT</target>
  14 </configuration>
  15 ------------
  16
  17   But even when no database is to be created, hibernate always needs to know
  18   the dialect. Hence, the plugin will fail if this parameter is missing!
  19
  20 * Dependency for driver-class XYZ is missing
  21
  22   One regular problem is the scope of the jdbc-driver-dependency.
  23   It is very unlikely, that this dependency is needed at compile-time.
  24   So a tidy maven-developer would usually scope it for <<<runtime>>>.
  25
  26   But this will break the execution of the <<<hibernate4-maven-plugin>>>.
  27   Since it will not be able to see the needed dependency, it will fail with
  28   an error-message like:
  29
  30 ---------------
  31 [INFO] Gathered hibernate-configuration (turn on debugging for details):
  32 [INFO]   hibernate.connection.username = sa
  33 [INFO]   hibernate.connection.password =
  34 [INFO]   hibernate.dialect = org.hibernate.dialect.HSQLDialect
  35 [INFO]   hibernate.connection.url = jdbc:hsqldb:/home/kai/mmf/target/mmf;shutdown=true
  36 [INFO]   hibernate.connection.driver_class = org.hsqldb.jdbcDriver
  37 [ERROR] Dependency for driver-class org.hsqldb.jdbcDriver is missing!
  38 [INFO] ------------------------------------------------------------------------
  39 [ERROR] BUILD ERROR
  40 [INFO] ------------------------------------------------------------------------
  41 [INFO] org.hsqldb.jdbcDriver
  42 [INFO] ------------------------------------------------------------------------
  43 [INFO] For more information, run Maven with the -e switch
  44 [INFO] ------------------------------------------------------------------------
  45 [INFO] Total time: 2 seconds
  46 [INFO] Finished at: Thu Nov 29 11:31:14 CET 2012
  47 [INFO] Final Memory: 32M/342M
  48 [INFO] ------------------------------------------------------------------------
  49 ---------------
  50
  51   A quick workaround for this error would be, to delete the runtime-constraint
  52   for the jdbc-driver-dependency.
  53
  54   A much cleaner way is, to (additionally) ad the dependency, to the
  55   plugin-definition:
  56
  57 ---------------
  58 <plugin>
  59   <groupId>de.juplo</groupId>
  60   <artifactId>hibernate4-maven-plugin</artifactId>
  61   <version>${project.version}</version>
  62   <executions>
  63     <execution>
  64       <goals>
  65         <goal>export</goal>
  66       </goals>
  67     </execution>
  68   </executions>
  69   <dependencies>
  70   <dependency>
  71     <groupId>org.hsqldb</groupId>
  72     <artifactId>hsqldb</artifactId>
  73     <version>2.2.8</version>
  74   </dependency>
  75   </dependencies>
  76 </plugin>
  77 ---------------
  78
  79   This is also the best way, if you use a different jdbc-driver for
  80   testing, than in production.
  81   Because otherwise, this dependency will unnecessarily bloat the
  82   runtime-dependencies of your project.
  83
  84 * DBUnit {fails} after execution of hibernate4 was skipped because nothing has changed
  85
  86   If hibernate4-maven-plugin skips its excecution, this may lead to errors in
  87   other plugins.
  88   For example, when importing sample-data in the automatically created database
  89   with the help of the {{{http://mojo.codehaus.org/dbunit-maven-plugin/}dbunit-plugin}},
  90   the <<<CLEAN_INSERT>>>-operation may fail because of foreign-key-constraints,
  91   if the database was not recreated, because the hibernate4-maven-plugin has
  92   skipped its excecution.
  93
  94   A quick fix to this problem is, to {{{./force.html}force}}
  95   hibernate4-maven-plugin to export the schema every time it is running.
  96   But to recreate the database on every testrun may noticeable slow down your
  97   development cycle, if you have to wait for slow IO.
  98
  99   To circumvent this problem, hibernate4-maven-plugin signals a skipped
 100   excecution by setting the  maven property <<<${hibernate.export.skipped}>>> to
 101   <<<true>>>.
 102   You can configure other plugins to react on this signal.
 103   For example, the dbunit-plugin can be configured to skip its excecution, if
 104   hibernate4-maven-plugin was skipped like this:
 105
 106 ------------
 107 <plugin>
 108   <groupId>org.codehaus.mojo</groupId>
 109   <artifactId>dbunit-maven-plugin</artifactId>
 110   <configuration>
 111     <skip>${hibernate.export.skipped}</skip>
 112   </configuration>
 113 </plugin>
 114 ------------
 115
 116 * The database will not be recreated after a manual drop/clean
 117
 118   If one manually drops the database or removes the hsqldb-files, it will not
 119   be recreated by the hibernate4-maven-plugin, because it cannot detect, that
 120   the database needs to be recreated.
 121   This happens, because the plugin will not recreate the database if neither
 122   the configuration nor the annotated classes have changed, because an
 123   unnecessary drop-create-cycle might take a long time. The plugin will
 124   report that like this:
 125
 126 -------------
 127 [INFO] No modified annotated classes found and dialect unchanged.
 128 [INFO] Skipping schema generation!
 129 -------------
 130
 131   If one always uses <<<mvn clen>>> for cleanup, this will not happen.
 132   Otherwise the recreation must be {{{./force.html}forced}}:
 133
 134 -------------
 135 mvn hibernate4:export -Dhibernate.export.force=true
 136 -------------
 137
 138 * The hibernate4:export goal is executed, even if <<<maven.test.skip>>> is
 139   <<<true>>>
 140
 141   Up to version 1.0.2 the hibernate4-maven-plugin automatically skipped
 142   its execution, when <<<maven.test.skip>>> was set to <<<true>>>. Starting
 143   with version 1.0.3 this behaviour was changed. The plugin now only skips
 144   its execution, when explicitliy told so via the configuration-parameter
 145   <<<skip>>> or via the property <<<hibernate.export.skip>>>.
 146
 147   This change was made, because in some use-cases it is necessary, that the
 148   database-schema is always build and/or exported, even if the tests are
 149   skipped, which was not possible with the old behaviour.
 150
 151   If you need/like the old behaviour, you can turn it on in your configuration:
 152
 153 ------------
 154 <plugin>
 155   <groupId>de.juplo</groupId>
 156   <artifactId>hibernate4-maven-plugin</artifactId>
 157   ...
 158   <configuration>
 159     <skip>${maven.test.skip}</skip>
 160   </configuration>
 161 </plugin>
 162 ------------