juplo.de Git - hibernate4-maven-plugin/blob - src/site/apt/configuration.apt

   1   ---
   2   Configuration Examples
   3   ---
   4   Kai Moritz
   5   ---
   6
   7 Configuration through a hibernate.properties-File
   8
   9   The most simple way to configure the plugin is, to put all the
  10   hibernate-configuration in a <<hibernate.properties>>-file on your
  11   classpath. Put the file in the <<<resources>>>-folder. Maven will put
  12   it in the <<<class>>>-folder of your webapp, where it will be picked up
  13   by this plugin as well as by Hibernate 4.
  14
  15   Doing so, the only additionally configuration needed, to activat the plugin
  16   is the following entry in the <<<plugins>>>-section of your <<<pom.xml>>>:
  17
  18 ---------------
  19 <plugin>
  20   <groupId>de.juplo</groupId>
  21   <artifactId>hibernate4-maven-plugin</artifactId>
  22   <version>${project.version}</version>
  23   <executions>
  24     <execution>
  25       <goals>
  26         <goal>export</goal>
  27       </goals>
  28     </execution>
  29   </executions>
  30 </plugin>
  31 ---------------
  32
  33   But be aware, that in this case the database-url, that is
  34   build in the application is the same that is used while testing, where
  35   the database is droped and recreated by the plugin.
  36   <<<So, you should never fire up this configuration on your production
  37   system, or your database might be erased!>>>
  38
  39   Hence, you should specify a different url for testing like in the
  40   following snippet:
  41
  42 ---------------
  43 <plugin>
  44   <groupId>de.juplo</groupId>
  45   <artifactId>hibernate4-maven-plugin</artifactId>
  46   <version>${project.version}</version>
  47   <executions>
  48     <execution>
  49       <goals>
  50         <goal>export</goal>
  51       </goals>
  52     </execution>
  53   </executions>
  54   <configuration>
  55     <url><![CDATA[jdbc:mysql://localhost/test-db]]></url>
  56   </configuration>
  57 </plugin>
  58 ---------------
  59
  60   Configuration properties, that are set in the <<<configuration>>>-section
  61   of the plugin-configuration cannnot be overwritten elsewere (for details
  62   see {{Configuration-Method-Precedence}}).
  63   You never can overwrite them by accident when specifying a property on
  64   the commandline or in your <<<settings.xml>>>.
  65
  66 Configuration through maven-properties
  67
  68   Alternatively, it is possible, to configure the plugin via maven-properties.
  69   Each relevant configuration-option has a corresponding maven-property
  70   (for a full list see the {{{./export-mojo.html} Documentation of the export-Mojo}}).
  71   These are named after the
  72   {{{http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-hibernatejdbc} Hibernate JDBC Properties}}:
  73
  74     * <<<hibernate.connection.driver_class>>>
  75
  76     * <<<hibernate.dialect>>>
  77
  78     * <<<hibernate.connection.url>>>
  79
  80     * <<<hibernate.connection.username>>>
  81
  82     * <<<hibernate.connection.password>>>
  83
  84   So, instead of writing the hibernate-configuration in the properties-file,
  85   like above, you could put it in the <<<properties>>>-section of your
  86   <<<pom.xml>>>.
  87
  88   Thogether with the plugin-definition from above, the following would
  89   be a complete configuration (again, the database-url was overwritten in
  90   the plugin-configuration, to be sure to have a separate database for
  91   testing):
  92
  93 ---------------
  94 <properties>
  95   <hibernate.connection.driver_class>org.hsqldb.jdbcDriver</hibernate.connection.driver_class>
  96   <hibernate.dialect>org.hibernate.dialect.HSQLDialect</hibernate.dialect>
  97   <hibernate.connection.url><![CDATA[jdbc:hsqldb:res:org.my.path.production_db]]></hibernate.connection.url>
  98   <hibernate.connection.username>sa</hibernate.connection.username>
  99   <hibernate.connection.password></hibernate.connection.password>
 100 </properties>
 101
 102 ...
 103
 104 <plugins>
 105
 106   ...
 107
 108   <plugin>
 109     <groupId>de.juplo</groupId>
 110     <artifactId>hibernate4-maven-plugin</artifactId>
 111     <version>${project.version}</version>
 112     <executions>
 113       <execution>
 114         <goals>
 115           <goal>export</goal>
 116         </goals>
 117       </execution>
 118     </executions>
 119     <configuration>
 120       <url><![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]></url>
 121     </configuration>
 122   </plugin>
 123
 124 <plugins>
 125 ---------------
 126
 127 Configuration through the plugin-configuration
 128
 129   A third way for configuring the plugin is the plugin-configuration.
 130   The relevant configuration-parameters are:
 131
 132     * <<<driverClassName>>>
 133
 134     * <<<hibernateDialect>>>
 135
 136     * <<<url>>>
 137
 138     * <<<username>>>
 139
 140     * <<<password>>>
 141
 142   The equivalent of the configuration from the last section would look
 143   like this:
 144
 145 ---------------
 146 <plugin>
 147   <groupId>de.juplo</groupId>
 148   <artifactId>hibernate4-maven-plugin</artifactId>
 149   <version>${project.version}</version>
 150   <executions>
 151     <execution>
 152       <goals>
 153         <goal>export</goal>
 154       </goals>
 155     </execution>
 156   </executions>
 157   <configuration>
 158     <driverClassName>org.hsqldb.jdbcDriver</driverClassName>
 159     <hibernateDialect>org.hibernate.dialect.HSQLDialect</hibernateDialect>
 160     <url><![CDATA[jdbc:hsqldb:target/db/fotos;shutdown=true]]></url>
 161     <username>sa</username>
 162     <password></password>
 163   </configuration>
 164 </plugin>
 165 ---------------
 166
 167   The parameter <<hibernateProperties>> (name of the hibernate-properties-file
 168   to use, defaults to <<hibernate.properties>>) can only be configured through
 169   this approach.
 170
 171   For more explanations, see the
 172   {{{./export-mojo.html} Documentation of the export-Mojo}}.
 173
 174 {Configuration-Method-Precedence}
 175
 176   The configuration is gathered in a fix order:
 177
 178     [[1]] <<<hibernate.properties>>>
 179
 180     [[2]] maven-properties
 181
 182     [[3]] plugin-configuration
 183
 184   If you are in doubt about where a configuration-value comes from, run
 185   maven with the {{{./debugging.html}debug-output}} enabled: <<<mvn -X hibernate4:export>>>
 186   and be aware, that maven-properties can be overwitten on the command-line,
 187   in your <<<~/.m2/settings.xml>>> and in a profile.
 188
 189   The plugin-configuration comes last and overwrites everything else.
 190   That way, you can be sure, that a configuration-value, that is
 191   specified in the plugin-configuration will never be overwritten by any
 192   other configuration-method.
 193
 194
 195   If you realy need to overwrite plugin-configuration-values with
 196   maven-properties, you can use maven-properties in the plugin-configuration:
 197
 198 ----------------
 199 <plugin>
 200   <groupId>de.juplo</groupId>
 201   <artifactId>hibernate4-maven-plugin</artifactId>
 202   <version>${project.version}</version>
 203   <executions>
 204     <execution>
 205       <goals>
 206         <goal>export</goal>
 207       </goals>
 208     </execution>
 209   </executions>
 210   <configuration>
 211     <password>${my-password-property}</password>
 212   </configuration>
 213 </plugin>
 214 ----------------