juplo.de Git - hibernate4-maven-plugin/blob - src/site/xhtml/pitfalls.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>Known Pitfalls (FAQ)</h1></header>
   8   <h2>Annotated classes in dependencies are not found.</h2>
   9   <p>
  10   hibernate-maven-plugin by default scans dependencies in the scope
  11   <code>compile</code>. You can configure it to scan dependencies in other
  12   scopes as well. But it scans only direct dependencies. Transitive
  13   dependencies are not scanned for annotated classes. If some of your
  14   annotated classes are hidden in a transitive dependency, you can simply
  15   add that dependency explicitly.
  16   </p>
  17   <h2>hibernate-maven-plugin always needs a database-connection</h2>
  18   <p>
  19   The default-configuration executes the created SQL.
  20   Therefore, it needs a valid database-connection and fails, if none is
  21   available.
  22   If you do not need the generated SQL to be executed automatically,
  23   you can set the property <code>hibernate.schema.execute</code> to
  24   <code>false</code>.
  25   This can be achieved with the command-line parameter
  26   <code>-Dhibernate.schema.execute=false</code> or with the following
  27   configuration:
  28   </p>
  29   <pre class="prettyprint linenums lang-html">
  30 &lt;configuration&gt;
  31   &lt;execute&gt;false&lt;/execute&gt;
  32 &lt;/configuration&gt;</pre>
  33   <p>
  34   But even when no database is to be created, hibernate always needs to know
  35   the dialect. Hence, the plugin will still fail, if this parameter is also
  36   missing!
  37   </p>
  38   <h2>Dependency for driver-class XYZ is missing</h2>
  39   <p>
  40   One regular problem is the scope of the jdbc-driver-dependency.
  41   It is very unlikely, that this dependency is needed at compile-time.
  42   So a tidy maven-developer would usually scope it for <code>runtime</code>.
  43   </p>
  44   <p>
  45   But this will break the execution of the <code>hibernate-maven-plugin</code>.
  46   Since it will not be able to see the needed dependency, it will fail with
  47   an error-message like:
  48   </p>
  49   <pre class="prettyprint">
  50 [INFO] Gathered hibernate-configuration (turn on debugging for details):
  51 [INFO]   hibernate.connection.username = sa
  52 [INFO]   hibernate.connection.password =
  53 [INFO]   hibernate.dialect = org.hibernate.dialect.H2Dialect
  54 [INFO]   hibernate.connection.url = jdbc:h2:file:./db
  55 [INFO]   hibernate.hbm2dll.create_namespaces = false
  56 [INFO]   hibernate.connection.driver_class = org.h2.Driver
  57 [INFO]   hibernate.format_sql = true
  58 [INFO] HHH000412: Hibernate Core {5.0.2.Final}
  59 [INFO] HHH000206: hibernate.properties not found
  60 [INFO] HHH000021: Bytecode provider name : javassist
  61 [INFO] Adding /home/kai/project/target/classes to the list of roots to scan...
  62 [INFO] Adding dependencies from scope compile to the list of roots to scan
  63 [INFO] Adding dependencies from scope org.hibernate:hibernate-core:jar:4.3.0.Final to the list of roots to scan
  64 [INFO] Adding annotated resource: de.juplo.tests.SimplestMavenHib4Test
  65 [INFO] ------------------------------------------------------------------------
  66 [INFO] BUILD FAILURE
  67 [INFO] ------------------------------------------------------------------------
  68 [INFO] Total time: 1.760s
  69 [INFO] Finished at: Mon Mar 07 19:06:54 CET 2016
  70 [INFO] Final Memory: 11M/215M
  71 [INFO] ------------------------------------------------------------------------
  72 [ERROR] Failed to execute goal de.juplo:hibernate-maven-plugin:${project.version}:drop (default) on project hibernate4-properties-test: Could not open the JDBC-connection: Unable to load class [org.h2.Driver]: Could not load requested class : org.h2.Driver -&gt; [Help 1]
  73 [ERROR]
  74 [ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
  75 [ERROR] Re-run Maven using the -X switch to enable full debug logging.
  76 [ERROR]
  77 [ERROR] For more information about the errors and possible solutions, please read the following articles:
  78 [ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoFailureException</pre>
  79   <p>
  80   A quick workaround for this error would be, to delete the runtime-constraint
  81   for the jdbc-driver-dependency.
  82   </p>
  83   <p>
  84   A much cleaner way is, to (additionally) ad the dependency, to the
  85   plugin-definition:
  86   </p>
  87   <pre class="prettyprint linenums lang-html">
  88 &lt;plugin&gt;
  89   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
  90   &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
  91   &lt;version&gt;${project.version}&lt;/version&gt;
  92   &lt;executions&gt;
  93     &lt;execution&gt;
  94       &lt;goals&gt;
  95         &lt;goal&gt;drop&lt;/goal&gt;
  96         &lt;goal&gt;create&lt;/goal&gt;
  97       &lt;/goals&gt;
  98     &lt;/execution&gt;
  99   &lt;/executions&gt;
 100   &lt;dependencies&gt;
 101   &lt;dependency&gt;
 102     &lt;groupId&gt;org.hsqldb&lt;/groupId&gt;
 103     &lt;artifactId&gt;hsqldb&lt;/artifactId&gt;
 104     &lt;version&gt;2.2.8&lt;/version&gt;
 105   &lt;/dependency&gt;
 106   &lt;/dependencies&gt;
 107 &lt;/plugin&gt;</pre>
 108   <p>
 109   This is also the best way, if you use a different jdbc-driver for
 110   testing, than in production.
 111   Because otherwise, this dependency will unnecessarily bloat the
 112   runtime-dependencies of your project.
 113   </p>
 114   <h2 id="fails">DBUnit fails after execution of hibernate was skipped because nothing has changed</h2>
 115   <p>
 116   If hibernate-maven-plugin skips its excecution, this may lead to errors in
 117   other plugins.
 118   For example, when importing sample-data in the automatically created database
 119   with the help of the <a href="http://mojo.codehaus.org/dbunit-maven-plugin/">dbunit-plugin</a>,
 120   the <code>CLEAN_INSERT</code>-operation may fail because of foreign-key-constraints,
 121   if the database was not recreated, because the hibernate-maven-plugin has
 122   skipped its excecution.
 123   </p>
 124   <p>
 125   A quick fix to this problem is, to <a href="./force.html">force</a>
 126   hibernate-maven-plugin to generate and execute the SQL every time it is running.
 127   But to recreate the database on every testrun may noticeable slow down your
 128   development cycle, if you have to wait for slow IO.
 129   </p>
 130   <p>
 131   To circumvent this problem, hibernate-maven-plugin signals a skipped
 132   excecution by setting the  maven property <code>${hibernate.schema.skipped}</code> to
 133   <code>true</code>.
 134   You can configure other plugins to react on this signal.
 135   For example, the dbunit-plugin can be configured to skip its excecution, if
 136   hibernate-maven-plugin was skipped like this:
 137   </p>
 138   <pre class="prettyprint linenums lang-html">
 139 &lt;plugin&gt;
 140   &lt;groupId&gt;org.codehaus.mojo&lt;/groupId&gt;
 141   &lt;artifactId&gt;dbunit-maven-plugin&lt;/artifactId&gt;
 142   &lt;configuration&gt;
 143     &lt;skip&gt;${hibernate.schema.skipped}&lt;/skip&gt;
 144   &lt;/configuration&gt;
 145 &lt;/plugin&gt;</pre>
 146   <h2>The database will not be recreated after a manual drop/clean</h2>
 147   <p>
 148   If one manually drops the database or removes the hsqldb-files, it will not
 149   be recreated by the hibernate-maven-plugin, because it cannot detect, that
 150   the database needs to be recreated.
 151   This happens, because the plugin will not recreate the database if neither
 152   the configuration nor the annotated classes have changed, because an
 153   unnecessary drop-create-cycle might take a long time. The plugin will
 154   report that like this:
 155   </p>
 156   <pre class="prettyprint">
 157 [INFO] No modified annotated classes found and dialect unchanged.
 158 [INFO] Skipping schema generation!</pre>
 159   <p>
 160   If one always uses <code>mvn clean</code> for cleanup, this will not happen.
 161   Otherwise the recreation must be <a href="./force.html">forced</a>:
 162   </p>
 163   <pre class="prettyprint">
 164 mvn hibernate:create -Dhibernate.schema.force=true</pre>
 165   <h2>The hibernate:create goal is not executed, when tests are skipped</h2>
 166   <p>
 167   The hibernate-maven-plugin automatically skips its execution, when
 168   <code>maven.test.skip</code> is set to <code>true</code>. If you need it to be always
 169   executed, you can configure that explicitly like this:
 170   </p>
 171   <pre class="prettyprint linenums lang-html">
 172 &lt;plugin&gt;
 173   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
 174   &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
 175   ...
 176   &lt;configuration&gt;
 177     &lt;skip&gt;false&lt;/skip&gt;
 178   &lt;/configuration&gt;
 179 &lt;/plugin&gt;</pre>
 180   <p>
 181   Background-information for this design-decission can be found on the extra
 182   page <a href="./skip.html">To skip or not to skip: that is the question</a>...
 183   </p>
 184   <h2>I do not want my dependencies to be scanned for hibernate annotations</h2>
 185   <p>
 186     If you do not want your dependencies to be scanned for hibernate annotations,
 187     you can pass <code>-Dhibernate.schema.scan.dependencies=none</code> to maven
 188     or set <code>scanDependencies</code> to <code>none</code> in the configuration
 189     of the plugin like this:
 190   </p>
 191   <pre class="prettyprint linenums lang-html">
 192 &lt;plugin&gt;
 193   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
 194   &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
 195   ...
 196   &lt;configuration&gt;
 197     &lt;scanDependencies&gt;none&lt;/scanDependencies&gt;
 198   &lt;/configuration&gt;
 199 &lt;/plugin&gt;</pre>
 200   <h2>No annotated classes found</h2>
 201   <p>
 202     If you are working under Windows and get the error-message
 203     <code>No annotated classes found in directory C:\projects\X Y Z\path-to-project\target\classes</code>,
 204     but you are really sure, that there are annotated classes in that
 205     directory, you are expiriencing a bug, in the scannotation-library, that
 206     was closed in version 1.1.0 of the hibernate-maven-plugin.
 207   </p>
 208   <p>
 209     <strong>
 210       You should consider to upgrade to the latest version of the plugin.
 211     </strong>
 212   </p>
 213   <h2>If two goals are specified, the second one is always skipped</h2>
 214   <p>
 215     If you specify two goals, for example <code>drop</code> and
 216     <code>create</code>, each goal has to be specified in its own
 217     <code>execution</code>, so that you can specify two different
 218     output-files for the two goals.
 219     Otherwise, both goals will use the same output-file and the goal, that
 220     is run second, will always skip, becaus it will find, that the output
 221     file already exists and conclude, that its work was already done in a
 222     prior run.
 223   </p>
 224   <p>
 225     Example configuration for two goals:
 226   </p>
 227   <pre class="prettyprint linenums lang-html">
 228 &lt;executions&gt;
 229   &lt;execution&gt;
 230     &lt;id&gt;Create Drop-Schema&lt;/id&gt;
 231     &lt;phase&gt;test-compile&lt;/phase&gt;
 232     &lt;goals&gt;
 233       &lt;goal&gt;drop&lt;/goal&gt;
 234     &lt;/goals&gt;
 235     &lt;configuration&gt;
 236       &lt;outputFile&gt;db-schema/drop-schema.ddl&lt;/outputFile&gt;
 237     &lt;/configuration&gt;
 238   &lt;/execution&gt;
 239   &lt;execution&gt;
 240     &lt;id&gt;Create Create-Schema&lt;/id&gt;
 241     &lt;phase&gt;test-compile&lt;/phase&gt;
 242     &lt;goals&gt;
 243       &lt;goal&gt;create&lt;/goal&gt;
 244     &lt;/goals&gt;
 245     &lt;configuration&gt;
 246       &lt;outputFile&gt;db-schema/create-schema.ddl&lt;/outputFile&gt;
 247     &lt;/configuration&gt;
 248   &lt;/execution&gt;
 249 &lt;/executions&gt;</pre>
 250  </body>
 251 </html>