From: Kai Moritz <kai@coolibri.de>
Date: Wed, 28 Nov 2012 23:11:04 +0000 (+0100)
Subject: Reworked documentation (described example-configurations)
X-Git-Tag: hibernate4-maven-plugin-1.0~3
X-Git-Url: https://juplo.de/gitweb/?p=hibernate4-maven-plugin;a=commitdiff_plain;h=17b00da14edf0d80c738b82dae9a4b3a1ba21ac7

Reworked documentation (described example-configurations)
---

diff --git a/src/site/apt/examples.apt b/src/site/apt/examples.apt
new file mode 100644
index 00000000..da04a251
--- /dev/null
+++ b/src/site/apt/examples.apt
@@ -0,0 +1,323 @@
+Configuration Examples
+
+  The plugin was designed with two main goals in mind:
+
+    * It should be easy to use.
+
+    * It should be maximal unlikely, to erase a producation-database by
+      accident.
+
+  To achieve the first goal, the convention-over-configuration paradigma
+  was applied and the plugin was stuffed with usefull logging-messages.
+  So, if in doubt, just turn on the {{Debug-Output}} with the <<<mvn -X ...>>>. 
+
+  To achieve the second goal, the precedence in which the configuration
+  locations are consulted was layouted in a way that makes it possible, to
+  prevent overwrites of the wrong database by accident.
+
+Configuration through a hibernate.properties-File
+
+  The most simple way to configure the plugin is, to put all the
+  hibernate-configuration in a <<hibernate.properties>>-file on your
+  classpath. Put the file in the <<<resources>>>-folder. Maven will put
+  it in the <<<class>>>-folder of your webapp, where it will be picked up
+  by this plugin as well as by Hibernate 4.
+
+  Doing so, the only additionally configuration needed, to activat the plugin
+  is the following entry in the <<<plugins>>>-section of your <<<pom.xml>>>:
+
+---------------
+<plugin>
+  <groupId>de.juplo</groupId>
+  <artifactId>hibernate4-maven-plugin</artifactId>
+  <version>1.0-SNAPSHOT</version>
+  <executions>
+    <execution>
+      <goals>
+        <goal>export</goal>
+      </goals>
+    </execution>
+  </executions>
+</plugin>
+---------------
+
+  But be aware, that in this case the database-url, that is
+  build in the application is the same that is used while testing, where
+  the database is droped and recreated by the plugin.
+  <<<So, you should never fire up this configuration on your production
+  system, or your database might be erased!>>>
+
+  Hence, you should specify a different url for testing like in the
+  following snippet:
+
+---------------
+<plugin>
+  <groupId>de.juplo</groupId>
+  <artifactId>hibernate4-maven-plugin</artifactId>
+  <version>1.0-SNAPSHOT</version>
+  <executions>
+    <execution>
+      <goals>
+        <goal>export</goal>
+      </goals>
+    </execution>
+  </executions>
+  <configuration>
+    <url><![CDATA[jdbc:mysql://localhost/test-db]]></url>
+  </configuration>
+</plugin>
+---------------
+
+  Configuration properties, that are set in the <<<configuration>>>-section
+  of the plugin-configuration cannnot be overwritten elsewere (for details
+  see {{Configuration-Method-Precedence}}).
+  You never can overwrite them by accident when specifying a property on
+  the commandline or in your <<<settings.xml>>>.
+
+Configuration through maven-properties
+
+  Alternatively, it is possible, to configure the plugin via maven-properties.
+  Each relevant configuration-option has a corresponding maven-property
+  (for a full list see the {{{./export-mojo.html} Documentation of the export-Mojo}}).
+  These are named after the
+  {{{http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-hibernatejdbc} Hibernate JDBC Properties}}:
+
+    * <<<hibernate.connection.driver_class>>>
+
+    * <<<hibernate.dialect>>>
+
+    * <<<hibernate.connection.url>>>
+
+    * <<<hibernate.connection.username>>>
+
+    * <<<hibernate.connection.password>>>
+
+  So, instead of writing the hibernate-configuration in the properties-file,
+  like above, you could put it in the <<<properties>>>-section of your
+  <<<pom.xml>>>.
+
+  Thogether with the plugin-definition from above, the following would
+  be a complete configuration (again, the database-url was overwritten in
+  the plugin-configuration, to be sure to have a separate database for
+  testing):
+
+---------------
+<properties>
+  <hibernate.connection.driver_class>org.hsqldb.jdbcDriver</hibernate.connection.driver_class>
+  <hibernate.dialect>org.hibernate.dialect.HSQLDialect</hibernate.dialect>
+  <hibernate.connection.url><![CDATA[jdbc:hsqldb:res:org.my.path.production_db]]></hibernate.connection.url>
+  <hibernate.connection.username>sa</hibernate.connection.username>
+  <hibernate.connection.password></hibernate.connection.password>
+</properties>
+
+...
+
+<plugins>
+
+  ...
+
+  <plugin>
+    <groupId>de.juplo</groupId>
+    <artifactId>hibernate4-maven-plugin</artifactId>
+    <version>1.0-SNAPSHOT</version>
+    <executions>
+      <execution>
+        <goals>
+          <goal>export</goal>
+        </goals>
+      </execution>
+    </executions>
+    <configuration>
+      <url><![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]></url>
+    </configuration>
+  </plugin>
+
+<plugins>
+---------------
+
+Configuration through the plugin-configuration
+
+  A third way for configuring the plugin is the plugin-configuration.
+  The relevant configuration-parameters are:
+
+    * <<<driverClassName>>>
+
+    * <<<hibernateDialect>>>
+
+    * <<<url>>>
+
+    * <<<username>>>
+
+    * <<<password>>>
+
+  The equivalent of the configuration from the last section would look
+  like this:
+
+---------------
+<plugin>
+  <groupId>de.juplo</groupId>
+  <artifactId>hibernate4-maven-plugin</artifactId>
+  <version>1.0-SNAPSHOT</version>
+  <executions>
+    <execution>
+      <goals>
+        <goal>export</goal>
+      </goals>
+    </execution>
+  </executions>
+  <configuration>
+    <driverClassName>org.hsqldb.jdbcDriver</driverClassName>
+    <hibernateDialect>org.hibernate.dialect.HSQLDialect</hibernateDialect>
+    <url><![CDATA[jdbc:hsqldb:target/db/fotos;shutdown=true]]></url>
+    <username>sa</username>
+    <password></password>
+  </configuration>
+</plugin>
+---------------
+
+  There are some seldom used parameters, that can only be configured throug
+  this method:
+
+    * <<delimiter>> the delimiter used in the generated sql-script
+
+    * <<format>> wether the generated sql-script is formatted, or not
+
+    * <<hibernateProperties>> name of the hibernate-properties-file
+
+    * <<outputFile>> name of the generated sql-script
+
+    * <<target>> create database or generate sql-script or both
+
+    * <<type>> create or drop the database or do both or nothing
+      (just validate the annotation-configuration)
+
+  For explanations, see the
+  {{{./export-mojo.html} Documentation of the export-Mojo}}.
+
+{Configuration-Method-Precedence}
+
+  The configuration is gathered in a fix order:
+
+    [[1]] <<<hibernate.properties>>>
+
+    [[2]] maven-properties
+
+    [[3]] plugin-configuration
+
+  If you are in doubt about where a configuration-value comes from, run
+  maven with the {{Debug-Output}} enabled: <<<mvn -X hibernate4:export>>>
+  and be aware, that maven-properties can be overwitten on the command-line,
+  in your <<<~/.m2/settings.xml>>> and in a profile.
+
+  The plugin-configuration comes last and overwrites everything else.
+  That way, you can be sure, that a configuration-value, that is
+  specified in the plugin-configuration will never be overwritten by any
+  other configuration-method.
+
+
+  If you realy need to overwrite plugin-configuration-values with
+  maven-properties, you can use maven-properties in the plugin-configuration:
+
+----------------
+<plugin>
+  <groupId>de.juplo</groupId>
+  <artifactId>hibernate4-maven-plugin</artifactId>
+  <version>1.0-SNAPSHOT</version>
+  <executions>
+    <execution>
+      <goals>
+        <goal>export</goal>
+      </goals>
+    </execution>
+  </executions>
+  <configuration>
+    <password>${my-password-property}</password>
+  </configuration>
+</plugin>
+----------------
+
+Enabling {Debug-Output}
+
+  If you are new to <<<hibernate4-maven-plugin>>>, in many cases, the
+  {Configuration-Method-Precedence} may be the source of configuration
+  errors.
+  To solve this problem, you should run maven with the debugging output
+  enabled.
+  For example, by executing:
+
+-------------
+mvn -X compile hibernate4:export 
+-------------
+
+  (The <<<compile>>> might be necessary, because <<<hibernate4-maven-plugin>>>
+  has to scan the compiled classes for annotations!)
+
+  Unlike the majority of the maven-plugins, <<<hibernate4-maven-plugin>>> was
+  designed to give a good many hints, when debugging is enabled.
+  Because, if you do not know, what went wrong, you can't fix it!
+
+  <<But be warned:>> <<<hibernate4-maven-plugin>>> tends to be very chatty ;)
+
+Known Pitfalls
+
+  One regular problem is the scope of the jdbc-driver-dependency.
+  It is very unlikely, that this dependency is needed at compile-time.
+  So a tidy maven-developer would usually scope it for <<<runtime>>>.
+
+  But this will break the execution of the <<<hibernate4-maven-plugin>>>.
+  Since it will not be able to see the needed dependency, it will fail with
+  an error-message like:
+
+---------------
+[INFO] Gathered hibernate-configuration (turn on debugging for details):
+[INFO]   hibernate.connection.username = sa
+[INFO]   hibernate.connection.password = 
+[INFO]   hibernate.dialect = org.hibernate.dialect.HSQLDialect
+[INFO]   hibernate.connection.url = jdbc:hsqldb:/home/kai/mmf/target/mmf;shutdown=true
+[INFO]   hibernate.connection.driver_class = org.hsqldb.jdbcDriver
+[ERROR] Dependency for driver-class org.hsqldb.jdbcDriver is missing!
+[INFO] ------------------------------------------------------------------------
+[ERROR] BUILD ERROR
+[INFO] ------------------------------------------------------------------------
+[INFO] org.hsqldb.jdbcDriver
+[INFO] ------------------------------------------------------------------------
+[INFO] For more information, run Maven with the -e switch
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 2 seconds
+[INFO] Finished at: Thu Nov 29 11:31:14 CET 2012
+[INFO] Final Memory: 32M/342M
+[INFO] ------------------------------------------------------------------------
+---------------
+
+  A quick workaround for this error would be, to delete the runtime-constraint
+  for the jdbc-driver-dependency.
+
+  A much cleaner way is, to (additionally) ad the dependency, to the
+  plugin-definition:
+
+---------------
+<plugin>
+  <groupId>de.juplo</groupId>
+  <artifactId>hibernate4-maven-plugin</artifactId>
+  <version>1.0-SNAPSHOT</version>
+  <executions>
+    <execution>
+      <goals>
+        <goal>export</goal>
+      </goals>
+    </execution>
+  </executions>
+  <dependencies>
+  <dependency>
+    <groupId>org.hsqldb</groupId>
+    <artifactId>hsqldb</artifactId>
+    <version>2.2.8</version>
+  </dependency>
+  </dependencies>
+</plugin>
+---------------
+
+  This is also the best way, if you use a different jdbc-driver for
+  testing, than in production.
+  Because otherwise, this dependency will unnecessarily bloat the
+  runtime-dependencies of your project.
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
index 3b237a2c..3698529b 100644
--- a/src/site/apt/index.apt
+++ b/src/site/apt/index.apt
@@ -1,26 +1,21 @@
-A simple plugin for generating a database-schema from Hibernate 4 mapping-annotations.
+A simple Plugin for generating a Database-Schema from Hibernate 4 Mapping-Annotations.
 
-  Hibernate comes with the buildin functionality, to automatically create or
-  update the database schema.
-  This functionality is configured in the session-configuraton via the
-  parameter <hbm2ddl.auto>
-  (see {{{http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-optional} Hibernate Reference Documentation - Chapter 3.4. Optional configuration properties}}).
-  But doing so
-  {{{http://stackoverflow.com/questions/221379/hibernate-hbm2ddl-auto-update-in-production} is not very wise}}, because you can easily corrupt or erase your
-  production database, if this configuration parameter slips through to your
-  production environment.
-  Alternatively, you can
-  {{{http://stackoverflow.com/questions/835961/how-to-creata-database-schema-using-hibernate} run the tools SchemaExport or SchemaUpdate by hand}}.
-  But that is not very comfortable and being used to maven you will quickly
-  long for a plugin, that does that job automatically for you, when you fire
-  up your test cases.
+  <<hibernate4-maven-plugin>> is a plugin for generating a database-schema
+  from your Hibernate-4-Mappings and create or update your database
+  accordingly.
 
-  In the good old times, there was the
-  {{{http://mojo.codehaus.org/maven-hibernate3/hibernate3-maven-plugin/} Maven Hibernate3 Plugin}}, that does this for you.
-  But unfortunatly, this plugin is not compatible with Hibernate 4.x.
+  The plugin was designed to be easy and safe to use, because it must not 
+  never, never happen, that you blow away your production database when
+  firering a maven-build of your webapp on your production-machine!
+  For more information about the insiration to write this tiny plugin,
+  {{{/hibernate4-maven-plugin-a-simple-plugin-for-generating-a-database-schema-from-hibernate-4-mapping-annotations/} read our blog-article about the hibernate4-maven-plugin}}.
 
-  Since there does not seem to be any successor for the Maven Hibernate3 Plugin
-  and {{{http://www.google.de/search?q=hibernate4+maven+plugin} googeling}}
-  does not help, I decided to write up this simple plugin (inspired by these
-  two articles I found: {{{http://www.tikalk.com/alm/blog/schema-export-hibernate-4-and-maven} Schema Export with Hibernate 4 and Maven}} and
-  {{{http://doingenterprise.blogspot.de/2012/05/schema-generation-with-hibernate-4-jpa.html} Schema generation with Hibernate 4, JPA and Maven}}).
+Documentation and Examples
+
+ * See {{{./examples.html} Examples}} for Usage-Eplanations and simple
+   examples of how to use this plugin.
+
+ * See {{{./plugin-info.html} Plugin Documentation}} for the full
+   autogenerated documentation. These are mostly configuration-options
+   of the Hibernate-Tools <<<SchemaExport>>> and <<<SchemaUpdate>>>, that do
+   the work in the background.
diff --git a/src/site/site.xml b/src/site/site.xml
index a50f2c43..3c35c973 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -2,7 +2,8 @@
   <body>
     <menu name="Overview">
       <item name="Introduction" href="index.html"/>
-      <item name="Goals" href="plugin-info.html"/>
+      <item name="Examples" href="examples.html"/>
+      <item name="Documentation" href="plugin-info.html"/>
     </menu>
     <menu ref="reports"/>
   </body>