Author: smukhina Date: 2008-10-29 12:24:29 -0400 (Wed, 29 Oct 2008) New Revision: 11302 Added: branches/jbosstools-3.0.0.Beta1/hibernatetools/docs/reference/en/master_output.xml Modified: branches/jbosstools-3.0.0.Beta1/hibernatetools/docs/reference/pom.xml Log: https://jira.jboss.org/jira/browse/JBDS-463 markers for new and updated are added Added: branches/jbosstools-3.0.0.Beta1/hibernatetools/docs/reference/en/master_output.xml =================================================================== --- branches/jbosstools-3.0.0.Beta1/hibernatetools/docs/reference/en/master_output.xml (rev 0) +++ branches/jbosstools-3.0.0.Beta1/hibernatetools/docs/reference/en/master_output.xml 2008-10-29 16:24:29 UTC (rev 11302) @@ -0,0 +1,5047 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.docbook.org/xml/4.3/docbookx.dtd" + +[ +<!ENTITY preface SYSTEM "modules/preface.xml"> +<!ENTITY setup SYSTEM "modules/setup.xml"> +<!ENTITY codegenarchitecture SYSTEM "modules/codegenarchitecture.xml"> +<!ENTITY plugins SYSTEM "modules/plugins.xml"> +<!ENTITY ant SYSTEM "modules/ant.xml"> +<!ENTITY reveng SYSTEM "modules/reverseengineering.xml"> +<!ENTITY codegen SYSTEM "modules/codegen.xml"> + +<!ENTITY seamlink "../../seam/html_single/index.html"> +<!ENTITY aslink "../../as/html_single/index.html"> +<!ENTITY esblink "../../esb_ref_guide/html_single/index.html"> +<!ENTITY gsglink "../../GettingStartedGuide/html_single/index.html"> +<!ENTITY hibernatelink "../../hibernatetools/html_single/index.html"> +<!ENTITY jbpmlink "../../jbpm/html_single/index.html"> +<!ENTITY jsflink "../../jsf/html_single/index.html"> +<!ENTITY jsfreflink "../../jsf_tools_ref_guide/html_single/index.html"> +<!ENTITY jsftutoriallink "../../jsf_tools_tutorial/html_single/index.html"> +<!ENTITY strutsreflink "../../struts_tools_ref_guide/html_single/index.html"> +<!ENTITY strutstutoriallink "../../struts_tools_tutorial/html_single/index.html"> + +]><book lang="en" xmlns:diffmk="http://diffmk.sf.net/ns/diff"> + <bookinfo> + <title>Hibernate Tools Reference Guide</title> + + <author&gt;&lt;firstname&gt;Max&lt;/firstname&gt;&lt;surname&gt;Andersen&lt;/surname&gt;&lt;email&gt;max.andersen(a)jboss.com&lt;/email&gt;&lt;/author&gt; + <author><firstname>Olga</firstname><surname>Chikvina</surname></author> + <author&gt;&lt;firstname&gt;Svetlana&lt;/firstname&gt;&lt;surname&gt;Mukhina&lt;/surname&gt;&lt;email&gt;smukhina(a)exadel.com&lt;/email&gt;&lt;/author&gt; + + <pubdate>April 2008</pubdate> + <copyright> + <year>2007</year> + <year>2008</year> + <holder>JBoss, a division of Red Hat Inc.</holder> + </copyright> + + <releaseinfo> + Version: <diffmk:wrapper diffmk:change="changed">3.0.0.beta1 + </diffmk:wrapper></releaseinfo> + + + <mediaobject> + <imageobject> + <imagedata fileref="images/hibernate_logo_a.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + +<abstract diffmk:change="added"> + <title diffmk:change="added"></title> + <para diffmk:change="added"> + <ulink diffmk:change="added" url="http://download.jboss.org/jbosstools/nightly-docs/en/hibernatet... diffmk:change="added">PDF version</diffmk:wrapper></ulink> + </para> +</abstract> + + + </bookinfo> + <toc></toc> + + +<chapter id="preface" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/hibernatetools/docs/reference/en/modules/preface.xml"> + + <title>Preface</title> + + <para><property moreinfo="none">Hibernate Tools</property> is a toolset for <ulink url="http://www.hibernate.org/6.html">Hibernate 3</ulink> and <ulink url="http://www.hibernate.org/27.html">related projects</ulink>. The tools provide Ant + tasks and Eclipse plugins for performing reverse engineering, code generation, visualization + and interaction with Hibernate.</para> + + <section id="hibernate_key_features"> + <title>Key Features</title> + + <para>First, we propose to look through the list of key features that you can benefit from + if you start using <property moreinfo="none">Hibernate Tools</property>.</para> + + <table> + <title>Key Functionality for Hibernate Tools</title> + <tgroup cols="3"> + + <colspec align="left" colnum="1" colwidth="1*"></colspec> + <colspec colnum="2" colwidth="5*"></colspec> + <colspec align="left" colnum="3" colwidth="1*"></colspec> + + <thead> + <row> + <entry>Feature</entry> + <entry>Benefit</entry> + <entry>Chapter</entry> + </row> + </thead> + + <tbody> + + <row> + <entry> + <para>Code Generation through Ant Task</para> + </entry> + <entry> + <para>Allows to execute mapping or Java code generation from reverse + engineering, schema generation and generation of other artifacts + during the build process.</para> + </entry> + <entry><link linkend="ant">ant task</link></entry> + </row> + + <row> + <entry> + <para>Wizards for creation + purposes and code + generation</para> + </entry> + <entry> + <para> A set of wizards are provided with the Hibernate Eclipse tools to + quickly create common Hibernate files such as configuration + (cfg.xml) files, mapping files and revenge.xml as well. Code + Generation wizard helps to generate a series of various artifacts, + there is even support for completely reverse engineer an existing + database schema.</para> + </entry> + <entry> <link linkend="map_file_wizard">hibernate mapping file</link> + <link linkend="hib_config_file">hibernate configuration file</link> + <link linkend="code_gen">code generation</link> + </entry> + </row> + + + <row> + <entry> + <para> + Mapping and Configuration files + Editors + </para> + </entry> + <entry> + <para>Support auto-completion and syntax highlighting. Editors also + support semantic auto-completion for class names and property/field + names, making it much more versatile than a normal XML + editor.</para> + </entry> + <entry> <link linkend="map_config_editor">mapping and configuration files editors</link></entry> + </row> + + <row> + <entry> + <para>Tools for organizing and controlling Reverse Engineering</para> + </entry> + <entry> + <para>Code Generation wizard provides powerful functionality for + generating a series of various artifacts like domain model classes, + mapping files, annotated EJB3 entity beans, etc. and reveng.xml file + editor allows to control this processes.</para> + </entry> + <entry><link linkend="code_gen">code generation</link> + <link linkend="rev_xml_editor">reveng.xml editor</link></entry> + </row> + + <row> + <entry> + <para>Hibernate Console</para> + </entry> + <entry> + <para>It is a new perspective in Eclipse which provides an overview of + your Hibernate Console configurations, were you also can get an + interactive view of your persistent classes and their relationships. + The console allows you to execute HQL queries against your database + and browse the result directly in Eclipse.</para> + </entry> + <entry><link linkend="hib_console">hibernate console</link></entry> + </row> + + <row> + <entry> + <para>Functional Mapping Diagram</para> + </entry> + <entry> + <para>Makes possible to visualize structure of entities and + relationships between them.</para> + </entry> + <entry><link linkend="map_diagram">mapping diagram</link></entry> + </row> + + + <row> + <entry> + <para>Eclipse JDT integration</para> + </entry> + <entry> + <para>Hibernate Tools integrates into the Java code completion and build + support of Java in Eclipse. This gives you code completion of HQL + inside Java code. Additionally, Hibernate Tools will add problem + markers if your queries are not valid against the console + configuration associated with the project.</para> + </entry> + </row> + + </tbody> + </tgroup> + </table> + </section> + + <section> + <title>Other relevant resources on the topic</title> + <para>All JBoss Developer Studio/JBoss Tools documentation you can find <ulink url="http://www.jboss.com/products/devstudio/docs">here</... + <para>The latest documentation builds are available <ulink url="http://download.jboss.org/jbosstools/nightly-docs/">her... + </section> + +</chapter> + + +<chapter id="setup" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/hibernatetools/docs/reference/en/modules/setup.xml"> + <title>Download and install Hibernate Tools</title> + + <para><property moreinfo="none">Hibernate Tools</property> can be used "standalone" via Ant + 1.6.x or fully integrated into an Eclipse 3.3.x + WTP 2.x based IDE, such as <property moreinfo="none">JBoss + Tools</property> or a default Eclipse 3.3.x + WTP 2.x installation. The following describes + the install steps in these environments.</para> + + <section> + <title>JBoss Tools</title> + + <para><property moreinfo="none">JBoss Tools 2.x</property> includes <property moreinfo="none">Hibernate Tools</property> and + thus nothing is required besides <ulink url="http://labs.jboss.com/tools/download/index.html">downlo... and <ulink url="../../GettingStartedGuide/html_single/index.html#JBossToolsInstall">installing JBoss Tools</ulink>. If you need to update to a newer version of the + <property moreinfo="none">Hibernate Tools</property> just follow the instructions in the Eclipse IDE + section.</para> + </section> + + <section> + <title>Eclipse IDE</title> + + <para>To install into any <property moreinfo="none">Eclipse 3.3.x</property> based Eclipse IDE you can either + download the <property moreinfo="none">Hibernate Tools</property> distribution from the <ulink url="http://www.hibernate.org/6.html">Hibernate website</ulink> or use the <ulink url="http://download.jboss.org/jbosstools/updates/stable/">J... Tools Update Site</ulink> + (see also <ulink url="http://tools.hibernate.org">http://tools.hibernate.org</ulink> for links + to the update site).</para> + + <para>If you download the <property moreinfo="none">Hibernate Tools</property> distribution you need to place + the <emphasis> + <property moreinfo="none">/plugins</property> + </emphasis> and <emphasis> + <property moreinfo="none">/feature</property> + </emphasis> directory into your eclipse directory or eclipse extensions directory. Sometimes + Eclipse does not automatically detect new plugins and thus the tools will not be activated. To + ensure eclipse sees these changes just clean up the cached plugin information by running eclipse with the <emphasis> + <property moreinfo="none">-clean</property></emphasis> option, e.g. <emphasis> + <property moreinfo="none">eclipse + -clean</property>.</emphasis> Using the updatesite does not require any additional steps.</para> + + <note> + <title>Note:</title> + <para>If you need more basic instructions on installing plugins and general usage of eclipse + then check out <ulink url="https://eclipse-tutorial.dev.java.net/">https://eclipse... and especially <ulink url="https://eclipse-tutorial.dev.java.net/visual-tutorials/updatema... which + covers using the update manager.</para> + </note> + + <section> + <title>Usage of Eclipse WTP</title> + + <para>The <property moreinfo="none">Hibernate Tools</property> plugins currently use <property moreinfo="none">WTP + 2.x</property> which at this time is the latest stable release from the Eclipse Webtools + project.</para> + + <para>Because the WTP project not always have had proper versioning of their plugins there + might exist WTP plugins in your existing eclipse directory from other Eclipse based projects + that are from an earlier WTP release but has either the same version number or higher. It is + thus recommended that if you have issues with WTP provided features to try and install the + plugins on a clean install of eclipse to ensure there are no version collisions.</para> + + </section> + </section> + + <section> + <title>Ant</title> + + <para>To use the tools via Ant you need the <emphasis> + <property moreinfo="none">hibernate-tools.jar</property> + </emphasis> and associated libraries. The libraries are included in the distribution from the + Hibernate website and the Eclipse updatesite. The libraries are located in the eclipse plugins + directory at <emphasis> + <property moreinfo="none">/plugins/org.hibernate.eclipse.x.x.x/lib/tools/</property></emphasis>. These libraries are 100% + independent from the eclipse platform. How to use these via ant tasks are described in the + <link linkend="ant">Ant Tools</link> chapter.</para> + </section> +</chapter> + + +<chapter id="codegenarchitecture" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/hibernatetools/docs/reference/en/modules/codegenarchitecture.xml"> + <title>Code generation architecture</title> + + <para>The code generation mechanism in the <property moreinfo="none">Hibernate Tools</property> consists of a few + core concepts. This section explains their overall structure which are the same for the Ant and + Eclipse tools.</para> + + <section> + <title>Hibernate Meta Model</title> + + <para>The meta model is the model used by Hibernate Core to perform its object relational + mapping. The model includes information about tables, columns, classes, properties, + components, values, collections etc. The API is in <literal moreinfo="none">org.hibernate.mapping</literal> + and its main entry point is the <literal moreinfo="none">Configuration</literal> class, the same class that is + used to build a session factory.</para> + + <para>The model represented by the <literal moreinfo="none">Configuration</literal> class can be build in many + ways. The following list the currently supported ones in <property moreinfo="none">Hibernate Tools</property>. </para> + + <para> + <itemizedlist> + <listitem> + <para>A Core configuration uses Hibernate Core and supports reading <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> files, requires a <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis>. Named core in Eclipse and <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;configuration&gt;</literal> + </property> + </emphasis> in ant.</para> + </listitem> + + <listitem> + <para>An Annotation configuration uses Hibernate Annotations and supports <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> and annotated classes, requires a <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis>. Named annotations in Eclipse and <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;annotationconfiguration&gt;</literal> + </property> + </emphasis> in ant.</para> + </listitem> + + <listitem> + <para>A JPA configuration uses a Hibernate EntityManager and supports <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> and annotated classes requires that the project has a <emphasis> + <property moreinfo="none">META-INF/persistence.xml</property> + </emphasis> in its classpath. Named JPA in Eclipse and <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;jpaconfiguration&gt;</literal> + </property> + </emphasis> in ant.</para> + </listitem> + + <listitem> + <para>A JDBC configuration uses <property moreinfo="none">Hibernate Tools</property> reverse engineering + and reads its mappings via JDBC metadata + additional reverse engineering files + (reveng.xml). Automatically used in Eclipse when doing reverse engineering from JDBC and + named <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;jdbcconfiguration&gt;</literal> + </property> + </emphasis> in ant.</para> + </listitem> + </itemizedlist> + </para> + + <para>In most projects you will normally use only one of the Core, Annotation or JPA + configuration and possibly the JDBC configuration if you are using the reverse engineering + facilities of <property moreinfo="none">Hibernate Tools</property>. </para> + + <note> + <title>Note:</title> + <para>No matter which Hibernate Configuration type you are using <property moreinfo="none">Hibernate + Tools</property> supports them.</para> + </note> + + <para>The following drawing illustrates the core concepts:</para> + + <para> + <figure float="0"> + <title>Hibernate Core Concepts</title> + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="images/code_generation/code_generation_1.png" format="PNG"></imagedata> + </imageobject> + + <imageobject role="html"> + + <imagedata align="center" fileref="images/code_generation/code_generation_1.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + </para> + + <para>The code generation is done based on the Configuration model no matter which type of + configuration have been used to create the meta model, and thus the code generation is + independent on the source of the meta model and represented via Exporters.</para> + </section> + + <section> + <title>Exporters</title> + + <para>Code generation is done in so called Exporters. An <literal moreinfo="none">Exporter</literal> is handed a + Hibernate Meta Model represented as a <literal moreinfo="none">Configuration</literal> instance and it is then + the job of the exporter to generate a set of code artifacts.</para> + + <para>The tools provides a default set of Exporter's which can be used in both Ant and the + Eclipse UI. Documentation for these Exporters is in the <link linkend="ant">Ant Tools</link> + and <link linkend="plugins">Eclipse Plugins</link> chapters.</para> + + <para>Users can provide their own customer Exporter's, either by custom classes implementing the + Exporter interface or simply be providing custom templates. This is documented at <xref linkend="hbmtemplate"></xref></para> + </section> +</chapter> + + +<chapter id="plugins" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/hibernatetools/docs/reference/en/modules/plugins.xml"> + <title>Eclipse Plugins</title> + + <para>This chapter will introduce you to the functionality that <property moreinfo="none">Hibernate + Tools</property> provide within Eclipse. That is a set of wizards and editors for simplifying + the work with <property moreinfo="none">Hibernate</property>.</para> + + <section> + <title>Introduction</title> + + <para>Hibernate Eclipse Tools include wizards for creating Hibernate mapping files, + configuration files (.cfg.xml), revenge.xml as well as wizards for adjusting Console + Configuration and Code Generation. Special structured and XML editors, editors for executing + HQL and Criteria queries are also provided in Hibernate Console. Refer to <link linkend="hibernate_key_features">Key Features</link> section to find all benefits that you + can take advantage of while using the tools within Eclipse.</para> + + <note> + <title>Note:</title> + <para>Please note that these tools do not try to hide any functionality of + <property moreinfo="none">Hibernate</property>. The tools make working with <property moreinfo="none">Hibernate</property> + easier, but you are still encouraged/required to read the <ulink url="http://www.hibernate.org/5.html">Hibernate Documentation</ulink> to fully utilize + <property moreinfo="none">Hibernate Tools</property> and especially <property moreinfo="none">Hibernate</property> it + self.</para> + </note> + </section> + + <section id="map_file_wizard" revisionflag="added"> + <title>Creating a Hibernate Mapping File</title> + + <para>Hibernate mapping files are used to specify how your objects are related to database + tables.</para> + + <para>For creating a skeleton mapping file, i. e. any <emphasis> + <property moreinfo="none">.hbm.xml</property> + </emphasis>, Hibernate Tools provide a basic wizard which you can bring up by navigating <emphasis> + <property moreinfo="none">New &gt; Hibernate XML mapping file</property>.</emphasis></para> + + <figure float="0"> + <title>Hibernate XML Mapping File Wizard</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_0.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>At first you'll be asked to specify the location and the name for a new mapping + file. On the next dialog you should type or browse the class to map.</para> + <figure float="0"> + <title>Specifying the Class to Map</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_0_a.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Pressing finish creates the file and opens it in the <link linkend="map_config_struct_editor">structured hbm.xml editor</link>.</para> + + <para> If you start the wizard from the selected class, all values will be detected there + automatically.</para> + + <figure float="0"> + <title>Creating Mapping File for Selected Class</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_0_b.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + </section> + + <section id="hib_config_file"> + <title>Creating a Hibernate Configuration File</title> + + <para>To be able to reverse engineer, prototype queries, and of course to simply use + <property moreinfo="none">Hibernate Core</property> a <emphasis> + <property moreinfo="none">hibernate.properties</property> + </emphasis> or <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> file is needed. The <property moreinfo="none">Hibernate Tools</property> provide a wizard for + generating the <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> file if you do not already have such one.</para> + + <para>Start the wizard by clicking <emphasis> + <property moreinfo="none">New &gt; Other (Ctrl+N)</property> + </emphasis>, then <emphasis> + <property moreinfo="none">Hibernate &gt; Hibernate Configuration File (cfg.xml)</property> + </emphasis> and press <emphasis> + <property moreinfo="none">Next</property> + </emphasis>. After selecting the wanted location for the <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> file, you will see the following page:</para> + + <figure float="0"> + <title>Hibernate Configuration File Wizard</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_1.png" format="PNG"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_1.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <note> + <title>Note:</title> + <para>The contents in the combo boxes for the JDBC driver class and JDBC URL change + automatically, depending on the Dialect and actual driver you have chosen.</para> + </note> + + <para>Enter your configuration information in this dialog. Details about the configuration + options can be found in <ulink url="http://docs.jboss.org/ejb3/app-server/Hibernate3/reference/en/h... + Reference Documentation</ulink>.</para> + + <para>Press <emphasis> + <property moreinfo="none">Finish</property> + </emphasis> to create the configuration file, after optionally creating a Console + configuration, the <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> will be automatically opened in an editor. The last option <emphasis> + <property moreinfo="none">Create Console Configuration</property> + </emphasis> is enabled by default and when enabled, it will automatically use the <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> for the basis of a Console configuration.</para> + </section> + + <section id="console_conf" role="updated"> + <title>Creating a Hibernate Console Configuration</title> + + <para>A Console configuration describes how the <property moreinfo="none">Hibernate plugin</property> should + configure <property moreinfo="none">Hibernate</property> and what configuration files, including which + classpath are needed to load the POJO's, JDBC drivers etc. It is required to make usage of + query prototyping, reverse engineering and code generation. You can have multiple named + console configurations. Normally you would just need one per project, but more is definitely + possible if your project requires this.</para> + + <para>You create a console configuration by running the <property moreinfo="none">Console Configuration + Wizard</property>, shown in the following screenshot. The same wizard will also be used if you + are coming from the <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> wizard and had enabled <emphasis> + <property moreinfo="none">Create Console Configuration</property> + </emphasis>.</para> + + <note> + <title>Note:</title> + <para>The wizard will look at the current selection in the IDE and try and auto-detect the + settings which you then can just approve or modify to suit your needs.</para> + </note> + <para></para> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">The dialog consists of five tabs: </diffmk:wrapper></para> + + <itemizedlist diffmk:change="added"> + <listitem diffmk:change="added"> + <para diffmk:change="added"><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Main</diffmk:wrapper></property> + </emphasis> <diffmk:wrapper diffmk:change="added">for the basic/required settings</diffmk:wrapper></para> + </listitem> + </itemizedlist> + + <figure float="0"> + <title> Creating Hibernate Console Configuration</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_2.png" format="PNG"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_2.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The <diffmk:wrapper diffmk:change="added">following</diffmk:wrapper><diffmk:wrapper diffmk:change="deleted">dialog consists of three tabs, </diffmk:wrapper><diffmk:wrapper diffmk:change="added">table + </diffmk:wrapper><diffmk:wrapper diffmk:change="deleted">General + </diffmk:wrapper><diffmk:wrapper diffmk:change="changed">describes </diffmk:wrapper>the <diffmk:wrapper diffmk:change="added">available</diffmk:wrapper><diffmk:wrapper diffmk:change="deleted">basic/required settings, + Classpath + for classpath and + Mappings + for additional mappings. The two latter ones are normally not required if you + specify a project and it has + + </diffmk:wrapper><diffmk:wrapper diffmk:change="changed">settings </diffmk:wrapper><diffmk:wrapper diffmk:change="added">on + + </diffmk:wrapper><diffmk:wrapper diffmk:change="changed">the </diffmk:wrapper><emphasis> + <property moreinfo="none"><diffmk:wrapper diffmk:change="added">Main + </diffmk:wrapper><diffmk:wrapper diffmk:change="deleted">/META-INF/persistence.xml + </diffmk:wrapper></property> + </emphasis> <diffmk:wrapper diffmk:change="added">tab.</diffmk:wrapper><diffmk:wrapper diffmk:change="deleted">in its project classpath. + + The following table describes the available settings. </diffmk:wrapper>The wizard can automatically detect default values for most of these if you + started the wizard with the relevant java project or resource selected.</para> + + <table> + <title>Hibernate Console Configuration Parameters</title> + + <tgroup cols="3"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + + <colspec colnum="2" colwidth="3*"></colspec> + + <colspec align="left" colnum="3" colwidth="1*"></colspec> + + <thead> + <row> + <entry align="center"> + <para>Parameter</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + + <entry align="center"> + <para>Auto detected value</para> + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>Name</para> + </entry> + + <entry> + <para>The unique name of the console configuration</para> + </entry> + + <entry> + <para>Name of the selected project</para> + </entry> + </row> + + <row> + <entry> + <para><diffmk:wrapper diffmk:change="added">Type</diffmk:wrapper></para> + </entry> + + <entry diffmk:change="added"> + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Choose between "Core", "Annotations" and + "JPA". Note that the two latter requires running Eclipse IDE with + a JDK 5 runtime, otherwise you will get classloading and/or version errors.</diffmk:wrapper></para> + </entry> + + <entry diffmk:change="added"> + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">No default value</diffmk:wrapper></para> + </entry> + </row> + + <row diffmk:change="added"> + <entry diffmk:change="added"> + <para diffmk:change="added">Project</para> + </entry> + + <entry> + <para>The name of a java project which classpath should be used in the console + configuration</para> + </entry> + + <entry> + <para>Name of the selected project</para> + </entry> + </row> + + <row> + <entry> + <para><diffmk:wrapper diffmk:change="added">Database connection</diffmk:wrapper><diffmk:wrapper diffmk:change="deleted">Type</diffmk:wrapper></para> + </entry> + + <entry> + <para><diffmk:wrapper diffmk:change="changed">DTP provided connection that </diffmk:wrapper><diffmk:wrapper diffmk:change="added">you</diffmk:wrapper><diffmk:wrapper diffmk:change="deleted">and + "JPA". </diffmk:wrapper><diffmk:wrapper diffmk:change="changed">can use instead of what is in cfg.xml and jpa + persistence.xml. It's possible to use already configured connection </diffmk:wrapper><diffmk:wrapper diffmk:change="added">or + specify</diffmk:wrapper><diffmk:wrapper diffmk:change="deleted">classloading </diffmk:wrapper><diffmk:wrapper diffmk:change="changed">a new </diffmk:wrapper><diffmk:wrapper diffmk:change="added">one here.</diffmk:wrapper><diffmk:wrapper diffmk:change="deleted">errors.</diffmk:wrapper></para> + </entry> + + <entry> + <para><diffmk:wrapper diffmk:change="changed">[Hibernate Configured connection]</diffmk:wrapper></para> + </entry> + </row> + + <row> + <entry> + <para>Property file</para> + </entry> + + <entry> + <para>Path to a hibernate.properties file</para> + </entry> + + <entry> + <para>First hibernate.properties file found in the selected project</para> + </entry> + </row> + + <row> + <entry> + <para>Configuration file</para> + </entry> + + <entry> + <para>Path to a hibernate.cfg.xml file</para> + </entry> + + <entry> + <para>First hibernate.cfg.xml file found in the selected project</para> + </entry> + </row> + + <row> + <entry> + <para>Persistence unit</para> + </entry> + + <entry> + <para>Name of the persistence unit to use</para> + </entry> + + <entry> + <para>No default value (lets Hibernate Entity Manager find the persistence + unit)</para> + </entry> + </row> + + </tbody> + </tgroup> + </table> + + <tip diffmk:change="added"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Tip:</diffmk:wrapper></title> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">The two latter settings are normally not required if you specify a project and it has </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"> + <literal diffmk:change="added" moreinfo="none"> <diffmk:wrapper diffmk:change="added">/hibernate.cfg.xml </diffmk:wrapper></literal> + </property> + </emphasis> <diffmk:wrapper diffmk:change="added">or </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"> + <literal diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">/META-INF/persistence.xml</diffmk:wrapper></literal> + </property> + </emphasis> <diffmk:wrapper diffmk:change="added">in its project classpath.</diffmk:wrapper></para> + </tip> + + + <itemizedlist diffmk:change="added"> + <listitem diffmk:change="added"> + <para diffmk:change="added"> + <emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Options</diffmk:wrapper></property> + </emphasis> <diffmk:wrapper diffmk:change="added">for the additional/optional settings</diffmk:wrapper></para> + </listitem> + </itemizedlist> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Options Tab of the Console Configuration Wizard</diffmk:wrapper></title> + + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/plugins/plugins_2_a.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">The next table describes Hibernate Console Configuration options available on the </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Options</diffmk:wrapper></property> + </emphasis> <diffmk:wrapper diffmk:change="added">tab.</diffmk:wrapper></para> + + <table diffmk:change="added"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Hibernate Console Configuration Options</diffmk:wrapper></title> + + <tgroup cols="3" diffmk:change="added"> + <colspec align="left" colnum="1" colwidth="1*" diffmk:change="added"></colspec> + + <colspec colnum="2" colwidth="3*" diffmk:change="added"></colspec> + + <colspec align="left" colnum="3" colwidth="1*" diffmk:change="added"></colspec> + + <thead diffmk:change="added"> + <row diffmk:change="added"> + <entry align="center" diffmk:change="added"> + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Parameter</diffmk:wrapper></para> + </entry> + + <entry align="center" diffmk:change="added"> + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Description</diffmk:wrapper></para> + </entry> + + <entry align="center" diffmk:change="added"> + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Auto detected value</diffmk:wrapper></para> + </entry> + </row> + </thead> + + <tbody diffmk:change="added"> + + + <row> + <entry> + <para>Naming strategy</para> + </entry> + + <entry> + <para>Fully qualified classname of a custom NamingStrategy. Only required if you use a + special naming strategy.</para> + </entry> + + <entry> + <para>No default value</para> + </entry> + </row> + + <row> + <entry> + <para>Entity resolver</para> + </entry> + + <entry> + <para>Fully qualified classname of a custom EntityResolver. Only required if you have + special xml entity includes in your mapping files.</para> + </entry> + + <entry> + <para>No default value</para> + </entry> + </row> + + </tbody> + </tgroup> + </table> + + <itemizedlist diffmk:change="added"> + <listitem diffmk:change="added"> + <para diffmk:change="added"><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Classpath</diffmk:wrapper></property> + </emphasis> <diffmk:wrapper diffmk:change="added">for classpath</diffmk:wrapper></para> + </listitem> + </itemizedlist> + + <figure float="0"> + <title>Specifying Classpath in Hibernate Console Configuration</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_3.png" format="PNG"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_3.png" format="PNG"></imagedata> + </imageobject> + + </mediaobject> + </figure> + + <para>The <diffmk:wrapper diffmk:change="changed">following </diffmk:wrapper>table specifies the parameters of the Classpath tab of the wizard.</para> + + <table> + <title>Hibernate Console Configuration Classpath</title> + + <tgroup cols="3"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + + <colspec colnum="2" colwidth="3*"></colspec> + + <colspec colnum="3" colwidth="1*"></colspec> + + <thead> + <row> + <entry align="center"> + <para>Parameter</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + + <entry align="center"> + <para>Auto detected value</para> + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>Classpath</para> + </entry> + + <entry> + <para>The classpath for loading POJO and JDBC drivers; only needed if the default + classpath of the Project does not contain the required classes. Do not add Hibernate + core libraries or dependencies, they are already included. If you get ClassNotFound + errors then check this list for possible missing or redundant + directories/jars.</para> + </entry> + + <entry> + <para>Empty</para> + </entry> + </row> + + <row> + <entry> + <para>Include default classpath from project</para> + </entry> + + <entry> + <para>When enabled the project classpath will be appended to the classpath specified + above</para> + </entry> + + <entry> + <para>Enabled</para> + </entry> + </row> + + </tbody> + </tgroup> + </table> + + <itemizedlist diffmk:change="added"> + <listitem diffmk:change="added"> + <para><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Mappings</diffmk:wrapper></property> + </emphasis> <diffmk:wrapper diffmk:change="added">for additional mappings</diffmk:wrapper></para> + </listitem> + </itemizedlist> + + <figure float="0"> + <title>Specifying additional Mappings in Hibernate Console Configuration</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_4.png" format="PNG"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_4.png" format="PNG"></imagedata> + + </imageobject> + </mediaobject> + </figure> + + + + + <para>Parameters of the Mappings tab <diffmk:wrapper diffmk:change="changed">of </diffmk:wrapper>the <property moreinfo="none">Hibernate Console Configuration + wizard</property> are explained below:</para> + <table> + <title>Hibernate Console Configuration Mappings</title> + + <tgroup cols="3"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + + <colspec colnum="2" colwidth="3*"></colspec> + + <colspec colnum="3" colwidth="1*"></colspec> + + <thead> + <row> + <entry align="center"> + <para>Parameter</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + + <entry align="center"> + <para>Auto detected value</para> + + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>Mapping files </para> + </entry> + + <entry> + <para>List of additional mapping files that should be loaded. Note: A + hibernate.cfg.xml or persistence.xml can also contain mappings. Thus if these are + duplicated here, you will get "Duplicate mapping" errors when using the console + configuration.</para> + </entry> + + <entry> + <para>empty</para> + + </entry> + </row> + </tbody> + </tgroup> + </table> + + <itemizedlist diffmk:change="added"> + <listitem diffmk:change="added"> + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">and the last tab </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Common</diffmk:wrapper></property> + </emphasis></para> + </listitem> + </itemizedlist> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Common Tab of the Console Configuration Wizard</diffmk:wrapper></title> + + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/plugins/plugins_4_a.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para><diffmk:wrapper diffmk:change="added">It allows to define general aspects of the launch configuration including storage + location, console encoding and some others.</diffmk:wrapper></para> + + <para diffmk:change="added">Clicking <emphasis> + <property moreinfo="none">Finish</property> + </emphasis> creates the configuration and shows it in the <property moreinfo="none">Hibernate Configurations + <diffmk:wrapper diffmk:change="changed">view</diffmk:wrapper></property>.</para> + + <figure float="0"> + <title>Console Overview</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_5.png" format="PNG"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_5.png" format="PNG"></imagedata> + </imageobject> + + </mediaobject> + </figure> + </section> + + <section> + <title>Reverse Engineering and Code Generation</title> + + <para>A "click-and-generate" reverse engineering and code generation facility is available. This + facility allows you to generate a range of artifacts based on database or an already existing + Hibernate configuration, be that mapping files or annotated classes. Some of these are POJO + Java source file, Hibernate <emphasis> + <property moreinfo="none">.hbm.xml</property> + </emphasis>, <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> generation and schema documentation.</para> + + <para>To start working with this process, start the <property moreinfo="none">Hibernate Code + Generation</property> which is available in the toolbar via the <property moreinfo="none">Hibernate</property> + icon or via the <emphasis> + <property moreinfo="none">Run &gt; Hibernate Code Generation</property> + </emphasis> menu item.</para> + + <section id="code_gen"> + <title>Code Generation Launcher</title> + + <para>When you click on <emphasis> + <property moreinfo="none">Open Hibernate Code Generation Dialog...</property> + </emphasis> the standard Eclipse launcher dialog will appear. In this dialog you can create, + edit and delete named Hibernate code generation "launchers".</para> + + <figure float="0" id="hib_code_gen"> + <title>Getting Hibernate Code Generation Wizard</title> + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="images/plugins/plugins_6.png" format="PNG"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_6.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para></para> + + <figure float="0"> + <title>Hibernate Code Generation Wizard</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_7.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_7.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The first time you create a code generation launcher you should give it a meaningful + name, otherwise the default prefix <emphasis> + <property moreinfo="none">New_Generation</property> + </emphasis> will be used.</para> + + <tip> + <title>Tip:</title> + <para>The "At least one exporter option must be selected" is just a + warning stating that for this launch to work you need to select an exporter on the + Exporter tab. When an exporter has been selected the warning will disappear.</para> + </tip> + + <para>The dialog also have the standard tabs <emphasis> + <property moreinfo="none">Refresh</property> + </emphasis> and <emphasis> + <property moreinfo="none">Common</property> + </emphasis> that can be used to configure which directories should be automatically + refreshed and various general settings launchers, such as saving them in a project for + sharing the launcher within a team.</para> + + <para>On the <emphasis> + <property moreinfo="none">Main</property> + </emphasis> tab you see the following fields:</para> + + <table> + <title>Code generation "Main" tab fields</title> + + <tgroup cols="2"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + + <colspec colnum="2" colwidth="3*"></colspec> + + <colspec colnum="3" colwidth="0.5*"></colspec> + + <thead> + <row> + <entry align="center"> + <para>Field</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>Console Configuration</para> + </entry> + + <entry> + <para>The name of the console configuration which should be used when code + generating</para> + </entry> + </row> + + <row> + <entry> + <para>Output directory</para> + </entry> + + <entry> + <para>Path to a directory where all output will be written by default. Be aware that + existing files will be overwritten, so be sure to specify the correct + directory.</para> + </entry> + </row> + + <row> + <entry> + <para>Reverse engineer from JDBC Connection</para> + </entry> + + <entry> + <para>If enabled, the tools will reverse engineer the database available via the + connection information in the selected Hibernate Console Configuration and + generate code based on the database schema. If not enabled, the code generation + will just be based on the mappings already specified in the Hibernate Console + configuration.</para> + </entry> + </row> + + <row> + <entry> + <para>Package</para> + </entry> + + <entry> + <para>The package name here is used as the default package name for any entities + found when reverse engineering</para> + </entry> + </row> + + <row> + <entry> + <para>reveng.xml</para> + </entry> + + <entry> + <para>Path to a reveng.xml file. A reveng.xml file allows you to control certain + aspects of the reverse engineering. e.g. how jdbc types are mapped to hibernate + types and especially important which tables are included/excluded from the + process. Clicking "setup" allows you to select an existing reveng.xml file or + create a new one. See more details about the reveng.xml file in <xref linkend="reverseengineering"></xref>.</para> + </entry> + </row> + + <row> + <entry> + <para>reveng. strategy</para> + </entry> + + <entry> + <para>If reveng.xml does not provide enough customization you can provide your own + implementation of an ReverseEngineeringStrategy. The class needs to be in the + classpath of the Console Configuration, otherwise you will get class not found + exceptions. See <xref linkend="custom-reveng-strategy"></xref> for details and an + example of a custom strategy.</para> + </entry> + </row> + + <row> + <entry> + <para>Generate basic typed composite ids</para> + </entry> + + <entry> + <para>A table that has a multi-colum primary key a &lt;composite-id&gt; + mapping will always be created. If this option is enabled and there are matching + foreign-keys each key column is still considered a 'basic' scalar (string, long, + etc.) instead of a reference to an entity. If you disable this option a + &lt;key-many-to-one&gt; instead. Note: a &lt;many-to-one&gt; + property is still created, but is simply marked as non-updatable and + non-insertable.</para> + </entry> + </row> + + <row> + <entry> + <para>Detect optimistic lock columns</para> + </entry> + + <entry> + <para>Automatically detect optimistic lock columns. Controllable via reveng. + strategy; the current default is to use columns named VERSION or TIMESTAMP.</para> + </entry> + </row> + + <row> + <entry> + <para>Detect many-to-many tables</para> + </entry> + + <entry> + <para>Automatically detect many-to-many tables. Controllable via reveng. + strategy.</para> + </entry> + </row> + + <row> + <entry> + <para>Use custom templates</para> + </entry> + + <entry> + <para>If enabled, the Template directory will be searched first when looking up the + templates, allowing you to redefine how the individual templates process the + hibernate mapping model.</para> + </entry> + </row> + + <row> + <entry> + <para>Template directory</para> + </entry> + + <entry> + <para>A path to a directory with custom templates</para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section> + <title>Exporters</title> + + <para>The <emphasis> + <property moreinfo="none">Exporters</property> + </emphasis> tab is used to specify which type of code that should be generated. Each + selection represents an Exporter that is responsible for generating the code, hence the + name.</para> + + <figure float="0"> + <title>Selecting Exporters</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_8.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_8.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The following table describes in short the various exporters. Remember you can + add/remove any Exporters depending on your needs.</para> + + <table> + <title>Code generation "Exporter" tab fields</title> + + <tgroup cols="2"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + + <colspec colnum="2" colwidth="3*"></colspec> + + <thead> + <row> + <entry align="center"> + <para>Field</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>Domain code</para> + </entry> + + <entry> + <para>Generates POJO's for all the persistent classes and components found in the + given Hibernate configuration.</para> + </entry> + </row> + + <row> + <entry> + <para>DAO code</para> + </entry> + + <entry> + <para>Generates a set of DAO's for each entity found.</para> + </entry> + </row> + + <row> + <entry> + <para>Hibernate XML Mappings</para> + </entry> + + <entry> + <para>Generate mapping (hbm.xml) files for each entity.</para> + </entry> + </row> + + <row> + <entry> + <para>Hibernate XML Configuration</para> + </entry> + + <entry> + <para>Generate a hibernate.cfg.xml file. Used to keep the hibernate.cfg.xml update + with any new found mapping files.</para> + </entry> + </row> + + <row> + <entry> + <para>Schema Documentation (.html)</para> + </entry> + + <entry> + <para>Generates a set of html pages that documents the database schema and some of + the mappings.</para> + </entry> + </row> + + <row> + <entry> + <para>Generic Exporter (hbmtemplate)</para> + </entry> + + <entry> + <para>Fully customizable exporter which can be used to perform custom + generation.</para> + </entry> + </row> + + </tbody> + </tgroup> + </table> + + <para>Each Exporter listens to certain properties and these can be setup in the <emphasis> + <property moreinfo="none">Properties</property> + </emphasis> section where you can add/remove predefined or customer properties for each of + the exporters. The following table lists the time of writing predefined properties:</para> + + <para> + <table> + <title>Exporter Properties</title> + + <tgroup cols="2"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + + <colspec colnum="2" colwidth="3*"></colspec> + + <thead> + <row> + <entry align="center"> + <para>Name</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>jdk5</para> + </entry> + + <entry> + <para>Generate Java 5 syntax</para> + </entry> + </row> + + <row> + <entry> + <para>ejb3</para> + </entry> + + <entry> + <para>Generate EJB 3 annotations</para> + </entry> + </row> + + <row> + <entry> + <para>for_each</para> + </entry> + + <entry> + <para>Specifies for which type of model elements the exporter should create a file + and run through the templates. Possible values are: entity, component, + configuration</para> + </entry> + </row> + + <row> + <entry> + <para>template_path</para> + </entry> + + <entry> + <para>Custom template directory for this specific exporter. You can use Eclipse + variables.</para> + </entry> + </row> + + <row> + <entry> + <para>template_name</para> + </entry> + + <entry> + <para>Name for template relative to the template path</para> + </entry> + </row> + + <row> + <entry> + <para>outputdir</para> + </entry> + + <entry> + <para>Custom output directory for this specific exporter. You can use Eclipse + variables.</para> + </entry> + </row> + + <row> + <entry> + <para>file_pattern</para> + </entry> + + <entry> + <para>Pattern to use for the generated files, relatively for the output dir. + Example: {package-name}/{class-name}.java .</para> + </entry> + </row> + + + + <row> + <entry> + <para>dot.executable</para> + </entry> + + <entry> + <para>Executable to run GraphViz (only relevant, but optional for Schema + documentation)</para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </section> + </section> + + <section id="map_config_editor"> + <title>Hibernate Mapping and Configuration File Editor</title> + + <para>The <property moreinfo="none">Hibernate Mapping File editor</property> provides XML editing functionality + for the <emphasis> + <property moreinfo="none">hbm.xml </property> + </emphasis> and <emphasis> + <property moreinfo="none">cfg.xml</property> + </emphasis> files. The editor is based on the Eclipse WTP tools and extends its functionality + to provide Hibernate specific code completion.</para> + + <figure float="0"> + <title>XML Editing Functionality</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_9.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_9.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <section> + <title>Java property/class completion</title> + + <para>Package, class, and field completion is enabled for relevant XML attributes. The + auto-completion detects its context and limits the completion for e.g. <emphasis> + <property moreinfo="none">&lt;property&gt;</property> + </emphasis> and only shows the properties/fields available in the enclosing <emphasis> + <property moreinfo="none">&lt;class&gt;</property> + </emphasis>, <emphasis> + <property moreinfo="none">&lt;subclass&gt;</property> + </emphasis> etc. It is also possible to navigate from the <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> files to the relevant class/field in java code.</para> + + <figure float="0"> + <title>Navigation Functionality</title> + + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_10.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_10.png" format="PNG"></imagedata> + + </imageobject> + </mediaobject> + + </figure> + + <para>This is done via the standard hyperlink navigation functionality in Eclipse; per default + it is done by pressing F3 while the cursor is on a class/field or by pressing <emphasis> + <property moreinfo="none">Ctrl</property> + </emphasis> and the mouse button to perform the same navigation.</para> + + <para>For java completion and navigation to work the file needs to reside inside an Eclipse + Java project, otherwise no completion will occur.</para> + <note> + <title>Note:</title> + <para>Java completion does not require a Hibernate console configuration to be used.</para> + </note> + </section> + + <section> + <title>Table/Column completion</title> + + <para>Table and column completion is also available for all table and column attributes. </para> + + <figure float="0"> + <title>Table and Column Completion</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_11.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_11.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <important> + <title>Important:</title> + <para>Table/Column completion requires a proper configured hibernate console configuration + and this configuration should be the default for the project where the <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> resides.</para> + </important> + + <para>You can check which console configuration is selected under the Properties of a project + and look under the <emphasis> + <property moreinfo="none">Hibernate Settings</property> + </emphasis> page. When a proper configuration is selected it will be used to fetch the + table/column names in the background.</para> + + <note> + <title>Note:</title> + <para>Currently it is not recommended to use this feature on large databases since it does + not fetch the information iteratively. It will be improved in future versions.</para> + </note> + </section> + + <section> + <title>Configuration property completion</title> + + <para>In <emphasis> + <property moreinfo="none">cfg.xml</property> + </emphasis> code completion for the value of <emphasis> + <property moreinfo="none">&lt;property&gt; name</property> + </emphasis> attributes is available.</para> + + + <figure float="0"> + <title>Property Completion</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_12.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_12.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + </section> + </section> + + <section id="map_config_struct_editor" revisionflag="added"> + <title>Structured Hibernate Mapping and Configuration File Editor</title> + <para>The structured editor represents the file in the tree form. It also allows to modify the + structure of the file and its elements with the help of tables provided on the right-hand + area.</para> + + <para>To open any mapping file in the editor, choose <emphasis> + <property moreinfo="none">Open With &gt; Hibernate 3.0 XML Editor</property> + </emphasis> option from the context menu of the file. The editor should look as follows:</para> + + <figure float="0"> + <title>Structured hbm.xml Editor</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_12_a.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>For the configuration file you should choose <emphasis> + <property moreinfo="none">Open With &gt; Hibernate Configuration 3.0 XML Editor</property> + </emphasis>option.</para> + + <figure float="0"> + <title>Structured cfg.xml Editor</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_12_b.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + </section> + + <section id="rev_xml_editor"> + <title>Reveng.xml Editor</title> + + <para>A <emphasis> + <property moreinfo="none">reveng.xml </property> + </emphasis> file is used to customize and control how reverse engineering is performed by the + tools. The plugins provide an editor to ease the editing of this file and hence used to + configure the reverse engineering process.</para> + + <para>The editor is intended to allow easy definition of type mappings, table include/excludes + and specific override settings for columns, e.g. define an explicit name for a column when the + default naming rules are not applicable.</para> + + <note> + <title>Note:</title> + <para> Not all the features of the <emphasis> + <property moreinfo="none">.reveng.xml </property> + </emphasis> file are exposed or fully implemented in the editor, but the main functionality + is there. To understand the full flexibility of the <emphasis> + <property moreinfo="none">reveng.xml</property> + </emphasis>, please see <xref linkend="hibernaterevengxmlfile"></xref> + </para> + </note> + + <para>The editor is activated as soon as an <emphasis> + <property moreinfo="none">.reveng.xml </property> + </emphasis> file is opened. To get an initial <emphasis> + <property moreinfo="none">reveng.xml </property> + </emphasis> file the <property moreinfo="none">Reverse Engineering File Wizard</property> can be started via <emphasis> + <property moreinfo="none">Ctrl+N</property> + </emphasis> and <emphasis> + <property moreinfo="none">Hibernate &gt; Hibernate Reverse Engineering File (reveng.xml)</property> + </emphasis> then.</para> + + <figure float="0"> + <title>Overview Page</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_22.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_22.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Or you can get it via the <property moreinfo="none">Code Generation Launcher</property> by checking the + proper section in the <emphasis> + <property moreinfo="none">Main</property> + </emphasis> tab of the <link linkend="hib_code_gen">Hibernate Code Generation Wizard</link>.</para> + + <para>The following screenshot shows the <emphasis> + <property moreinfo="none">Overview</property> + </emphasis> page where the wanted console configuration is selected (auto-detected if + Hibernate 3 support is enabled for the project)</para> + + <figure float="0"> + <title>Overview Page</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_13.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_13.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The <emphasis> + <property moreinfo="none">Table Filter</property> + </emphasis> page allows you to specify which tables to include and exclude. Pressing <emphasis> + <property moreinfo="none">Refresh</property> + </emphasis> shows the tables from the database that have not yet been excluded.</para> + + <figure float="0"> + <title>Table Filters Page</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_14.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_14.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The <emphasis> + <property moreinfo="none">Type Mappings</property> + </emphasis> page is used for specifying type mappings from JBDC types to any Hibernate type + (including usertypes) if the default rules are not applicable. Here again to see the database + tables press <emphasis> + <property moreinfo="none">Refresh</property> + </emphasis> button underneath. More about type mappings you can find further in the <link linkend="type_map">Type Mappings</link> section.</para> + + <figure float="0"> + <title>Type Mappings Page</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_15.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_15.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The <emphasis> + <property moreinfo="none">Table and Columns</property> + </emphasis> page allows you to explicit set e.g. which hibernatetype and propertyname that + should be used in the reverse engineered model. For more details on how to configure the + tables while reverse engineering read the <link linkend="tab_and_col">Specific table + configuration</link> section.</para> + + <figure float="0"> + <title>Table and Columns Page</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_16.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_16.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Now that you have configured all necessary parts, you can learn how to work with + <property moreinfo="none">Hibernate Console Perspective</property>.</para> + </section> + + <section id="hib_console"> + <title>Hibernate Console Perspective</title> + + <para>The <property moreinfo="none">Hibernate Console Perspective</property> combines a set of views which allow + you to see the structure of your mapped entities/classes, edit HQL queries, execute the + queries, and see the results. To use this perspective you need to create a <link linkend="console_conf">Console configuration</link>.</para> + + <section> + <title>Viewing the entity structure</title> + + <para>To view your new configuration and entity/class structure, switch to <property moreinfo="none">Hibernate + Configurations View</property>. Expanding the tree allows you to browse the class/entity + structure and see the relationships.</para> + + <figure float="0"> + <title>Hibernate Console Perspective</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_17.png" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_17.png"></imagedata> + </imageobject> + </mediaobject> + + </figure> + + <para>The <property moreinfo="none">Console Configuration</property> does not dynamically adjust to changes + done in mappings and java code. To reload the configuration select the configuration and + click the <emphasis> + <property moreinfo="none">Reload</property> + </emphasis> button in the view toolbar or in the context menu.</para> + + <para>Besides, it's possible to open source and mapping files for objects showed in + <property moreinfo="none">Hibernate Configurations View</property>. Just bring up the context menu for a + necessary object and select <emphasis> + <property moreinfo="none">Open Source File</property> + </emphasis> to see appropriate Java class or <emphasis> + <property moreinfo="none">Open Mapping File</property> + </emphasis> to open a proper <emphasis> + <property moreinfo="none">.hbm.xml</property>.</emphasis></para> + + <figure float="0"> + <title>Opening Source for Objects</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_17_a.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <section id="map_diagram"> + <title>Mapping Diagram</title> + + <para>In order to get a visual feel on how entities are related as well as view their + structures, a <property moreinfo="none">Mapping Diagram</property> is provided. It is available by right + clicking on the entity you want a mapping diagram for and then choosing <emphasis> + <property moreinfo="none">Open Mapping Diagram</property>.</emphasis></para> + + <figure float="0"> + <title>Mapping Diagram</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_18.png" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_18.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>For better navigating on the Diagram use <property moreinfo="none">Outline view</property> which is + available in the structural and graphical modes.</para> + <figure float="0"> + <title>Navigating in the Structural Mode</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_18_a.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>To switch over between the modes use the buttons in the top-right corner of the + <property moreinfo="none">Outline view</property>.</para> + + <figure float="0"> + <title>Navigating in the Graphical Mode</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_18_b.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>As in <property moreinfo="none">Hibernate Configurations View</property> in <property moreinfo="none">Mapping + Diagram</property> it's also possible to open source/mapping file for a chosen + object by selecting appropriate option in the context menu. </para> + + <figure float="0"> + <title>Navigating on the Diagram</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_18_c.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>If you ask to open source/mapping file by right clicking on any entity element, this + element will be highlighted in the open file.</para> + + <figure float="0"> + <title>Opening Source for Object</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_18_d.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Finally, if you need to have your Diagram exported as <emphasis><property moreinfo="none">.png + </property>,</emphasis> + <emphasis> + <property moreinfo="none">.jpeg</property> + </emphasis> or <emphasis><property moreinfo="none">.bmp </property>,</emphasis> you should right-click + anywhere in the <property moreinfo="none">Mapping Diagram editor</property> and select <emphasis> + <property moreinfo="none">Export as Image</property> + </emphasis>.</para> + + <figure float="0"> + <title>Mapping Diagram Export</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_18_e.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>As you can see on the figure above, <emphasis><property moreinfo="none">Undo</property>, </emphasis> + <emphasis> + <property moreinfo="none">Redo</property> + </emphasis> and <emphasis> + <property moreinfo="none">Auto layout </property> + </emphasis> options are also available through the context menu.</para> + </section> + </section> + + <section revisionflag="changed"> + <title>Prototyping Queries</title> + + <para>Queries can be prototyped by entering them in the <property moreinfo="none">HQL</property> or + <property moreinfo="none">Criteria Editor</property>. The query editors are opened by right-clicking the + <property moreinfo="none">Console Configuration</property> and selecting either <property moreinfo="none">HQL + Editor</property> or <property moreinfo="none">Hibernate Criteria Editor</property>. The editors + automatically detect the chosen configuration.</para> + + <para>If the menu item is disabled then you need at first to create a <property moreinfo="none">Session + Factory</property>. That is done by simply expanding the <property moreinfo="none">Session + Factory</property> node.</para> + + <para>By brining up the context menu for a chosen entity or property in the <property moreinfo="none">Console + Configuration</property> and opening <emphasis> + <property moreinfo="none">HQL Editor</property> + </emphasis> or <emphasis> + <property moreinfo="none">Hibernate Criteria Editor</property> + </emphasis> you'll get a prefill query.</para> + + <figure float="0"> + <title>Entering Simple Queries</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_19.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_19.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>To copy a portion of code from .java file into a HQL or Criteria editor, make use of the + Quick Fix option (Ctrl + 1).</para> + + <figure float="0"> + <title>Quick Fix Option Demonstration</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_19_b.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>You can also update the original java code according to changes in the HQL or Criteria + editor. For that you should save your HQL/Criteria query and submit the replacing in + appeared confirmation dialog.</para> + + <figure float="0"> + <title>Updating Java Code</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_19_c.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Executing the query is done by clicking the green run button in the toolbar or pressing <emphasis> + <property moreinfo="none">Ctrl+Enter</property> + </emphasis>.</para> + + <para>Errors during creation of the <property moreinfo="none">Session Factory</property> or running the + queries (e.g. if your configuration or query is incorrect) will be shown in a message dialog + or inclined in the view that detected the error, you may get more information about the + error in the <property moreinfo="none">Error Log View</property> on the right pane.</para> + + <para>Results of a query will be shown in the <property moreinfo="none">Hibernate Query Result View</property> + and details of possible errors (syntax errors, database errors, etc.) can be seen in the + <property moreinfo="none">Error Log View</property>.</para> + + + <note> + <title>Note:</title> + <para>HQL queries are executed by default using <literal moreinfo="none">list()</literal> thus without any + limit of the size of the output the query could return a large result set. You might run + out of memory. To avoid this you can put a value in the Max results field to reduce the + number of elements returned.</para> + </note> + + <section> + <title>Dynamic Query Translator</title> + + <para>If the <property moreinfo="none">Hibernate Dynamic Query Translator View</property> is visible while + writing in the <property moreinfo="none">HQL Editor</property> it will show the generated SQL for a HQL + query.</para> + + <figure float="0"> + <title>Hibernate Dynamic Query Translator View</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_20.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_20.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The translation is done each time you stop typing into the editor, if there are errors + in the HQL the parse exception will be shown embedded in the view.</para> + </section> + </section> + + <section> + <title>Properties View</title> + + <para>As you can see on the figure, <property moreinfo="none">Properties view</property> shows the number of + query results as well as the time of executing.</para> + + <figure float="0"> + <title>Properties View</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_21_a.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_21_a.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>It also displays the structure of any persistent object selected in the + <property moreinfo="none">Hibernate Query Results View</property>. Editing is not yet supported.</para> + + <figure float="0"> + <title>Properties View for Selected Object</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_21_b.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_21_b.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + </section> + + <section id="debug_log"> + <title>Enable debug logging in the plugins</title> + + <para>It is possible to configure the eclipse plugin to route all logging made by the plugins + and hibernate code it self to the <property moreinfo="none">Error Log View</property> in Eclipse.</para> + + <para>This is done by editing the <emphasis> + <property moreinfo="none">hibernate-log4j.properties</property> + </emphasis> in <emphasis> + <property moreinfo="none">org.hibernate.eclipse/ directory/jar</property> + </emphasis>. This file includes a default configuration that only logs WARN and above to a set + of custom appenders (PluginFileAppender and PluginLogAppender). You can change these settings + to be as verbose or silent as you please - see <ulink url="http://www.hibernate.org/5.html">Hibernate Documentation</ulink> for interesting categories and Log4j documentation.</para> + + <section> + <title>Relevant Resources Links</title> + <para>Find more on how to configure logging via a log4j property file in <ulink url="http://supportweb.cs.bham.ac.uk/docs/tutorials/docsystem/build/tutorials/log4j/log4j.html">Log4j documentation</ulink>.</para> + </section> + </section> + + <section diffmk:change="added" id="dali_integration" role="new"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Hibernate support for Dali plugins in Eclipse WTP</diffmk:wrapper></title> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Starting from 3.0.0 Alpha1 version of </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Tools</diffmk:wrapper></property> <diffmk:wrapper diffmk:change="added">Hibernate plugins + support Eclipse Dali integration what now makes it possible to use a Hibernate as a complete + JPA development platform.</diffmk:wrapper></para> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">When starting your new JPA project from </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">New &gt; Other... &gt; JPA &gt; JPA Project</diffmk:wrapper></property> + </emphasis> <diffmk:wrapper diffmk:change="added">(or simply </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">New &gt; JPA Project</diffmk:wrapper></property> + </emphasis> <diffmk:wrapper diffmk:change="added">in </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JPA Perspective</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added">) on the JPA Facet page you'll be + prompted to choose Hibernate as a target platform.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Targeting at Hibernate Platform</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/plugins/plugins_23.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">By enabling Hibernate platform specific features you can now generate DDL and Entities. + For that find </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JPA Tools &gt; Generate DDL.../Generate Entities...</diffmk:wrapper></property> + </emphasis> <diffmk:wrapper diffmk:change="added">options in the context menu of your JPA project.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Generate DDL/Entities</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/plugins/plugins_24.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">The Generate DDL/Entities wizards first will ask you to choose the </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Console + Configuration</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Generate Entities Wizard</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/plugins/plugins_25.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <note diffmk:change="added"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Note:</diffmk:wrapper></title> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Please note, currently the wizards require that you have a </diffmk:wrapper><link diffmk:change="added" linkend="console_conf"><diffmk:wrapper diffmk:change="added">Hibernate Console Configuration</diffmk:wrapper></link> <diffmk:wrapper diffmk:change="added">already configured.</diffmk:wrapper></para> + </note> + </section> +</chapter> + + +<chapter id="ant" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/hibernatetools/docs/reference/en/modules/ant.xml"> + <title>Ant Tools</title> + + <para>Maybe somebody will find it more preferable to use Ant for generation purposes. Thus, this + chapter is intended to get you ready to start using Hibernate Tools via Ant tasks.</para> + + <section> + <title>Introduction</title> + + <para>The <emphasis> + <property moreinfo="none">hibernate-tools.jar</property> + </emphasis> contains the core for the <property moreinfo="none">Hibernate Tools</property>. It is used as the + basis for both the Ant tasks described in this document and the eclipse plugins both available + from tools.hibernate.org. The <emphasis> + <property moreinfo="none">hibernate-tools.jar</property> + </emphasis> is located in your eclipse plugins directory at <emphasis> + <property moreinfo="none">/plugins/org.hibernate.eclipse.x.x.x/lib/tools/hibernate-tools.jar</property>.</emphasis></para> + <para>This jar is 100% independent from the eclipse platform and can thus be used independently + of eclipse.</para> + + <note> + <title>Note:</title> + <para>There might be incompatibilities with respect to the Hibernate3.jar bundled with the + tools and your own jar. Thus to avoid any confusion it is recommended to use the + hibernate3.jar and hibernate-annotations.jar bundled with the tools when you want to use the + Ant tasks. Do not worry about using e.g. Hibernate 3.2 jar's with e.g. a Hibernate 3.1 + project since the output generated will work with previous Hibernate 3 versions. </para> + </note> + </section> + + <section> + <title>The &lt;hibernatetool&gt; Ant Task</title> + + <para>To use the ant tasks you need to have the <emphasis> + <property moreinfo="none">hibernatetool</property> + </emphasis> task defined. That is done in your <emphasis> + <property moreinfo="none">build.xml</property> + </emphasis> by inserting the following xml (assuming the jars are in the + <literal moreinfo="none">lib</literal> directory): </para> + + <programlisting format="linespecific" role="XML">&lt;path id="toolslib"&gt; + &lt;path location="lib/hibernate-tools.jar" /&gt; + &lt;path location="lib/hibernate3.jar" /&gt; + &lt;path location="lib/freemarker.jar" /&gt; + &lt;path location="${jdbc.driver.jar}" /&gt; +&lt;/path&gt; + +&lt;taskdef name="hibernatetool" + classname="org.hibernate.tool.ant.HibernateToolTask" + classpathref="toolslib" /&gt; +</programlisting> + + <para>This <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;taskdef&gt;</literal> + </property> + </emphasis> defines an Ant task called <emphasis> + <property moreinfo="none"> hibernatetool </property> + </emphasis> which now can be used anywhere in your ant <emphasis> + <property moreinfo="none">build.xml</property> + </emphasis> files. It is important to include all the <property moreinfo="none">Hibernate Tools</property> + dependencies as well as the jdbc driver.</para> + + <para>Notice that to use the annotation based Configuration you must <ulink url="http://annotations.hibernate.org">get a release</ulink>. </para> + + <para></para> + + <para>When using the <emphasis> + <property moreinfo="none"> hibernatetool </property> + </emphasis> task you have to specify one or more of the following:</para> + + <programlisting format="linespecific" role="XML">&lt;hibernatetool + destdir="defaultDestinationDirectory" + templatepath="defaultTemplatePath" +&gt; + &lt;classpath ...&gt; + &lt;property key="propertyName" value="value"/&gt; + &lt;propertyset ...&gt; + (&lt;configuration ...&gt;|&lt;annotationconfiguration ...&gt;| + &lt;jpaconfiguration ...&gt;|&lt;jdbcconfiguration ...&gt;) + (&lt;hbm2java&gt;,&lt;hbm2cfgxml&gt;,&lt;hbmtemplate&gt;,...) +&lt;/hibernatetool&gt;</programlisting> + + <table frame="topbot"> + <title>Hibernatetool attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>destdir</para> + </entry> + + <entry> + <para>Destination directory for files generated with exporters</para> + </entry> + + <entry> + <para>Required</para> + </entry> + </row> + + <row> + <entry> + <para>templatepath</para> + </entry> + + <entry> + <para>A path to be used to look up user-edited templates</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>classpath</para> + </entry> + + <entry> + <para>A classpath to be used to resolve resources, such as mappings and + usertypes</para> + </entry> + + <entry> + <para>Optional, but very often required</para> + </entry> + </row> + + + <row> + <entry> + <para>property (and propertyset)</para> + </entry> + + <entry> + <para>Used to set properties to control the exporters. Mostly relevant for providing + custom properties to user defined templates</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>configuration (annotationconfiguration, jpaconfiguration, + jdbcconfiguration)</para> + </entry> + + <entry> + <para>One of four different ways of configuring the Hibernate Meta Model must be + specified</para> + </entry> + + <entry> + <para></para> + </entry> + </row> + + <row> + <entry> + <para>hbm2java (hbm2cfgxml, hbmtemplate, etc.)</para> + </entry> + + <entry> + <para>One or more of the exporters must be specified</para> + </entry> + + <entry> + <para></para> + </entry> + </row> + + </tbody> + + </tgroup> + </table> + + <section> + <title>Basic examples</title> + + <para>The following example shows the most basic setup for generating pojo's via <emphasis> + <property moreinfo="none">&lt;hbm2java&gt;</property> + </emphasis> from a normal <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">hibernate.cfg.xml</literal> + </property>. </emphasis> The output will be put in the <emphasis> + <property moreinfo="none">${build.dir}/generated</property> + </emphasis> directory.</para> + + <programlisting format="linespecific" role="XML">&lt;hibernatetool destdir="${build.dir}/generated"&gt; + &lt;classpath&gt; + &lt;path location="${build.dir}/classes"/&gt; + &lt;/classpath&gt; + + &lt;configuration configurationfile="hibernate.cfg.xml"/&gt; + &lt;hbm2java/&gt; +&lt;/hibernatetool&gt;</programlisting> + + + <para>The following example is similar, but now we are performing multiple exports from the + same configuration. We are exporting the schema via <emphasis> + <property moreinfo="none">&lt;hbm2dll&gt;</property>, </emphasis> generates some DAO code via <emphasis> + <property moreinfo="none">&lt;hbm2dao&gt;</property> + </emphasis> and finally runs a custom code generation via <emphasis> + <property moreinfo="none">&lt;hbmtemplate&gt;</property>. </emphasis> This is again from a normal <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> and the output is still put in the <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">${build.dir}/generated</literal> + </property> + </emphasis> directory. Furthermore the example also shows where a classpath is specified + when you e.g. have custom usertypes or some mappings that is needed to be looked up as a + classpath resource.</para> + + <programlisting format="linespecific" role="XML">&lt;hibernatetool destdir="${build.dir}/generated"&gt; + &lt;classpath&gt; + &lt;path location="${build.dir}/classes"/&gt; + &lt;/classpath&gt; + + &lt;configuration configurationfile="hibernate.cfg.xml"/&gt; + &lt;hbm2ddl/&gt; + &lt;hbm2dao/&gt; + &lt;hbmtemplate + filepattern="{package-name}/I{class-name}Constants.java" + templatepath="${etc.dir}/customtemplates" + template="myconstants.vm" + /&gt; +&lt;/hibernatetool&gt;</programlisting> + + </section> + </section> + + <section> + <title>Hibernate Configurations</title> + + <para><literal moreinfo="none">Hibernatetool</literal> supports four different Hibernate configurations: A + standard Hibernate configuration <emphasis> + (<property moreinfo="none">&lt;configuration&gt;</property>), </emphasis> Annotation based + configuration <emphasis> (<property moreinfo="none">&lt;annotationconfiguration&gt;</property>), + </emphasis> JPA persistence based configuration <emphasis> + (<property moreinfo="none">&lt;jpaconfiguration&gt;</property>) </emphasis> and a JDBC based + configuration <emphasis> (<property moreinfo="none">&lt;jdbcconfiguration&gt;</property>) </emphasis> + for use when reverse engineering.</para> + + <para>Each have in common that they are able to build up a Hibernate Configuration object from + which a set of exporters can be run to generate various output. </para> + + <note> + <title>Note:</title> + <para>Output can be anything, e.g. specific files, statements execution against a database, + error reporting or anything else that can be done in java code.</para> + </note> + + <para>The following sections describe what the various configurations can do, plus lists the + individual settings they have.</para> + + <section> + <title>Standard Hibernate Configuration (&lt;configuration&gt;)</title> + + <para>A <emphasis> + <property moreinfo="none">&lt;configuration&gt;</property> + </emphasis> is used to define a standard Hibernate configuration. A standard Hibernate + configuration reads the mappings from a <emphasis> + <property moreinfo="none">cfg.xml</property> + </emphasis> and/or a fileset.</para> + + <programlisting format="linespecific" role="XML">&lt;configuration + configurationfile="hibernate.cfg.xml" + propertyfile="hibernate.properties" + entityresolver="EntityResolver classname" + namingstrategy="NamingStrategy classname" +&gt; + &lt;fileset...&gt; + + &lt;/configuration&gt;</programlisting> + + <table frame="topbot"> + <title>Configuration attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>configurationfile</para> + </entry> + + <entry> + <para>The name of a Hibernate configuration file, e.g. "hibernate.cfg.xml"</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>propertyfile</para> + </entry> + + <entry> + <para>The name of a property file, e.g. "hibernate.properties"</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>entity-resolver</para> + </entry> + + <entry> + <para>Name of a class that implements org.xml.sax.EntityResolver. Used if the + mapping files require custom entity resolver</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + + <row> + <entry> + <para>namingstrategy</para> + </entry> + + <entry> + <para>Name of a class that implements org.hibernate.cfg.NamingStrategy. Used for + setting up the naming strategy in Hibernate which controls the automatic naming of + tables and columns.</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>fileset</para> + </entry> + + <entry> + <para>A standard Ant fileset. Used to include hibernate mapping files. Remember that + if mappings are already specified in the hibernate.cfg.xml then it should not be + included via the fileset as it will result in duplicate import exceptions.</para> + </entry> + + <entry> + <para></para> + </entry> + </row> + + </tbody> + + </tgroup> + </table> + + <section> + <title>Example</title> + + <para>This example shows an example where no <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">hibernate.cfg.xml</literal> + </property> + </emphasis> exists, and a <emphasis> + <property moreinfo="none"> hibernate.properties </property> + </emphasis> and fileset is used instead. </para> + + <note> + <title>Note:</title> + <para> Hibernate will still read any global <emphasis> + <property moreinfo="none">hibernate.properties</property> + </emphasis> available in the classpath, but the specified properties file here will + override those values for any non-global property.</para> + </note> + + <programlisting format="linespecific" role="XML">&lt;hibernatetool destdir="${build.dir}/generated"&gt; + &lt;configuration propertyfile="{etc.dir}/hibernate.properties"&gt; + &lt;fileset dir="${src.dir}"&gt; + &lt;include name="**/*.hbm.xml"/&gt; + &lt;exclude name="**/*Test.hbm.xml"/&gt; + &lt;/fileset&gt; + &lt;/configuration&gt; + + &lt;!-- list exporters here --&gt; + +&lt;/hibernatetool&gt;</programlisting> + + </section> + </section> + + <section> + <title>Annotation based Configuration (&lt;annotationconfiguration&gt;)</title> + + <para>An <emphasis> + <property moreinfo="none">&lt;annotationconfiguration&gt;</property> + </emphasis> is used when you want to read the metamodel from EJB3/Hibernate Annotations + based POJO's.</para> + + <important> + <title>Important:</title> + <para>To use it remember to put the jar files needed for using hibernate annotations in the + classpath of the <emphasis> + <property moreinfo="none">&lt;taskdef&gt;</property>, </emphasis> i. e. + hibernate-annotations.jar and hibernate-commons-annotations.jar.</para> + </important> + + <para>The <emphasis> + <property moreinfo="none">&lt;annotationconfiguration&gt;</property> + </emphasis> supports the same attributes as a <emphasis> + <property moreinfo="none">&lt;configuration&gt;</property> + </emphasis> except that the configurationfile attribute is now required as that is from + where an <literal moreinfo="none">AnnotationConfiguration</literal> gets the list of classes/packages it + should load.</para> + + <para>Thus the minimal usage is:</para> + + <programlisting format="linespecific" role="XML">&lt;hibernatetool destdir="${build.dir}/generated"&gt; + &lt;annotationconfiguration + configurationfile="hibernate.cfg.xml"/&gt; + + &lt;!-- list exporters here --&gt; + +&lt;/hibernatetool&gt; +</programlisting> + + </section> + + <section> + <title>JPA based configuration (&lt;jpaconfiguration&gt;)</title> + + <para>A <emphasis> + <property moreinfo="none">&lt;jpaconfiguration&gt;</property> + </emphasis> is used when you want to read the metamodel from JPA/Hibernate Annotation where + you want to use the auto-scan configuration as defined in the JPA spec (part of EJB3). In + other words, when you do not have a <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property>, </emphasis> but instead have a setup where you use + a <emphasis> + <property moreinfo="none">persistence.xml</property> + </emphasis> packaged in a JPA compliant manner.</para> + + <para>The <emphasis> + <property moreinfo="none">&lt;jpaconfiguration&gt;</property> + </emphasis> will simply just try and auto-configure it self based on the available + classpath, e.g. look for <emphasis> + <property moreinfo="none">META-INF/persistence.xml</property>. </emphasis></para> + + <para>The <emphasis> + <property moreinfo="none">persistenceunit</property> + </emphasis> attribute can be used to select a specific persistence unit. If no <emphasis> + <property moreinfo="none">persistenceunit</property> + </emphasis> is specified it will automatically search for one and if a unique one is found, + use it, but if multiple persistence units are available it will error.</para> + + <para>To use a <emphasis> + <property moreinfo="none">&lt;jpaconfiguration&gt;</property> + </emphasis> you will need to specify some additional jars from Hibernate EntityManager in + the <emphasis> + <property moreinfo="none">&lt;taskdef&gt;</property> + </emphasis> of the hibernatetool. The following shows a full setup:</para> + + <programlisting format="linespecific" role="XML">&lt;path id="ejb3toolslib"&gt; + &lt;path refid="jpatoolslib"/&gt; &lt;!-- ref to previously defined toolslib --&gt; + &lt;path location="lib/hibernate-annotations.jar" /&gt; + &lt;path location="lib/ejb3-persistence.jar" /&gt; + &lt;path location="lib/hibernate-entitymanager.jar" /&gt; + &lt;path location="lib/jboss-archive-browsing.jar" /&gt; + &lt;path location="lib/javaassist.jar" /&gt; +&lt;/path&gt; + +&lt;taskdef name="hibernatetool" + classname="org.hibernate.tool.ant.HibernateToolTask" + classpathref="jpatoolslib" /&gt; + +&lt;hibernatetool destdir="${build.dir}"&gt; + &lt;jpaconfiguration persistenceunit="caveatemptor"/&gt; + &lt;classpath&gt; + &lt;!-- it is in this classpath you put your classes dir, + and/or jpa persistence compliant jar --&gt; + &lt;path location="${build.dir}/jpa/classes" /&gt; + &lt;/classpath&gt; + + &lt;!-- list exporters here --&gt; + +&lt;/hibernatetool&gt; +</programlisting> + + + <note> + <title>Note:</title> + <para>ejb3configuration was the name used in previous versions. It still works but will emit + a warning telling you to use <literal moreinfo="none">jpaconfiguration</literal> instead.</para> + </note> + + </section> + + <section> + <title>JDBC Configuration for reverse engineering (&lt;jdbcconfiguration&gt;)</title> + + <para>A <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;jdbcconfiguration&gt;</literal> + </property> + </emphasis> is used to perform reverse engineering of the database from a JDBC connection.</para> + + <para>This configuration works by reading the connection properties either from <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> or <emphasis> + <property moreinfo="none">hibernate.properties</property> + </emphasis> with a fileset.</para> + + <para>The <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;jdbcconfiguration&gt;</literal> + </property> + </emphasis> has the same attributes as a <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;configuration&gt;</literal> + </property> + </emphasis> plus the following additional attributes:</para> + + <programlisting format="linespecific" role="XML">&lt;jdbcconfiguration + ... + packagename="package.name" + revengfile="hibernate.reveng.xml" + reversestrategy="ReverseEngineeringStrategy classname" + detectmanytomany="true|false" + detectoptmisticlock="true|false" +&gt; + ... + &lt;/jdbcconfiguration&gt;</programlisting> + + <table frame="topbot"> + <title>Jdbcconfiguration attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>packagename</para> + </entry> + + <entry> + <para>The default package name to use when mappings for classes are created</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>revengfile</para> + </entry> + + <entry> + <para>The name of a property file, e.g. "hibernate.properties"</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>reversestrategy</para> + </entry> + + <entry> + <para>Name of a class that implements + org.hibernate.cfg.reveng.ReverseEngineeringStrategy. Used for setting up the + strategy the tools will use to control the reverse engineering, e.g. naming of + properties, which tables to include/exclude etc. Using a class instead of (or as + addition to) a reveng.xml file gives you full programmatic control of the reverse + engineering.</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + + <row> + <entry> + <para>detectManytoMany</para> + </entry> + + <entry> + <para>If true, tables which are pure many-to-many link tables will be mapped as + such. A pure many-to-many table is one which primary-key contains exactly two + foreign-keys pointing to other entity tables and has no other columns.</para> + </entry> + + <entry> + <para>Default: true</para> + </entry> + </row> + + <row> + <entry> + <para>detectOptimisticLock</para> + </entry> + + <entry> + <para>If true, columns named VERSION or TIMESTAMP with appropriate types will be + mapped with the appropriate optimistic locking corresponding to + &lt;version&gt; or &lt;timestamp&gt;.</para> + </entry> + + <entry> + <para>Default: true</para> + </entry> + </row> + + </tbody> + + </tgroup> + </table> + + <section> + <title>Example</title> + + <para>Here is an example of using <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;jdbcconfiguration&gt;</literal> + </property> + </emphasis> to generate Hibernate xml mappings via <emphasis> + <property moreinfo="none">&lt;hbm2hbmxml&gt;</property>.</emphasis> The connection settings here + is read from a <emphasis> + <property moreinfo="none"> hibernate.properties </property> + </emphasis> file but could just as well have been read from a <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property>. </emphasis></para> + + <programlisting format="linespecific" role="XML">&lt;hibernatetool&gt; + &lt;jdbcconfiguration propertyfile="etc/hibernate.properties" /&gt; + &lt;hbm2hbmxml destdir="${build.dir}/src" /&gt; +&lt;/hibernatetool&gt; +</programlisting> + </section> + </section> + </section> + + <section> + <title>Exporters</title> + + <para>Exporters are the parts that do the actual job of converting the hibernate metamodel into + various artifacts, mainly code. The following section describes the current supported set of + exporters in the <property moreinfo="none">Hibernate Tool</property> distribution. It is also possible for + userdefined exporters, that is done through the <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;hbmtemplate&gt;</literal> + </property> + </emphasis> exporter.</para> + + <section> + <title>Database schema exporter (&lt;hbm2ddl&gt;)</title> + + <para><emphasis> + <property moreinfo="none">&lt;hbm2ddl&gt;</property> + </emphasis> lets you run schemaexport and schemaupdate which generates the appropriate SQL + DDL and allow you to store the result in a file or export it directly to the database. + Remember that if a custom naming strategy is needed it is placed on the configuration + element.</para> + + <programlisting format="linespecific" role="XML">&lt;hbm2ddl + export="true|false" + update="true|false" + drop="true|false" + create="true|false" + outputfilename="filename.ddl" + delimiter=";" + format="true|false" + haltonerror="true|false" + &gt;</programlisting> + + <table frame="topbot"> + <title>Hbm2ddl exporter attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>export</para> + </entry> + + <entry> + <para>Executes the generated statements against the database</para> + </entry> + + <entry> + <para>Default: true</para> + </entry> + </row> + + <row> + <entry> + <para>update</para> + </entry> + + <entry> + <para>Try and create an update script representing the "delta" + between what is in the database and what the mappings specify. Ignores + create/update attributes. (<emphasis>Do *not* use against production databases, no + guarantees at all that the proper delta can be generated nor that the underlying + database can actually execute the needed operations</emphasis>).</para> + </entry> + + <entry> + <para>Default: false</para> + </entry> + </row> + + <row> + <entry> + <para>drop</para> + </entry> + + <entry> + <para>Output will contain drop statements for the tables, indices and + constraints</para> + </entry> + + <entry> + <para>Default: false</para> + </entry> + </row> + + + <row> + <entry> + <para>create</para> + </entry> + + <entry> + <para>Output will contain create statements for the tables, indices and + constraints</para> + </entry> + + <entry> + <para>Default: true</para> + </entry> + </row> + + <row> + <entry> + <para>outputfilename</para> + </entry> + + <entry> + <para>If specified the statements will be dumped to this file</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>delimiter</para> + </entry> + + <entry> + <para>If specified the statements will be dumped to this file</para> + </entry> + + <entry> + <para>Default: ";"</para> + </entry> + </row> + + <row> + <entry> + <para>format</para> + </entry> + + <entry> + <para>Apply basic formatting to the statements</para> + </entry> + + <entry> + <para>Default: false</para> + </entry> + </row> + + <row> + <entry> + <para>haltonerror</para> + </entry> + + <entry> + <para>Halt build process if an error occurs</para> + </entry> + + <entry> + <para>Default: false</para> + </entry> + </row> + </tbody> + + </tgroup> + </table> + + <section> + <title>Example</title> + + <para>Basic example of using <emphasis> + <property moreinfo="none">&lt;hbm2ddl&gt;</property>, </emphasis> which does not export to the + database but simply dumps the sql to a file named <emphasis> + <property moreinfo="none">sql.ddl</property>. </emphasis></para> + + <programlisting format="linespecific" role="XML">&lt;hibernatetool destdir="${build.dir}/generated"&gt; + &lt;configuration configurationfile="hibernate.cfg.xml"/&gt; + &lt;hbm2ddl export="false" outputfilename="sql.ddl"/&gt; +&lt;/hibernatetool&gt;</programlisting> + </section> + </section> + + <section> + <title>POJO java code exporter (<literal moreinfo="none">&lt;hbm2java&gt;</literal>)</title> + + <para><emphasis> + <property moreinfo="none">&lt;hbm2java&gt;</property> + </emphasis> is a java codegenerator. Options for controlling whether JDK 5 syntax can be + used and whether the POJO should be annotated with EJB3/Hibernate Annotations.</para> + + <programlisting format="linespecific" role="XML">&lt;hbm2java + jdk5="true|false" + ejb3="true|false" +&gt;</programlisting> + + <table frame="topbot"> + <title>Hbm2java exporter attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Default value</entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>jdk</para> + </entry> + + <entry> + <para>Code will contain JDK 5 constructs such as generics and static imports</para> + </entry> + + <entry> + <para>False</para> + </entry> + </row> + + <row> + <entry> + <para>ejb3</para> + </entry> + + <entry> + <para>Code will contain EJB 3 features, e.g. using annotations from + javax.persistence and org.hibernate.annotations</para> + </entry> + + <entry> + <para>False</para> + </entry> + </row> + + </tbody> + + </tgroup> + </table> + + <section> + <title>Example</title> + + <para>Basic example of using <emphasis> + <property moreinfo="none">&lt;hbm2java&gt;</property> + </emphasis> to generate POJO's that utilize jdk5 constructs.</para> + + <programlisting format="linespecific" role="XML">&lt;hibernatetool destdir="${build.dir}/generated"&gt; + &lt;configuration configurationfile="hibernate.cfg.xml"/&gt; + &lt;hbm2java jdk5="true"/&gt; +&lt;/hibernatetool&gt;</programlisting> + </section> + </section> + + <section> + <title>Hibernate Mapping files exporter (<literal moreinfo="none">&lt;hbm2hbmxml&gt;</literal>)</title> + + <para><emphasis> + <property moreinfo="none">&lt;hbm2hbmxml&gt;</property> + </emphasis> generates a set of .hbm files. Intended to be used together with a <emphasis> + <property moreinfo="none">&lt;jdbcconfiguration&gt;</property> + </emphasis> when performing reverse engineering, but can be used with any kind of + configuration. e.g. to convert from annotation based pojo's to <emphasis> + <property moreinfo="none">hbm.xml</property>. </emphasis></para> + + <note> + <title>Note:</title> + <para>Not every possible mapping transformation is possible/implemented (contributions + welcome) so some hand editing might be necessary.</para> + </note> + + <programlisting format="linespecific" role="XML">&lt;hbm2hbmxml/&gt;</programlisting> + + <section> + <title>Example</title> + + <para>Basic usage of <emphasis> + <property moreinfo="none">&lt;hbm2hbmxml&gt;</property>. </emphasis></para> + + <programlisting format="linespecific" role="XML">&lt;hibernatetool destdir="${build.dir}/generated"&gt; + &lt;configuration configurationfile="hibernate.cfg.xml"/&gt; + &lt;hbm2hbmxml/&gt; +&lt;/hibernatetool&gt;</programlisting> + + <para><emphasis> + <property moreinfo="none">&lt;hbm2hbmxml&gt;</property> + </emphasis> is normally used with a <emphasis> + <property moreinfo="none">&lt;jdbcconfiguration&gt;</property> + </emphasis> like in the above example, but any other configuration can also be used to + convert between the different ways of performing mappings. Here is an example of that, + using an <emphasis> + <property moreinfo="none">&lt;annotationconfiguration&gt;</property> + </emphasis>.</para> + + <note> + <title>Note:</title> + <para>Not all conversions are implemented (contributions welcome), so some hand editing + might be necessary.</para> + </note> + + <programlisting format="linespecific" role="XML">&lt;hibernatetool destdir="${build.dir}/generated"&gt; + &lt;annotationconfiguration configurationfile="hibernate.cfg.xml"/&gt; + &lt;hbm2hbmxml/&gt; +&lt;/hibernatetool&gt;</programlisting> + </section> + </section> + + <section> + <title>Hibernate Configuration file exporter (<literal moreinfo="none">&lt;hbm2cfgxml&gt;</literal>)</title> + + <para><emphasis> + <property moreinfo="none">&lt;hbm2cfgxml&gt;</property> + </emphasis> generates a <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property>. </emphasis> Intended to be used together with a <emphasis> + <property moreinfo="none">&lt;jdbcconfiguration&gt;</property> + </emphasis> when performing reverse engineering, but it can be used with any kind of + configuration. The <emphasis> + <property moreinfo="none">&lt;hbm2cfgxml&gt;</property> + </emphasis> will contain the properties used and adds mapping entries for each mapped class.</para> + + <programlisting format="linespecific" role="XML">&lt;hbm2cfgxml + ejb3="true|false" +/&gt; +</programlisting> + + <table frame="topbot"> + <title>Hbm2cfgxml exporter attribute</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Default value</entry> + </row> + </thead> + + <tbody> + + <row> + <entry> + <para>ejb3</para> + </entry> + + <entry> + <para>The generated cfg.xml will have &lt;mapping class=".."/&gt;, opposed + to &lt;mapping resource="..."/&gt; for each mapping.</para> + </entry> + + <entry> + <para>False</para> + </entry> + </row> + + </tbody> + + </tgroup> + </table> + + </section> + + <section> + <title>Documentation exporter (<literal moreinfo="none">&lt;hbm2doc&gt;</literal>)</title> + + <para><emphasis> + <property moreinfo="none">&lt;hbm2doc&gt;</property> + </emphasis> generates html documentation a'la javadoc for the database schema et.al.</para> + + <programlisting format="linespecific" role="XML">&lt;hbm2doc/&gt;</programlisting> + </section> + + <section> + <title>Query exporter (&lt;query&gt;)</title> + + <para><emphasis> + <property moreinfo="none">&lt;query&gt;</property> + </emphasis> is used to execute a HQL query statements and optionally sends the output to a + file. It can be used for verifying the mappings and for basic data extraction.</para> + + <programlisting format="linespecific" role="XML">&lt;query + destfile="filename"&gt; + &lt;hql&gt;[a HQL query string]&lt;/hql&gt; +&lt;/query&gt; +</programlisting> + + <para>Currently one session is opened and used for all queries and the query is executed via + the list() method. In the future more options might become available, like performing + executeUpdate(), use named queries and etc.</para> + + <para></para> + + <section> + <title>Examples</title> + + <para>The simplest usage of <emphasis> + <property moreinfo="none">&lt;query&gt;</property> + </emphasis> will just execute the query without dumping to a file. This can be used to + verify that queries can actually be performed.</para> + + <programlisting format="linespecific" role="XML">&lt;hibernatetool&gt; + &lt;configuration configurationfile="hibernate.cfg.xml"/&gt; + &lt;query&gt;from java.lang.Object&lt;/query&gt; +&lt;/hibernatetool&gt;</programlisting> + + <para>Multiple queries can be executed by nested <emphasis> + <property moreinfo="none">&lt;hql&gt;</property> + </emphasis> elements. In this example we also let the output be dumped to <emphasis> + <property moreinfo="none">queryresult.txt</property>. </emphasis></para> + + <note> + <title>Note:</title> + <para> Currently the dump is simply a call to toString on each element.</para> + </note> + + <programlisting format="linespecific" role="XML">&lt;hibernatetool&gt; + &lt;configuration configurationfile="hibernate.cfg.xml"/&gt; + &lt;query destfile="queryresult.txt"&gt; + &lt;hql&gt;select c.name from Customer c where c.age &gt; 42&lt;/hql&gt; + &lt;hql&gt;from Cat&lt;/hql&gt; +&lt;/hibernatetool&gt;</programlisting> + + </section> + </section> + + <section id="hbmtemplate"> + <title>Generic Hibernate metamodel exporter (<literal moreinfo="none">&lt;hbmtemplate&gt;</literal>)</title> + + <para>Generic exporter that can be controlled by a user provides a template or class.</para> + + <programlisting format="linespecific" role="XML">&lt;hbmtemplate + filepattern="{package-name}/{class-name}.ftl" + template="somename.ftl" + exporterclass="Exporter classname" +/&gt;</programlisting> + + <note> + <title>Note:</title> + <para>Previous versions of the tools used Velocity. We are now using Freemarker which + provides us much better exception and error handling.</para> + </note> + + <section> + <title>Exporter via &lt;hbmtemplate&gt;</title> + + <para>The following is an example of reverse engineering via <emphasis> + <property moreinfo="none">&lt;jdbcconfiguration&gt;</property> + </emphasis> and usage of a custom Exporter via the <emphasis> + <property moreinfo="none">&lt;hbmtemplate&gt;</property> + </emphasis>.</para> + + <programlisting format="linespecific" role="XML"> &lt;hibernatetool destdir="${destdir}"&gt; + &lt;jdbcconfiguration + configurationfile="hibernate.cfg.xml" + packagename="my.model"/&gt; + + &lt;!-- setup properties --&gt; + &lt;property key="appname" value="Registration"/&gt; + &lt;property key="shortname" value="crud"/&gt; + + &lt;hbmtemplate + exporterclass="my.own.Exporter" + filepattern="."/&gt; + +&lt;/hibernatetool&gt; +</programlisting> + + </section> + <section> + <title>Relevant Resources Links</title> + + <para>Read more about <ulink url="http://velocity.apache.org/">Velocity</ulink> and <ulink url="http://freemarker.org/">Freemarker</ulink> to find out why using the last is better + or refer to Max Andersen discussion on the topic in <ulink url="http://in.relation.to/2110.lace;jsessionid=3462F47B17556604C15DF1B96572E940">"A story about FreeMarker and Velocity"</ulink>.</para> + </section> + </section> + </section> + + + + <section> + <title>Using properties to configure Exporters</title> + + <para>Exporters can be controlled by user properties. The user properties are specified via <emphasis> + <property moreinfo="none">&lt;property&gt;</property> + </emphasis> or <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;propertyset&gt;</literal> + </property> + </emphasis> and each exporter will have access to them directly in the templates and via + <property moreinfo="none">Exporter.setProperties()</property>.</para> + + <section> + <title><literal moreinfo="none">&lt;property&gt;</literal> and + <literal moreinfo="none">&lt;propertyset&gt;</literal></title> + + <para>The <emphasis> + <property moreinfo="none">&lt;property&gt;</property> + </emphasis> allows you bind a string value to a key. The value will be available in the + templates via <emphasis> + <property moreinfo="none">$&lt;key&gt;</property> + </emphasis>. The following example will assign the string value <emphasis> + <property moreinfo="none">"true"</property> + </emphasis> to the variable <emphasis> + <property moreinfo="none">$descriptors</property> + </emphasis>.</para> + + <programlisting format="linespecific" role="XML">&lt;property key="descriptors" value="true"/&gt;</programlisting> + + <para>Most times using <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;property&gt;</literal> + </property> + </emphasis> is enough for specifying the properties needed for the exporters. Still the ant + tools supports the notion of <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;propertyset&gt;</literal> + </property> + </emphasis> that is used for grouping a set of properties. More about the functionality of <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;propertyset&gt;</literal> + </property> + </emphasis> is explained in detail in the <ulink url="http://ant.apache.org/manual/">Ant + manual</ulink>.</para> + </section> + + <section> + <title>Getting access to user specific classes</title> + + <para>If the templates need to access some user class it becomes possible by specifying a <emphasis> + <property moreinfo="none">"toolclass"</property> + </emphasis> in the properties.</para> + + <programlisting format="linespecific" role="XML">&lt;property key="hibernatetool.sometool.toolclass" value="x.y.z.NameOfToolClass"/&gt; +</programlisting> + + <para>Placing the above <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;property&gt;</literal> + </property> + </emphasis> tag in <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">&lt;hibernatetool&gt;</literal> + </property> + </emphasis> or inside any exporter will automatically create an instance of + <literal moreinfo="none">x.y.z.NameOfToolClass</literal> and it will be available in the templates as + <literal moreinfo="none">$sometool</literal>. This is useful to delegate logic and code generation to java + code instead of placing such logic in the templates.</para> + + <section> + <title>Example</title> + + <para>Here is an example that uses <emphasis> + <property moreinfo="none">&lt;hbmtemplate&gt;</property> + </emphasis> together with <emphasis> + <property moreinfo="none">&lt;property&gt;</property> + </emphasis> which will be available to the templates/exporter. </para> + <note> + <title>Note:</title> + <para> This example actually simulates what &lt;hbm2java&gt; actually does.</para> + </note> + + <programlisting format="linespecific" role="XML">&lt;hibernatetool destdir="${build.dir}/generated"&gt; +&lt;configuration + configurationfile="etc/hibernate.cfg.xml"/&gt; + &lt;hbmtemplate + templateprefix="pojo/" + template="pojo/Pojo.ftl" + filepattern="{package-name}/{class-name}.java"&gt; + &lt;property key="jdk5" value="true" /&gt; + &lt;property key="ejb3" value="true" /&gt; + &lt;/hbmtemplate&gt; +&lt;/hibernatetool&gt; +</programlisting> + </section> + </section> + </section> +</chapter> + + +<chapter id="reverseengineering" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/hibernatetools/docs/reference/en/modules/reverseengineering.xml"> + <title>Controlling reverse engineering</title> + + <para>When using the <emphasis> + <property moreinfo="none">&lt;jdbcconfiguration&gt;</property>, </emphasis> the ant task will read the + database metadata and thus will perform a reverse engineering of the database schema into a + normal Hibernate Configuration. It is from this object e.g. <emphasis> + <property moreinfo="none">&lt;hbm2java&gt;</property> + </emphasis>can generate other artifacts such as <emphasis> + <property moreinfo="none">.java</property> + </emphasis>, <emphasis> + <property moreinfo="none">.hbm.xml</property> + </emphasis> etc.</para> + + <para>To govern this process <property moreinfo="none">Hibernate</property> uses a reverse engineering strategy. A + reverse engineering strategy is mainly called to provide more java like names for tables, column + and foreignkeys into classes, properties and associations. It also used to provide mappings from + SQL types to <property moreinfo="none">Hibernate</property> types. The strategy can be customized by a user. The + user can even provide its own custom reverse engineering strategy if the provided strategy is + not enough, or simply just provide a small part of the strategy and delegate the rest to the + default strategy.</para> + + <para>Thus, further in this chapter we will discuss how you can configure the process of a reverse + engineering, what default reverse engineering strategy includes as well as some custom concepts.</para> + + <section> + <title>Default reverse engineering strategy</title> + + <para>The default strategy uses some rules for mapping JDBC artifact names to java artifact + names. It also provide basic typemappings from JDBC types to <property moreinfo="none">Hibernate</property> + types. It is the default strategy that uses the packagename attribute to convert a table name + to a fully qualified classname.</para> + </section> + + <section id="hibernaterevengxmlfile"> + <title>hibernate.reveng.xml file</title> + + <para>To have fine control over the process a <emphasis> + <property moreinfo="none">hibernate.reveng.xml</property> + </emphasis> file can be provided. In this file you can specify type mappings and table + filtering. This file can be created by hand (it's just basic XML) or you can use the + <ulink url="http://www.hibernate.org/30.html">Hibernate plugins</ulink> which have a + specialized editor.</para> + + <note> + <title>Note:</title> + <para>Many databases are case-sensitive with their names and thus if you cannot make some + table match and you are sure it is not excluded by a &lt;table-filter&gt; then check + if the case matches; most databases stores table names in uppercase.</para> + </note> + + <para>Below you can see an example of a <emphasis> + <property moreinfo="none">reveng.xml</property>. </emphasis> Following the example gives you more details + about the format.</para> + + <programlisting format="linespecific" role="XML">&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;!DOCTYPE hibernate-reverse-engineering + SYSTEM "http://hibernate.sourceforge.net/hibernate-reverse-engineering-3.0.dtd" &gt; + +&lt;hibernate-reverse-engineering&gt; + +&lt;type-mapping&gt; + &lt;!-- jdbc-type is name fom java.sql.Types --&gt; + &lt;sql-type jdbc-type="VARCHAR" length='20' hibernate-type="SomeUserType" /&gt; + &lt;sql-type jdbc-type="VARCHAR" length='1' hibernate-type="yes_no" /&gt; + &lt;!-- length, scale and precision can be used to specify the mapping precisly --&gt; + &lt;sql-type jdbc-type="NUMERIC" precision='1' hibernate-type="boolean" /&gt; + &lt;!-- the type-mappings are ordered. This mapping will be consulted last, + thus overriden by the previous one if precision=1 for the column --&gt; + &lt;sql-type jdbc-type="NUMERIC" hibernate-type="long" /&gt; +&lt;/type-mapping&gt; + +&lt;!-- BIN$ is recycle bin tables in Oracle --&gt; +&lt;table-filter match-name="BIN$.*" exclude="true" /&gt; + +&lt;!-- Exclude DoNotWantIt from all catalogs/schemas --&gt; +&lt;table-filter match-name="DoNotWantIt" exclude="true" /&gt; + +&lt;!-- exclude all tables from the schema SCHEMA in catalog BAD. --&gt; +&lt;table-filter match-catalog="BAD" match-schema="SCHEMA" match-name=".*" exclude="true" /&gt; + +&lt;!-- table allows you to override/define how reverse engineering + is done for a specific table --&gt; +&lt;table name="ORDERS"&gt; + &lt;primary-key&gt; + &lt;!-- setting up a specific id generator for a table --&gt; + &lt;generator class="sequence"&gt; + &lt;param name="table"&gt;seq_table&lt;/param&gt; + &lt;/generator&gt; + &lt;key-column name="CUSTID"/&gt; + &lt;/primary-key&gt; + &lt;column name="NAME" property="orderName" type="string" /&gt; + &lt;!-- control many-to-one and set names for a specific named foreign key constraint --&gt; + &lt;foreign-key constraint-name="ORDER_CUST"&gt; + &lt;many-to-one property="customer"/&gt; + &lt;set property="orders"/&gt; + &lt;/foreign-key&gt; + <diffmk:wrapper diffmk:change="added">&lt;!-- can also control a pure (shared pk) one-to-one --&gt; + &lt;foreign-key constraint-name="ADDRESS_PERSON"&gt; + &lt;one-to-one exclude="false"/&gt; + &lt;inverse-one-to-one exclude="true"/&gt; + &lt;/foreign-key&gt; +</diffmk:wrapper>&lt;/table&gt; + +&lt;/hibernate-reverse-engineering&gt;</programlisting> + + + <section> + <title>Schema Selection (&lt;schema-selection&gt;)</title> + + <para><emphasis> + <property moreinfo="none">&lt;schema-selection&gt;</property> + </emphasis> is used to drive which schemas the reverse engineering will try and + process.</para> + + <para>By default the reverse engineering will read all schemas and then use <emphasis> + <property moreinfo="none">&lt;table-filter&gt;</property> + </emphasis> to decide which tables get reverse engineered and which do not; this makes it + easy to get started but can be inefficient on databases with many schemas.</para> + + <para>With <emphasis> + <property moreinfo="none">&lt;schema-selection&gt;</property> + </emphasis> it is thus possible to limit the actual processed schemas and thus significantly + speed-up the reverse engineering. <emphasis> + <property moreinfo="none">&lt;table-filter&gt;</property> + </emphasis> is still used to then decide which tables will be included/excluded.</para> + + <note> + <title>Note:</title> + <para>If no <literal moreinfo="none">&lt;schema-selection&gt;</literal> is specified, the reverse + engineering works as if all schemas should be processed. This is equal to: + &lt;schema-selection/&gt;. Which in turn is equal to: + &lt;schema-selection match-catalog=".*" match-schema=".*" match-table=".*"/&gt;</para> + </note> + + <section> + <title>Examples</title> + + <para>The following will process all tables from <emphasis> + <property moreinfo="none">"MY_SCHEMA"</property>. + </emphasis></para> + + <programlisting format="linespecific" role="XML">&lt;schema-selection match-schema="MY_SCHEMA"/&gt;</programlisting> + + <para>It is possible to have multiple <literal moreinfo="none">schema-selection</literal>'s to support + multi-schema reading or simply to limit the processing to very specific tables. The + following example processes all tables in <emphasis> + <property moreinfo="none">"MY_SCHEMA"</property>, + </emphasis> a specific <emphasis> + <property moreinfo="none">"CITY"</property> + </emphasis> table plus all tables that starts with <emphasis> + <property moreinfo="none">"CODES_"</property> + </emphasis> in <emphasis> + <property moreinfo="none">"COMMON_SCHEMA"</property>. + </emphasis></para> + + <programlisting format="linespecific" role="XML">&lt;schema-selection match-schema="MY_SCHEMA"/&gt; +&lt;schema-selection match-schema="COMMON_SCHEMA" match-table="CITY"/&gt; +&lt;schema-selection match-schema="COMMON_SCHEMA" match-table="CODES_.*"/&gt;</programlisting> + </section> + </section> + + <section id="type_map"> + <title>Type mappings (&lt;type-mapping&gt;)</title> + + <para>The <emphasis> + <property moreinfo="none">&lt;type-mapping&gt;</property> + </emphasis> section specifies how the JDBC types found in the database should be mapped to + Hibernate types. e.g. <emphasis> + <property moreinfo="none">java.sql.Types.VARCHAR</property></emphasis> with a length of 1 should be mapped to the + Hibernate type <emphasis> + <property moreinfo="none">yes_no</property></emphasis> or <emphasis> + <property moreinfo="none">java.sql.Types.NUMERIC</property></emphasis> should generally just be + converted to the Hibernate type <literal moreinfo="none">long</literal>.</para> + + <programlisting format="linespecific" role="XML">&lt;type-mapping&gt; + &lt;sql-type + jdbc-type="integer value or name from java.sql.Types" + length="a numeric value" + precision="a numeric value" + scale="a numeric value" + not-null="true|false" + hibernate-type="hibernate type name" + /&gt; +&lt;/type-mapping&gt;</programlisting> + + <para>The number of attributes specified and the sequence of the <literal moreinfo="none">sql-type</literal>'s + is important. Meaning that <property moreinfo="none">Hibernate</property> will search for the most specific + first, and if no specific match is found it will seek from top to bottom when trying to + resolve a type mapping.</para> + + <section> + <title>Example</title> + + <para>The following is an example of a type-mapping which shows the flexibility and the + importance of ordering of the type mappings.</para> + + <programlisting format="linespecific" role="XML">&lt;type-mapping&gt; + &lt;sql-type jdbc-type="NUMERIC" precision="15" hibernate-type="big_decimal"/&gt; + &lt;sql-type jdbc-type="NUMERIC" not-null="true" hibernate-type="long" /&gt; + &lt;sql-type jdbc-type="NUMERIC" not-null="false" hibernate-type="java.lang.Long" /&gt; + &lt;sql-type jdbc-type="VARCHAR" length="1" not-null="true" + hibernate-type="java.lang.Character"/&gt; + &lt;sql-type jdbc-type="VARCHAR" hibernate-type="your.package.TrimStringUserType"/&gt; + &lt;sql-type jdbc-type="VARCHAR" length="1" hibernate-type="char"/&gt; + &lt;sql-type jdbc-type="VARCHAR" hibernate-type="string"/&gt; +&lt;/type-mapping&gt;</programlisting> + + <para>The following table shows how this affects an example table named <emphasis> + <property moreinfo="none">CUSTOMER</property>:</emphasis></para> + + <table frame="topbot"> + <title>sql-type examples</title> + + <tgroup cols="7"> + <colspec colwidth="0.4*"></colspec> + + <colspec colwidth="0.4*"></colspec> + + <colspec colwidth="0.2*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="0.2*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.7*"></colspec> + + <thead> + <row> + <entry>Column</entry> + + <entry>jdbc-type</entry> + + <entry>length</entry> + + <entry>precision</entry> + + <entry>not-null</entry> + + <entry>Resulting hibernate-type</entry> + + <entry>Rationale</entry> + </row> + </thead> + + <tbody> + <row> + <entry>ID</entry> + + <entry>INTEGER</entry> + + <entry></entry> + + <entry>10</entry> + + <entry>true</entry> + + <entry>int</entry> + + <entry>Nothing is defined for INTEGER. Falling back to default behavior.</entry> + </row> + + <row> + <entry>NAME</entry> + + <entry>VARCHAR</entry> + + <entry>30</entry> + + <entry></entry> + + <entry>false</entry> + + <entry>your.package.TrimStringUserType</entry> + + <entry>No type-mapping matches length=30 and not-null=false, but type-mapping + matches the 2 mappings which only specifies VARCHAR. The type-mapping that comes + first is chosen.</entry> + </row> + + <row> + <entry>INITIAL</entry> + + <entry>VARCHAR</entry> + + <entry>1</entry> + + <entry></entry> + + <entry>false</entry> + + <entry>char</entry> + + <entry>Even though there is a generic match for VARCHAR, the more specific + type-mapping for VARCHAR with not-null="false" is chosen. The first VARCHAR + sql-type matches in length but has no value for not-null and thus is not + considered.</entry> + </row> + + <row> + <entry>CODE</entry> + + <entry>VARCHAR</entry> + + <entry>1</entry> + + <entry></entry> + + <entry>true</entry> + + <entry>java.lang.Character</entry> + + <entry>The most specific VARCHAR with not-null="true" is selected</entry> + </row> + + <row> + <entry>SALARY</entry> + + <entry>NUMERIC</entry> + + <entry></entry> + + <entry>15</entry> + + <entry>false</entry> + + <entry>big_decimal</entry> + + <entry>There is a precise match for NUMERIC with precision 15</entry> + </row> + + <row> + <entry>AGE</entry> + + <entry>NUMERIC</entry> + + <entry></entry> + + <entry>3</entry> + + <entry>false</entry> + + <entry>java.lang.Long</entry> + + <entry>type-mapping for NUMERIC with not-null="false"</entry> + </row> + </tbody> + </tgroup> + </table> + + <para></para> + </section> + </section> + + <section> + <title>Table filters (&lt;table-filter&gt;)</title> + + <para>The <emphasis> + <property moreinfo="none">&lt;table-filter&gt;</property> + </emphasis> let you specify matching rules for performing general filtering/setup for + tables, e.g. let you include or exclude specific tables based on the schema or even a + specific prefix.</para> + + <programlisting format="linespecific" role="XML">&lt;table-filter + match-catalog="catalog_matching_rule" + match-schema="schema_matching_rule" + match-name="table_matching_rule" + exclude="true|false" + package="package.name" +/&gt;</programlisting> + + <table frame="topbot"> + <title>Table-filter attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Default value</entry> + </row> + </thead> + + <tbody> + <row> + <entry><para>match-catalog</para></entry> + + <entry><para>Pattern for matching catalog part of the table</para></entry> + + <entry><para>.*</para></entry> + </row> + + <row> + <entry><para>match-schema</para></entry> + + <entry><para>Pattern for matching schema part of the table</para></entry> + + <entry><para>.*</para></entry> + </row> + + <row> + <entry><para>match-table</para></entry> + + <entry><para>Pattern for matching table part of the table</para></entry> + + <entry><para>.*</para></entry> + </row> + + <row> + <entry><para>exclude </para></entry> + + <entry><para>If true the table will not be part of the reverse + engineering</para></entry> + + <entry><para>false</para></entry> + </row> + + <row> + <entry><para>package</para></entry> + + <entry><para>The default package name to use for classes based on tables + matched by this table-filter</para></entry> + + <entry><para>""</para></entry> + </row> + </tbody> + + </tgroup> + </table> + + </section> + + <section id="tab_and_col"> + <title>Specific table configuration (&lt;table&gt;)</title> + + <para><emphasis> + <property moreinfo="none">&lt;table&gt;</property> + </emphasis> allows you to provide explicit configuration on how a table should be reverse + engineered. Amongst other things it allows controlling over the naming of a class for the + table, specifying which identifier generator should be used for the primary key etc.</para> + + <programlisting format="linespecific" role="XML">&lt;table + catalog="catalog_name" + schema="schema_name" + name="table_name" + class="ClassName" +&gt; + &lt;primary-key.../&gt; + &lt;column.../&gt; + &lt;foreign-key.../&gt; + &lt;/table&gt;</programlisting> + + <table frame="topbot"> + <title>Table attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry><para>catalog</para></entry> + + <entry><para>Catalog name for a table. It has to be specified if you are + reverse engineering multiple catalogs or if it is not equal to + hiberante.default_catalog.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>schema</para></entry> + + <entry><para>Schema name for a table. It has to be specified if you are + reverse engineering multiple schemas or if it is not equal to + hiberante.default_schema.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>name</para></entry> + + <entry><para>Name for a table.</para></entry> + + <entry><para>Required</para></entry> + </row> + + <row> + <entry><para>class</para></entry> + + <entry><para>The class name for a table. Default name is a camelcase version + of the table name.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + </tbody> + + </tgroup> + </table> + + <section> + <title>&lt;primary-key&gt;</title> + + <para>A <emphasis> + <property moreinfo="none">&lt;primary-key&gt;</property> + </emphasis> allows you to define a primary-key for tables that don't have it + defined in the database, and probably more importantly it allows you to define which + identifier strategy should be used (even for already existing primary-key's).</para> + + <programlisting format="linespecific" role="XML">&lt;primary-key + &lt;generator class="generatorname"&gt; + &lt;param name="param_name"&gt;parameter value&lt;/param&gt; + &lt;/generator&gt; + &lt;key-column...&gt; + &lt;/primary-key&gt;</programlisting> + + <table frame="topbot"> + <title>Primary-key attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry><para>generator/class</para></entry> + + <entry><para>Defines which identifier generator should be used. + The class name is any hibernate short hand name or fully qualified class name for an + identifier strategy.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>generator/param</para></entry> + + <entry><para>Allows to specify which parameter with a name and + value should be passed to the identifier generator.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>key-column</para></entry> + + <entry><para>Specifies which column(s ) the primary-key consists of. A + key-column is same as column, but does not have the exclude property.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + </tbody> + + </tgroup> + </table> + + </section> + + <section> + <title>&lt;column&gt;</title> + + <para>With a <emphasis> + <property moreinfo="none">&lt;column&gt;</property> + </emphasis> it is possible to explicitly name the resulting property for a column. It is + also possible to redefine what jdbc and/or Hibernate type a column should be processed as + and finally it is possible to completely exclude a column from processing.</para> + + <programlisting format="linespecific" role="XML">&lt;column + name="column_name" + jdbc-type="java.sql.Types type" + type="hibernate_type" + property="propertyName" + exclude="true|false" +/&gt;</programlisting> + + <table frame="topbot"> + <title>Column attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry><para>name</para></entry> + + <entry><para>Column name</para></entry> + + <entry><para>Required</para></entry> + </row> + + <row> + <entry><para>jdbc-type</para></entry> + + <entry><para>Which jdbc-type this column should be processed as. A + value from java.sql.Types, either numerical (93) or the constant name + (TIMESTAMP).</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>type</para></entry> + + <entry><para>Which hibernate-type to use for this specific column</para></entry> + + <entry><para>Optional</para></entry> + </row> + + + <row> + <entry><para>property</para></entry> + + <entry><para>What property name will be generated for this + column</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>exclude</para></entry> + + <entry><para>Set to true if this column should be ignored</para></entry> + + <entry><para>default: false</para></entry> + </row> + + </tbody> + + </tgroup> + </table> + + </section> + + <section> + <title>&lt;foreign-key&gt;</title> + + <para>The <emphasis> + <property moreinfo="none">&lt;foreign-key&gt;</property> + </emphasis> has two purposes. One for allowing to define foreign-keys in databases that + does not support them or does not have them defined in their schema. Secondly, to allow + defining the name of the resulting properties <diffmk:wrapper diffmk:change="added">(many-to-one, one-to-one</diffmk:wrapper><diffmk:wrapper diffmk:change="deleted">(many-to-one </diffmk:wrapper>and one-to-many's).</para> + + <programlisting format="linespecific" role="XML">&lt;foreign-key + constraint-name="foreignKeyName" + foreign-catalog="catalogName" + foreign-schema="schemaName" + foreign-table="tableName" + &gt; + &lt;column-ref local-column="columnName" foreign-column="foreignColumnName"/&gt; + &lt;many-to-one + property="aPropertyName" + exclude="true|false"/&gt; + &lt;set + property="aCollectionName" + <diffmk:wrapper diffmk:change="added">exclude="true|false" + + &lt;one-to-one + property="aPropertyName" + exclude="true|false"/&gt; + &lt;inverse-one-to-one + property="aPropertyName" + </diffmk:wrapper>exclude="true|false"/&gt; + &lt;/foreign-key&gt;</programlisting> + <table frame="topbot"> + <title>Foreign-key attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry><para>constraint-name</para></entry> + + <entry><para>Name of the foreign key constraint. Important when + naming <diffmk:wrapper diffmk:change="changed">many-to-one, </diffmk:wrapper><diffmk:wrapper diffmk:change="added">one-to-one </diffmk:wrapper>and set. It is the constraint-name that is used to link the + processed foreign-keys with the resulting property names.</para></entry> + + <entry><para>Required</para></entry> + </row> + + <row> + <entry><para>foreign-catalog</para></entry> + + <entry><para>Name of the foreign table's catalog. (Only + relevant if you want to explicitly define a foreign key).</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>foreign-schema</para></entry> + + <entry><para>Name of the foreign table's schema. (Only relevant + if you want to explicitly define a foreign key).</para></entry> + + <entry><para>Optional</para></entry> + </row> + + + <row> + <entry><para>foreign-table</para></entry> + + <entry><para>Name of the foreign table. (Only relevant if you + want to explicitly define a foreign key).</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>column-ref </para></entry> + + <entry><para>Defines that the foreign-key constraint between a + local-column and foreign-column name. (Only relevant if you want to explicitly + define a foreign key).</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>many-to-one</para></entry> + + <entry><para>Defines that a many-to-one should be created and the + property attribute specifies the name of the resulting property. Exclude can be + used to explicitly define that it should be created or not.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>set</para></entry> + + <entry><para>Defines that a set should be created based on this foreign-key + and the property attribute specifies the name of the resulting (set) property. + Exclude can be used to explicitly define that it should be created or not.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row diffmk:change="added"> + <entry diffmk:change="added"><para diffmk:change="added"><diffmk:wrapper diffmk:change="added">one-to-one</diffmk:wrapper></para></entry> + + <entry diffmk:change="added"><para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Defines that a one-to-one should be created and the + property attribute specifies the name of the resulting property. Exclude can be + used to explicitly define that it should be created or not.</diffmk:wrapper></para></entry> + + <entry diffmk:change="added"><para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Optional</diffmk:wrapper></para></entry> + </row> + + <row diffmk:change="added"> + <entry diffmk:change="added"><para diffmk:change="added"><diffmk:wrapper diffmk:change="added">inverse-one-to-one</diffmk:wrapper></para></entry> + + <entry diffmk:change="added"><para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Defines that an inverse one-to-one should be created based on this foreign-key + and the property attribute specifies the name of the resulting property. + Exclude can be used to explicitly define that it should be created or not.</diffmk:wrapper></para></entry> + + <entry diffmk:change="added"><para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Optional</diffmk:wrapper></para></entry> + </row> + </tbody> + + </tgroup> + </table> + + </section> + </section> + </section> + + <section id="custom-reveng-strategy"> + <title>Custom strategy</title> + + <para>It is possible to implement a user strategy. Such strategy must implement <emphasis> + <property moreinfo="none">org.hibernate.cfg.reveng.ReverseEngineeringStrategy</property>. + </emphasis> It is recommended that one uses the + <property moreinfo="none">DelegatingReverseEngineeringStrategy</property> and provide a public constructor + which takes another <property moreinfo="none">ReverseEngineeringStrategy </property> as an argument. This will + allow you to only implement the relevant methods and provide a fallback strategy. Example of + custom delegating strategy which converts all column names that ends with <emphasis> + <property moreinfo="none">"PK"</property> + </emphasis> into a property named <emphasis> + <property moreinfo="none">"id"</property>. + </emphasis></para> + + <programlisting format="linespecific" role="JAVA">public class ExampleStrategy extends DelegatingReverseEngineeringStrategy { + + public ExampleStrategy(ReverseEngineeringStrategy delegate) { + super(delegate); + } + + public String columnToPropertyName(TableIdentifier table, String column) { + if(column.endsWith("PK")) { + return "id"; + } else { + return super.columnToPropertyName(table, column); + } + } +}</programlisting> + </section> + + <section> + <title>Custom Database Metadata</title> + + <para>By default the reverse engineering is performed by reading using the JDBC database + metadata API. This is done via the class <emphasis> + <property moreinfo="none">org.hibernate.cfg.reveng.dialect.JDBCMetaDataDialect</property> + </emphasis> which is an implementation of <emphasis> + <property moreinfo="none">org.hibernate.cfg.reveng.dialect.MetaDataDialect</property>. + </emphasis></para> + + <para>The default implementation can be replaced with an alternative implementation by setting + the property <emphasis> + <property moreinfo="none">hibernatetool.metadatadialect</property> + </emphasis> to a fully qualified classname for a class that implements + <property moreinfo="none">JDBCMetaDataDialect</property>.</para> + + <para>This can be used to provide database specific optimized metadata reading. If you create an + optimized/better metadata reading for your database it will be a very welcome + contribution.</para> + </section> +</chapter> + + +<chapter id="codegen" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/hibernatetools/docs/reference/en/modules/codegen.xml"> + <title>Controlling POJO code generation</title> + + <para>When using <emphasis> + <property moreinfo="none">&lt;hbm2java&gt;</property> + </emphasis> or the eclipse plugin to generate POJO java code you have the possibility to control + certain aspects of the code generation. This is primarily done with the <emphasis> + <property moreinfo="none">&lt;meta&gt;</property> + </emphasis> tag in the mapping files. The following section describes the possible <emphasis> + <property moreinfo="none">&lt;meta&gt;</property> + </emphasis> tags and their use.</para> + + <section> + <title>The <literal moreinfo="none">&lt;meta&gt;</literal> attribute</title> + + <para>The <emphasis> + <property moreinfo="none">&lt;meta&gt;</property> + </emphasis> tag is a simple way of annotating the <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> with information, so tools have a natural place to store/read information that is + not directly related to the Hibernate core.</para> + + <para>You can use the <emphasis> + <property moreinfo="none">&lt;meta&gt;</property> + </emphasis> tag to e.g. tell <emphasis> + <property moreinfo="none">&lt;hbm2java&gt;</property> + </emphasis> to only generate <emphasis> + <property moreinfo="none">"protected"</property> + </emphasis> setters, have classes always implement a certain set of interfaces or even have + them extend a certain base class and even more.</para> + + <para>The following example shows how to use various <emphasis> + <property moreinfo="none">&lt;meta&gt;</property> + </emphasis> attributes and the resulting java code.</para> + + <programlisting format="linespecific" role="XML">&lt;class name="Person"&gt; + &lt;meta attribute="class-description"&gt; + Javadoc for the Person class + @author Frodo + &lt;/meta&gt; + &lt;meta attribute="implements"&gt;IAuditable&lt;/meta&gt; + &lt;id name="id" type="long"&gt; + &lt;meta attribute="scope-set"&gt;protected&lt;/meta&gt; + &lt;generator class="increment"/&gt; + &lt;/id&gt; + &lt;property name="name" type="string"&gt; + &lt;meta attribute="field-description"&gt;The name of the person&lt;/meta&gt; + &lt;/property&gt; +&lt;/class&gt;</programlisting> + + <para>The above <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> will produce something like the following (code shortened for better + understanding). Notice the Javadoc comment and the protected set methods:</para> + + <programlisting format="linespecific" role="JAVA">// default package + +import java.io.Serializable; +import org.apache.commons.lang.builder.EqualsBuilder; +import org.apache.commons.lang.builder.HashCodeBuilder; +import org.apache.commons.lang.builder.ToStringBuilder; + +/** + * Javadoc for the Person class + * @author Frodo + */ +public class Person implements Serializable, IAuditable { + + public Long id; + + public String name; + + public Person(java.lang.String name) { + this.name = name; + } + + public Person() { + } + + public java.lang.Long getId() { + return this.id; + } + + protected void setId(java.lang.Long id) { + this.id = id; + } + + /** + * The name of the person + */ + public java.lang.String getName() { + return this.name; + } + + public void setName(java.lang.String name) { + this.name = name; + } + +}</programlisting> + + <table frame="topbot"> + <title>Supported meta tags</title> + + <tgroup cols="2"> + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="2*"></colspec> + + <thead> + <row> + <entry>Attribute</entry> + + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <literal moreinfo="none">class-description</literal> + </entry> + + <entry>inserted into the javadoc for classes</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">field-description</literal> + </entry> + + <entry>inserted into the javadoc for fields/properties</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">interface</literal> + </entry> + + <entry>If true, an interface is generated instead of an class.</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">implements</literal> + </entry> + + <entry>interface the class should implement</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">extends</literal> + </entry> + + <entry>class that the current class should extend (ignored for subclasses)</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">generated-class</literal> + </entry> + + <entry>overrule the name of the actual class generated</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">scope-class</literal> + </entry> + + <entry>scope for class</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">scope-set</literal> + </entry> + + <entry>scope for setter method</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">scope-get</literal> + </entry> + + <entry>scope for getter method</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">scope-field</literal> + </entry> + + <entry>scope for actual field</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">default-value</literal> + </entry> + + <entry>default initialization value for a field</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">use-in-tostring</literal> + </entry> + + <entry>include this property in the <literal moreinfo="none">toString()</literal></entry> + </row> + + <row> + <entry> + <literal moreinfo="none">use-in-equals</literal> + </entry> + + <entry>include this property in the <literal moreinfo="none">equals()</literal> and + <literal moreinfo="none">hashCode()</literal> method. If no use-in-equals is specified, no + equals/hashcode will be generated.</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">gen-property</literal> + </entry> + + <entry>property will not be generated if false (use with care)</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">property-type</literal> + </entry> + + <entry>Overrides the default type of property. Use this with any tag's to specify the + concrete type instead of just Object.</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">class-code</literal> + </entry> + + <entry>Extra code that will inserted at the end of the class</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">extra-import</literal> + </entry> + + <entry>Extra import that will inserted at the end of all other imports</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Attributes declared via the <emphasis> + <property moreinfo="none">&lt;meta&gt;</property> + </emphasis> tag are per default <emphasis> + <property moreinfo="none">"inherited"</property> + </emphasis> inside an <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> file.</para> + + <para>What does that mean? It means that if you e.g want to have all your classes implement + <literal moreinfo="none">IAuditable</literal> then you just add an <emphasis> &lt;meta + attribute="implements"&gt;IAuditable&lt;/meta&gt;</emphasis> in the top of the <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> file, just after <emphasis> + <property moreinfo="none">&lt;hibernate-mapping&gt;</property>. </emphasis> Now all classes defined + in that <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> file will implement <literal moreinfo="none">IAuditable</literal>!</para> + + <note> + <title>Note:</title> + <para>This applies to <emphasis>all</emphasis> + <literal moreinfo="none">&lt;meta&gt;</literal>-tags. Thus it can also e.g. be used to specify that + all fields should be declare protected, instead of the default private. This is done by + adding <literal moreinfo="none">&lt;meta + attribute="scope-field"&gt;protected&lt;/meta&gt;</literal> at e.g. just under + the <literal moreinfo="none">&lt;class&gt;</literal> tag and all fields of that class will be + protected.</para> + </note> + + <para>To avoid having a <emphasis> + <property moreinfo="none">&lt;meta&gt;</property> + </emphasis> tag inherited then you can simply specify <emphasis> inherit = "false"</emphasis> + for the attribute, e.g. <emphasis> &lt;meta attribute = "scope-class" inherit = + "false"&gt;public abstract&lt;/meta&gt;</emphasis> will restrict the <emphasis> + <property moreinfo="none">"class-scope"</property> + </emphasis> to the current class, not the subclasses.</para> + + <section> + <title>Recommendations</title> + + <para>The following are some good practices when using <emphasis> + <property moreinfo="none">&lt;meta&gt;</property> + </emphasis> attributes.</para> + + <section> + <title>Dangers of a class level <literal moreinfo="none">use-in-string and use-in-equals</literal> meta + attributes when having bi-directional associations</title> + + <para>If we have two entities with a bi-directional association between them and define at + class scope level the meta attributes: <emphasis> + <property moreinfo="none">use-in-string</property>, </emphasis> + <emphasis> + <property moreinfo="none">use-in-equals</property>: </emphasis></para> + + <programlisting format="linespecific" role="XML">&lt;hibernate-mapping&gt; + &lt;class name="Person"&gt; + &lt;meta attribute="use-in-tostring"&gt;true&lt;/meta&gt; + &lt;meta attribute="use-in-equals"&gt;true&lt;/meta&gt; + ... + &lt;/class&gt; +&lt;/hibernate-mapping&gt;</programlisting> + + <para>And for <emphasis> + <property moreinfo="none">Event.hbm</property> + </emphasis> file:</para> + + <programlisting format="linespecific" role="XML">&lt;hibernate-mapping&gt; + &lt;class name="events.Event" table="EVENTS"&gt; + &lt;meta attribute="use-in-tostring"&gt;true&lt;/meta&gt; + &lt;meta attribute="use-in-equals"&gt;true&lt;/meta&gt; + &lt;id name="id" column="EVENT_ID"&gt; + &lt;generator class="native"/&gt; + &lt;/id&gt; + &lt;property name="date" type="timestamp" column="EVENT_DATE"/&gt; + &lt;property name="title"/&gt; + &lt;set name="participants" table="PERSON_EVENT" inverse="true"&gt; + &lt;key column="EVENT_ID"/&gt; + &lt;many-to-many column="PERSON_ID" class="events.Person"/&gt; + &lt;/set&gt; + &lt;/class&gt; +&lt;/hibernate-mapping&gt;</programlisting> + + <para>Then <emphasis> + <property moreinfo="none">&lt;hbm2java&gt;</property> + </emphasis> will assume you want to include all properties and collections in the + <property moreinfo="none">toString()/equals()</property> methods and this can result in infinite + recursive calls.</para> + + <para>To remedy this you have to decide which side of the association will include the other + part (if at all) in the <property moreinfo="none">toString()/equals()</property> methods. Therefore it is + not a good practice to put at class scope such <emphasis> + <property moreinfo="none">meta</property> + </emphasis> attributes, unless you are defining a class without bi-directional + associations.</para> + + <para>We recomend instead to add the <emphasis> + <property moreinfo="none">meta</property> + </emphasis> attributes at the property level:</para> + + <programlisting format="linespecific" role="XML">&lt;hibernate-mapping&gt; + &lt;class name="events.Event" table="EVENTS"&gt; + &lt;id name="id" column="EVENT_ID"&gt; + &lt;meta attribute="use-in-tostring"&gt;true&lt;/meta&gt; + &lt;generator class="native"/&gt; + &lt;/id&gt; + &lt;property name="date" type="timestamp" column="EVENT_DATE"/&gt; + &lt;property name="title"&gt; + &lt;meta attribute="use-in-tostring"&gt;true&lt;/meta&gt; + &lt;meta attribute="use-in-equals"&gt;true&lt;/meta&gt; + &lt;/property&gt; + &lt;set name="participants" table="PERSON_EVENT" inverse="true"&gt; + &lt;key column="EVENT_ID"/&gt; + &lt;many-to-many column="PERSON_ID" class="events.Person"/&gt; + &lt;/set&gt; + &lt;/class&gt; +&lt;/hibernate-mapping&gt;</programlisting> + + <para>and now for <property moreinfo="none">Person</property>:</para> + + <programlisting format="linespecific" role="XML">&lt;hibernate-mapping&gt; + &lt;class name="Person"&gt; + &lt;meta attribute="class-description"&gt; + Javadoc for the Person class + @author Frodo + &lt;/meta&gt; + &lt;meta attribute="implements"&gt;IAuditable&lt;/meta&gt; + &lt;id name="id" type="long"&gt; + &lt;meta attribute="scope-set"&gt;protected&lt;/meta&gt; + &lt;meta attribute="use-in-tostring"&gt;true&lt;/meta&gt; + &lt;generator class="increment"/&gt; + &lt;/id&gt; + &lt;property name="name" type="string"&gt; + &lt;meta attribute="field-description"&gt;The name of the person&lt;/meta&gt; + &lt;meta attribute="use-in-tostring"&gt;true&lt;/meta&gt; + &lt;/property&gt; + &lt;/class&gt; +&lt;/hibernate-mapping&gt;</programlisting> + </section> + + <section> + <title>Be aware of putting at class scope level <literal moreinfo="none">&lt;meta&gt;</literal> + attribute <literal moreinfo="none">use-in-equals</literal></title> + + <para>For <property moreinfo="none">equal()/hashCode()</property> method generation, you have to take into + account that the attributes that participate on such method definition, should take into + account only attributes with business meaning (the name, social security number, etc, but + no generated id's, for example).</para> + + <para>This is important because Java's hashbased collections, such as + <property moreinfo="none">java.util.Set</property> relies on <property moreinfo="none">equals()</property> and + <property moreinfo="none">hashcode()</property> to be correct and not change for objects in the set; + this can be a problem if the id gets assigned for an object after you inserted it into a + set.</para> + + <para>Therefore automatically configuration of the generation of + <property moreinfo="none">equals()/hashCode()</property> methods specifying at class scope level the <emphasis> + <property moreinfo="none">&lt;meta&gt;</property> + </emphasis> attribute <emphasis> + <property moreinfo="none">use-in-equals</property> + </emphasis> could be a dangerous decision that could produce non expected side-effect.</para> + + <para><ulink url="http://www.hibernate.org/109.html">Here</ulink> you can get more in-depth + explanation on the subject of <property moreinfo="none">equals()</property> and + <property moreinfo="none">hashcode()</property>.</para> + </section> + </section> + + <section> + <title>Advanced &lt;meta&gt; attribute examples</title> + + <para>This section shows an example for using meta attributes (including userspecific + attributes) together with the code generation features in <property moreinfo="none">Hibernate + Tools</property>.</para> + + <para>The usecase being implemented is to automatically insert some pre- and post-conditions + into the getter and setters of the generated POJO. </para> + + <section> + <title>Generate pre/post-conditions for methods</title> + + <para>With a <emphasis> &lt;meta attribute="class-code"&gt;</emphasis>, you can add + additional methods on a given class, nevertheless such <emphasis> + <property moreinfo="none">&lt;meta&gt;</property> + </emphasis> attribute can not be used at a property scope level and <property moreinfo="none">Hibernate + Tools</property> does not provide such <emphasis> + <property moreinfo="none">&lt;meta&gt;</property> + </emphasis> attributes.</para> + + <para>A possible solution for this is to modify the freemarker templates responsible for + generating the POJO's. If you look inside <emphasis> + <property moreinfo="none">hibernate-tools.jar</property>, </emphasis> you can find the template: <emphasis> + <property moreinfo="none">pojo/PojoPropertyAccessor.ftl</property> + </emphasis></para> + + <para>This file is as the name indicates used to generate property accessors for pojo's.</para> + + <para>Extract the <emphasis> + <property moreinfo="none">PojoPropertyAccessor.ftl</property> + </emphasis> into a local folder i.e. <emphasis> + <property moreinfo="none">${hbm.template.path}</property>, </emphasis> respecting the whole path, for + example: <emphasis> + <property moreinfo="none">${hbm.template.path}/pojo/PojoPropertyAccessor.ftl</property> + </emphasis></para> + + <para>The contents of the file is something like this:</para> + + <programlisting format="linespecific" role="XML">&lt;#foreach property in pojo.getAllPropertiesIterator()&gt; + ${pojo.getPropertyGetModifiers(property)} + ${pojo.getJavaTypeName(property, jdk5)} + ${pojo.getGetterSignature(property)}() { + return this.${property.name}; + } + + ${pojo.getPropertySetModifiers(property)} void set${pojo.getPropertyName(property)} + (${pojo.getJavaTypeName(property, jdk5)} ${property.name}) + { + this.${property.name} = ${property.name}; + } +&lt;/#foreach&gt;</programlisting> + + <para>We can add conditionally pre/post-conditions on our <literal moreinfo="none">set</literal> method + generation just adding a little Freemarker syntax to the above source code:</para> + + <programlisting format="linespecific" role="XML">&lt;#foreach property in pojo.getAllPropertiesIterator()&gt; + ${pojo.getPropertyGetModifiers(property)} + ${pojo.getJavaTypeName(property, jdk5)} + ${pojo.getGetterSignature(property)}() + { + return this.${property.name}; + } + + ${pojo.getPropertySetModifiers(property)} void set${pojo.getPropertyName(property)} + (${pojo.getJavaTypeName(property, jdk5)} ${property.name}) + { + &lt;#if pojo.hasMetaAttribute(property, "pre-cond")&gt; + ${c2j.getMetaAsString(property, "pre-cond","\n")} + &lt;/#if&gt; + this.${property.name} = ${property.name}; + &lt;#if pojo.hasMetaAttribute(property, "post-cond")&gt; + ${c2j.getMetaAsString(property, "post-cond","\n")} + &lt;/#if&gt; +} +&lt;/#foreach&gt; +</programlisting> + + <para>Now if in any <emphasis> + <property moreinfo="none">.hbm.xml</property> + </emphasis> file we define the <emphasis> + <property moreinfo="none">&lt;meta&gt;</property> + </emphasis> attributes: <literal moreinfo="none">pre-cond</literal> or <literal moreinfo="none">post-cond</literal>, their + contents will be generated into the body of the relevant <literal moreinfo="none">set</literal> method.</para> + + <para>As an example let us add a pre-condition for property <literal moreinfo="none">name</literal> + preventing no <property moreinfo="none">Person</property> can have an empty name. Hence we have to modify the <emphasis> + <property moreinfo="none">Person.hbm.xml</property> + </emphasis> file like this:</para> + + <programlisting format="linespecific" role="XML">&lt;hibernate-mapping&gt; + &lt;class name="Person"&gt; + &lt;id name="id" type="long"&gt; + &lt;generator class="increment"/&gt; + &lt;/id&gt; + &lt;property name="firstName" type="string"&gt; + &lt;meta attribute="pre-cond"&gt; + if ((firstName != null) &amp;amp;&amp;amp; (firstName.length() == 0) ) { + throw new IllegalArgumentException("firstName can not be an empty String"); + } + &lt;/meta&gt; + &lt;/property&gt; +&lt;/class&gt; +&lt;/hibernate-mapping&gt;</programlisting> + + <note> + <title>Note:</title> + <para>I) To escape the &amp; symbol we put &amp;amp;. You can use + &lt;![CDATA[]]&gt; instead.</para> + <para>II) Note that we are referring to "firstName" directly and this is the parameter + name not the actual field name. If you want to refer the field you have to use + "this.firstName" instead. </para> + </note> + + <para>Finally we have to generate the <emphasis> + <property moreinfo="none">Person.java</property> + </emphasis> class, for this we can use both Eclipse and Ant as long as you remember to set + or fill in the templatepath setting. For Ant we configure <emphasis> + <property moreinfo="none">&lt;hibernatetool&gt;</property> + </emphasis> task via <literal moreinfo="none">the templatepath</literal> attribute as in:</para> + + <programlisting format="linespecific" role="XML"> + &lt;target name="hbm2java"&gt; + &lt;taskdef name="hibernatetool" + classname="org.hibernate.tool.ant.HibernateToolTask" + classpathref="lib.classpath"/&gt; + &lt;hibernatetool destdir="${hbm2java.dest.dir}" + templatepath="${hbm.template.path}"&gt; + &lt;classpath&gt; + &lt;path refid="pojo.classpath"/&gt; + &lt;/classpath&gt; + &lt;configuration&gt; + &lt;fileset dir="${hbm2java.src.dir}"&gt; + &lt;include name="**/*.hbm.xml"/&gt; + &lt;/fileset&gt; + &lt;/configuration&gt; + &lt;hbm2java/&gt; + &lt;/hibernatetool&gt; + &lt;/target&gt;</programlisting> + + <para>Invoking the target <emphasis> + <property moreinfo="none">&lt;hbm2java&gt;</property> + </emphasis> will generate on the <emphasis> + <property moreinfo="none">${hbm2java.dest.dir}</property> + </emphasis> the file <emphasis> + <property moreinfo="none">Person.java</property> + </emphasis>:</para> + + <programlisting format="linespecific" role="JAVA">// default package +import java.io.Serializable; +public class Person implements Serializable { + + public Long id; + + public String name; + + public Person(java.lang.String name) { + this.name = name; + } + + public Person() { + } + + public java.lang.Long getId() { + return this.id; + } + + public void setId(java.lang.Long id) { + this.id = id; + } + + public java.lang.String getName() { + return this.name; + } + + public void setName(java.lang.String name) { + if ((name != null) &amp;amp;&amp;amp; (name.length() == 0)) { + throw new IllegalArgumentException("name can not be an empty String"); + } + this.name = name; + } + }</programlisting> + + + + + + + <para>To find additional information about <property moreinfo="none">Hibernate Tools</property> we suggest that you + visit our <ulink url="http://www.hibernate.org/255.html">website</ulink>;. If you have questions, you are always welcome in our + <ulink url="http://forum.hibernate.org/viewforum.php?f=6">forum<... + </section> + </section> + + </section> + +</chapter> + + + + + </book> Modified: branches/jbosstools-3.0.0.Beta1/hibernatetools/docs/reference/pom.xml =================================================================== --- branches/jbosstools-3.0.0.Beta1/hibernatetools/docs/reference/pom.xml 2008-10-29 16:17:50 UTC (rev 11301) +++ branches/jbosstools-3.0.0.Beta1/hibernatetools/docs/reference/pom.xml 2008-10-29 16:24:29 UTC (rev 11302) @@ -32,7 +32,7 @@ </dependency> </dependencies> <configuration> - <sourceDocumentName>master.xml</sourceDocumentName> + <sourceDocumentName>master_output.xml</sourceDocumentName> <sourceDirectory>${pom.basedir}/en</sourceDirectory> <imageResource> <directory>${pom.basedir}/en</directory>