From: Kai Moritz Date: Tue, 29 Apr 2014 18:43:15 +0000 (+0200) Subject: Switched documentation to xhtml, to be able to integrate google-pretty-print X-Git-Tag: hibernate4-maven-plugin-1.0.4~2 X-Git-Url: http://juplo.de/gitweb/?p=hibernate4-maven-plugin;a=commitdiff_plain;h=64900890db2575b7a28790c5e4d5f45083ee94b3 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 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/pitfalls.apt b/src/site/apt/pitfalls.apt deleted file mode 100644 index 355e369e..00000000 --- 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 - 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 - - 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 - ------------- - - 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 <<>>. - - But this will break the execution of the <<>>. - 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: - ---------------- - - de.juplo - hibernate4-maven-plugin - ${project.version} - - - - export - - - - - - org.hsqldb - hsqldb - 2.2.8 - - - ---------------- - - 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 <<>>-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 - <<>>. - 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 - - 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 <<>> 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 - <<>> is set to <<>>. If you need it to be always - executed, you can configure that explicitly like this: - ------------- - - de.juplo - hibernate4-maven-plugin - ... - - false - - ------------- - - 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 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/xhtml/pitfalls.xhtml b/src/site/xhtml/pitfalls.xhtml new file mode 100644 index 00000000..50006953 --- /dev/null +++ b/src/site/xhtml/pitfalls.xhtml @@ -0,0 +1,167 @@ + + + + + + +

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

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

+ +