[jbosstools-commits] JBoss Tools SVN: r6304 - trunk/hibernatetools/docs/reference/en/modules.

Author: ochikvina Date: 2008-02-13 12:24:27 -0500 (Wed, 13 Feb 2008) New Revision: 6304 Modified: trunk/hibernatetools/docs/reference/en/modules/codegen.xml trunk/hibernatetools/docs/reference/en/modules/reverseengineering.xml Log: http://jira.jboss.com/jira/browse/JBDS-173 - highlighting code patterns; http://jira.jboss.com/jira/browse/JBDS-238 - making changes according to Svetlana remarks; replacing tables with new ones with headers Modified: trunk/hibernatetools/docs/reference/en/modules/codegen.xml =================================================================== --- trunk/hibernatetools/docs/reference/en/modules/codegen.xml 2008-02-13 17:22:22 UTC (rev 6303) +++ trunk/hibernatetools/docs/reference/en/modules/codegen.xml 2008-02-13 17:24:27 UTC (rev 6304) @@ -6,9 +6,10 @@ <property>&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 through the <emphasis> - <property>&lt;meta&gt;</property></emphasis> - tag in the mapping files. The following section describes the possible <emphasis> - <property>&lt;meta&gt;</property></emphasis> tags and their use.</para> + <property>&lt;meta&gt;</property> + </emphasis> tag in the mapping files. The following section describes the possible <emphasis> + <property>&lt;meta&gt;</property> + </emphasis> tags and their use.</para> <section> <title>The <literal>&lt;meta&gt;</literal> attribute</title> @@ -33,27 +34,27 @@ <property>&lt;meta&gt;</property> </emphasis> attributes and the resulting java code.</para> - <programlisting>&lt;class name="Person"&gt; - &lt;meta attribute="class-description"&gt; + <programlisting role="XML"><![CDATA[<class name="Person"> + <meta attribute="class-description"> 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> + </meta> + <meta attribute="implements">IAuditable</meta> + <id name="id" type="long"> + <meta attribute="scope-set">protected</meta> + <generator class="increment"/> + </id> + <property name="name" type="string"> + <meta attribute="field-description">The name of the person</meta> + </property> +</class>]]></programlisting> <para>The above <emphasis> <property>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>// default package + <programlisting role="JAVA"><![CDATA[// default package import java.io.Serializable; import org.apache.commons.lang.builder.EqualsBuilder; @@ -96,13 +97,13 @@ this.name = name; } -}</programlisting> +}]]></programlisting> <table frame="topbot"> <title>Supported meta tags</title> <tgroup cols="2"> - <colspec colwidth="1.5*"/> + <colspec colwidth="1.0*"/> <colspec colwidth="2*"/> @@ -270,8 +271,8 @@ attribute="implements"&gt;IAuditable&lt;/meta&gt;</emphasis> in the top of the <emphasis> <property>hbm.xml</property> </emphasis> file, just after <emphasis> - <property>&lt;hibernate-mapping&gt;</property> - </emphasis>. Now all classes defined in that <emphasis> + <property>&lt;hibernate-mapping&gt;</property>. </emphasis> Now all classes defined + in that <emphasis> <property>hbm.xml</property> </emphasis> file will implement <literal>IAuditable</literal>!</para> @@ -306,48 +307,47 @@ <para>If we have two entities with a bi-directional association between them and define at class scope level the meta attributes: <emphasis> - <property>use-in-string</property> - </emphasis>, <emphasis> - <property>use-in-equals</property> - </emphasis>:</para> + <property>use-in-string</property>, </emphasis> + <emphasis> + <property>use-in-equals</property>: </emphasis></para> - <programlisting>&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; + <programlisting role="XML"><![CDATA[<hibernate-mapping> + <class name="Person"> + <meta attribute="use-in-tostring">true</meta> + <meta attribute="use-in-equals">true</meta> ... - &lt;/class&gt; -&lt;/hibernate-mapping&gt;</programlisting> + </class> +</hibernate-mapping>]]></programlisting> <para>And for <emphasis> <property>Event.hbm</property> </emphasis> file:</para> - <programlisting>&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> + <programlisting role="XML"><![CDATA[<hibernate-mapping> + <class name="events.Event" table="EVENTS"> + <meta attribute="use-in-tostring">true</meta> + <meta attribute="use-in-equals">true</meta> + <id name="id" column="EVENT_ID"> + <generator class="native"/> + </id> + <property name="date" type="timestamp" column="EVENT_DATE"/> + <property name="title"/> + <set name="participants" table="PERSON_EVENT" inverse="true"> + <key column="EVENT_ID"/> + <many-to-many column="PERSON_ID" class="events.Person"/> + </set> + </class> +</hibernate-mapping>]]></programlisting> <para>Then <emphasis> <property>&lt;hbm2java&gt;</property> </emphasis> will assume you want to include all properties and collections in the - <property>toString()</property>/<property>equals()</property> methods and this can - result in infinite recursive calls.</para> + <property>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>toString()/equals()</property> - methods. Therefore it is not a good practice to put at class scope such <emphasis> + part (if at all) in the <property>toString()/equals()</property> methods. Therefore it is + not a good practice to put at class scope such <emphasis> <property>meta</property> </emphasis> attributes, unless you are defining a class without bi-directional associations.</para> @@ -356,54 +356,54 @@ <property>meta</property> </emphasis> attributes at the property level:</para> - <programlisting>&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> + <programlisting role="XML"><![CDATA[<hibernate-mapping> + <class name="events.Event" table="EVENTS"> + <id name="id" column="EVENT_ID"> + <meta attribute="use-in-tostring">true</meta> + <generator class="native"/> + </id> + <property name="date" type="timestamp" column="EVENT_DATE"/> + <property name="title"> + <meta attribute="use-in-tostring">true</meta> + <meta attribute="use-in-equals">true</meta> + </property> + <set name="participants" table="PERSON_EVENT" inverse="true"> + <key column="EVENT_ID"/> + <many-to-many column="PERSON_ID" class="events.Person"/> + </set> + </class> +</hibernate-mapping>]]></programlisting> - <para>and now for <literal>Person</literal>:</para> + <para>and now for <property>Person</property>:</para> - <programlisting>&lt;hibernate-mapping&gt; - &lt;class name="Person"&gt; - &lt;meta attribute="class-description"&gt; + <programlisting role="XML"><![CDATA[<hibernate-mapping> + <class name="Person"> + <meta attribute="class-description"> 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> + </meta> + <meta attribute="implements">IAuditable</meta> + <id name="id" type="long"> + <meta attribute="scope-set">protected</meta> + <meta attribute="use-in-tostring">true</meta> + <generator class="increment"/> + </id> + <property name="name" type="string"> + <meta attribute="field-description">The name of the person</meta> + <meta attribute="use-in-tostring">true</meta> + </property> + </class> +</hibernate-mapping>]]></programlisting> </section> <section> <title>Be aware of putting at class scope level <literal>&lt;meta&gt;</literal> attribute <literal>use-in-equals</literal></title> - <para>For <property>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>For <property>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>java.util.Set</property> relies on <property>equals()</property> and @@ -411,19 +411,21 @@ 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 the generation of - <property>equals()/hashCode()</property> methods specifying at class scope level the <emphasis> + <para>Therefore automatically configuration of the generation of + <property>equals()/hashCode()</property> methods specifying at class scope level the <emphasis> <property>&lt;meta&gt;</property> - </emphasis> attribute <emphasis><property>use-in-equals</property></emphasis> could be a dangerous decision that - could produce non expected side-effect.</para> + </emphasis> attribute <emphasis> + <property>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>equals()</property> and <property>hashcode()</property>.</para> + explanation on the subject of <property>equals()</property> and + <property>hashcode()</property>.</para> </section> </section> <section> - <title>Advanced <emphasis><property>&lt;meta&gt;</property></emphasis> attribute examples</title> + <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>Hibernate @@ -438,15 +440,14 @@ <para>With an <emphasis> &lt;meta attribute="class-code"&gt;</emphasis>, you can add additional methods on a given class, nevertheless such <emphasis> <property>&lt;meta&gt;</property> - </emphasis> attribute can not be used at property scope level and <property>Hibernate + </emphasis> attribute can not be used at a property scope level and <property>Hibernate Tools</property> does not provide such <emphasis> <property>&lt;meta&gt;</property> </emphasis> attributes.</para> <para>A possibly solution for this is to modify the freemarker templates responsible for generating the POJO's. If you look inside <emphasis> - <property>hibernate-tools.jar</property> - </emphasis>, you can find the template: <emphasis> + <property>hibernate-tools.jar</property>, </emphasis> you can find the template: <emphasis> <property>pojo/PojoPropertyAccessor.ftl</property> </emphasis></para> @@ -455,14 +456,14 @@ <para>Extract the <emphasis> <property>PojoPropertyAccessor.ftl</property> </emphasis> into a local folder i.e. <emphasis> - <property>${hbm.template.path}</property> - </emphasis>, respecting the whole path, for example: <emphasis> + <property>${hbm.template.path}</property>, </emphasis> respecting the whole path, for + example: <emphasis> <property>${hbm.template.path}/pojo/PojoPropertyAccessor.ftl</property> </emphasis></para> <para>The contents of the file is something like this:</para> - <programlisting>&lt;#foreach property in pojo.getAllPropertiesIterator()&gt; + <programlisting role="XML"><![CDATA[<#foreach property in pojo.getAllPropertiesIterator()> ${pojo.getPropertyGetModifiers(property)} ${pojo.getJavaTypeName(property, jdk5)} ${pojo.getGetterSignature(property)}() { @@ -474,12 +475,12 @@ { this.${property.name} = ${property.name}; } -&lt;/#foreach&gt;</programlisting> +</#foreach>]]></programlisting> <para>We can add conditionally pre/post-conditions on our <literal>set</literal> method generation just adding a little Freemarker syntax to the above source code:</para> - <programlisting>&lt;#foreach property in pojo.getAllPropertiesIterator()&gt; + <programlisting role="XML"><![CDATA[<#foreach property in pojo.getAllPropertiesIterator()> ${pojo.getPropertyGetModifiers(property)} ${pojo.getJavaTypeName(property, jdk5)} ${pojo.getGetterSignature(property)}() @@ -490,84 +491,87 @@ ${pojo.getPropertySetModifiers(property)} void set${pojo.getPropertyName(property)} (${pojo.getJavaTypeName(property, jdk5)} ${property.name}) { - &lt;#if pojo.hasMetaAttribute(property, "pre-cond")&gt; + <#if pojo.hasMetaAttribute(property, "pre-cond")> ${c2j.getMetaAsString(property, "pre-cond","\n")} - &lt;/#if&gt; + </#if> this.${property.name} = ${property.name}; - &lt;#if pojo.hasMetaAttribute(property, "post-cond")&gt; + <#if pojo.hasMetaAttribute(property, "post-cond")> ${c2j.getMetaAsString(property, "post-cond","\n")} - &lt;/#if&gt; + </#if> } -&lt;/#foreach&gt; +</#foreach>]]> </programlisting> <para>Now if in any <emphasis> - <property>*hbm.xml</property> + <property>.hbm.xml</property> </emphasis> file we define the <emphasis> <property>&lt;meta&gt;</property> </emphasis> attributes: <literal>pre-cond</literal> or <literal>post-cond</literal>, their contents will be generated into the body of the relevant <literal>set</literal> method.</para> <para>As an example let us add a pre-condition for property <literal>name</literal> - preventing no <literal>Person</literal> can have an empty name. So we have to modify the <emphasis> + preventing no <property>Person</property> can have an empty name. So we have to modify the <emphasis> <property>Person.hbm.xml</property> </emphasis> file like this:</para> - <programlisting>&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;&lt;![CDATA[ + <programlisting role="XML"><![CDATA[<hibernate-mapping> + <class name="Person"> + <id name="id" type="long"> + <generator class="increment"/> + </id> + <property name="firstName" type="string"> + <meta attribute="pre-cond"> if ((firstName != null) &amp;&amp; (firstName.length() == 0) ) { throw new IllegalArgumentException("firstName can not be an empty String"); - }]]&gt; - &lt;/meta&gt; - &lt;/property&gt; -&lt;/class&gt; -&lt;/hibernate-mapping&gt;</programlisting> + } + </meta> + </property> +</class> +</hibernate-mapping>]]></programlisting> <note> - <para>I) If you don'&apos; use <literal>&lt;[[CDATA[]]&gt;</literal> you have - to scape the &amp; symbol, i.e.: &amp;amp; </para> - <para>II). Note that we are referring to "firstName" directly and this is the parameter + <para>I) To scape 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 <property>Person.java</property> 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> + <para>Finally we have to generate the <emphasis> + <property>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>&lt;hibernatetool&gt;</property> </emphasis> task via <literal>the templatepath</literal> attribute as in:</para> - <programlisting> - &lt;target name="hbm2java"&gt; - &lt;taskdef name="hibernatetool" + <programlisting role="XML"><![CDATA[ + <target name="hbm2java"> + <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> + classpathref="lib.classpath"/> + <hibernatetool destdir="${hbm2java.dest.dir}" + templatepath="${hbm.template.path}"> + <classpath> + <path refid="pojo.classpath"/> + </classpath> + <configuration> + <fileset dir="${hbm2java.src.dir}"> + <include name="**/*.hbm.xml"/> + </fileset> + </configuration> + <hbm2java/> + </hibernatetool> + </target>]]></programlisting> <para>Invoking the target <emphasis> <property>&lt;hbm2java&gt;</property> </emphasis> will generate on the <emphasis> <property>${hbm2java.dest.dir}</property> - </emphasis> the file <property>Person.java</property>:</para> + </emphasis> the file <emphasis> + <property>Person.java</property> + </emphasis>:</para> - <programlisting>// default package + <programlisting role="JAVA"><![CDATA[// default package import java.io.Serializable; public class Person implements Serializable { @@ -600,10 +604,13 @@ } this.name = name; } -}</programlisting> +}]]></programlisting> <para/> </section> </section> </section> + <para>To find additional information about <property>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<... </chapter> Modified: trunk/hibernatetools/docs/reference/en/modules/reverseengineering.xml =================================================================== --- trunk/hibernatetools/docs/reference/en/modules/reverseengineering.xml 2008-02-13 17:22:22 UTC (rev 6303) +++ trunk/hibernatetools/docs/reference/en/modules/reverseengineering.xml 2008-02-13 17:24:27 UTC (rev 6304) @@ -3,10 +3,9 @@ <title>Controlling reverse engineering</title> <para>When using the <emphasis> - <property>&lt;jdbcconfiguration&gt;</property> - </emphasis> the ant task will read the database metadata and from that will perform a reverse - engineering of the database schema into a normal Hibernate Configuration. It is from this object - e.g. <emphasis> + <property>&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>&lt;hbm2java&gt;</property> </emphasis>can generate other artifacts such as <emphasis> <property>.java</property> @@ -22,6 +21,9 @@ 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> @@ -38,19 +40,20 @@ <property>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&apos;s just basic XML) or you can use the - Hibernate plugins which have a specialized editor.</para> + <ulink url="http://www.hibernate.org/30.html">Hibernate plugins</ulink> which have a + specialized editor.</para> <note> <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 + 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>The following is an example of a <emphasis> - <property>reveng.xml</property> - </emphasis>. Following the example gives you more details about the format.</para> + <para>Below you can see an example of a <emphasis> + <property>reveng.xml</property>. </emphasis> Following the example gives you more details + about the format.</para> - <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> + <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE hibernate-reverse-engineering SYSTEM "http://hibernate.sourceforge.net/hibernate-reverse-engineering-3.0.dtd" > @@ -102,7 +105,7 @@ <para><emphasis> <property>&lt;schema-selection&gt;</property> - </emphasis> is used to drive which schema&apos;s the reverse engineering will try and + </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> @@ -120,8 +123,7 @@ <note> <para>If no <literal>&lt;schema-selection&gt;</literal> is specified, the reverse engineering works as if all schemas should be processed. This is equal to: - <![CDATA[<schema-selection/>]]>. Which in turn is equal - to: + <![CDATA[<schema-selection/>]]>. Which in turn is equal to: <![CDATA[<schema-selection match-catalog=".*" match-schema=".*" match-table=".*"/>]]></para> </note> @@ -129,24 +131,24 @@ <title>Examples</title> <para>The following will process all tables from <emphasis> - <property>&quot;MY_SCHEMA&quot;</property> - </emphasis>.</para> + <property>&quot;MY_SCHEMA&quot;</property>. + </emphasis></para> - <programlisting><![CDATA[<schema-selection match-schema="MY_SCHEMA"/>]]></programlisting> + <programlisting role="XML"><![CDATA[<schema-selection match-schema="MY_SCHEMA"/>]]></programlisting> <para>It is possible to have multiple <literal>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>&quot;MY_SCHEMA&quot;</property> - </emphasis>, a specific <emphasis> + <property>&quot;MY_SCHEMA&quot;</property>, + </emphasis> a specific <emphasis> <property>&quot;CITY&quot;</property> </emphasis> table plus all tables that starts with <emphasis> <property>&quot;CODES_&quot;</property> </emphasis> in <emphasis> - <property>COMMON_SCHEMA&quot;</property> - </emphasis>.</para> + <property>&quot;COMMON_SCHEMA&quot;</property>. + </emphasis></para> - <programlisting><![CDATA[<schema-selection match-schema="MY_SCHEMA"/> + <programlisting role="XML"><![CDATA[<schema-selection match-schema="MY_SCHEMA"/> <schema-selection match-schema="COMMON_SCHEMA" match-table="CITY"/> <schema-selection match-schema="COMMON_SCHEMA" match-table="CODES_.*"/>]]></programlisting> </section> @@ -158,11 +160,14 @@ <para>The <emphasis> <property>&lt;type-mapping&gt;</property> </emphasis> section specifies how the JDBC types found in the database should be mapped to - Hibernate types. e.g. java.sql.Types.VARCHAR with a length of 1 should be mapped to the - Hibernate type <literal>yes_no</literal> or java.sql.Types.NUMERIC should generally just be + Hibernate types. e.g. <emphasis> + <property>java.sql.Types.VARCHAR</property></emphasis> with a length of 1 should be mapped to the + Hibernate type <emphasis> + <property>yes_no</property></emphasis> or <emphasis> + <property>java.sql.Types.NUMERIC</property></emphasis> should generally just be converted to the Hibernate type <literal>long</literal>.</para> - <programlisting><![CDATA[<type-mapping> + <programlisting role="XML"><![CDATA[<type-mapping> <sql-type jdbc-type="integer value or name from java.sql.Types" length="a numeric value" @@ -184,7 +189,7 @@ <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><![CDATA[<type-mapping> + <programlisting role="XML"><![CDATA[<type-mapping> <sql-type jdbc-type="NUMERIC" precision="15" hibernate-type="big_decimal"/> <sql-type jdbc-type="NUMERIC" not-null="true" hibernate-type="long" /> <sql-type jdbc-type="NUMERIC" not-null="false" hibernate-type="java.lang.Long" /> @@ -195,26 +200,27 @@ <sql-type jdbc-type="VARCHAR" hibernate-type="string"/> </type-mapping>]]></programlisting> - <para>The following table shows how this affects an example table named CUSTOMER:</para> + <para>The following table shows how this affects an example table named <emphasis> + <property>CUSTOMER</property>:</emphasis></para> <table frame="topbot"> <title>sql-type examples</title> <tgroup cols="7"> - <colspec colwidth="0.5*"/> + <colspec colwidth="0.4*"/> - <colspec colwidth="0.5*"/> + <colspec colwidth="0.4*"/> <colspec colwidth="0.2*"/> - <colspec colwidth="0.2*"/> + <colspec colwidth="0.3*"/> <colspec colwidth="0.2*"/> - <colspec colwidth="0.5*"/> - <colspec colwidth="1.0*"/> + <colspec colwidth="0.7*"/> + <thead> <row> <entry>Column</entry> @@ -351,51 +357,83 @@ tables, e.g. let you include or exclude specific tables based on the schema or even a specific prefix.</para> - <programlistingco> - <areaspec> - <area coords="2 55" id="tablefilter-matchcatalog"/> - - <area coords="3 55" id="tablefilter-matchschema"/> - - <area coords="4 55" id="tablefilter-matchname"/> - - <area coords="5 55" id="tablefilter-exclude"/> - - <area coords="6 55" id="tablefilter-package"/> - </areaspec> - - <programlisting><![CDATA[<table-filter + <programlisting role="XML"><![CDATA[<table-filter match-catalog="catalog_matching_rule" match-schema="schema_matching_rule" match-name="table_matching_rule" exclude="true|false" package="package.name" />]]></programlisting> - - <calloutlist> - <callout arearefs="tablefilter-matchcatalog"> - <para>match-catalog (default: .*): Pattern for matching catalog part of the table</para> - </callout> - - <callout arearefs="tablefilter-matchschema"> - <para>match-schema (default: .*): Pattern for matching schema part of the table</para> - </callout> - - <callout arearefs="tablefilter-matchname"> - <para>match-table (default: .*): Pattern for matching table part of the table</para> - </callout> - - <callout arearefs="tablefilter-exclude"> - <para>exclude (default: false): if true the table will not be part of the reverse - engineering</para> - </callout> - - <callout arearefs="tablefilter-package"> - <para>package (default: ""): The default package name to use for classes based on tables - matched by this table-filter</para> - </callout> - </calloutlist> - </programlistingco> + + <table frame="topbot"> + <title>Table-filter attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"/> + + <colspec colwidth="1.0*"/> + + <colspec colwidth="0.3*"/> + + + <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> @@ -404,21 +442,10 @@ <para><emphasis> <property>&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> + 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> - <programlistingco> - <areaspec> - <area coords="2 55" id="table-catalog"/> - - <area coords="3 55" id="table-schema"/> - - <area coords="4 55" id="table-name"/> - - <area coords="5 55" id="table-class"/> - </areaspec> - - <programlisting><![CDATA[<table + <programlisting role="XML"><![CDATA[<table catalog="catalog_name" schema="schema_name" name="table_name" @@ -427,75 +454,145 @@ <primary-key.../> <column.../> <foreign-key.../> -</table>]]></programlisting> + </table>]]></programlisting> + + <table frame="topbot"> + <title>Table attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"/> + + <colspec colwidth="1.0*"/> + + <colspec colwidth="0.3*"/> + + + <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> - <calloutlist> - <callout arearefs="tablefilter-matchcatalog"> - <para>catalog (Optional): Catalog name for a table. It has to be specified if you are reverse - engineering multiple catalogs or if it is not equal to - <literal>hiberante.default_catalog. </literal></para> - </callout> - - <callout arearefs="tablefilter-matchschema"> - <para>schema (Optional): Schema name for a table. It has to be specified if you are reverse - engineering multiple schemas or if it is not equal to - <literal>hiberante.default_schema.</literal></para> - </callout> - - <callout arearefs="tablefilter-matchname"> - <para>name (Required): Name for a table</para> - </callout> - - <callout arearefs="tablefilter-exclude"> - <para>clase (Optional): The class name for a table. Default name is a camelcase version of - the table name.</para> - </callout> - </calloutlist> - </programlistingco> - <section> <title>&lt;primary-key&gt;</title> <para>A <emphasis> <property>&lt;primary-key&gt;</property> - </emphasis> allows you to define a primary-key for tables that don&apos;t have such 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> + </emphasis> allows you to define a primary-key for tables that don&apos;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> - <programlistingco> - <areaspec> - <area coords="2 55" id="pk-generatorclass"/> - - <area coords="3 55" id="pk-generatorparam"/> - - <area coords="5 55" id="pk-keycolumn"/> - </areaspec> - - <programlisting><![CDATA[<primary-key + <programlisting role="XML"><![CDATA[<primary-key <generator class="generatorname"> <param name="param_name">parameter value</param> </generator> <key-column...> -</primary-key>]]></programlisting> + </primary-key>]]></programlisting> + + <table frame="topbot"> + <title>Primary-key attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"/> + + <colspec colwidth="1.0*"/> + + <colspec colwidth="0.3*"/> + + + <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> - <calloutlist> - <callout arearefs="pk-generatorclass"> - <para>generator/class (Optional): 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> - </callout> - - <callout arearefs="pk-generatorparam"> - <para>generator/param (Optional): Allows to specify which parameter with a name and - value should be passed to the identifier generator</para> - </callout> - - <callout arearefs="pk-keycolumn"> - <para>key-column (Optional): Specifies which column(s ) the primary-key consists of. A - key-column is same as column, but does not have the exclude property.</para> - </callout> - </calloutlist> - </programlistingco> </section> <section> @@ -504,24 +601,10 @@ <para>With a <emphasis> <property>&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> - - <para> - <programlistingco> - <areaspec> - <area coords="2 55" id="column-name"/> - - <area coords="3 55" id="column-jdbctype"/> - - <area coords="4 55" id="column-type"/> - - <area coords="5 55" id="column-propertytype"/> - - <area coords="6 55" id="column-exclude"/> - </areaspec> - - <programlisting><![CDATA[<column + 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 role="XML"><![CDATA[<column name="column_name" jdbc-type="java.sql.Types type" type="hibernate_type" @@ -529,32 +612,78 @@ exclude="true|false" />]]></programlisting> - <calloutlist> - <callout arearefs="column-name"> - <para>name (Required): Column name</para> - </callout> - - <callout arearefs="column-jdbctype"> - <para>jdbc-type (Optional): Which jdbc-type this column should be processed as. A + <table frame="topbot"> + <title>Column attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"/> + + <colspec colwidth="1.0*"/> + + <colspec colwidth="0.3*"/> + + + <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> - </callout> - - <callout arearefs="column-type"> - <para>type (Optional): Which hibernate-type to use for this specific column</para> - </callout> - - <callout arearefs="column-propertytype"> - <para>property (Optional): What property name will be generated for this - column</para> - </callout> - - <callout arearefs="column-exclude"> - <para>exclude (default: false): set to true if this column should be ignored</para> - </callout> - </calloutlist> - </programlistingco> - </para> + (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> @@ -568,25 +697,7 @@ <para>Note:</para> - <para> - <programlistingco> - <areaspec> - <area coords="2 55" id="foreignkey-name"/> - - <area coords="3 55" id="foreignkey-catalog"/> - - <area coords="4 55" id="foreignkey-schema"/> - - <area coords="5 55" id="foreignkey-table"/> - - <area coords="7 55" id="foreignkey-columnref"/> - - <area coords="8 55" id="foreignkey-manytoone"/> - - <area coords="10 55" id="foreignkey-set"/> - </areaspec> - - <programlisting><![CDATA[<foreign-key + <programlisting role="XML"><![CDATA[<foreign-key constraint-name="foreignKeyName" foreign-catalog="catalogName" foreign-schema="schemaName" @@ -599,50 +710,103 @@ <set property="aCollectionName" exclude="true|false"/> -</foreign-key>]]></programlisting> - - <calloutlist> - <callout arearefs="foreignkey-name"> - <para>constraint-name (Required): Name of the foreign key constraint. Important when + </foreign-key>]]></programlisting> + + <table frame="topbot"> + <title>Foreign-key attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"/> + + <colspec colwidth="1.0*"/> + + <colspec colwidth="0.3*"/> + + + <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 many-to-one and set. It is the constraint-name that is used to link the - processed foreign-keys with the resulting property names.</para> - </callout> - - <callout arearefs="foreignkey-catalog"> - <para>foreign-catalog (Optional): Name of the foreign table's catalog. (Only - relevant if you want to explicitly define a foreign key).</para> - </callout> - - <callout arearefs="foreignkey-schema"> - <para>foreign-schema (Optional): Name of the foreign table's schema. (Only relevant - if you want to explicitly define a foreign key).</para> - </callout> - - <callout arearefs="foreignkey-table"> - <para>foreign-table (Optional): Name of the foreign table. (Only relevant if you - want to explicitly define a foreign key).</para> - </callout> - - <callout arearefs="foreignkey-columnref"> - <para>column-ref (Optional): Defines that the foreign-key constraint between a + 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> - </callout> - - <callout arearefs="foreignkey-manytoone"> - <para>many-to-one (Optional): Defines that a many-to-one should be created and the + 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> - </callout> - - <callout arearefs="foreignkey-set"> - <para>set (Optional): Defines that a set should be created based on this foreign-key + 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> - </callout> - </calloutlist> - </programlistingco> - </para> + Exclude can be used to explicitly define that it should be created or not.</para></entry> + + <entry><para>Optional</para></entry> + </row> + </tbody> + + </tgroup> + </table> + </section> </section> </section> @@ -650,19 +814,19 @@ <section id="custom-reveng-strategy"> <title>Custom strategy</title> - <para>It is possible to implement an user strategy. Such strategy must implement <emphasis> - <property>org.hibernate.cfg.reveng.ReverseEngineeringStrategy</property> - </emphasis>. It is recommended that one uses the + <para>It is possible to implement a user strategy. Such strategy must implement <emphasis> + <property>org.hibernate.cfg.reveng.ReverseEngineeringStrategy</property>. + </emphasis> It is recommended that one uses the <property>DelegatingReverseEngineeringStrategy</property> and provide a public constructor - which takes another <property>ReverseEngineeringStrategy </property> as argument. This will + which takes another <property>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>&quot;PK&quot;</property> </emphasis> into a property named <emphasis> - <property>&quot;id&quot;</property> - </emphasis>.</para> + <property>&quot;id&quot;</property>. + </emphasis></para> - <programlisting><![CDATA[public class ExampleStrategy extends DelegatingReverseEngineeringStrategy { + <programlisting role="JAVA"><![CDATA[public class ExampleStrategy extends DelegatingReverseEngineeringStrategy { public ExampleStrategy(ReverseEngineeringStrategy delegate) { super(delegate); @@ -685,8 +849,8 @@ metadata API. This is done via the class <emphasis> <property>org.hibernate.cfg.reveng.dialect.JDBCMetaDataDialect</property> </emphasis> which is an implementation of <emphasis> - <property>org.hibernate.cfg.reveng.dialect.MetaDataDialect</property> - </emphasis>.</para> + <property>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>