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