From 0611db682bc69b80d8567bf9316668a1b6161725 Mon Sep 17 00:00:00 2001 From: Kai Moritz 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 | 9 ++- src/site/xhtml/pitfalls.xhtml | 68 ++++++++++------ src/site/xhtml/skip.xhtml | 10 +-- 8 files changed, 124 insertions(+), 58 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 true, the execution is skipped. *

* A skipped execution is signaled via the maven-property - * ${hibernate.export.skipped}. + * ${hibernate.schema.skipped}. *

* 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 @@

- + + 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 @@ -

Configuration through a hibernate.properties-File

Configuration Through A Configuration-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. + hibernate-configuration in a hibernate.properties- or + a hibernate.cfg.xml-file on your classpath or in the + persistence.xml-file of your JPA-configuration, just + like you would do, if you are not using the + hibernate-maven-plugin.

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>

- 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 + drop: +

+<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>

+ A correspondin goal for the command update is missing in this + version, but we are planning to implement it in near feature. +

+ 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 hibernate.properties-file may look like this: +

+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=

+ 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, 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 @@

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 Documentation of the export-Mojo). + (for a full list see the Documentation of the goal create). These are named after the Hibernate JDBC Properties:

@@ -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> +
+ 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. +

Configuration through the plugin-configuration

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 @@

For more explanations, see the - Documentation of the export-Mojo. + Documentation of the goal create.

Configuration-Method-Precedence

@@ -182,7 +227,7 @@
If you are in doubt about where a configuration-value comes from, run - maven with the debug-output enabled: mvn -X hibernate:export + maven with the debug-output enabled: mvn -X hibernate:create and be aware, that maven-properties can be overwitten on the command-line, in your ~/.m2/settings.xml and in a profile.
@@ -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 @@
If you are new to hibernate-maven-plugin, in many cases, the - {Configuration-Method-Precedence} may be the source of configuration - errors. + 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 hibernate:export
+mvn -X compile hibernate:create
(The compile might be necessary, because hibernate-maven-plugin 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 @@

The plugin signals, that the execution was skipped by setting the maven - property $\{hibernate.export.skipped\} to true. + property ${hibernate.schema.skipped} to true. This may be helpful, because other plugins like dbunit-plugin may fail, when the execution is skipped.

- If you need the hibernate-maven-plugin to <never skip execution automatically>, + If you need the hibernate-maven-plugin to never skip execution automatically, you can force it to do so, if you set the parameter force to true:
@@ -33,7 +33,7 @@ </configuration> </plugin>
- Or you may specify -Dhibernate.export.force=true at the command line, + Or you may specify -Dhibernate.schema.force=true at the command line, if you want to force hibernate-maven-plugin only once.
diff --git a/src/site/xhtml/index.xhtml b/src/site/xhtml/index.xhtml index a30e6d62..7a2b02c8 100644 --- a/src/site/xhtml/index.xhtml +++ b/src/site/xhtml/index.xhtml @@ -4,11 +4,11 @@ -
Hibernate 4 Maven Plugin
-
A simple Plugin for generating a Database-Schema from Hibernate 4 Mapping-Annotations
+
Hibernate Maven Plugin
+
A simple Plugin for generating a Database-Schema from Hibernate Mapping-Annotations

The hibernate-maven-plugin is a plugin for generating a database-schema - from your Hibernate-4-Mappings and create or update your database + from your Hibernate-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 @@ -48,7 +48,8 @@ and simple examples of how to use this plugin.
- See hibernate:export and + See hibernate:create, + See hibernate:drop and Plugin Documentation for the full autogenerated documentation. These are mostly configuration-options of the Hibernate-Tools SchemaExport and SchemaUpdate, 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 @@

hibernate-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 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 hibernate.schema.export to + false. This can be achieved with the command-line parameter - -Dhibernate.export.target=SCRIPT or with the following configuration: + -Dhibernate.schema.export=false or with the following + configuration:

<configuration> - <target>SCRIPT</target> + <export>false</export> </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! + the dialect. Hence, the plugin will still fail, if this parameter is also + missing!

Dependency for driver-class XYZ is missing

@@ -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] ------------------------------------------------------------------------ +[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
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 @@

To circumvent this problem, hibernate-maven-plugin signals a skipped - excecution by setting the maven property $\{hibernate.export.skipped\} to + excecution by setting the maven property ${hibernate.schema.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 @@ -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>
The database will not be recreated after a manual drop/clean
@@ -143,8 +161,8 @@ Otherwise the recreation must be forced:

-mvn hibernate:export -Dhibernate.export.force=true
-
The hibernate:export goal is not executed, when tests are skipped
+mvn hibernate:create -Dhibernate.schema.force=true +
The hibernate:create goal is not executed, when tests are skipped

The hibernate-maven-plugin automatically skips its execution, when maven.test.skip is set to true. If you need it to be always @@ -166,7 +184,7 @@ mvn hibernate:export -Dhibernate.export.force=true
I do not want my dependencies to be scanned for hibernate annotations

If you do not want your dependencies to be scanned for hibernate annotations, - you can pass -Dhibernate.export.scan_dependencies=none to maven + you can pass -Dhibernate.schema.scan.dependencies=none to maven or set scanDependencies to none in the configuration of the plugin like this:
@@ -189,7 +207,7 @@ mvn hibernate:export -Dhibernate.export.force=true

- You should consider to upgrade to that version of the plugin. + You should consider to upgrade to the latest version of the plugin.
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 jetty-maven-plugin. - 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.

@@ -23,8 +23,8 @@ 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, + 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 skip to false:

@@ -37,7 +37,7 @@ </configuration> </plugin>

- 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 skip to a custom property. For example:
@@ -51,7 +51,7 @@ </configuration> </plugin>
- 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 foo.bar to true. For example, if you specify -Dfoo.bar=true on the command-line.
-- 2.20.1