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

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