Updated documentation hibernate5
authorKai Moritz <kai@juplo.de>
Mon, 7 Mar 2016 15:01:59 +0000 (16:01 +0100)
committerKai Moritz <kai@juplo.de>
Mon, 7 Mar 2016 19:19:30 +0000 (20:19 +0100)
src/main/java/de/juplo/plugins/hibernate/AbstractSchemaMojo.java
src/site/site.xml
src/site/xhtml/configuration.xhtml
src/site/xhtml/debugging.xhtml
src/site/xhtml/force.xhtml
src/site/xhtml/index.xhtml
src/site/xhtml/pitfalls.xhtml
src/site/xhtml/skip.xhtml

index f6e18ea..d4386eb 100644 (file)
@@ -136,7 +136,7 @@ public abstract class AbstractSchemaMojo extends AbstractMojo
    * If set to <code>true</code>, the execution is skipped.
    * <p>
    * A skipped execution is signaled via the maven-property
-   * <code>${hibernate.export.skipped}</code>.
+   * <code>${hibernate.schema.skipped}</code>.
    * <p>
    * The execution is skipped automatically, if no modified or newly added
    * annotated classes are found and the dialect was not changed.
index 7c28ac2..111fb6b 100644 (file)
@@ -3,7 +3,8 @@
   <body>
     <menu>
       <item name="Configuration Examples" href="configuration.html"/>
-      <item name="Parameter Documentation" href="export-mojo.html"/>
+      <item name="Goal: CREATE" href="create-mojo.html"/>
+      <item name="Goal: DROP" href="drop-mojo.html"/>
       <item name="Enable Debug-Output" href="debugging.html"/>
       <item name="Skipping Execution" href="skip.html"/>
       <item name="Force Exceution" href="force.html"/>
index e8c5afd..712bdfb 100644 (file)
@@ -4,13 +4,14 @@
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  </head>
  <body>
-  <h2>Configuration through a hibernate.properties-File</h2>
+  <h2>Configuration Through A Configuration-File</h2>
   <p>
   The most simple way to configure the plugin is, to put all the
-  hibernate-configuration in a <strong>hibernate.properties</strong>-file on your
-  classpath. Put the file in the <code>resources</code>-folder. Maven will put
-  it in the <code>class</code>-folder of your webapp, where it will be picked up
-  by this plugin as well as by Hibernate 4.
+  hibernate-configuration in a <strong>hibernate.properties</strong>- or
+  a <strong>hibernate.cfg.xml</strong>-file on your classpath or in the
+  <strong>persistence.xml</strong>-file of your JPA-configuration, just
+  like you would do, if you are not using the
+  <code>hibernate-maven-plugin</code>.
   </p>
   <p>
   Doing so, the only additionally configuration needed, to activat the plugin
   &lt;executions&gt;
     &lt;execution&gt;
       &lt;goals&gt;
-        &lt;goal&gt;export&lt;/goal&gt;
+        &lt;goal&gt;create&lt;/goal&gt;
       &lt;/goals&gt;
     &lt;/execution&gt;
   &lt;/executions&gt;
 &lt;/plugin&gt;</pre>
   <p>
-  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.
+  This would create the configured database.
+  If you want it to be droped beforehand, you have to add the goal
+  <code>drop</code>:
+  </p>
+  <pre class="prettyprint linenums lang-html">
+&lt;plugin&gt;
+  &lt;groupId&gt;de.juplo&lt;/groupId&gt;
+  &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
+  &lt;version&gt;${project.version}&lt;/version&gt;
+  &lt;executions&gt;
+    &lt;execution&gt;
+      &lt;goals&gt;
+        &lt;goal&gt;drop&lt;/goal&gt;
+        &lt;goal&gt;create&lt;/goal&gt;
+      &lt;/goals&gt;
+    &lt;/execution&gt;
+  &lt;/executions&gt;
+&lt;/plugin&gt;</pre>
+  <p>
+  A correspondin goal for the command <code>update</code> is missing in this
+  version, but we are planning to implement it in near feature.
+  </p>
+  <p>
+  In order to let this configuration work, your configuration file must
+  contain a complete valid configuration for the database, that you want
+  to use.
+  A simple example <code>hibernate.properties</code>-file may look like this:
+  </p>
+  <pre class="prettyprint linenums lang-properties">
+hibernate.dialect=org.hibernate.dialect.H2Dialect
+hibernate.connection.url=jdbc:h2:file:./target/db
+hibernate.connection.driver_class=org.h2.Driver
+hibernate.connection.username=sa
+hibernate.connection.password=</pre>
+  <p>
+  But be aware, that using this configuration-approach 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.
   Because of that,
   <strong>
     you should never fire up this configuration on your production
@@ -51,7 +87,8 @@
   &lt;executions&gt;
     &lt;execution&gt;
       &lt;goals&gt;
-        &lt;goal&gt;export&lt;/goal&gt;
+        &lt;goal&gt;drop&lt;/goal&gt;
+        &lt;goal&gt;create&lt;/goal&gt;
       &lt;/goals&gt;
     &lt;/execution&gt;
   &lt;/executions&gt;
   <p>
   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 <a href="./export-mojo.html">Documentation of the export-Mojo</a>).
+  (for a full list see the <a href="./create-mojo.html">Documentation of the goal create</a>).
   These are named after the
   <a href="http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-hibernatejdbc">Hibernate JDBC Properties</a>:
   </p>
     &lt;executions&gt;
       &lt;execution&gt;
         &lt;goals&gt;
-          &lt;goal&gt;export&lt;/goal&gt;
+          &lt;goal&gt;drop&lt;/goal&gt;
+          &lt;goal&gt;create&lt;/goal&gt;
         &lt;/goals&gt;
       &lt;/execution&gt;
     &lt;/executions&gt;
   &lt;/plugin&gt;
 
 &lt;plugins&gt;</pre>
+  <p>
+  This way, you can reuse the same properties to provide a
+  default-configurationthe, that is build into your application, and
+  overwrite the database-url, that is used during testing to prevent
+  accidential drops of your production database.
+  </p>
   <h2>Configuration through the plugin-configuration</h2>
   <p>
   A third way for configuring the plugin is the plugin-configuration.
   &lt;executions&gt;
     &lt;execution&gt;
       &lt;goals&gt;
-        &lt;goal&gt;export&lt;/goal&gt;
+        &lt;goal&gt;drop&lt;/goal&gt;
+        &lt;goal&gt;create&lt;/goal&gt;
       &lt;/goals&gt;
     &lt;/execution&gt;
   &lt;/executions&gt;
   </p>
   <p>
   For more explanations, see the
-  <a href="./export-mojo.html">Documentation of the export-Mojo</a>.
+  <a href="./create-mojo.html">Documentation of the goal create</a>.
   </p>
   <h2 id="precedence">Configuration-Method-Precedence</h2>
   <p>
   </ol>
   <p>
   If you are in doubt about where a configuration-value comes from, run
-  maven with the <a href="./debugging.html">debug-output</a> enabled: <code>mvn -X hibernate:export</code>
+  maven with the <a href="./debugging.html">debug-output</a> enabled: <code>mvn -X hibernate:create</code>
   and be aware, that maven-properties can be overwitten on the command-line,
   in your <code>~/.m2/settings.xml</code> and in a profile.
   </p>
   &lt;executions&gt;
     &lt;execution&gt;
       &lt;goals&gt;
-        &lt;goal&gt;export&lt;/goal&gt;
+        &lt;goal&gt;drop&lt;/goal&gt;
+        &lt;goal&gt;create&lt;/goal&gt;
       &lt;/goals&gt;
     &lt;/execution&gt;
   &lt;/executions&gt;
index c67d8c0..6271077 100644 (file)
@@ -6,14 +6,14 @@
  <body>
   <p>
   If you are new to <code>hibernate-maven-plugin</code>, in many cases, the
-  {Configuration-Method-Precedence} may be the source of configuration
-  errors.
+  <a href="./configuration.html#precedence">Configuration-Method-Precedence</a>
+  may be the source of configuration errors.
   To solve this problem, you should run maven with the debugging output
   enabled.
   For example, by executing:
   </p>
   <pre class="prettyprint linenums lang-html">
-mvn -X compile hibernate:export</pre>
+mvn -X compile hibernate:create</pre>
   <p>
   (The <code>compile</code> might be necessary, because <code>hibernate-maven-plugin</code>
   has to scan the compiled classes for annotations!)
index cd582db..ecdab5b 100644 (file)
   </p>
   <p>
   The plugin signals, that the execution was skipped by setting the maven
-  property <code>$\{hibernate.export.skipped\}</code> to <code>true</code>.
+  property <code>${hibernate.schema.skipped}</code> to <code>true</code>.
   This may be helpful, because other plugins like
   <a href="http://mojo.codehaus.org/dbunit-maven-plugin/">dbunit-plugin</a>
   <a href="./pitfalls.html#fails">may fail</a>, when the execution is skipped.
   </p>
   <p>
-  If you need the hibernate-maven-plugin to &lt;never skip execution automatically&gt;,
+  If you need the hibernate-maven-plugin to <em>never skip execution automatically</em>,
   you can force it to do so, if you set the parameter <code>force</code> to
   <code>true</code>:
   </p>
@@ -33,7 +33,7 @@
   &lt;/configuration&gt;
 &lt;/plugin&gt;</pre>
   <p>
-  Or you may specify <code>-Dhibernate.export.force=true</code> at the command line,
+  Or you may specify <code>-Dhibernate.schema.force=true</code> at the command line,
   if you want to force hibernate-maven-plugin only once.
   </p>
  </body>
index a30e6d6..6606fd9 100644 (file)
@@ -48,7 +48,8 @@
    and simple examples of how to use this plugin.
    </li>
    <li>
-   See <a href="./export-mojo.html">hibernate:export</a> and
+   See <a href="./create-mojo.html">hibernate:create</a>,
+   See <a href="./drop-mojo.html">hibernate:drop</a> and
    <a href="./plugin-info.html">Plugin Documentation</a> for the full
    autogenerated documentation. These are mostly configuration-options
    of the Hibernate-Tools <code>SchemaExport</code> and <code>SchemaUpdate</code>, that do
index 3967811..d762b3a 100644 (file)
   </p>
   <h2>hibernate-maven-plugin always needs a database-connection</h2>
   <p>
-  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.
+  The default-configuration exports the created schema to the configured
+  database.
+  Therefore, it needs a valid database-connection and fails, if none is
+  available.
+  If you do not need to export the created schema to a database,
+  you can set the property <code>hibernate.schema.export</code> to
+  <code>false</code>.
   This can be achieved with the command-line parameter
-  <code>-Dhibernate.export.target=SCRIPT</code> or with the following configuration:
+  <code>-Dhibernate.schema.export=false</code> or with the following
+  configuration:
   </p>
   <pre class="prettyprint linenums lang-html">
 &lt;configuration&gt;
-  &lt;target&gt;SCRIPT&lt;/target&gt;
+  &lt;export&gt;false&lt;/export&gt;
 &lt;/configuration&gt;</pre>
   <p>
   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!
+  the dialect. Hence, the plugin will still fail, if this parameter is also
+  missing!
   </p>
   <h2>Dependency for driver-class XYZ is missing</h2>
   <p>
 [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]   hibernate.dialect = org.hibernate.dialect.H2Dialect
+[INFO]   hibernate.connection.url = jdbc:h2:file:./db
+[INFO]   hibernate.hbm2dll.create_namespaces = false
+[INFO]   hibernate.connection.driver_class = org.h2.Driver
+[INFO]   hibernate.format_sql = true
+[INFO] HHH000412: Hibernate Core {5.0.2.Final}
+[INFO] HHH000206: hibernate.properties not found
+[INFO] HHH000021: Bytecode provider name : javassist
+[INFO] Adding /home/kai/project/target/classes to the list of roots to scan...
+[INFO] Adding dependencies from scope compile to the list of roots to scan
+[INFO] Adding dependencies from scope org.hibernate:hibernate-core:jar:4.3.0.Final to the list of roots to scan
+[INFO] Adding annotated resource: de.juplo.tests.SimplestMavenHib4Test
 [INFO] ------------------------------------------------------------------------
-[ERROR] BUILD ERROR
+[INFO] BUILD FAILURE
 [INFO] ------------------------------------------------------------------------
-[INFO] org.hsqldb.jdbcDriver
+[INFO] Total time: 1.760s
+[INFO] Finished at: Mon Mar 07 19:06:54 CET 2016
+[INFO] Final Memory: 11M/215M
 [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] ------------------------------------------------------------------------</pre>
+[ERROR] Failed to execute goal de.juplo:hibernate-maven-plugin:${project.version}:drop (default) on project hibernate4-properties-test: Could not open the JDBC-connection: Unable to load class [org.h2.Driver]: Could not load requested class : org.h2.Driver -&gt; [Help 1]
+[ERROR] 
+[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
+[ERROR] Re-run Maven using the -X switch to enable full debug logging.
+[ERROR] 
+[ERROR] For more information about the errors and possible solutions, please read the following articles:
+[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoFailureException</pre>
   <p>
   A quick workaround for this error would be, to delete the runtime-constraint
   for the jdbc-driver-dependency.
@@ -75,7 +92,8 @@
   &lt;executions&gt;
     &lt;execution&gt;
       &lt;goals&gt;
-        &lt;goal&gt;export&lt;/goal&gt;
+        &lt;goal&gt;drop&lt;/goal&gt;
+        &lt;goal&gt;create&lt;/goal&gt;
       &lt;/goals&gt;
     &lt;/execution&gt;
   &lt;/executions&gt;
   </p>
   <p>
   To circumvent this problem, hibernate-maven-plugin signals a skipped
-  excecution by setting the  maven property <code>$\{hibernate.export.skipped\}</code> to
+  excecution by setting the  maven property <code>${hibernate.schema.skipped}</code> to
   <code>true</code>.
   You can configure other plugins to react on this signal.
   For example, the dbunit-plugin can be configured to skip its excecution, if
   &lt;groupId&gt;org.codehaus.mojo&lt;/groupId&gt;
   &lt;artifactId&gt;dbunit-maven-plugin&lt;/artifactId&gt;
   &lt;configuration&gt;
-    &lt;skip&gt;${hibernate.export.skipped}&lt;/skip&gt;
+    &lt;skip&gt;${hibernate.schema.skipped}&lt;/skip&gt;
   &lt;/configuration&gt;
 &lt;/plugin&gt;</pre>
   <h2>The database will not be recreated after a manual drop/clean</h2>
   Otherwise the recreation must be <a href="./force.html">forced</a>:
   </p>
   <pre class="prettyprint">
-mvn hibernate:export -Dhibernate.export.force=true</pre>
-  <h2>The hibernate:export goal is not executed, when tests are skipped</h2>
+mvn hibernate:create -Dhibernate.schema.force=true</pre>
+  <h2>The hibernate:create goal is not executed, when tests are skipped</h2>
   <p>
   The hibernate-maven-plugin automatically skips its execution, when
   <code>maven.test.skip</code> is set to <code>true</code>. If you need it to be always
@@ -166,7 +184,7 @@ mvn hibernate:export -Dhibernate.export.force=true</pre>
   <h2>I do not want my dependencies to be scanned for hibernate annotations</h2>
   <p>
     If you do not want your dependencies to be scanned for hibernate annotations,
-    you can pass <code>-Dhibernate.export.scan_dependencies=none</code> to maven
+    you can pass <code>-Dhibernate.schema.scan.dependencies=none</code> to maven
     or set <code>scanDependencies</code> to <code>none</code> in the configuration
     of the plugin like this:
   </p>
@@ -189,7 +207,7 @@ mvn hibernate:export -Dhibernate.export.force=true</pre>
   </p>
   <p>
     <strong>
-      You should consider to upgrade to that version of the plugin.
+      You should consider to upgrade to the latest version of the plugin.
     </strong>
   </p>
  </body>
index 5f893b8..e25ed0e 100644 (file)
@@ -13,7 +13,7 @@
   the production-database, in order to run other tests, like starting a
   local webserver with the
   <a href="http://wiki.eclipse.org/Jetty/Feature/Jetty_Maven_Plugin">jetty-maven-plugin</a>.
-  If the export-goal would be executed in such a scenario, it might erase the
+  If the drop-goal would be executed in such a scenario, it might erase the
   hole production-database, which is not very desireable.
   </p>
   <p>
@@ -23,8 +23,8 @@
   skipped. Think of it as a build-in security-belt.
   </p>
   <p>
-  If you do not like that, because you need the plugin to always execute the
-  export-goal, even if the tests are skipped you can configure that explicitly,
+  If you do not like that, because you need the plugin to always,
+  even if the tests are skipped you can configure that explicitly,
   by setting the configuration-parameter <code>skip</code> to false:
   </p>
   <pre class="prettyprint linenums lang-html">
@@ -37,7 +37,7 @@
   &lt;/configuration&gt;
 &lt;/plugin&gt;</pre>
   <p>
-  Or, if you want the export-goal to be executed by default and to be skipped
+  Or, if you want the plugin to be executed by default and to be skipped
   if you say so, you can bind the value of the configuration-parameter
   <code>skip</code> to a custom property. For example:
   </p>
@@ -51,7 +51,7 @@
   &lt;/configuration&gt;
 &lt;/plugin&gt;</pre>
   <p>
-  This way, the export-goal would be skipped, if you set the property
+  This way, the plugin would be skipped, if you set the property
   <code>foo.bar</code> to <code>true</code>. For example, if you specify <code>-Dfoo.bar=true</code>
   on the command-line.
   </p>