X-Git-Url: http://juplo.de/gitweb/?p=hibernate4-maven-plugin;a=blobdiff_plain;f=src%2Fsite%2Fapt%2Fpitfalls.apt;fp=src%2Fsite%2Fapt%2Fpitfalls.apt;h=0000000000000000000000000000000000000000;hp=355e369ecdc73040d68c921aa8deae7f51495049;hb=64900890db2575b7a28790c5e4d5f45083ee94b3;hpb=bd78c276663790bf7a3f121db85a0d62c64ce38c
diff --git a/src/site/apt/pitfalls.apt b/src/site/apt/pitfalls.apt
deleted file mode 100644
index 355e369e..00000000
--- a/src/site/apt/pitfalls.apt
+++ /dev/null
@@ -1,169 +0,0 @@
- ---
- Known Pitfalls
- ---
- Kai Moritz
- ---
-
-Annotated classes in dependencies are not found.
-
- hibernate4-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.
-
-hibernate4-maven-plugin always needs a database-connection
-
- The default-configuration uses the EXPORT-target of the SchemaExport-Tool.
- If you do not need to create a database with the evaluated schema, you can
- use the NONE- or the SCRIPT-target.
- This can be achieved with the command-line parameter
- <<<-Dhibernate.export.target=SCRIPT>>> or with the following configuration:
-
-------------
-
- SCRIPT
-
-------------
-
- But even when no database is to be created, hibernate always needs to know
- the dialect. Hence, the plugin will fail if this parameter is 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 <<>>.
-
- 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
- ${project.version}
-
-
-
- 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.
-
-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 <<>>-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.html}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
- <<>>.
- 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:
-
-------------
-
- org.codehaus.mojo
- dbunit-maven-plugin
-
- ${hibernate.export.skipped}
-
-
-------------
-
-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 hibernate4-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 <<>> for cleanup, this will not happen.
- Otherwise the recreation must be {{{./force.html}forced}}:
-
--------------
-mvn hibernate4:export -Dhibernate.export.force=true
--------------
-
-The hibernate4:export goal is not executed, when tests are skipped
-
- The hibernate4-maven-plugin automatically skips its execution, when
- <<>> is set to <<>>. If you need it to be always
- executed, you can configure that explicitly like this:
-
-------------
-
- de.juplo
- hibernate4-maven-plugin
- ...
-
- false
-
-
-------------
-
- Background-information for this design-decission can be found on the extra
- page {{{./skip.html}To skip or not to skip: that is the question}}...