Fixed bug in site-configuration

[hibernate4-maven-plugin] / src / site / apt / pitfalls.apt

diff --git a/src/site/apt/pitfalls.apt b/src/site/apt/pitfalls.apt
index 0640e7f..355e369 100644 (file)
--- a/src/site/apt/pitfalls.apt
+++ b/src/site/apt/pitfalls.apt
@@ -1,11 +1,24 @@
-Known Pitfalls
+  ---
+  Known Pitfalls
+  ---
+  Kai Moritz
+  ---

 
 

-* hibernate4-maven-plugin always needs a database-connection
+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.
 
   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 commandline-parameter
+  This can be achieved with the command-line parameter

   <<<-Dhibernate.export.target=SCRIPT>>> or with the following configuration:
 
 ------------
   <<<-Dhibernate.export.target=SCRIPT>>> or with the following configuration:
 
 ------------


@@ -17,7 +30,7 @@ Known Pitfalls
   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!
 
   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
+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.
 
   One regular problem is the scope of the jdbc-driver-dependency.
   It is very unlikely, that this dependency is needed at compile-time.


@@ -81,7 +94,7 @@ Known Pitfalls
   Because otherwise, this dependency will unnecessarily bloat the
   runtime-dependencies of your project.
 
   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.
 
   If hibernate4-maven-plugin skips its excecution, this may lead to errors in
   other plugins.


@@ -113,7 +126,7 @@ Known Pitfalls
 </plugin>
 ------------
 
 </plugin>
 ------------
 

-* The database will not be recreated after a manual drop/clean
+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
 
   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


@@ -128,27 +141,18 @@ Known Pitfalls
 [INFO] Skipping schema generation!
 -------------
 
 [INFO] Skipping schema generation!
 -------------
 

-  If one always uses <<<mvn clen>>> for cleanup, this will not happen.
+  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
 -------------
 
   Otherwise the recreation must be {{{./force.html}forced}}:
 
 -------------
 mvn hibernate4:export -Dhibernate.export.force=true
 -------------
 

-* The hibernate4:export goal is executed, even if <<<maven.test.skip>>> is
-  <<<true>>>
-
-  Up to version 1.0.2 the hibernate4-maven-plugin automatically skipped
-  its execution, when <<<maven.test.skip>>> was set to <<<true>>>. Starting
-  with version 1.0.3 this behaviour was changed. The plugin now only skips
-  its execution, when explicitliy told so via the configuration-parameter
-  <<<skip>>> or via the property <<<hibernate.export.skip>>>.
+The hibernate4:export goal is not executed, when tests are skipped

 
 

-  This change was made, because in some use-cases it is necessary, that the
-  database-schema is always build and/or exported, even if the tests are
-  skipped, which was not possible with the old behaviour.
-
-  If you need/like the old behaviour, you can turn it on in your configuration:
+  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>
 
 ------------
 <plugin>


@@ -156,7 +160,10 @@ mvn hibernate4:export -Dhibernate.export.force=true
   <artifactId>hibernate4-maven-plugin</artifactId>
   ...
   <configuration>
   <artifactId>hibernate4-maven-plugin</artifactId>
   ...
   <configuration>

-    <skip>${maven.test.skip}</skip>
+    <skip>false</skip>

   </configuration>
 </plugin>
 ------------
   </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}}...