From 8c35bc05b4d7bc9dd1ab538e522247032407fab2 Mon Sep 17 00:00:00 2001
From: Kai Moritz <kai@juplo.de>
Date: Mon, 7 Mar 2016 16:01:59 +0100
Subject: [PATCH] Updated documentation
---
.../plugins/hibernate/AbstractSchemaMojo.java | 2 +-
src/site/site.xml | 3 +-
src/site/xhtml/configuration.xhtml | 78 +++++++++++++++----
src/site/xhtml/debugging.xhtml | 6 +-
src/site/xhtml/force.xhtml | 6 +-
src/site/xhtml/index.xhtml | 3 +-
src/site/xhtml/pitfalls.xhtml | 68 ++++++++++------
src/site/xhtml/skip.xhtml | 10 +--
8 files changed, 121 insertions(+), 55 deletions(-)
diff --git a/src/main/java/de/juplo/plugins/hibernate/AbstractSchemaMojo.java b/src/main/java/de/juplo/plugins/hibernate/AbstractSchemaMojo.java
index f6e18ea4..d4386ebe 100644
--- a/src/main/java/de/juplo/plugins/hibernate/AbstractSchemaMojo.java
+++ b/src/main/java/de/juplo/plugins/hibernate/AbstractSchemaMojo.java
@@ -136,7 +136,7 @@ public abstract class AbstractSchemaMojo extends AbstractMojo
* If set to <code>true</code>, the execution is skipped.
* <p>
* A skipped execution is signaled via the maven-property
- * <code>${hibernate.export.skipped}</code>.
+ * <code>${hibernate.schema.skipped}</code>.
* <p>
* The execution is skipped automatically, if no modified or newly added
* annotated classes are found and the dialect was not changed.
diff --git a/src/site/site.xml b/src/site/site.xml
index 7c28ac28..111fb6b4 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -3,7 +3,8 @@
<body>
<menu>
<item name="Configuration Examples" href="configuration.html"/>
- <item name="Parameter Documentation" href="export-mojo.html"/>
+ <item name="Goal: CREATE" href="create-mojo.html"/>
+ <item name="Goal: DROP" href="drop-mojo.html"/>
<item name="Enable Debug-Output" href="debugging.html"/>
<item name="Skipping Execution" href="skip.html"/>
<item name="Force Exceution" href="force.html"/>
diff --git a/src/site/xhtml/configuration.xhtml b/src/site/xhtml/configuration.xhtml
index e8c5afd5..712bdfb4 100644
--- a/src/site/xhtml/configuration.xhtml
+++ b/src/site/xhtml/configuration.xhtml
@@ -4,13 +4,14 @@
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</head>
<body>
- <h2>Configuration through a hibernate.properties-File</h2>
+ <h2>Configuration Through A Configuration-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.
+ hibernate-configuration in a <strong>hibernate.properties</strong>- or
+ a <strong>hibernate.cfg.xml</strong>-file on your classpath or in the
+ <strong>persistence.xml</strong>-file of your JPA-configuration, just
+ like you would do, if you are not using the
+ <code>hibernate-maven-plugin</code>.
</p>
<p>
Doing so, the only additionally configuration needed, to activat the plugin
@@ -24,15 +25,50 @@
<executions>
<execution>
<goals>
- <goal>export</goal>
+ <goal>create</goal>
</goals>
</execution>
</executions>
</plugin></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.
+ This would create the configured database.
+ If you want it to be droped beforehand, you have to add the goal
+ <code>drop</code>:
+ </p>
+ <pre class="prettyprint linenums lang-html">
+<plugin>
+ <groupId>de.juplo</groupId>
+ <artifactId>hibernate-maven-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <goals>
+ <goal>drop</goal>
+ <goal>create</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin></pre>
+ <p>
+ A correspondin goal for the command <code>update</code> is missing in this
+ version, but we are planning to implement it in near feature.
+ </p>
+ <p>
+ In order to let this configuration work, your configuration file must
+ contain a complete valid configuration for the database, that you want
+ to use.
+ A simple example <code>hibernate.properties</code>-file may look like this:
+ </p>
+ <pre class="prettyprint linenums lang-properties">
+hibernate.dialect=org.hibernate.dialect.H2Dialect
+hibernate.connection.url=jdbc:h2:file:./target/db
+hibernate.connection.driver_class=org.h2.Driver
+hibernate.connection.username=sa
+hibernate.connection.password=</pre>
+ <p>
+ But be aware, that using this configuration-approach 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.
Because of that,
<strong>
you should never fire up this configuration on your production
@@ -51,7 +87,8 @@
<executions>
<execution>
<goals>
- <goal>export</goal>
+ <goal>drop</goal>
+ <goal>create</goal>
</goals>
</execution>
</executions>
@@ -70,7 +107,7 @@
<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>).
+ (for a full list see the <a href="./create-mojo.html">Documentation of the goal create</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>
@@ -114,7 +151,8 @@
<executions>
<execution>
<goals>
- <goal>export</goal>
+ <goal>drop</goal>
+ <goal>create</goal>
</goals>
</execution>
</executions>
@@ -124,6 +162,12 @@
</plugin>
<plugins></pre>
+ <p>
+ This way, you can reuse the same properties to provide a
+ default-configurationthe, that is build into your application, and
+ overwrite the database-url, that is used during testing to prevent
+ accidential drops of your production database.
+ </p>
<h2>Configuration through the plugin-configuration</h2>
<p>
A third way for configuring the plugin is the plugin-configuration.
@@ -148,7 +192,8 @@
<executions>
<execution>
<goals>
- <goal>export</goal>
+ <goal>drop</goal>
+ <goal>create</goal>
</goals>
</execution>
</executions>
@@ -167,7 +212,7 @@
</p>
<p>
For more explanations, see the
- <a href="./export-mojo.html">Documentation of the export-Mojo</a>.
+ <a href="./create-mojo.html">Documentation of the goal create</a>.
</p>
<h2 id="precedence">Configuration-Method-Precedence</h2>
<p>
@@ -182,7 +227,7 @@
</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 hibernate:export</code>
+ maven with the <a href="./debugging.html">debug-output</a> enabled: <code>mvn -X hibernate:create</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>
@@ -204,7 +249,8 @@
<executions>
<execution>
<goals>
- <goal>export</goal>
+ <goal>drop</goal>
+ <goal>create</goal>
</goals>
</execution>
</executions>
diff --git a/src/site/xhtml/debugging.xhtml b/src/site/xhtml/debugging.xhtml
index c67d8c00..6271077d 100644
--- a/src/site/xhtml/debugging.xhtml
+++ b/src/site/xhtml/debugging.xhtml
@@ -6,14 +6,14 @@
<body>
<p>
If you are new to <code>hibernate-maven-plugin</code>, in many cases, the
- {Configuration-Method-Precedence} may be the source of configuration
- errors.
+ <a href="./configuration.html#precedence">Configuration-Method-Precedence</a>
+ 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 hibernate:export</pre>
+mvn -X compile hibernate:create</pre>
<p>
(The <code>compile</code> might be necessary, because <code>hibernate-maven-plugin</code>
has to scan the compiled classes for annotations!)
diff --git a/src/site/xhtml/force.xhtml b/src/site/xhtml/force.xhtml
index cd582db3..ecdab5bd 100644
--- a/src/site/xhtml/force.xhtml
+++ b/src/site/xhtml/force.xhtml
@@ -13,13 +13,13 @@
</p>
<p>
The plugin signals, that the execution was skipped by setting the maven
- property <code>$\{hibernate.export.skipped\}</code> to <code>true</code>.
+ property <code>${hibernate.schema.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 hibernate-maven-plugin to <never skip execution automatically>,
+ If you need the hibernate-maven-plugin to <em>never skip execution automatically</em>,
you can force it to do so, if you set the parameter <code>force</code> to
<code>true</code>:
</p>
@@ -33,7 +33,7 @@
</configuration>
</plugin></pre>
<p>
- Or you may specify <code>-Dhibernate.export.force=true</code> at the command line,
+ Or you may specify <code>-Dhibernate.schema.force=true</code> at the command line,
if you want to force hibernate-maven-plugin only once.
</p>
</body>
diff --git a/src/site/xhtml/index.xhtml b/src/site/xhtml/index.xhtml
index a30e6d62..6606fd90 100644
--- a/src/site/xhtml/index.xhtml
+++ b/src/site/xhtml/index.xhtml
@@ -48,7 +48,8 @@
and simple examples of how to use this plugin.
</li>
<li>
- See <a href="./export-mojo.html">hibernate:export</a> and
+ See <a href="./create-mojo.html">hibernate:create</a>,
+ See <a href="./drop-mojo.html">hibernate:drop</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
diff --git a/src/site/xhtml/pitfalls.xhtml b/src/site/xhtml/pitfalls.xhtml
index 3967811b..d762b3ae 100644
--- a/src/site/xhtml/pitfalls.xhtml
+++ b/src/site/xhtml/pitfalls.xhtml
@@ -15,19 +15,25 @@
</p>
<h2>hibernate-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.
+ The default-configuration exports the created schema to the configured
+ database.
+ Therefore, it needs a valid database-connection and fails, if none is
+ available.
+ If you do not need to export the created schema to a database,
+ you can set the property <code>hibernate.schema.export</code> to
+ <code>false</code>.
This can be achieved with the command-line parameter
- <code>-Dhibernate.export.target=SCRIPT</code> or with the following configuration:
+ <code>-Dhibernate.schema.export=false</code> or with the following
+ configuration:
</p>
<pre class="prettyprint linenums lang-html">
<configuration>
- <target>SCRIPT</target>
+ <export>false</export>
</configuration></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!
+ the dialect. Hence, the plugin will still fail, if this parameter is also
+ missing!
</p>
<h2>Dependency for driver-class XYZ is missing</h2>
<p>
@@ -44,21 +50,32 @@
[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] hibernate.dialect = org.hibernate.dialect.H2Dialect
+[INFO] hibernate.connection.url = jdbc:h2:file:./db
+[INFO] hibernate.hbm2dll.create_namespaces = false
+[INFO] hibernate.connection.driver_class = org.h2.Driver
+[INFO] hibernate.format_sql = true
+[INFO] HHH000412: Hibernate Core {5.0.2.Final}
+[INFO] HHH000206: hibernate.properties not found
+[INFO] HHH000021: Bytecode provider name : javassist
+[INFO] Adding /home/kai/project/target/classes to the list of roots to scan...
+[INFO] Adding dependencies from scope compile to the list of roots to scan
+[INFO] Adding dependencies from scope org.hibernate:hibernate-core:jar:4.3.0.Final to the list of roots to scan
+[INFO] Adding annotated resource: de.juplo.tests.SimplestMavenHib4Test
[INFO] ------------------------------------------------------------------------
-[ERROR] BUILD ERROR
+[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
-[INFO] org.hsqldb.jdbcDriver
+[INFO] Total time: 1.760s
+[INFO] Finished at: Mon Mar 07 19:06:54 CET 2016
+[INFO] Final Memory: 11M/215M
[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>
+[ERROR] Failed to execute goal de.juplo:hibernate-maven-plugin:${project.version}:drop (default) on project hibernate4-properties-test: Could not open the JDBC-connection: Unable to load class [org.h2.Driver]: Could not load requested class : org.h2.Driver -> [Help 1]
+[ERROR]
+[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
+[ERROR] Re-run Maven using the -X switch to enable full debug logging.
+[ERROR]
+[ERROR] For more information about the errors and possible solutions, please read the following articles:
+[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoFailureException</pre>
<p>
A quick workaround for this error would be, to delete the runtime-constraint
for the jdbc-driver-dependency.
@@ -75,7 +92,8 @@
<executions>
<execution>
<goals>
- <goal>export</goal>
+ <goal>drop</goal>
+ <goal>create</goal>
</goals>
</execution>
</executions>
@@ -111,7 +129,7 @@
</p>
<p>
To circumvent this problem, hibernate-maven-plugin signals a skipped
- excecution by setting the maven property <code>$\{hibernate.export.skipped\}</code> to
+ excecution by setting the maven property <code>${hibernate.schema.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
@@ -122,7 +140,7 @@
<groupId>org.codehaus.mojo</groupId>
<artifactId>dbunit-maven-plugin</artifactId>
<configuration>
- <skip>${hibernate.export.skipped}</skip>
+ <skip>${hibernate.schema.skipped}</skip>
</configuration>
</plugin></pre>
<h2>The database will not be recreated after a manual drop/clean</h2>
@@ -143,8 +161,8 @@
Otherwise the recreation must be <a href="./force.html">forced</a>:
</p>
<pre class="prettyprint">
-mvn hibernate:export -Dhibernate.export.force=true</pre>
- <h2>The hibernate:export goal is not executed, when tests are skipped</h2>
+mvn hibernate:create -Dhibernate.schema.force=true</pre>
+ <h2>The hibernate:create goal is not executed, when tests are skipped</h2>
<p>
The hibernate-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
@@ -166,7 +184,7 @@ mvn hibernate:export -Dhibernate.export.force=true</pre>
<h2>I do not want my dependencies to be scanned for hibernate annotations</h2>
<p>
If you do not want your dependencies to be scanned for hibernate annotations,
- you can pass <code>-Dhibernate.export.scan_dependencies=none</code> to maven
+ you can pass <code>-Dhibernate.schema.scan.dependencies=none</code> to maven
or set <code>scanDependencies</code> to <code>none</code> in the configuration
of the plugin like this:
</p>
@@ -189,7 +207,7 @@ mvn hibernate:export -Dhibernate.export.force=true</pre>
</p>
<p>
<strong>
- You should consider to upgrade to that version of the plugin.
+ You should consider to upgrade to the latest version of the plugin.
</strong>
</p>
</body>
diff --git a/src/site/xhtml/skip.xhtml b/src/site/xhtml/skip.xhtml
index 5f893b82..e25ed0ed 100644
--- a/src/site/xhtml/skip.xhtml
+++ b/src/site/xhtml/skip.xhtml
@@ -13,7 +13,7 @@
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
+ If the drop-goal would be executed in such a scenario, it might erase the
hole production-database, which is not very desireable.
</p>
<p>
@@ -23,8 +23,8 @@
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,
+ If you do not like that, because you need the plugin to always,
+ 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">
@@ -37,7 +37,7 @@
</configuration>
</plugin></pre>
<p>
- Or, if you want the export-goal to be executed by default and to be skipped
+ Or, if you want the plugin 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>
@@ -51,7 +51,7 @@
</configuration>
</plugin></pre>
<p>
- This way, the export-goal would be skipped, if you set the property
+ This way, the plugin 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>
--
2.20.1