From: Kai Moritz Date: Wed, 28 Nov 2012 23:11:04 +0000 (+0100) Subject: Reworked documentation (described example-configurations) X-Git-Tag: hibernate4-maven-plugin-1.0~3 X-Git-Url: http://juplo.de/gitweb/?a=commitdiff_plain;h=17b00da14edf0d80c738b82dae9a4b3a1ba21ac7;p=hibernate4-maven-plugin Reworked documentation (described example-configurations) --- 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. diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt index 3b237a2c..3698529b 100644 --- a/src/site/apt/index.apt +++ b/src/site/apt/index.apt @@ -1,26 +1,21 @@ -A simple plugin for generating a database-schema from Hibernate 4 mapping-annotations. +A simple Plugin for generating a Database-Schema from Hibernate 4 Mapping-Annotations. - Hibernate comes with the buildin functionality, to automatically create or - update the database schema. - This functionality is configured in the session-configuraton via the - parameter - (see {{{http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-optional} Hibernate Reference Documentation - Chapter 3.4. Optional configuration properties}}). - But doing so - {{{http://stackoverflow.com/questions/221379/hibernate-hbm2ddl-auto-update-in-production} is not very wise}}, because you can easily corrupt or erase your - production database, if this configuration parameter slips through to your - production environment. - Alternatively, you can - {{{http://stackoverflow.com/questions/835961/how-to-creata-database-schema-using-hibernate} run the tools SchemaExport or SchemaUpdate by hand}}. - But that is not very comfortable and being used to maven you will quickly - long for a plugin, that does that job automatically for you, when you fire - up your test cases. + <> is a plugin for generating a database-schema + from your Hibernate-4-Mappings and create or update your database + accordingly. - In the good old times, there was the - {{{http://mojo.codehaus.org/maven-hibernate3/hibernate3-maven-plugin/} Maven Hibernate3 Plugin}}, that does this for you. - But unfortunatly, this plugin is not compatible with Hibernate 4.x. + The plugin was designed to be easy and safe to use, because it must not + never, never happen, that you blow away your production database when + firering a maven-build of your webapp on your production-machine! + For more information about the insiration 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}}. - Since there does not seem to be any successor for the Maven Hibernate3 Plugin - and {{{http://www.google.de/search?q=hibernate4+maven+plugin} googeling}} - does not help, I decided to write up this simple plugin (inspired by these - two articles I found: {{{http://www.tikalk.com/alm/blog/schema-export-hibernate-4-and-maven} Schema Export with Hibernate 4 and Maven}} and - {{{http://doingenterprise.blogspot.de/2012/05/schema-generation-with-hibernate-4-jpa.html} Schema generation with Hibernate 4, JPA and Maven}}). +Documentation and Examples + + * See {{{./examples.html} Examples}} for Usage-Eplanations and simple + examples of how to use this plugin. + + * See {{{./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. diff --git a/src/site/site.xml b/src/site/site.xml index a50f2c43..3c35c973 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -2,7 +2,8 @@ - + +