+++ /dev/null
-Configuration Examples
-
- 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 {{Debug-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).
-
-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 {{{./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}}:
-
- * <<<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>
----------------
-
- There are some seldom used parameters, that can only be configured throug
- this method:
-
- * <<delimiter>> the delimiter used in the generated sql-script
-
- * <<format>> wether the generated sql-script is formatted, or not
-
- * <<hibernateProperties>> name of the hibernate-properties-file
-
- * <<outputFile>> name of the generated sql-script
-
- * <<target>> create database or generate sql-script or both
-
- * <<type>> create or drop the database or do both or nothing
- (just validate the annotation-configuration)
-
- For explanations, see the
- {{{./export-mojo.html} Documentation of the export-Mojo}}.
-
-{Configuration-Method-Precedence}
-
- The configuration is gathered in a fix order:
-
- [[1]] <<<hibernate.properties>>>
-
- [[2]] maven-properties
-
- [[3]] 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>
-----------------
-
-Enabling {Debug-Output}
-
- 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 ;)
-
-{Force execution}
-
- 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
- {{{http://mojo.codehaus.org/dbunit-maven-plugin/}dbunit-plugin}}
- {{{DBUnit fails}may fail}}, when the execution is skipped.
-
- If you need the hibernate4-maven-plugin to <never skip automatically>
- execution, 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.
-
-Known Pitfalls
-
-* 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 {{{http://mojo.codehaus.org/dbunit-maven-plugin/}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 execution}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>
-------------
projects / hibernate4-maven-plugin / blobdiff