From 64900890db2575b7a28790c5e4d5f45083ee94b3 Mon Sep 17 00:00:00 2001 From: Kai Moritz Date: Tue, 29 Apr 2014 20:43:15 +0200 Subject: [PATCH] Switched documentation to xhtml, to be able to integrate google-pretty-print --- src/site/apt/configuration.apt | 214 ------------------ src/site/apt/debugging.apt | 25 -- src/site/apt/force.apt | 35 --- src/site/apt/index.apt | 59 ----- src/site/apt/issue-tracking.apt | 11 - src/site/apt/mail-lists.apt | 10 - src/site/apt/skip.apt | 55 ----- src/site/site.xml | 1 + src/site/xhtml/configuration.xhtml | 213 +++++++++++++++++ src/site/xhtml/debugging.xhtml | 30 +++ src/site/xhtml/force.xhtml | 40 ++++ src/site/xhtml/index.xhtml | 68 ++++++ src/site/xhtml/issue-tracking.xhtml | 13 ++ src/site/xhtml/mail-lists.xhtml | 13 ++ .../pitfalls.apt => xhtml/pitfalls.xhtml} | 206 +++++++++-------- src/site/xhtml/skip.xhtml | 59 +++++ 16 files changed, 539 insertions(+), 513 deletions(-) delete mode 100644 src/site/apt/configuration.apt delete mode 100644 src/site/apt/debugging.apt delete mode 100644 src/site/apt/force.apt delete mode 100644 src/site/apt/index.apt delete mode 100644 src/site/apt/issue-tracking.apt delete mode 100644 src/site/apt/mail-lists.apt delete mode 100644 src/site/apt/skip.apt create mode 100644 src/site/xhtml/configuration.xhtml create mode 100644 src/site/xhtml/debugging.xhtml create mode 100644 src/site/xhtml/force.xhtml create mode 100644 src/site/xhtml/index.xhtml create mode 100644 src/site/xhtml/issue-tracking.xhtml create mode 100644 src/site/xhtml/mail-lists.xhtml rename src/site/{apt/pitfalls.apt => xhtml/pitfalls.xhtml} (53%) create mode 100644 src/site/xhtml/skip.xhtml diff --git a/src/site/apt/configuration.apt b/src/site/apt/configuration.apt deleted file mode 100644 index 98fad3bc..00000000 --- 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 <>-file on your - classpath. Put the file in the <<>>-folder. Maven will put - it in the <<>>-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 <<>>-section of your <<>>: - ---------------- - - de.juplo - hibernate4-maven-plugin - ${project.version} - - - - export - - - - ---------------- - - 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. - <<>> - - Hence, you should specify a different url for testing like in the - following snippet: - ---------------- - - de.juplo - hibernate4-maven-plugin - ${project.version} - - - - export - - - - - - - ---------------- - - Configuration properties, that are set in the <<>>-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 <<>>. - -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}}: - - * <<>> - - * <<>> - - * <<>> - - * <<>> - - * <<>> - - So, instead of writing the hibernate-configuration in the properties-file, - like above, you could put it in the <<>>-section of your - <<>>. - - 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): - ---------------- - - org.hsqldb.jdbcDriver - org.hibernate.dialect.HSQLDialect - - sa - - - -... - - - - ... - - - de.juplo - hibernate4-maven-plugin - ${project.version} - - - - export - - - - - - - - - ---------------- - -Configuration through the plugin-configuration - - A third way for configuring the plugin is the plugin-configuration. - The relevant configuration-parameters are: - - * <<>> - - * <<>> - - * <<>> - - * <<>> - - * <<>> - - The equivalent of the configuration from the last section would look - like this: - ---------------- - - de.juplo - hibernate4-maven-plugin - ${project.version} - - - - export - - - - - org.hsqldb.jdbcDriver - org.hibernate.dialect.HSQLDialect - - sa - - - ---------------- - - The parameter <> (name of the hibernate-properties-file - to use, defaults to <>) 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]] <<>> - - [[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: <<>> - 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: - ----------------- - - de.juplo - hibernate4-maven-plugin - ${project.version} - - - - export - - - - - ${my-password-property} - - ----------------- diff --git a/src/site/apt/debugging.apt b/src/site/apt/debugging.apt deleted file mode 100644 index 37e81186..00000000 --- a/src/site/apt/debugging.apt +++ /dev/null @@ -1,25 +0,0 @@ - --- - Enabling Debug-Output - --- - Kai Moritz - --- - - If you are new to <<>>, 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 <<>> might be necessary, because <<>> - has to scan the compiled classes for annotations!) - - Unlike the majority of the maven-plugins, <<>> 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! - - <> <<>> tends to be very chatty ;) diff --git a/src/site/apt/force.apt b/src/site/apt/force.apt deleted file mode 100644 index bff87d87..00000000 --- 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 <<>>. - 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 , - you can force it to do so, if you set the parameter <<>> to - <<>>: - ----------------- - - de.juplo - hibernate4-maven-plugin - ${project.version} - - true - - ----------------- - - 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 index 76af6732..00000000 --- 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 - --- - - <> 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 <<>>. - - 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 <<>> and <<>>, 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 index 42292e1a..00000000 --- a/src/site/apt/issue-tracking.apt +++ /dev/null @@ -1,11 +0,0 @@ - --- - Issue Tracking - --- - Kai Moritz - ---- - - <> - - 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 index e8c17ec5..00000000 --- a/src/site/apt/mail-lists.apt +++ /dev/null @@ -1,10 +0,0 @@ - --- - Mailing Lists - --- - Kai Moritz - --- - - <> - - Please send your bug-reports, questions or feature-requests directly - to the developer. diff --git a/src/site/apt/skip.apt b/src/site/apt/skip.apt deleted file mode 100644 index 676a7def..00000000 --- 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 <<>> defaults to the value - of the proptery <<>>. 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 <<>> to false: - ------------- - - de.juplo - hibernate4-maven-plugin - ... - - false - - ------------- - - 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 - <<>> to a custom property. For example: - ------------- - - de.juplo - hibernate4-maven-plugin - ... - - ${foo.bar} - - ------------- - - This way, the export-goal would be skipped, if you set the property - <<>> to <<>>. 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 f3e19969..5399d177 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -14,6 +14,7 @@ de.juplo juplo-maven-skin + 1.0.7 diff --git a/src/site/xhtml/configuration.xhtml b/src/site/xhtml/configuration.xhtml new file mode 100644 index 00000000..bfaf6fec --- /dev/null +++ b/src/site/xhtml/configuration.xhtml @@ -0,0 +1,213 @@ + + + + + + +

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 Documentation of the export-Mojo). + These are named after the + 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 + Documentation of the export-Mojo. +

Configuration-Method-Precedence

+ The configuration is gathered in a fix order: +

hibernate.properties
maven-properties
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>${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/xhtml/debugging.xhtml b/src/site/xhtml/debugging.xhtml new file mode 100644 index 00000000..8f91f3f9 --- /dev/null +++ b/src/site/xhtml/debugging.xhtml @@ -0,0 +1,30 @@ + + + + + + +

+ 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/xhtml/force.xhtml b/src/site/xhtml/force.xhtml new file mode 100644 index 00000000..0a94070e --- /dev/null +++ b/src/site/xhtml/force.xhtml @@ -0,0 +1,40 @@ + + + + + + +

+ 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 + dbunit-plugin + 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/xhtml/index.xhtml b/src/site/xhtml/index.xhtml new file mode 100644 index 00000000..ef7de69c --- /dev/null +++ b/src/site/xhtml/index.xhtml @@ -0,0 +1,68 @@ + + + + + + +

Hibernate 4 Maven Plugin

A simple Plugin for generating a Database-Schema from Hibernate 4 Mapping-Annotations

+ The 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 + 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 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, + read our blog-article about the hibernate4-maven-plugin. +

Documentation

+ See Configuration Examples for Usage-Explanations + and simple examples of how to use this plugin. +
+ See hibernate4:export and + 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

current version
${project.version} (this version)
1.0.3
1.0.2
1.0.1
1.0

+ + diff --git a/src/site/xhtml/issue-tracking.xhtml b/src/site/xhtml/issue-tracking.xhtml new file mode 100644 index 00000000..f7e68598 --- /dev/null +++ b/src/site/xhtml/issue-tracking.xhtml @@ -0,0 +1,13 @@ + + + + + + + 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/xhtml/mail-lists.xhtml b/src/site/xhtml/mail-lists.xhtml new file mode 100644 index 00000000..ff8d7f2b --- /dev/null +++ b/src/site/xhtml/mail-lists.xhtml @@ -0,0 +1,13 @@ + + + + + + + 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/xhtml/pitfalls.xhtml similarity index 53% rename from src/site/apt/pitfalls.apt rename to src/site/xhtml/pitfalls.xhtml index 355e369e..50006953 100644 --- a/src/site/apt/pitfalls.apt +++ b/src/site/xhtml/pitfalls.xhtml @@ -1,46 +1,46 @@ - --- - Known Pitfalls - --- - Kai Moritz - --- - -Annotated classes in dependencies are not found. - + + + + + + +

Annotated classes in dependencies are not found.

hibernate4-maven-plugin by default scans dependencies in the scope compile. 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 - +

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

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 <<>>. - - But this will break the execution of the <<>>. + 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 = 
@@ -58,76 +58,75 @@ Dependency for driver-class XYZ is missing
 [INFO] Total time: 2 seconds
 [INFO] Finished at: Thu Nov 29 11:31:14 CET 2012
 [INFO] Final Memory: 32M/342M
-[INFO] ------------------------------------------------------------------------
----------------
-
+[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: - ---------------- - - de.juplo - hibernate4-maven-plugin - ${project.version} - - - - export - - - - - - org.hsqldb - hsqldb - 2.2.8 - - - ---------------- - +

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

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 <<>>-operation may fail because of foreign-key-constraints, + with the help of the 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}} +

+ A quick fix to this problem is, to 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 - <<>>. + 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: - ------------- - - org.codehaus.mojo - dbunit-maven-plugin - - ${hibernate.export.skipped} - - ------------- - -The database will not be recreated after a manual drop/clean - +

+<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. @@ -135,35 +134,34 @@ The database will not be recreated after a manual drop/clean 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 <<>> 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
-
+[INFO] Skipping schema generation!

+ If one always uses mvn clean for cleanup, this will not happen. + Otherwise the recreation must be 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 - <<>> is set to <<>>. If you need it to be always + maven.test.skip is set to true. If you need it to be always executed, you can configure that explicitly like this: - ------------- - - de.juplo - hibernate4-maven-plugin +

+>plugin<
+  <groupId>de.juplo</groupId>
+  <artifactId>hibernate4-maven-plugin</artifactId>
   ...
-  
-    false
-  
-
-------------
-
+  <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}}... + page To skip or not to skip: that is the question... +

+ + diff --git a/src/site/xhtml/skip.xhtml b/src/site/xhtml/skip.xhtml new file mode 100644 index 00000000..51a20af7 --- /dev/null +++ b/src/site/xhtml/skip.xhtml @@ -0,0 +1,59 @@ + + + + + + +

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

+ + -- 2.20.1