X-Git-Url: http://juplo.de/gitweb/?p=hibernate4-maven-plugin;a=blobdiff_plain;f=src%2Fsite%2Fapt%2Fconfiguration.apt;fp=src%2Fsite%2Fapt%2Fconfiguration.apt;h=ea11db0cdff9571f53a3d7ee7ae3a0018b2a0b06;hp=0000000000000000000000000000000000000000;hb=4b507b15b0122ac180e44b8418db8d9143ae9c3a;hpb=65bbbdbaa7df1edcc92a3869122ff06a3895fe57

diff --git a/src/site/apt/configuration.apt b/src/site/apt/configuration.apt
new file mode 100644
index 00000000..ea11db0c
--- /dev/null
+++ b/src/site/apt/configuration.apt
@@ -0,0 +1,222 @@
+Configuration Examples
+
+* Configuration through a hibernate.properties-File
+
+  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>${project.version}</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>${project.version}</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>>>.
+
+* 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}}:
+
+    * <<<hibernate.connection.driver_class>>>
+
+    * <<<hibernate.dialect>>>
+
+    * <<<hibernate.connection.url>>>
+
+    * <<<hibernate.connection.username>>>
+
+    * <<<hibernate.connection.password>>>
+
+  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>${project.version}</version>
+    <executions>
+      <execution>
+        <goals>
+          <goal>export</goal>
+        </goals>
+      </execution>
+    </executions>
+    <configuration>
+      <url><![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]></url>
+    </configuration>
+  </plugin>
+
+<plugins>
+---------------
+
+* Configuration through the plugin-configuration
+
+  A third way for configuring the plugin is the plugin-configuration.
+  The relevant configuration-parameters are:
+
+    * <<<driverClassName>>>
+
+    * <<<hibernateDialect>>>
+
+    * <<<url>>>
+
+    * <<<username>>>
+
+    * <<<password>>>
+
+  The equivalent of the configuration from the last section would look
+  like this:
+
+---------------
+<plugin>
+  <groupId>de.juplo</groupId>
+  <artifactId>hibernate4-maven-plugin</artifactId>
+  <version>${project.version}</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:
+
+    * <<delimiter>> the delimiter used in the generated sql-script
+
+    * <<format>> wether the generated sql-script is formatted, or not
+
+    * <<hibernateProperties>> name of the hibernate-properties-file
+
+    * <<outputFile>> name of the generated sql-script
+
+    * <<target>> create database or generate sql-script or both
+
+    * <<type>> 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]] <<<hibernate.properties>>>
+
+    [[2]] maven-properties
+
+    [[3]] plugin-configuration
+
+  If you are in doubt about where a configuration-value comes from, run
+  maven with the {{{./debugging.html}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>${project.version}</version>
+  <executions>
+    <execution>
+      <goals>
+        <goal>export</goal>
+      </goals>
+    </execution>
+  </executions>
+  <configuration>
+    <password>${my-password-property}</password>
+  </configuration>
+</plugin>
+----------------