7746bcda2753c819732d8e409e5e11ff65e32acc
[website] / configuration.html
1 <!DOCTYPE html>
2 <!-- Generated by Apache Maven Doxia Site Renderer 1.6 at 2016-03-09 -->
3                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       <!-- Current: configuration.html -->
4 <!-- Active: index.html -->
5 <!-- Path: [index.html, configuration.html] -->
6 <!-- Skiplist: [index.html, configuration.html, create-mojo.html, drop-mojo.html, debugging.html, skip.html, force.html, pitfalls.html] -->
7 <html>
8   <head>
9     <title>juplo - Hibernate Maven Plugin - Configuration Examples</title>
10     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
11     <link rel="canonical" href="http://juplo.de/hibernate-maven-plugin/configuration.html"/>
12     <meta name="viewport" content="width=device-width, initial-scale=1" />
13     <link rel="stylesheet" type="text/css" href="/css/base.css" />
14     <style type="text/css">
15       @import '/css/screen.css' screen;
16     </style>
17     <script src="/js/prettify.js"></script>
18     <!--[if lt IE 9]>
19       <script src="/js/html5shiv.js"></script>
20     <![endif]-->
21     <!--[if IE 8]>
22       <link rel="stylesheet" type="text/css" href="/css/ie8.css" />
23     <![endif]-->
24         <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
25   </head>
26   <body class="menu" onload="prettyPrint()">
27     <div id="page" class="cf">
28       <header id="header">
29         <h1 id="logo"><a href="/" title="Home" class="l">juplo</a></h1>
30         <span id="slogan"><strong>Java</strong> bits from nerds for nerds</span>
31         <hr class="h" />
32       </header>
33       <div id="breadcrumb">
34         <strong class="b title">You are here:</strong>
35         <ol class="b">
36           <li class="b"><a class="b" href="/">Home</a></li>
37           <li class="b"><a class="b" href="/projects.html">Projects</a></li>
38                       <li class="b"><a class="b" href="./index.html">Hibernate Maven Plugin</a></li>
39                         <li class="b"><strong class="b">Configuration Examples</strong></li>
40                   </ol>
41         <a class="hide" href="#navigation">Jump to navigation</a>
42         <hr class="b" />
43       </div>
44       <main class="content cf">
45         <article id="content" class="main">
46           <header><h1>Configuration Examples</h1></header>
47           
48  
49  
50   
51 <div class="section">
52 <h2><a name="Configuration_Through_A_Configuration-File"></a>Configuration Through A Configuration-File</h2>
53   
54 <p>
55   The most simple way to configure the plugin is, to put all the
56   hibernate-configuration in a <b>hibernate.properties</b>- or
57   a <b>hibernate.cfg.xml</b>-file on your classpath or in the
58   <b>persistence.xml</b>-file of your JPA-configuration, just
59   like you would do, if you are not using the
60   <tt>hibernate-maven-plugin</tt>.
61   </p>
62   
63 <p>
64   Doing so, the only additionally configuration needed, to activat the plugin
65   is the following entry in the <tt>plugins</tt>-section of your <tt>pom.xml</tt>:
66   </p>
67   
68 <div>
69 <pre class="prettyprint linenums lang-html">
70 &lt;plugin&gt;
71   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
72   &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
73   &lt;version&gt;2.0.0&lt;/version&gt;
74   &lt;executions&gt;
75     &lt;execution&gt;
76       &lt;goals&gt;
77         &lt;goal&gt;create&lt;/goal&gt;
78       &lt;/goals&gt;
79     &lt;/execution&gt;
80   &lt;/executions&gt;
81 &lt;/plugin&gt;</pre></div>
82   
83 <p>
84   This would create the configured database.
85   If you want it to be droped beforehand, you have to add the goal
86   <tt>drop</tt>:
87   </p>
88   
89 <div>
90 <pre class="prettyprint linenums lang-html">
91 &lt;plugin&gt;
92   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
93   &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
94   &lt;version&gt;2.0.0&lt;/version&gt;
95   &lt;executions&gt;
96     &lt;execution&gt;
97       &lt;goals&gt;
98         &lt;goal&gt;drop&lt;/goal&gt;
99         &lt;goal&gt;create&lt;/goal&gt;
100       &lt;/goals&gt;
101     &lt;/execution&gt;
102   &lt;/executions&gt;
103 &lt;/plugin&gt;</pre></div>
104   
105 <p>
106   A correspondin goal for the command <tt>update</tt> is missing in this
107   version, but we are planning to implement it in near feature.
108   </p>
109   
110 <p>
111   In order to let this configuration work, your configuration file must
112   contain a complete valid configuration for the database, that you want
113   to use.
114   A simple example <tt>hibernate.properties</tt>-file may look like this:
115   </p>
116   
117 <div>
118 <pre class="prettyprint linenums lang-properties">
119 hibernate.dialect=org.hibernate.dialect.H2Dialect
120 hibernate.connection.url=jdbc:h2:file:./target/db
121 hibernate.connection.driver_class=org.h2.Driver
122 hibernate.connection.username=sa
123 hibernate.connection.password=</pre></div>
124   
125 <p>
126   But be aware, that using this configuration-approach the database-url,
127   that is build in the application is the same that is used while testing,
128   where the database is droped and recreated by the plugin.
129   Because of that,
130   <b>
131     you should never fire up this configuration on your production
132     system, or your database might be erased!
133   </b>
134   </p>
135   
136 <p>
137   A better approach is, to specify a different url for testing like in the
138   following snippet:
139   </p>
140   
141 <div>
142 <pre class="prettyprint linenums lang-html">
143 &lt;plugin&gt;
144   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
145   &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
146   &lt;version&gt;2.0.0&lt;/version&gt;
147   &lt;executions&gt;
148     &lt;execution&gt;
149       &lt;goals&gt;
150         &lt;goal&gt;drop&lt;/goal&gt;
151         &lt;goal&gt;create&lt;/goal&gt;
152       &lt;/goals&gt;
153     &lt;/execution&gt;
154   &lt;/executions&gt;
155   &lt;configuration&gt;
156     &lt;url&gt;&lt;![CDATA[jdbc:mysql://localhost/test-db]]&gt;&lt;/url&gt;
157   &lt;/configuration&gt;
158 &lt;/plugin&gt;</pre></div>
159   
160 <p>
161   Configuration properties, that are set in the <tt>configuration</tt>-section
162   of the plugin-configuration cannnot be overwritten elsewere (for details
163   see <a href="#precedence">Configuration-Method-Precedence</a>).
164   You never can overwrite them by accident when specifying a property on
165   the commandline or in your <tt>settings.xml</tt>.
166   </p>
167   </div>
168 <div class="section">
169 <h2><a name="Configuration_through_maven-properties"></a>Configuration through maven-properties</h2>
170   
171 <p>
172   Alternatively, it is possible, to configure the plugin via maven-properties.
173   Each relevant configuration-option has a corresponding maven-property
174   (for a full list see the <a href="./create-mojo.html">Documentation of the goal create</a>).
175   These are named after the
176   <a class="externalLink" href="http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html_single/#configuration-hibernatejdbc">Hibernate JDBC Properties</a>:
177   </p>
178   
179 <ul>
180     
181 <li><tt>hibernate.connection.driver_class</tt></li>
182     
183 <li><tt>hibernate.dialect</tt></li>
184     
185 <li><tt>hibernate.connection.url</tt></li>
186     
187 <li><tt>hibernate.connection.username</tt></li>
188     
189 <li><tt>hibernate.connection.password</tt></li>
190   </ul>
191   
192 <p>
193   So, instead of writing the hibernate-configuration in the properties-file,
194   like above, you could put it in the <tt>properties</tt>-section of your
195   <tt>pom.xml</tt>.
196   </p>
197   
198 <p>
199   Thogether with the plugin-definition from above, the following would
200   be a complete configuration (again, the database-url was overwritten in
201   the plugin-configuration, to be sure to have a separate database for
202   testing):
203   </p>
204   
205 <div>
206 <pre class="prettyprint linenums lang-html">
207 &lt;properties&gt;
208   &lt;hibernate.connection.driver_class&gt;org.hsqldb.jdbcDriver&lt;/hibernate.connection.driver_class&gt;
209   &lt;hibernate.dialect&gt;org.hibernate.dialect.HSQLDialect&lt;/hibernate.dialect&gt;
210   &lt;hibernate.connection.url&gt;&lt;![CDATA[jdbc:hsqldb:res:org.my.path.production_db]]&gt;&lt;/hibernate.connection.url&gt;
211   &lt;hibernate.connection.username&gt;sa&lt;/hibernate.connection.username&gt;
212   &lt;hibernate.connection.password&gt;&lt;/hibernate.connection.password&gt;
213 &lt;/properties&gt;
214
215 ...
216
217 &lt;plugins&gt;
218
219   ...
220
221   &lt;plugin&gt;
222     &lt;groupId&gt;de.juplo&lt;/groupId&gt;
223     &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
224     &lt;version&gt;2.0.0&lt;/version&gt;
225     &lt;executions&gt;
226       &lt;execution&gt;
227         &lt;goals&gt;
228           &lt;goal&gt;drop&lt;/goal&gt;
229           &lt;goal&gt;create&lt;/goal&gt;
230         &lt;/goals&gt;
231       &lt;/execution&gt;
232     &lt;/executions&gt;
233     &lt;configuration&gt;
234       &lt;url&gt;&lt;![CDATA[jdbc:hsqldb:target/db/testdb;shutdown=true]]&gt;&lt;/url&gt;
235     &lt;/configuration&gt;
236   &lt;/plugin&gt;
237
238 &lt;plugins&gt;</pre></div>
239   
240 <p>
241   This way, you can reuse the same properties to provide a
242   default-configurationthe, that is build into your application, and
243   overwrite the database-url, that is used during testing to prevent
244   accidential drops of your production database.
245   </p>
246   </div>
247 <div class="section">
248 <h2><a name="Configuration_through_the_plugin-configuration"></a>Configuration through the plugin-configuration</h2>
249   
250 <p>
251   A third way for configuring the plugin is the plugin-configuration.
252   The relevant configuration-parameters are:
253   </p>
254   
255 <ul>
256     
257 <li><tt>driver</tt></li>
258     
259 <li><tt>dialect</tt></li>
260     
261 <li><tt>url</tt></li>
262     
263 <li><tt>username</tt></li>
264     
265 <li><tt>password</tt></li>
266   </ul>
267   
268 <p>
269   The equivalent of the configuration from the last section would look
270   like this:
271   </p>
272   
273 <div>
274 <pre class="prettyprint linenums lang-html">
275 &lt;plugin&gt;
276   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
277   &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
278   &lt;version&gt;2.0.0&lt;/version&gt;
279   &lt;executions&gt;
280     &lt;execution&gt;
281       &lt;goals&gt;
282         &lt;goal&gt;drop&lt;/goal&gt;
283         &lt;goal&gt;create&lt;/goal&gt;
284       &lt;/goals&gt;
285     &lt;/execution&gt;
286   &lt;/executions&gt;
287   &lt;configuration&gt;
288     &lt;driver&gt;org.hsqldb.jdbcDriver&lt;/driver&gt;
289     &lt;dialect&gt;org.hibernate.dialect.HSQLDialect&lt;/dialect&gt;
290     &lt;url&gt;&lt;![CDATA[jdbc:hsqldb:target/db/fotos;shutdown=true]]&gt;&lt;/url&gt;
291     &lt;username&gt;sa&lt;/username&gt;
292     &lt;password&gt;&lt;/password&gt;
293   &lt;/configuration&gt;
294 &lt;/plugin&gt;</pre></div>
295   
296 <p>
297   The parameter <b>hibernateProperties</b> (name of the hibernate-properties-file
298   to use, defaults to <b>hibernate.properties</b>) can only be configured through
299   this approach.
300   </p>
301   
302 <p>
303   For more explanations, see the
304   <a href="./create-mojo.html">Documentation of the goal create</a>.
305   </p>
306   </div>
307 <div class="section" id="precedence">
308 <h2 id="precedence">Configuration-Method-Precedence</h2>
309   
310 <p>
311   The configuration is gathered in a fix order:
312   </p>
313   
314 <ol style="list-style-type: decimal">
315     
316 <li><tt>hibernate.properties</tt></li>
317     
318 <li><tt>hibernate.cfg.xml</tt></li>
319     
320 <li><tt>persistence.xml</tt></li>
321     
322 <li>maven-properties</li>
323     
324 <li>plugin-configuration</li>
325   </ol>
326   
327 <p>
328   If you are in doubt about where a configuration-value comes from, run
329   maven with the <a href="./debugging.html">debug-output</a> enabled: <tt>mvn -X hibernate:create</tt>
330   and be aware, that maven-properties can be overwitten on the command-line,
331   in your <tt>~/.m2/settings.xml</tt> and in a profile.
332   </p>
333   
334 <p>
335   The plugin-configuration comes last and overwrites everything else.
336   That way, you can be sure, that a configuration-value, that is
337   specified in the plugin-configuration will never be overwritten by any
338   other configuration-method.
339   </p>
340   
341 <p>
342   If you need to overwrite plugin-configuration-values with
343   maven-properties, you can use maven-properties in the plugin-configuration:
344   </p>
345   
346 <div>
347 <pre class="prettyprint linenums lang-html">
348 &lt;plugin&gt;
349   &lt;groupId&gt;de.juplo&lt;/groupId&gt;
350   &lt;artifactId&gt;hibernate-maven-plugin&lt;/artifactId&gt;
351   &lt;version&gt;2.0.0&lt;/version&gt;
352   &lt;executions&gt;
353     &lt;execution&gt;
354       &lt;goals&gt;
355         &lt;goal&gt;drop&lt;/goal&gt;
356         &lt;goal&gt;create&lt;/goal&gt;
357       &lt;/goals&gt;
358     &lt;/execution&gt;
359   &lt;/executions&gt;
360   &lt;configuration&gt;
361     &lt;password&gt;${my-password-property}&lt;/password&gt;
362   &lt;/configuration&gt;
363 &lt;/plugin&gt;</pre></div>
364  </div>
365
366         </article>
367         <div class="marginal">
368           <nav id="nav">
369             <hr class="n" />
370             <a id="navigation"></a>
371             <a class="hide" href="#top" title="Show Content">Jump back to the top of the page</a>
372             <h2 class="nav menu">Section-Menu</h2>
373             <ul id="menu">
374               <li class="m blog"><a href="/blog/" class="m">Blog</a></li>
375               <li class="m projects"><a href="/projects.html" class="m selected">Projects</a></li>
376               <li class="m about"><a href="/about.html" class="m">About</a></li>
377             </ul>
378             <h2 class="nav submenu">
379               <span class="s">Submenu for section</span>
380               <a class="s selected" href="/projects.html">Projects</a>
381             </h2>
382             <ul id="submenu" class="s">
383                                                               <li class="s sub">
384                                           <a class="s selected" href="./index.html">Hibernate Maven Plugin</a>
385                                         <ul class="s active">
386                                                                                                                                                                                                                                                                 <li class="s">
387               <strong class="s">Configuration Examples</strong>
388                 </li>
389                                                                                                                   <li class="s">
390                     <a href="create-mojo.html" class="s" title="Goal: CREATE">Goal: CREATE</a>
391                 </li>
392                                                                                                                   <li class="s">
393                     <a href="drop-mojo.html" class="s" title="Goal: DROP">Goal: DROP</a>
394                 </li>
395                                                                                                                   <li class="s">
396                     <a href="debugging.html" class="s" title="Enable Debug-Output">Enable Debug-Output</a>
397                 </li>
398                                                                                                                   <li class="s">
399                     <a href="skip.html" class="s" title="Skipping Execution">Skipping Execution</a>
400                 </li>
401                                                                                                                   <li class="s">
402                     <a href="force.html" class="s" title="Force Exceution">Force Exceution</a>
403                 </li>
404                                                                                                                   <li class="s">
405                     <a href="pitfalls.html" class="s" title="Known Pitfalls (FAQ)">Known Pitfalls (FAQ)</a>
406                 </li>
407                                                                                                                                                                                                                                                                                                                                                             <li class="s sub">
408                     <a href="project-info.html" class="s" title="Project Information">Project Information</a>
409                 </li>
410                                                                                                                                                                                                             <li class="s sub">
411                     <a href="project-reports.html" class="s" title="Project Reports">Project Reports</a>
412                 </li>
413                                                                                               </ul>
414                   </li>
415                                           </ul>
416             <hr class="n" />
417           </nav>
418           <aside class="m">
419             <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
420               <img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
421             </a>
422           </aside>
423         </div>
424       </main>
425       <footer id="footer">
426         <hr class="f" />
427         <ul id="footerlinks">
428           <li class="f" id="copyright">&#xa9; <strong>mo</strong>             2016
429       </li>
430           <li class="f"><a class="f" href="/impressum.html">Impressum</a></li>
431           <li class="f about"><a class="f" href="/about.html">About</a></li>
432         </ul>
433       </footer>
434     </div>
435         <script type="text/javascript"><!--//--><![CDATA[//><!--
436       var _gaq = _gaq || [];
437       _gaq.push(['_setAccount', 'UA-571104-3']);
438       _gaq.push(['_trackPageview']);
439       (function() {
440         var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
441         ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
442         var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
443       })();
444     //--><!]]>
445     </script>
446       </body>
447 </html>