Switched documentation to xhtml, to be able to integrate google-pretty-print

diff --git a/src/site/apt/configuration.apt b/src/site/apt/configuration.apt
deleted file mode 100644 (file)
index 98fad3b..0000000
--- a/src/site/apt/configuration.apt
+++ /dev/null
@@ -1,214 +0,0 @@
-  ---
-  Configuration Examples
-  ---
-  Kai Moritz
-  ---
-
-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>${project.version}</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>${project.version}</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>${project.version}</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>${project.version}</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>
----------------
-
-  The parameter <<hibernateProperties>> (name of the hibernate-properties-file
-  to use, defaults to <<hibernate.properties>>) can only be configured through
-  this approach.
-
-  For more 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 {{{./debugging.html}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>${project.version}</version>
-  <executions>
-    <execution>
-      <goals>
-        <goal>export</goal>
-      </goals>
-    </execution>
-  </executions>
-  <configuration>
-    <password>${my-password-property}</password>
-  </configuration>
-</plugin>
-----------------

diff --git a/src/site/apt/debugging.apt b/src/site/apt/debugging.apt
deleted file mode 100644 (file)
index 37e8118..0000000
--- a/src/site/apt/debugging.apt
+++ /dev/null
@@ -1,25 +0,0 @@
-  ---
-  Enabling Debug-Output
-  ---
-  Kai Moritz
-  ---
-
-  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 ;)

diff --git a/src/site/apt/force.apt b/src/site/apt/force.apt
deleted file mode 100644 (file)
index bff87d8..0000000
--- a/src/site/apt/force.apt
+++ /dev/null
@@ -1,35 +0,0 @@
-  ---
-  Force execution
-  ---
-  Kai Moritz
-  ---
-
-  The hibernate4-maven-plugin computes MD5-sums for all found annotated
-  classes and stores them together with the generated schema.
-  If no classes were changed or added and the dialect wasn't changed too, it
-  automatically skips the configured schema-export, to speed up the development
-  cycle.
-
-  The plugin signals, that the execution was skipped by setting the maven
-  property <<<${hibernate.export.skipped}>>> to <<<true>>>.
-  This may be helpful, because other plugins like
-  {{{http://mojo.codehaus.org/dbunit-maven-plugin/}dbunit-plugin}}
-  {{{./pitfalls.html#fails}may fail}}, when the execution is skipped.
-
-  If you need the hibernate4-maven-plugin to <never skip execution automatically>,
-  you can force it to do so, if you set the parameter <<<force>>> to
-  <<<true>>>:
-
-----------------
-<plugin>
-  <groupId>de.juplo</groupId>
-  <artifactId>hibernate4-maven-plugin</artifactId>
-  <version>${project.version}</version>
-  <configuration>
-    <force>true</force>
-  </configuration>
-</plugin>
-----------------
-
-  Or you may specify <<<-Dhibernate.export.force=true>>> at the command line,
-  if you want to force hibernate4-maven-plugin only once.

diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
deleted file mode 100644 (file)
index 76af673..0000000
--- a/src/site/apt/index.apt
+++ /dev/null
@@ -1,59 +0,0 @@
-  ---
-  A simple Plugin for generating a Database-Schema from Hibernate 4 Mapping-Annotations.
-  ---
-  Kai Moritz
-  ---
-
-  <<hibernate4-maven-plugin>> is a plugin for generating a database-schema
-  from your Hibernate-4-Mappings and create or update your database
-  accordingly.
-  Its main usage is to automatically create and populate a test-database
-  for unit-tests in cooperation with the
-  {{{http://mojo.codehaus.org/dbunit-maven-plugin/} dbunit-maven-plugin}}.
-
-  The plugin was designed with three main goals in mind:
-
-    * It should be easy to use.
-
-    * It should be maximal unlikely, to erase a producation-database by
-      accident.
-
-    * It should not slow down the development cycle.
-
-  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 {{{./debugging.html} debugging 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.
-
-  Last but not least, in order to not slow down the development cycle, the
-  hibernate4-maven-plugin only executes the schema-export, if the mapping
-  or the dialect changes (or if you force it to do so).
-
-  For more information about the inspiration 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}}.
-
-Documentation
-
- * See {{{./configuration.html} Configuration Examples}} for Usage-Explanations
-   and simple examples of how to use this plugin.
-
- * See {{{./export-mojo.html}hibernate4:export}} and
-    {{{./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.
-
-Releases
-
- * {{{http://juplo.de/hibernate4-maven-plugin} current version}}
-
- * ${project.version} (this version)
-
- * {{{http://juplo.de/hibernate4-maven-plugin-1.0.2} 1.0.2}}
-
- * {{{http://juplo.de/hibernate4-maven-plugin-1.0.1} 1.0.1}}
-
- * {{{http://juplo.de/hibernate4-maven-plugin-1.0} 1.0}}

diff --git a/src/site/apt/issue-tracking.apt b/src/site/apt/issue-tracking.apt
deleted file mode 100644 (file)
index 42292e1..0000000
--- a/src/site/apt/issue-tracking.apt
+++ /dev/null
@@ -1,11 +0,0 @@
-  ---
-  Issue Tracking
-  ---
-  Kai Moritz
-  ----
-
-  <<There is no bug-tracking system set up for this project!>>
-
-  Please send your bug-reports, questions or feature-requests directly
-  to the developer.
-

diff --git a/src/site/apt/mail-lists.apt b/src/site/apt/mail-lists.apt
deleted file mode 100644 (file)
index e8c17ec..0000000
--- a/src/site/apt/mail-lists.apt
+++ /dev/null
@@ -1,10 +0,0 @@
-  ---
-  Mailing Lists
-  ---
-  Kai Moritz
-  ---
-
-  <<There are no mailinglists defined for this project!>>
-
-  Please send your bug-reports, questions or feature-requests directly
-  to the developer.

diff --git a/src/site/apt/pitfalls.apt b/src/site/apt/pitfalls.apt
deleted file mode 100644 (file)
index 355e369..0000000
--- a/src/site/apt/pitfalls.apt
+++ /dev/null
@@ -1,169 +0,0 @@
-  ---
-  Known Pitfalls
-  ---
-  Kai Moritz
-  ---
-
-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.
-  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>${project.version}</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.
-
-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.
-  For example, when importing sample-data in the automatically created database
-  with the help of the {{{http://mojo.codehaus.org/dbunit-maven-plugin/}dbunit-plugin}},
-  the <<<CLEAN_INSERT>>>-operation may fail because of foreign-key-constraints,
-  if the database was not recreated, because the hibernate4-maven-plugin has
-  skipped its excecution.
-
-  A quick fix to this problem is, to {{{./force.html}force}}
-  hibernate4-maven-plugin to export the schema every time it is running.
-  But to recreate the database on every testrun may noticeable slow down your
-  development cycle, if you have to wait for slow IO.
-
-  To circumvent this problem, hibernate4-maven-plugin signals a skipped
-  excecution by setting the  maven property <<<${hibernate.export.skipped}>>> to
-  <<<true>>>.
-  You can configure other plugins to react on this signal.
-  For example, the dbunit-plugin can be configured to skip its excecution, if
-  hibernate4-maven-plugin was skipped like this:
-
-------------
-<plugin>
-  <groupId>org.codehaus.mojo</groupId>
-  <artifactId>dbunit-maven-plugin</artifactId>
-  <configuration>
-    <skip>${hibernate.export.skipped}</skip>
-  </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}}...

diff --git a/src/site/apt/skip.apt b/src/site/apt/skip.apt
deleted file mode 100644 (file)
index 676a7de..0000000
--- a/src/site/apt/skip.apt
+++ /dev/null
@@ -1,55 +0,0 @@
-  ---
-  To Skip or not to skip: that is the question
-  ---
-  Kai Moritz
-  ---
-
-  In most use-cases, the hibernate4-maven-plugin is used to create a
-  test-database automatically. In this use-cases, it is very likely, that it
-  will result in mistakes/errors, if the goal is executed, when the tests
-  are skipped.
-  For example, one might manually overwrite the database-url with the url of
-  the production-database, in order to run other tests, like starting a
-  local webserver with the
-  {{{http://wiki.eclipse.org/Jetty/Feature/Jetty_Maven_Plugin}jetty-maven-plugin}}.
-  If the export-goal would be executed in such a scenario, it might erase the
-  hole production-database, which is not very desireable.
-
-  Because of this, the configuration-parameter <<<skip>>> defaults to the value
-  of the proptery <<<maven.test.skip>>>. This way, the execution of the
-  hibernate4-maven-plugin is skipped automatically, when the tests are
-  skipped. Think of it as a build-in security-belt.
-
-  If you do not like that, because you need the plugin to always execute the
-  export-goal, even if the tests are skipped you can configure that explicitly,
-  by setting the configuration-parameter <<<skip>>> to false:
-
-------------
-<plugin>
-  <groupId>de.juplo</groupId>
-  <artifactId>hibernate4-maven-plugin</artifactId>
-  ...
-  <configuration>
-    <skip>false</skip>
-  </configuration>
-</plugin>
-------------
-
-  Or, if you want the export-goal to be executed by default and to be skipped
-  if you say so, you can bind the value of the configuration-parameter
-  <<<skip>>> to a custom property. For example:
-
-------------
-<plugin>
-  <groupId>de.juplo</groupId>
-  <artifactId>hibernate4-maven-plugin</artifactId>
-  ...
-  <configuration>
-    <skip>${foo.bar}</skip>
-  </configuration>
-</plugin>
-------------
-
-  This way, the export-goal would be skipped, if you set the property
-  <<<foo.bar>>> to <<<true>>>. For example, if you specify <<<-Dfoo.bar=true>>>
-  on the command-line.

diff --git a/src/site/site.xml b/src/site/site.xml
index f3e1996..5399d17 100644 (file)
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -14,6 +14,7 @@
   <skin>
     <groupId>de.juplo</groupId>
     <artifactId>juplo-maven-skin</artifactId>
+    <version>1.0.7</version>
   </skin>
 </project>
 

diff --git a/src/site/xhtml/configuration.xhtml b/src/site/xhtml/configuration.xhtml
new file mode 100644 (file)
index 0000000..bfaf6fe
--- /dev/null
+++ b/src/site/xhtml/configuration.xhtml
@@ -0,0 +1,213 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ </head>
+ <body>
+  <h2>Configuration through a hibernate.properties-File</h2>
+  <p>
+  The most simple way to configure the plugin is, to put all the
+  hibernate-configuration in a <strong>hibernate.properties</strong>-file on your
+  classpath. Put the file in the <code>resources</code>-folder. Maven will put
+  it in the <code>class</code>-folder of your webapp, where it will be picked up
+  by this plugin as well as by Hibernate 4.
+  </p>
+  <p>
+  Doing so, the only additionally configuration needed, to activat the plugin
+  is the following entry in the <code>plugins</code>-section of your <code>pom.xml</code>:
+  </p>
+  <pre class="prettyprint linenums lang-html">
+&lt;plugin&gt;
+  &lt;groupId&gt;de.juplo&lt;/groupId&gt;
+  &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
+  &lt;version&gt;${project.version}&lt;/version&gt;
+  &lt;executions&gt;
+    &lt;execution&gt;
+      &lt;goals&gt;
+        &lt;goal&gt;export&lt;/goal&gt;
+      &lt;/goals&gt;
+    &lt;/execution&gt;
+  &lt;/executions&gt;
+&lt;/plugin&gt;</pre>
+  <p>
+  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.
+  <strong>
+    So, you should never fire up this configuration on your production
+    system, or your database might be erased!
+  </strong>
+  </p>
+  <p>
+  Hence, you should specify a different url for testing like in the
+  following snippet:
+  </p>
+  <pre class="prettyprint linenums lang-html">
+&lt;plugin&gt;
+  &lt;groupId&gt;de.juplo&lt;/groupId&gt;
+  &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
+  &lt;version&gt;${project.version}&lt;/version&gt;
+  &lt;executions&gt;
+    &lt;execution&gt;
+      &lt;goals&gt;
+        &lt;goal&gt;export&lt;/goal&gt;
+      &lt;/goals&gt;
+    &lt;/execution&gt;
+  &lt;/executions&gt;
+  &lt;configuration&gt;
+    &lt;url&gt;&lt;![CDATA[jdbc:mysql://localhost/test-db]]&gt;&lt;/url&gt;
+  &lt;/configuration&gt;
+&lt;/plugin&gt;</pre>
+  <p>
+  Configuration properties, that are set in the <code>configuration</code>-section
+  of the plugin-configuration cannnot be overwritten elsewere (for details
+  see <a href="#precedence">Configuration-Method-Precedence</a>).
+  You never can overwrite them by accident when specifying a property on
+  the commandline or in your <code>settings.xml</code>.
+  </p>
+  <h2>Configuration through maven-properties</h2>
+  <p>
+  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 <a href="./export-mojo.html">Documentation of the export-Mojo</a>).
+  These are named after the
+  <a href="http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-hibernatejdbc">Hibernate JDBC Properties</a>:
+  </p>
+  <ul>
+    <li><code>hibernate.connection.driver_class</code></li>
+    <li><code>hibernate.dialect</code></li>
+    <li><code>hibernate.connection.url</code></li>
+    <li><code>hibernate.connection.username</code></li>
+    <li><code>hibernate.connection.password</code></li>
+  </ul>
+  <p>
+  So, instead of writing the hibernate-configuration in the properties-file,
+  like above, you could put it in the <code>properties</code>-section of your
+  <code>pom.xml</code>.
+  </p>
+  <p>
+  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):
+  </p>
+  <pre class="prettyprint linenums lang-html">
+&lt;properties&gt;
+  &lt;hibernate.connection.driver_class&gt;org.hsqldb.jdbcDriver&lt;/hibernate.connection.driver_class&gt;
+  &lt;hibernate.dialect&gt;org.hibernate.dialect.HSQLDialect&lt;/hibernate.dialect&gt;
+  &lt;hibernate.connection.url&gt;&lt;![CDATA[jdbc:hsqldb:res:org.my.path.production_db]]&gt;&lt;/hibernate.connection.url&gt;
+  &lt;hibernate.connection.username&gt;sa&lt;/hibernate.connection.username&gt;
+  &lt;hibernate.connection.password&gt;&lt;/hibernate.connection.password&gt;
+&lt;/properties&gt;
+
+...
+
+&lt;plugins&gt;
+
+  ...
+
+  &lt;plugin&gt;
+    &lt;groupId&gt;de.juplo&lt;/groupId&gt;
+    &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
+    &lt;version&gt;${project.version}&lt;/version&gt;
+    &lt;executions&gt;
+      &lt;execution&gt;
+        &lt;goals&gt;
+          &lt;goal&gt;export&lt;/goal&gt;
+        &lt;/goals&gt;
+      &lt;/execution&gt;
+    &lt;/executions&gt;
+    &lt;configuration&gt;
+      &lt;url&gt;&lt;![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]&gt;&lt;/url&gt;
+    &lt;/configuration&gt;
+  &lt;/plugin&gt;
+
+&lt;plugins&gt;</pre>
+  <h2>Configuration through the plugin-configuration</h2>
+  <p>
+  A third way for configuring the plugin is the plugin-configuration.
+  The relevant configuration-parameters are:
+  </p>
+  <ul>
+    <li><code>driverClassName</code></li>
+    <li><code>hibernateDialect</code></li>
+    <li><code>url</code></li>
+    <li><code>username</code></li>
+    <li><code>password</code></li>
+  </ul>
+  <p>
+  The equivalent of the configuration from the last section would look
+  like this:
+  </p>
+  <pre class="prettyprint linenums lang-html">
+&lt;plugin&gt;
+  &lt;groupId&gt;de.juplo&lt;/groupId&gt;
+  &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
+  &lt;version&gt;${project.version}&lt;/version&gt;
+  &lt;executions&gt;
+    &lt;execution&gt;
+      &lt;goals&gt;
+        &lt;goal&gt;export&lt;/goal&gt;
+      &lt;/goals&gt;
+    &lt;/execution&gt;
+  &lt;/executions&gt;
+  &lt;configuration&gt;
+    &lt;driverClassName&gt;org.hsqldb.jdbcDriver&lt;/driverClassName&gt;
+    &lt;hibernateDialect&gt;org.hibernate.dialect.HSQLDialect&lt;/hibernateDialect&gt;
+    &lt;url&gt;&lt;![CDATA[jdbc:hsqldb:target/db/fotos;shutdown=true]]&gt;&lt;/url&gt;
+    &lt;username&gt;sa&lt;/username&gt;
+    &lt;password&gt;&lt;/password&gt;
+  &lt;/configuration&gt;
+&lt;/plugin&gt;</pre>
+  <p>
+  The parameter <strong>hibernateProperties</strong> (name of the hibernate-properties-file
+  to use, defaults to <strong>hibernate.properties</strong>) can only be configured through
+  this approach.
+  </p>
+  <p>
+  For more explanations, see the
+  <a href="./export-mojo.html">Documentation of the export-Mojo</a>.
+  </p>
+  <h2 id="precedence">Configuration-Method-Precedence</h2>
+  <p>
+  The configuration is gathered in a fix order:
+  </p>
+  <ol>
+    <li><code>hibernate.properties</code></li>
+    <li>maven-properties</li>
+    <li>plugin-configuration</li>
+  </ol>
+  <p>
+  If you are in doubt about where a configuration-value comes from, run
+  maven with the <a href="./debugging.html">debug-output</a> enabled: <code>mvn -X hibernate4:export</code>
+  and be aware, that maven-properties can be overwitten on the command-line,
+  in your <code>~/.m2/settings.xml</code> and in a profile.
+  </p>
+  <p>
+  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.
+  </p>
+  <p>
+  If you realy need to overwrite plugin-configuration-values with
+  maven-properties, you can use maven-properties in the plugin-configuration:
+  </p>
+  <pre class="prettyprint linenums lang-html">
+&lt;plugin&gt;
+  &lt;groupId&gt;de.juplo&lt;/groupId&gt;
+  &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
+  &lt;version&gt;${project.version}&lt;/version&gt;
+  &lt;executions&gt;
+    &lt;execution&gt;
+      &lt;goals&gt;
+        &lt;goal&gt;export&lt;/goal&gt;
+      &lt;/goals&gt;
+    &lt;/execution&gt;
+  &lt;/executions&gt;
+  &lt;configuration&gt;
+    &lt;password&gt;${my-password-property}&lt;/password&gt;
+  &lt;/configuration&gt;
+&lt;/plugin&gt;</pre>
+ </body>
+</html>

diff --git a/src/site/xhtml/debugging.xhtml b/src/site/xhtml/debugging.xhtml
new file mode 100644 (file)
index 0000000..8f91f3f
--- /dev/null
+++ b/src/site/xhtml/debugging.xhtml
@@ -0,0 +1,30 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ </head>
+ <body>
+  <p>
+  If you are new to <code>hibernate4-maven-plugin</code>, 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:
+  </p>
+  <pre class="prettyprint linenums lang-html">
+mvn -X compile hibernate4:export</pre>
+  <p>
+  (The <code>compile</code> might be necessary, because <code>hibernate4-maven-plugin</code>
+  has to scan the compiled classes for annotations!)
+  </p>
+  <p>
+  Unlike the majority of the maven-plugins, <code>hibernate4-maven-plugin</code> 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!
+  </p>
+  <p>
+  <strong>But be warned:</strong> <code>hibernate4-maven-plugin</code> tends to be very chatty ;)
+  </p>
+ </body>
+</html>

diff --git a/src/site/xhtml/force.xhtml b/src/site/xhtml/force.xhtml
new file mode 100644 (file)
index 0000000..0a94070
--- /dev/null
+++ b/src/site/xhtml/force.xhtml
@@ -0,0 +1,40 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ </head>
+ <body>
+  <p>
+  The hibernate4-maven-plugin computes MD5-sums for all found annotated
+  classes and stores them together with the generated schema.
+  If no classes were changed or added and the dialect wasn't changed too, it
+  automatically skips the configured schema-export, to speed up the development
+  cycle.
+  </p>
+  <p>
+  The plugin signals, that the execution was skipped by setting the maven
+  property <code>$\{hibernate.export.skipped\}</code> to <code>true</code>.
+  This may be helpful, because other plugins like
+  <a href="http://mojo.codehaus.org/dbunit-maven-plugin/">dbunit-plugin</a>
+  <a href="./pitfalls.html#fails">may fail</a>, when the execution is skipped.
+  </p>
+  <p>
+  If you need the hibernate4-maven-plugin to &lt;never skip execution automatically&gt;,
+  you can force it to do so, if you set the parameter <code>force</code> to
+  <code>true</code>:
+  </p>
+  <pre class="prettyprint linenums lang-html">
+&lt;plugin&gt;
+  &lt;groupId&gt;de.juplo&lt;/groupId&gt;
+  &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
+  &lt;version&gt;${project.version}&lt;/version&gt;
+  &lt;configuration&gt;
+    &lt;force&gt;true&lt;/force&gt;
+  &lt;/configuration&gt;
+&lt;/plugin&gt;</pre>
+  <p>
+  Or you may specify <code>-Dhibernate.export.force=true</code> at the command line,
+  if you want to force hibernate4-maven-plugin only once.
+  </p>
+ </body>
+</html>

diff --git a/src/site/xhtml/index.xhtml b/src/site/xhtml/index.xhtml
new file mode 100644 (file)
index 0000000..ef7de69
--- /dev/null
+++ b/src/site/xhtml/index.xhtml
@@ -0,0 +1,68 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ </head>
+ <body>
+  <h1>Hibernate 4 Maven Plugin</h1>
+  <h2>A simple Plugin for generating a Database-Schema from Hibernate 4 Mapping-Annotations</h2>
+  <p>
+  The <strong>hibernate4-maven-plugin</strong> is a plugin for generating a database-schema
+  from your Hibernate-4-Mappings and create or update your database
+  accordingly.
+  Its main usage is to automatically create and populate a test-database
+  for unit-tests in cooperation with the
+  <a href="http://mojo.codehaus.org/dbunit-maven-plugin">dbunit-maven-plugin</a>.
+  </p>
+  <p>
+  The plugin was designed with three main goals in mind:
+  </p>
+  <ul>
+    <li>It should be easy to use.</li>
+    <li>It should be maximal unlikely, to erase a producation-database by accident.</li>
+    <li>It should not slow down the development cycle.</li>
+  </ul>
+  <p>
+  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 <a href="./debugging.html">debugging output</a> with the <code>mvn -X ...</code>. 
+  </p>
+  <p>
+  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.
+  </p>
+  <p>
+  Last but not least, in order to not slow down the development cycle, the
+  hibernate4-maven-plugin only executes the schema-export, if the mapping
+  or the dialect changes (or if you force it to do so).
+  </p>
+  <p>
+  For more information about the inspiration to write this tiny plugin,
+  <a href="/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</a>.
+  </p>
+  <h2>Documentation</h2>
+  <ul>
+   <li>
+   See <a href="./configuration.html">Configuration Examples</a> for Usage-Explanations
+   and simple examples of how to use this plugin.
+   </li>
+   <li>
+   See <a href="./export-mojo.html">hibernate4:export</a> and
+   <a href="./plugin-info.html">Plugin Documentation</a> for the full
+   autogenerated documentation. These are mostly configuration-options
+   of the Hibernate-Tools <code>SchemaExport</code> and <code>SchemaUpdate</code>, that do
+   the work in the background.
+   </li>
+  </ul>
+  <h2>Releases</h2>
+  <ul>
+    <li><a href="http://juplo.de/hibernate4-maven-plugin">current version</a></li>
+    <li>${project.version} (this version)</li>
+    <li><a href="http://juplo.de/hibernate4-maven-plugin-1.0.3">1.0.3</a></li>
+    <li><a href="http://juplo.de/hibernate4-maven-plugin-1.0.2">1.0.2</a></li>
+    <li><a href="http://juplo.de/hibernate4-maven-plugin-1.0.1">1.0.1</a></li>
+    <li><a href="http://juplo.de/hibernate4-maven-plugin-1.0">1.0</a></li>
+  </ul>
+ </body>
+</html>

diff --git a/src/site/xhtml/issue-tracking.xhtml b/src/site/xhtml/issue-tracking.xhtml
new file mode 100644 (file)
index 0000000..f7e6859
--- /dev/null
+++ b/src/site/xhtml/issue-tracking.xhtml
@@ -0,0 +1,13 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ </head>
+ <body>
+  <strong>There is no bug-tracking system set up for this project!</strong>
+  <p>
+  Please send your bug-reports, questions or feature-requests directly
+  to the developer.
+  </p>
+ </body>
+</html>

diff --git a/src/site/xhtml/mail-lists.xhtml b/src/site/xhtml/mail-lists.xhtml
new file mode 100644 (file)
index 0000000..ff8d7f2
--- /dev/null
+++ b/src/site/xhtml/mail-lists.xhtml
@@ -0,0 +1,13 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ </head>
+ <body>
+  <strong>There are no mailinglists defined for this project!</strong>
+  <p>
+  Please send your bug-reports, questions or feature-requests directly
+  to the developer.
+  </p>
+ </body>
+</html>

diff --git a/src/site/xhtml/pitfalls.xhtml b/src/site/xhtml/pitfalls.xhtml
new file mode 100644 (file)
index 0000000..5000695
--- /dev/null
+++ b/src/site/xhtml/pitfalls.xhtml
@@ -0,0 +1,167 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ </head>
+ <body>
+  <h2>Annotated classes in dependencies are not found.</h2>
+  <p>
+  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.
+  </p>
+  <h2>hibernate4-maven-plugin always needs a database-connection</h2>
+  <p>
+  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
+  <code>-Dhibernate.export.target=SCRIPT</code> or with the following configuration:
+  </p>
+  <pre class="prettyprint linenums lang-html">
+&lt;configuration&gt;
+  &lt;target&gt;SCRIPT&lt;/target&gt;
+&lt;/configuration&gt;</pre>
+  <p>
+  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!
+  </p>
+  <h2>Dependency for driver-class XYZ is missing</h2>
+  <p>
+  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 <code>runtime</code>.
+  </p>
+  <p>
+  But this will break the execution of the <code>hibernate4-maven-plugin</code>.
+  Since it will not be able to see the needed dependency, it will fail with
+  an error-message like:
+  </p>
+  <pre class="prettyprint">
+[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] ------------------------------------------------------------------------</pre>
+  <p>
+  A quick workaround for this error would be, to delete the runtime-constraint
+  for the jdbc-driver-dependency.
+  </p>
+  <p>
+  A much cleaner way is, to (additionally) ad the dependency, to the
+  plugin-definition:
+  </p>
+  <pre class="prettyprint linenums lang-html">
+&lt;plugin&gt;
+  &lt;groupId&gt;de.juplo&lt;/groupId&gt;
+  &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
+  &lt;version&gt;${project.version}&lt;/version&gt;
+  &lt;executions&gt;
+    &lt;execution&gt;
+      &lt;goals&gt;
+        &lt;goal&gt;export&lt;/goal&gt;
+      &lt;/goals&gt;
+    &lt;/execution&gt;
+  &lt;/executions&gt;
+  &lt;dependencies&gt;
+  &lt;dependency&gt;
+    &lt;groupId&gt;org.hsqldb&lt;/groupId&gt;
+    &lt;artifactId&gt;hsqldb&lt;/artifactId&gt;
+    &lt;version&gt;2.2.8&lt;/version&gt;
+  &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+&lt;/plugin&gt;</pre>
+  <p>
+  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.
+  </p>
+  <h2 id="fails">DBUnit fails after execution of hibernate4 was skipped because nothing has changed</h2>
+  <p>
+  If hibernate4-maven-plugin skips its excecution, this may lead to errors in
+  other plugins.
+  For example, when importing sample-data in the automatically created database
+  with the help of the <a href="http://mojo.codehaus.org/dbunit-maven-plugin/">dbunit-plugin</a>,
+  the <code>CLEAN_INSERT</code>-operation may fail because of foreign-key-constraints,
+  if the database was not recreated, because the hibernate4-maven-plugin has
+  skipped its excecution.
+  </p>
+  <p>
+  A quick fix to this problem is, to <a href="./force.html">force</a>
+  hibernate4-maven-plugin to export the schema every time it is running.
+  But to recreate the database on every testrun may noticeable slow down your
+  development cycle, if you have to wait for slow IO.
+  </p>
+  <p>
+  To circumvent this problem, hibernate4-maven-plugin signals a skipped
+  excecution by setting the  maven property <code>$\{hibernate.export.skipped\}</code> to
+  <code>true</code>.
+  You can configure other plugins to react on this signal.
+  For example, the dbunit-plugin can be configured to skip its excecution, if
+  hibernate4-maven-plugin was skipped like this:
+  </p>
+  <pre class="prettyprint linenums lang-html">
+&lt;plugin&gt;
+  &lt;groupId&gt;org.codehaus.mojo&lt;/groupId&gt;
+  &lt;artifactId&gt;dbunit-maven-plugin&lt;/artifactId&gt;
+  &lt;configuration&gt;
+    &lt;skip&gt;${hibernate.export.skipped}&lt;/skip&gt;
+  &lt;/configuration&gt;
+&lt;/plugin&gt;</pre>
+  <h2>The database will not be recreated after a manual drop/clean</h2>
+  <p>
+  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:
+  </p>
+  <pre class="prettyprint">
+[INFO] No modified annotated classes found and dialect unchanged.
+[INFO] Skipping schema generation!</pre>
+  <p>
+  If one always uses <code>mvn clean</code> for cleanup, this will not happen.
+  Otherwise the recreation must be <a href="./force.html">forced</a>:
+  </p>
+  <pre class="prettyprint">
+mvn hibernate4:export -Dhibernate.export.force=true</pre>
+  <h2>The hibernate4:export goal is not executed, when tests are skipped</h2>
+  <p>
+  The hibernate4-maven-plugin automatically skips its execution, when
+  <code>maven.test.skip</code> is set to <code>true</code>. If you need it to be always
+  executed, you can configure that explicitly like this:
+  </p>
+  <pre class="prettyprint linenums lang-html">
+&gt;plugin&lt;
+  &lt;groupId&gt;de.juplo&lt;/groupId&gt;
+  &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
+  ...
+  &lt;configuration&gt;
+    &lt;skip&gt;false&lt;/skip&gt;
+  &lt;/configuration&gt;
+&lt;/plugin&gt;</pre>
+  <p>
+  Background-information for this design-decission can be found on the extra
+  page <a href="./skip.html">To skip or not to skip: that is the question</a>...
+  </p>
+ </body>
+</html>

diff --git a/src/site/xhtml/skip.xhtml b/src/site/xhtml/skip.xhtml
new file mode 100644 (file)
index 0000000..51a20af
--- /dev/null
+++ b/src/site/xhtml/skip.xhtml
@@ -0,0 +1,59 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ </head>
+ <body>
+  <p>
+  In most use-cases, the hibernate4-maven-plugin is used to create a
+  test-database automatically. In this use-cases, it is very likely, that it
+  will result in mistakes/errors, if the goal is executed, when the tests
+  are skipped.
+  For example, one might manually overwrite the database-url with the url of
+  the production-database, in order to run other tests, like starting a
+  local webserver with the
+  <a href="http://wiki.eclipse.org/Jetty/Feature/Jetty_Maven_Plugin">jetty-maven-plugin</a>.
+  If the export-goal would be executed in such a scenario, it might erase the
+  hole production-database, which is not very desireable.
+  </p>
+  <p>
+  Because of this, the configuration-parameter <code>skip</code> defaults to the value
+  of the proptery <code>maven.test.skip</code>. This way, the execution of the
+  hibernate4-maven-plugin is skipped automatically, when the tests are
+  skipped. Think of it as a build-in security-belt.
+  </p>
+  <p>
+  If you do not like that, because you need the plugin to always execute the
+  export-goal, even if the tests are skipped you can configure that explicitly,
+  by setting the configuration-parameter <code>skip</code> to false:
+  </p>
+  <pre class="prettyprint linenums lang-html">
+&lt;plugin&gt;
+  &lt;groupId&gt;de.juplo&lt;/groupId&gt;
+  &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
+  ...
+  &lt;configuration&gt;
+    &lt;skip&gt;false&lt;/skip&gt;
+  &lt;/configuration&gt;
+&lt;/plugin&gt;</pre>
+  <p>
+  Or, if you want the export-goal to be executed by default and to be skipped
+  if you say so, you can bind the value of the configuration-parameter
+  <code>skip</code> to a custom property. For example:
+  </p>
+  <pre class="prettyprint linenums lang-html">
+&lt;plugin&gt;
+  &lt;groupId&gt;de.juplo&lt;/groupId&gt;
+  &lt;artifactId&gt;hibernate4-maven-plugin&lt;/artifactId&gt;
+  ...
+  &lt;configuration&gt;
+    &lt;skip&gt;${foo.bar}&lt;/skip&gt;
+  &lt;/configuration&gt;
+&lt;/plugin&gt;</pre>
+  <p>
+  This way, the export-goal would be skipped, if you set the property
+  <code>foo.bar</code> to <code>true</code>. For example, if you specify <code>-Dfoo.bar=true</code>
+  on the command-line.
+  </p>
+ </body>
+</html>