The plugin was designed with two 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 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.
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>1.0</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>1.0</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.
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:
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>1.0</version>
<executions>
<execution>
<goals>
<goal>export</goal>
</goals>
</execution>
</executions>
<configuration>
<url><![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]></url>
</configuration>
</plugin>
<plugins>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>hibernate4-maven-plugin</artifactId>
<version>1.0</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:
For explanations, see the Documentation of the export-Mojo.
The configuration is gathered in a fix order:
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>1.0</version>
<executions>
<execution>
<goals>
<goal>export</goal>
</goals>
</execution>
</executions>
<configuration>
<password>${my-password-property}</password>
</configuration>
</plugin>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 ;)
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>1.0</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.