From: Kai Moritz Date: Sun, 11 Jan 2026 11:19:49 +0000 (+0100) Subject: Switched to `maven-hugo-skin` -- MOVE X-Git-Url: http://juplo.de/gitweb/?a=commitdiff_plain;h=646211b83a3ef849fd67aa3992b01780cfcc03c6;p=hibernate-maven-plugin Switched to `maven-hugo-skin` -- MOVE --- diff --git a/src/site/markdown/configuration.md b/src/site/markdown/configuration.md new file mode 100644 index 00000000..e6e738da --- /dev/null +++ b/src/site/markdown/configuration.md @@ -0,0 +1,263 @@ + + + + + + +

Configuration Examples

+

Configuration Through A Configuration-File

+

+ The most simple way to configure the plugin is, to put all the + 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 + is the following entry in the plugins-section of your pom.xml: +

+ 
+<plugin>
+  <groupId>de.juplo</groupId>
+  <artifactId>hibernate-maven-plugin</artifactId>
+  <version>${project.version}</version>
+  <executions>
+    <execution>
+      <goals>
+        <goal>create</goal>
+      </goals>
+    </execution>
+  </executions>
+</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 + system, or your database might be erased! + +

+

+ A better approach is, to specify a different url for testing like in the + following snippet: +

+ 
+<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>
+  <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 goal create). + These are named after the + Hibernate JDBC Properties: +

+ +

+ 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>hibernate-maven-plugin</artifactId>
+    <version>${project.version}</version>
+    <executions>
+      <execution>
+        <goals>
+          <goal>drop</goal>
+          <goal>create</goal>
+        </goals>
+      </execution>
+    </executions>
+    <configuration>
+      <url><![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]></url>
+    </configuration>
+  </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. + The relevant configuration-parameters are: +

+ +

+ The equivalent of the configuration from the last section would look + like this: +

+ 
+<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>
+  <configuration>
+    <driver>org.hsqldb.jdbcDriver</driver>
+    <dialect>org.hibernate.dialect.HSQLDialect</dialect>
+    <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 goal create. +

+

Configuration-Method-Precedence

+

+ The configuration is gathered in a fix order: +

+
    +
  1. hibernate.properties
    2. +
  2. hibernate.cfg.xml
    3. +
  3. persistence.xml
    4. +
  4. maven-properties
    5. +
  5. plugin-configuration
    6. +
+

+ If you are in doubt about where a configuration-value comes from, run + 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. +

+

+ 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 need to overwrite plugin-configuration-values with + maven-properties, you can use maven-properties in the plugin-configuration: +

+ 
+<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>
+  <configuration>
+    <password>${my-password-property}</password>
+  </configuration>
+</plugin>
+ + diff --git a/src/site/markdown/debugging.md b/src/site/markdown/debugging.md new file mode 100644 index 00000000..2fab3254 --- /dev/null +++ b/src/site/markdown/debugging.md @@ -0,0 +1,31 @@ + + + + + + +

Enable Debugging-Output

+

+ If you are new to hibernate-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 hibernate:create
+

+ (The compile might be necessary, because hibernate-maven-plugin + has to scan the compiled classes for annotations!) +

+

+ Unlike the majority of the maven-plugins, hibernate-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: hibernate-maven-plugin tends to be very chatty ;) +

+ + diff --git a/src/site/markdown/force.md b/src/site/markdown/force.md new file mode 100644 index 00000000..ee3586f7 --- /dev/null +++ b/src/site/markdown/force.md @@ -0,0 +1,42 @@ + + + + + + +

Force Execution

+

+ The hibernate-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 SQL-generation — and more + important in this respect — the execution of the generated SQL, + to speed up the development cycle. +

+

+ The plugin signals, that the execution was skipped by setting the maven + 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, + you can force it to do so, if you set the parameter force to + true: +

+ 
+<plugin>
+  <groupId>de.juplo</groupId>
+  <artifactId>hibernate-maven-plugin</artifactId>
+  <version>${project.version}</version>
+  <configuration>
+    <force>true</force>
+  </configuration>
+</plugin>
+

+ 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/markdown/index.md b/src/site/markdown/index.md new file mode 100644 index 00000000..57cac9b6 --- /dev/null +++ b/src/site/markdown/index.md @@ -0,0 +1,76 @@ + + + + + + +

${project.name}

+

${project.description}

+

+ The hibernate-maven-plugin is a plugin for generating a database-schema + 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 + dbunit-maven-plugin. +

+

+ The plugin was designed with three main goals in mind: +

+ +

+ 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 + hibernate-maven-plugin only executes the generated SQL, if the mapping + or the configuration has changed (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 hibernate-maven-plugin. +

+

Documentation

+ +

Releases

+ + + diff --git a/src/site/markdown/issue-tracking.md b/src/site/markdown/issue-tracking.md new file mode 100644 index 00000000..40e609d8 --- /dev/null +++ b/src/site/markdown/issue-tracking.md @@ -0,0 +1,14 @@ + + + + + + +

Issue Tracking

+ 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/markdown/mail-lists.md b/src/site/markdown/mail-lists.md new file mode 100644 index 00000000..3dbb7330 --- /dev/null +++ b/src/site/markdown/mail-lists.md @@ -0,0 +1,14 @@ + + + + + + +

Mailing Lists

+ 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/markdown/pitfalls.md b/src/site/markdown/pitfalls.md new file mode 100644 index 00000000..07438808 --- /dev/null +++ b/src/site/markdown/pitfalls.md @@ -0,0 +1,251 @@ + + + + + + +

Known Pitfalls (FAQ)

+

Annotated classes in dependencies are not found.

+

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

+

hibernate-maven-plugin always needs a database-connection

+

+ The default-configuration executes the created SQL. + Therefore, it needs a valid database-connection and fails, if none is + available. + If you do not need the generated SQL to be executed automatically, + you can set the property hibernate.schema.execute to + false. + This can be achieved with the command-line parameter + -Dhibernate.schema.execute=false or with the following + configuration: +

+ 
+<configuration>
+  <execute>false</execute>
+</configuration>
+

+ But even when no database is to be created, hibernate always needs to know + the dialect. Hence, the plugin will still fail, if this parameter is also + 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 hibernate-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.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] ------------------------------------------------------------------------
+[INFO] BUILD FAILURE
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 1.760s
+[INFO] Finished at: Mon Mar 07 19:06:54 CET 2016
+[INFO] Final Memory: 11M/215M
+[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. +

+

+ A much cleaner way is, to (additionally) ad the dependency, to the + plugin-definition: +

+ 
+<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>
+  <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 hibernate was skipped because nothing has changed

+

+ If hibernate-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 hibernate-maven-plugin has + skipped its excecution. +

+

+ A quick fix to this problem is, to force + hibernate-maven-plugin to generate and execute the SQL 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, hibernate-maven-plugin signals a skipped + 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 + hibernate-maven-plugin was skipped like this: +

+ 
+<plugin>
+  <groupId>org.codehaus.mojo</groupId>
+  <artifactId>dbunit-maven-plugin</artifactId>
+  <configuration>
+    <skip>${hibernate.schema.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 hibernate-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 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 + executed, you can configure that explicitly like this: +

+ 
+<plugin>
+  <groupId>de.juplo</groupId>
+  <artifactId>hibernate-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... +

+

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.schema.scan.dependencies=none to maven + or set scanDependencies to none in the configuration + of the plugin like this: +

+ 
+<plugin>
+  <groupId>de.juplo</groupId>
+  <artifactId>hibernate-maven-plugin</artifactId>
+  ...
+  <configuration>
+    <scanDependencies>none</scanDependencies>
+  </configuration>
+</plugin>
+

No annotated classes found

+

+ If you are working under Windows and get the error-message + No annotated classes found in directory C:\projects\X Y Z\path-to-project\target\classes, + but you are really sure, that there are annotated classes in that + directory, you are expiriencing a bug, in the scannotation-library, that + was closed in version 1.1.0 of the hibernate-maven-plugin. +

+

+ + You should consider to upgrade to the latest version of the plugin. + +

+

If two goals are specified, the second one is always skipped

+

+ If you specify two goals, for example drop and + create, each goal has to be specified in its own + execution, so that you can specify two different + output-files for the two goals. + Otherwise, both goals will use the same output-file and the goal, that + is run second, will always skip, becaus it will find, that the output + file already exists and conclude, that its work was already done in a + prior run. +

+

+ Example configuration for two goals: +

+ 
+<executions>
+  <execution>
+    <id>Create Drop-Schema</id>
+    <phase>test-compile</phase>
+    <goals>
+      <goal>drop</goal>
+    </goals>
+    <configuration>
+      <outputFile>db-schema/drop-schema.ddl</outputFile>
+    </configuration>
+  </execution>
+  <execution>
+    <id>Create Create-Schema</id>
+    <phase>test-compile</phase>
+    <goals>
+      <goal>create</goal>
+    </goals>
+    <configuration>
+      <outputFile>db-schema/create-schema.ddl</outputFile>
+    </configuration>
+  </execution>
+</executions>
+ + diff --git a/src/site/markdown/skip.md b/src/site/markdown/skip.md new file mode 100644 index 00000000..9b570c9f --- /dev/null +++ b/src/site/markdown/skip.md @@ -0,0 +1,60 @@ + + + + + + +

Skipping Execution

+

+ In most use-cases, the hibernate-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 drop-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 + hibernate-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, + 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>hibernate-maven-plugin</artifactId>
+  ...
+  <configuration>
+    <skip>false</skip>
+  </configuration>
+</plugin>
+

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

+ 
+<plugin>
+  <groupId>de.juplo</groupId>
+  <artifactId>hibernate-maven-plugin</artifactId>
+  ...
+  <configuration>
+    <skip>${foo.bar}</skip>
+  </configuration>
+</plugin>
+

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

+ + diff --git a/src/site/xhtml/configuration.xhtml b/src/site/xhtml/configuration.xhtml deleted file mode 100644 index e6e738da..00000000 --- a/src/site/xhtml/configuration.xhtml +++ /dev/null @@ -1,263 +0,0 @@ - - - - - - -

Configuration Examples

-

Configuration Through A Configuration-File

-

- The most simple way to configure the plugin is, to put all the - 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 - is the following entry in the plugins-section of your pom.xml: -

- 
-<plugin>
-  <groupId>de.juplo</groupId>
-  <artifactId>hibernate-maven-plugin</artifactId>
-  <version>${project.version}</version>
-  <executions>
-    <execution>
-      <goals>
-        <goal>create</goal>
-      </goals>
-    </execution>
-  </executions>
-</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 - system, or your database might be erased! - -

-

- A better approach is, to specify a different url for testing like in the - following snippet: -

- 
-<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>
-  <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 goal create). - These are named after the - Hibernate JDBC Properties: -

- -

- 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>hibernate-maven-plugin</artifactId>
-    <version>${project.version}</version>
-    <executions>
-      <execution>
-        <goals>
-          <goal>drop</goal>
-          <goal>create</goal>
-        </goals>
-      </execution>
-    </executions>
-    <configuration>
-      <url><![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]></url>
-    </configuration>
-  </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. - The relevant configuration-parameters are: -

- -

- The equivalent of the configuration from the last section would look - like this: -

- 
-<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>
-  <configuration>
-    <driver>org.hsqldb.jdbcDriver</driver>
-    <dialect>org.hibernate.dialect.HSQLDialect</dialect>
-    <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 goal create. -

-

Configuration-Method-Precedence

-

- The configuration is gathered in a fix order: -

-
    -
  1. hibernate.properties
    2. -
  2. hibernate.cfg.xml
    3. -
  3. persistence.xml
    4. -
  4. maven-properties
    5. -
  5. plugin-configuration
    6. -
-

- If you are in doubt about where a configuration-value comes from, run - 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. -

-

- 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 need to overwrite plugin-configuration-values with - maven-properties, you can use maven-properties in the plugin-configuration: -

- 
-<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>
-  <configuration>
-    <password>${my-password-property}</password>
-  </configuration>
-</plugin>
- - diff --git a/src/site/xhtml/debugging.xhtml b/src/site/xhtml/debugging.xhtml deleted file mode 100644 index 2fab3254..00000000 --- a/src/site/xhtml/debugging.xhtml +++ /dev/null @@ -1,31 +0,0 @@ - - - - - - -

Enable Debugging-Output

-

- If you are new to hibernate-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 hibernate:create
-

- (The compile might be necessary, because hibernate-maven-plugin - has to scan the compiled classes for annotations!) -

-

- Unlike the majority of the maven-plugins, hibernate-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: hibernate-maven-plugin tends to be very chatty ;) -

- - diff --git a/src/site/xhtml/force.xhtml b/src/site/xhtml/force.xhtml deleted file mode 100644 index ee3586f7..00000000 --- a/src/site/xhtml/force.xhtml +++ /dev/null @@ -1,42 +0,0 @@ - - - - - - -

Force Execution

-

- The hibernate-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 SQL-generation — and more - important in this respect — the execution of the generated SQL, - to speed up the development cycle. -

-

- The plugin signals, that the execution was skipped by setting the maven - 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, - you can force it to do so, if you set the parameter force to - true: -

- 
-<plugin>
-  <groupId>de.juplo</groupId>
-  <artifactId>hibernate-maven-plugin</artifactId>
-  <version>${project.version}</version>
-  <configuration>
-    <force>true</force>
-  </configuration>
-</plugin>
-

- 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 deleted file mode 100644 index 57cac9b6..00000000 --- a/src/site/xhtml/index.xhtml +++ /dev/null @@ -1,76 +0,0 @@ - - - - - - -

${project.name}

-

${project.description}

-

- The hibernate-maven-plugin is a plugin for generating a database-schema - 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 - dbunit-maven-plugin. -

-

- The plugin was designed with three main goals in mind: -

- -

- 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 - hibernate-maven-plugin only executes the generated SQL, if the mapping - or the configuration has changed (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 hibernate-maven-plugin. -

-

Documentation

- -

Releases

- - - diff --git a/src/site/xhtml/issue-tracking.xhtml b/src/site/xhtml/issue-tracking.xhtml deleted file mode 100644 index 40e609d8..00000000 --- a/src/site/xhtml/issue-tracking.xhtml +++ /dev/null @@ -1,14 +0,0 @@ - - - - - - -

Issue Tracking

- 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 deleted file mode 100644 index 3dbb7330..00000000 --- a/src/site/xhtml/mail-lists.xhtml +++ /dev/null @@ -1,14 +0,0 @@ - - - - - - -

Mailing Lists

- 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 deleted file mode 100644 index 07438808..00000000 --- a/src/site/xhtml/pitfalls.xhtml +++ /dev/null @@ -1,251 +0,0 @@ - - - - - - -

Known Pitfalls (FAQ)

-

Annotated classes in dependencies are not found.

-

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

-

hibernate-maven-plugin always needs a database-connection

-

- The default-configuration executes the created SQL. - Therefore, it needs a valid database-connection and fails, if none is - available. - If you do not need the generated SQL to be executed automatically, - you can set the property hibernate.schema.execute to - false. - This can be achieved with the command-line parameter - -Dhibernate.schema.execute=false or with the following - configuration: -

- 
-<configuration>
-  <execute>false</execute>
-</configuration>
-

- But even when no database is to be created, hibernate always needs to know - the dialect. Hence, the plugin will still fail, if this parameter is also - 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 hibernate-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.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] ------------------------------------------------------------------------
-[INFO] BUILD FAILURE
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 1.760s
-[INFO] Finished at: Mon Mar 07 19:06:54 CET 2016
-[INFO] Final Memory: 11M/215M
-[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. -

-

- A much cleaner way is, to (additionally) ad the dependency, to the - plugin-definition: -

- 
-<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>
-  <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 hibernate was skipped because nothing has changed

-

- If hibernate-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 hibernate-maven-plugin has - skipped its excecution. -

-

- A quick fix to this problem is, to force - hibernate-maven-plugin to generate and execute the SQL 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, hibernate-maven-plugin signals a skipped - 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 - hibernate-maven-plugin was skipped like this: -

- 
-<plugin>
-  <groupId>org.codehaus.mojo</groupId>
-  <artifactId>dbunit-maven-plugin</artifactId>
-  <configuration>
-    <skip>${hibernate.schema.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 hibernate-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 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 - executed, you can configure that explicitly like this: -

- 
-<plugin>
-  <groupId>de.juplo</groupId>
-  <artifactId>hibernate-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... -

-

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.schema.scan.dependencies=none to maven - or set scanDependencies to none in the configuration - of the plugin like this: -

- 
-<plugin>
-  <groupId>de.juplo</groupId>
-  <artifactId>hibernate-maven-plugin</artifactId>
-  ...
-  <configuration>
-    <scanDependencies>none</scanDependencies>
-  </configuration>
-</plugin>
-

No annotated classes found

-

- If you are working under Windows and get the error-message - No annotated classes found in directory C:\projects\X Y Z\path-to-project\target\classes, - but you are really sure, that there are annotated classes in that - directory, you are expiriencing a bug, in the scannotation-library, that - was closed in version 1.1.0 of the hibernate-maven-plugin. -

-

- - You should consider to upgrade to the latest version of the plugin. - -

-

If two goals are specified, the second one is always skipped

-

- If you specify two goals, for example drop and - create, each goal has to be specified in its own - execution, so that you can specify two different - output-files for the two goals. - Otherwise, both goals will use the same output-file and the goal, that - is run second, will always skip, becaus it will find, that the output - file already exists and conclude, that its work was already done in a - prior run. -

-

- Example configuration for two goals: -

- 
-<executions>
-  <execution>
-    <id>Create Drop-Schema</id>
-    <phase>test-compile</phase>
-    <goals>
-      <goal>drop</goal>
-    </goals>
-    <configuration>
-      <outputFile>db-schema/drop-schema.ddl</outputFile>
-    </configuration>
-  </execution>
-  <execution>
-    <id>Create Create-Schema</id>
-    <phase>test-compile</phase>
-    <goals>
-      <goal>create</goal>
-    </goals>
-    <configuration>
-      <outputFile>db-schema/create-schema.ddl</outputFile>
-    </configuration>
-  </execution>
-</executions>
- - diff --git a/src/site/xhtml/skip.xhtml b/src/site/xhtml/skip.xhtml deleted file mode 100644 index 9b570c9f..00000000 --- a/src/site/xhtml/skip.xhtml +++ /dev/null @@ -1,60 +0,0 @@ - - - - - - -

Skipping Execution

-

- In most use-cases, the hibernate-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 drop-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 - hibernate-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, - 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>hibernate-maven-plugin</artifactId>
-  ...
-  <configuration>
-    <skip>false</skip>
-  </configuration>
-</plugin>
-

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

- 
-<plugin>
-  <groupId>de.juplo</groupId>
-  <artifactId>hibernate-maven-plugin</artifactId>
-  ...
-  <configuration>
-    <skip>${foo.bar}</skip>
-  </configuration>
-</plugin>
-

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

- -