From 1ba817af3ae5ab23232fca001061f8050cecd6a7 Mon Sep 17 00:00:00 2001
From: Kai Moritz <kai@juplo.de>
Date: Thu, 1 Aug 2013 01:45:22 +0200
Subject: [PATCH] Improved documentaion (new FAQ-entries)

---
 .../juplo/plugins/hibernate4/Hbm2DdlMojo.java | 12 ++++--
 src/site/apt/pitfalls.apt                     | 38 +++++++++++++++++++
 src/site/site.xml                             |  2 +-
 3 files changed, 48 insertions(+), 4 deletions(-)

diff --git a/src/main/java/de/juplo/plugins/hibernate4/Hbm2DdlMojo.java b/src/main/java/de/juplo/plugins/hibernate4/Hbm2DdlMojo.java
index 044e3307..e67a0787 100644
--- a/src/main/java/de/juplo/plugins/hibernate4/Hbm2DdlMojo.java
+++ b/src/main/java/de/juplo/plugins/hibernate4/Hbm2DdlMojo.java
@@ -226,12 +226,15 @@ public class Hbm2DdlMojo extends AbstractMojo
   /**
    * Target of execution:
    * <ul>
-   *   <li><strong>NONE</strong> do nothing - just validate the configuration (forces excecution, signals skip)</li>
-   *   <li><strong>EXPORT</strong> create database (<strong>DEFAULT!</strong>. forces excecution, signals skip)</li>
-   *   <li><strong>SCRIPT</strong> export schema to SQL-script</li>
+   *   <li><strong>NONE</strong> only export schema to SQL-script (forces excecution, signals skip)</li>
+   *   <li><strong>EXPORT</strong> create database (<strong>DEFAULT!</strong>). forces excecution, signals skip)</li>
+   *   <li><strong>SCRIPT</strong> export schema to SQL-script and print it to STDOUT</li>
    *   <li><strong>BOTH</strong></li>
    * </ul>
    *
+   * A databaseconnection is only needed for EXPORT and BOTH, but a
+   * Hibernate-Dialect must always be choosen.
+   *
    * @parameter property="hibernate.export.target" default-value="EXPORT"
    */
   private String target;
@@ -245,6 +248,8 @@ public class Hbm2DdlMojo extends AbstractMojo
    *   <li><strong>BOTH</strong> (<strong>DEFAULT!</strong>)</li>
    * </ul>
    *
+   * If NONE is choosen, no databaseconnection is needed.
+   *
    * @parameter property="hibernate.export.type" default-value="BOTH"
    */
   private String type;
@@ -684,6 +689,7 @@ public class Hbm2DdlMojo extends AbstractMojo
        * hibernate does not use the context-classloader of the current
        * thread and, hence, would not be able to resolve the driver-class!
        */
+      getLog().debug("Target: " + target + ", Type: " + type);
       switch (target)
       {
         case EXPORT:
diff --git a/src/site/apt/pitfalls.apt b/src/site/apt/pitfalls.apt
index 5bbbff12..61b5bc95 100644
--- a/src/site/apt/pitfalls.apt
+++ b/src/site/apt/pitfalls.apt
@@ -1,5 +1,22 @@
 Known Pitfalls
 
+* 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 commandline-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.
@@ -95,3 +112,24 @@ 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 clen>>> for cleanup, this will not happen.
+  Otherwise the recreation must be forced:
+
+-------------
+mvn hibernate4:export -Dhibernate.export.force=true
+-------------
diff --git a/src/site/site.xml b/src/site/site.xml
index a8a3bef2..fcc59320 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -22,7 +22,7 @@
       <item name="Parameter Documentation" href="export-mojo.html"/>
       <item name="Enable Debug-Output" href="debugging.html"/>
       <item name="Force Exceution" href="force.html"/>
-      <item name="Known Pitfalls" href="pitfalls.html"/>
+      <item name="Known Pitfalls (FAQ)" href="pitfalls.html"/>
     </menu>
     <menu ref="reports"/>
     <breadcrumbs>
-- 
2.20.1