X-Git-Url: https://juplo.de/gitweb/?p=hibernate4-maven-plugin;a=blobdiff_plain;f=src%2Fsite%2Fapt%2Fexamples.apt;fp=src%2Fsite%2Fapt%2Fexamples.apt;h=da04a2517b5e4e437b2b3dec5e2550b8039f97ee;hp=0000000000000000000000000000000000000000;hb=17b00da14edf0d80c738b82dae9a4b3a1ba21ac7;hpb=d8f4466a2342587009406aae4f2a7023bc11f5ea diff --git a/src/site/apt/examples.apt b/src/site/apt/examples.apt new file mode 100644 index 00000000..da04a251 --- /dev/null +++ b/src/site/apt/examples.apt @@ -0,0 +1,323 @@ +Configuration Examples + + The plugin was designed with two main goals in mind: + + * It should be easy to use. + + * It should be maximal unlikely, to erase a producation-database by + accident. + + 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 <<>>. + + 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. + +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 + 1.0-SNAPSHOT + + + + 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 + 1.0-SNAPSHOT + + + + 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 + 1.0-SNAPSHOT + + + + 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 + 1.0-SNAPSHOT + + + + export + + + + + org.hsqldb.jdbcDriver + org.hibernate.dialect.HSQLDialect + + sa + + + +--------------- + + There are some seldom used parameters, that can only be configured throug + this method: + + * <> the delimiter used in the generated sql-script + + * <> wether the generated sql-script is formatted, or not + + * <> name of the hibernate-properties-file + + * <> name of the generated sql-script + + * <> create database or generate sql-script or both + + * <> 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]] <<>> + + [[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: <<>> + 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 + 1.0-SNAPSHOT + + + + export + + + + + ${my-password-property} + + +---------------- + +Enabling {Debug-Output} + + 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 ;) + +Known Pitfalls + + 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 + 1.0-SNAPSHOT + + + + 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.