X-Git-Url: http://juplo.de/gitweb/?p=hibernate4-maven-plugin;a=blobdiff_plain;f=src%2Fsite%2Fapt%2Fpitfalls.apt;h=355e369ecdc73040d68c921aa8deae7f51495049;hp=5bbbff126e548669147a8eea55ab7c874bacb57a;hb=bd78c276663790bf7a3f121db85a0d62c64ce38c;hpb=4b507b15b0122ac180e44b8418db8d9143ae9c3a

diff --git a/src/site/apt/pitfalls.apt b/src/site/apt/pitfalls.apt
index 5bbbff12..355e369e 100644
--- a/src/site/apt/pitfalls.apt
+++ b/src/site/apt/pitfalls.apt
@@ -1,6 +1,36 @@
-Known Pitfalls
+  ---
+  Known Pitfalls
+  ---
+  Kai Moritz
+  ---
 
-* Dependency for driver-class XYZ is missing
+Annotated classes in dependencies are not found.
+
+  hibernate4-maven-plugin by default scans dependencies in the scope
+  <code>compile</code>. You can configure it to scan dependencies in other
+  scopes as well. But it scans only direct dependencies. Transitive
+  dependencies are not scanned for annotated classes. If some of your
+  annotated classes are hidden in a transitive dependency, you can simply
+  add that dependency explicitly.
+
+hibernate4-maven-plugin always needs a database-connection
+
+  The default-configuration uses the EXPORT-target of the SchemaExport-Tool.
+  If you do not need to create a database with the evaluated schema, you can
+  use the NONE- or the SCRIPT-target.
+  This can be achieved with the command-line parameter
+  <<<-Dhibernate.export.target=SCRIPT>>> or with the following configuration:
+
+------------
+<configuration>
+  <target>SCRIPT</target>
+</configuration>
+------------
+
+  But even when no database is to be created, hibernate always needs to know
+  the dialect. Hence, the plugin will fail if this parameter is missing!
+
+Dependency for driver-class XYZ is missing
 
   One regular problem is the scope of the jdbc-driver-dependency.
   It is very unlikely, that this dependency is needed at compile-time.
@@ -64,7 +94,7 @@ Known Pitfalls
   Because otherwise, this dependency will unnecessarily bloat the
   runtime-dependencies of your project.
 
-* DBUnit {fails} after execution of hibernate4 was skipped because nothing has changed
+DBUnit {fails} after execution of hibernate4 was skipped because nothing has changed
 
   If hibernate4-maven-plugin skips its excecution, this may lead to errors in
   other plugins.
@@ -95,3 +125,45 @@ Known Pitfalls
   </configuration>
 </plugin>
 ------------
+
+The database will not be recreated after a manual drop/clean
+
+  If one manually drops the database or removes the hsqldb-files, it will not
+  be recreated by the hibernate4-maven-plugin, because it cannot detect, that
+  the database needs to be recreated.
+  This happens, because the plugin will not recreate the database if neither
+  the configuration nor the annotated classes have changed, because an
+  unnecessary drop-create-cycle might take a long time. The plugin will
+  report that like this:
+
+-------------
+[INFO] No modified annotated classes found and dialect unchanged.
+[INFO] Skipping schema generation!
+-------------
+
+  If one always uses <<<mvn clean>>> for cleanup, this will not happen.
+  Otherwise the recreation must be {{{./force.html}forced}}:
+
+-------------
+mvn hibernate4:export -Dhibernate.export.force=true
+-------------
+
+The hibernate4:export goal is not executed, when tests are skipped
+
+  The hibernate4-maven-plugin automatically skips its execution, when
+  <<<maven.test.skip>>> is set to <<<true>>>. If you need it to be always
+  executed, you can configure that explicitly like this:
+
+------------
+<plugin>
+  <groupId>de.juplo</groupId>
+  <artifactId>hibernate4-maven-plugin</artifactId>
+  ...
+  <configuration>
+    <skip>false</skip>
+  </configuration>
+</plugin>
+------------
+
+  Background-information for this design-decission can be found on the extra
+  page {{{./skip.html}To skip or not to skip: that is the question}}...