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

Author: ochikvina Date: 2008-02-13 12:22:22 -0500 (Wed, 13 Feb 2008) New Revision: 6303 Modified: trunk/hibernatetools/docs/reference/en/modules/ant.xml Log: http://jira.jboss.com/jira/browse/JBDS-173 - highlighting code patterns; http://jira.jboss.com/jira/browse/JBDS-238 - replacing tables with new ones that are with headers Modified: trunk/hibernatetools/docs/reference/en/modules/ant.xml =================================================================== --- trunk/hibernatetools/docs/reference/en/modules/ant.xml 2008-02-13 16:46:26 UTC (rev 6302) +++ trunk/hibernatetools/docs/reference/en/modules/ant.xml 2008-02-13 17:22:22 UTC (rev 6303) @@ -12,7 +12,8 @@ from tools.hibernate.org. The <emphasis> <property>hibernate-tools.jar</property> </emphasis> is located in your eclipse plugins directory at - /plugins/org.hibernate.eclipse.x.x.x/lib/tools/hibernate-tools.jar.</para> + <emphasis> + <property>/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> @@ -33,7 +34,9 @@ </emphasis> task defined. That is done in your <emphasis> <property>build.xml</property> </emphasis> by inserting the following xml (assuming the jars are in the - <literal>lib</literal> directory): <programlisting><![CDATA[<path id="toolslib"> + <literal>lib</literal> directory): </para> + + <programlisting role="XML"><![CDATA[<path id="toolslib"> <path location="lib/hibernate-tools.jar" /> <path location="lib/hibernate3.jar" /> <path location="lib/freemarker.jar" /> @@ -43,7 +46,7 @@ <taskdef name="hibernatetool" classname="org.hibernate.tool.ant.HibernateToolTask" classpathref="toolslib" /> -]]></programlisting></para> +]]></programlisting> <para>This <emphasis> <property> @@ -65,23 +68,7 @@ <property> hibernatetool </property> </emphasis> task you have to specify one or more of the following:</para> - <para> - <programlistingco> - <areaspec> - <area coords="2 55" id="ht1"/> - - <area coords="3 55" id="ht2"/> - - <area coords="4 55" id="ht3"/> - - <area coords="7 55" id="ht4"/> - - <area coords="8 55" id="ht5"/> - - <area coords="10 55" id="ht6"/> - </areaspec> - - <programlisting><![CDATA[<hibernatetool + <programlisting role="XML"><![CDATA[<hibernatetool destdir="defaultDestinationDirectory" templatepath="defaultTemplatePath" @@ -90,43 +77,92 @@ <propertyset ...> (<configuration ...>|<annotationconfiguration ...>| <jpaconfiguration ...>|<jdbcconfiguration ...>) - (<hbm2java>,<hbm2cfgxml>,<hbmtemplate>,...*) + (<hbm2java>,<hbm2cfgxml>,<hbmtemplate>,...) </hibernatetool>]]></programlisting> - <calloutlist> - <callout arearefs="ht1"> - <para><literal>destdir</literal> (required): destination directory for files generated - with exporters</para> - </callout> - - <callout arearefs="ht2"> - <para><literal>templatepath</literal> (optional): A path to be used to look up - user-edited templates</para> - </callout> - - <callout arearefs="ht3"> - <para>classpath (optional): A classpath to be used to resolve resources, such as - mappings and usertypes. Optional, but very often required.</para> - </callout> - - <callout arearefs="ht4"> - <para><literal>property</literal> and propertyset (optional): Used to set properties to + <table frame="topbot"> + <title>Hibernatetool 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>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> - </callout> - - <callout arearefs="ht5"> - <para>One of 4 different ways of configuring the Hibernate Meta Model must be - specified</para> - </callout> - - <callout arearefs="ht6"> - <para>One or more of the exporters must be specified</para> - </callout> - </calloutlist> - </programlistingco> - </para> - + 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> @@ -135,13 +171,12 @@ </emphasis> from a normal <emphasis> <property> <literal>hibernate.cfg.xml</literal> - </property> - </emphasis>. The output will be put in the <emphasis> + </property>. + </emphasis> The output will be put in the <emphasis> <property>${build.dir}/generated</property> </emphasis> directory.</para> - <para> - <programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <programlisting role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> <classpath> <path location="${build.dir}/classes"/> </classpath> @@ -149,16 +184,16 @@ <configuration configurationfile="hibernate.cfg.xml"/> <hbm2java/> </hibernatetool>]]></programlisting> - </para> + <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>&lt;hbm2dll&gt;</property> - </emphasis>, generates some DAO code via <emphasis> + <property>&lt;hbm2dll&gt;</property>, + </emphasis> generates some DAO code via <emphasis> <property>&lt;hbm2dao&gt;</property> </emphasis> and finally runs a custom code generation via <emphasis> - <property>&lt;hbmtemplate&gt;</property> - </emphasis>. This is again from a normal <emphasis> + <property>&lt;hbmtemplate&gt;</property>. + </emphasis> This is again from a normal <emphasis> <property>hibernate.cfg.xml</property> </emphasis> and the output is still put in the <emphasis> <property> @@ -168,8 +203,7 @@ when you e.g. have custom usertypes or some mappings that is needed to be looked up as a classpath resource.</para> - <para> - <programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <programlisting role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> <classpath> <path location="${build.dir}/classes"/> </classpath> @@ -183,7 +217,7 @@ template="myconstants.vm" /> </hibernatetool>]]></programlisting> - </para> + </section> </section> @@ -191,24 +225,25 @@ <title>Hibernate Configurations</title> <para><literal>Hibernatetool</literal> supports four different Hibernate configurations: A - standard Hibernate configuration (<emphasis> - <property>&lt;configuration&gt;</property> - </emphasis>), Annotation based configuration (<emphasis> - <property>&lt;annotationconfiguration&gt;</property> - </emphasis>), JPA persistence based configuration (<emphasis> - <property>&lt;jpaconfiguration&gt;</property> - </emphasis>) and a JDBC based configuration (<emphasis> - <property>&lt;jdbcconfiguration&gt;</property> - </emphasis>) for use when reverse engineering.</para> + standard Hibernate configuration <emphasis> + (<property>&lt;configuration&gt;</property>), + </emphasis> Annotation based configuration <emphasis> + (<property>&lt;annotationconfiguration&gt;</property>), + </emphasis> JPA persistence based configuration <emphasis> + (<property>&lt;jpaconfiguration&gt;</property>) + </emphasis> and a JDBC based configuration <emphasis> + (<property>&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 - <literal>Configuration</literal> object from which a set of exporters can be run to generate - various output. <note> + Configuration object from which a set of exporters can be run to generate + various output. </para> + + <note> <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> - + <para>The following section describes what the various configuration can do, plus list the individual settings they have.</para> @@ -222,21 +257,7 @@ <property>cfg.xml</property> </emphasis> and/or a fileset.</para> - <para> - <programlistingco> - <areaspec> - <area coords="2 55" id="cfg1"/> - - <area coords="3 55" id="cfg2"/> - - <area coords="4 55" id="cfg3"/> - - <area coords="5 55" id="cfg4"/> - - <area coords="7 55" id="cfg5"/> - </areaspec> - - <programlisting><![CDATA[<configuration + <programlisting role="XML"><![CDATA[<configuration configurationfile="hibernate.cfg.xml" propertyfile="hibernate.properties" entityresolver="EntityResolver classname" @@ -244,39 +265,84 @@ <fileset...> -</configuration>]]></programlisting> - - <calloutlist> - <callout arearefs="cfg1"> - <para><literal>configurationfile</literal> (optional): The name of a Hibernate - configuration file, e.g. "hibernate.cfg.xml"</para> - </callout> - - <callout arearefs="cfg2"> - <para><literal>propertyfile</literal> (optional): The name of a property file, e.g. - "hibernate.properties"</para> - </callout> - - <callout arearefs="cfg3"> - <para><literal>entity-resolver</literal> (optional): name of a class that implements + </configuration>]]></programlisting> + + <table frame="topbot"> + <title>Configuration 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>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> - </callout> - - <callout arearefs="cfg4"> - <para><literal>namingstrategy</literal> (optional): name of a class that implements + 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> - </callout> - - <callout arearefs="cfg5"> - <para>A standard Ant fileset. Used to include hibernate mapping files. Remember that + 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> - </callout> - </calloutlist> - </programlistingco> - </para> + 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> @@ -289,7 +355,8 @@ <property> hibernate.properties </property> - </emphasis> + fileset is used instead. </para> + </emphasis> and fileset is used instead. </para> + <note> <title>Tip:</title> <para> Hibernate will still read any global <emphasis><property>hibernate.properties</property></emphasis> @@ -297,8 +364,7 @@ values for any non-global property.</para> </note> - <para> - <programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <programlisting role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> <configuration propertyfile="{etc.dir}/hibernate.properties"> <fileset dir="${src.dir}"> <include name="**/*.hbm.xml"/> @@ -309,7 +375,7 @@ <!-- list exporters here --> </hibernatetool>]]></programlisting> - </para> + </section> </section> @@ -325,8 +391,8 @@ <title>Tip:</title> <para>To use it remember to put the jar files needed for using hibernate annotations in the classpath of the <emphasis> - <property>&lt;taskdef&gt;</property> - </emphasis>, i. e. hibernate-annotations.jar and hibernate-commons-annotations.jar.</para> + <property>&lt;taskdef&gt;</property>, + </emphasis> i. e. hibernate-annotations.jar and hibernate-commons-annotations.jar.</para> </note> <para>The <emphasis> @@ -339,8 +405,7 @@ <para>Thus the minimal usage is:</para> - <para> - <programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <programlisting role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> <annotationconfiguration configurationfile="hibernate.cfg.xml"/> @@ -348,7 +413,7 @@ </hibernatetool> ]]></programlisting> - </para> + </section> <section> @@ -359,8 +424,8 @@ </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>hibernate.cfg.xml</property> - </emphasis>, but instead have a setup where you use a <emphasis> + <property>hibernate.cfg.xml</property>, + </emphasis> but instead have a setup where you use a <emphasis> <property>persistence.xml</property> </emphasis> packaged in a JPA compliant manner.</para> @@ -368,8 +433,8 @@ <property>&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>META-INF/persistence.xml</property> - </emphasis>.</para> + <property>META-INF/persistence.xml</property>. + </emphasis></para> <para>The <emphasis> <property>persistenceunit</property></emphasis> attribute can be used to select a specific @@ -385,7 +450,7 @@ <property>&lt;taskdef&gt;</property> </emphasis> of the hibernatetool. The following shows a full setup:</para> - <programlisting><![CDATA[<path id="ejb3toolslib"> + <programlisting role="XML"><![CDATA[<path id="ejb3toolslib"> <path refid="jpatoolslib"/> <!-- ref to previously defined toolslib --> <path location="lib/hibernate-annotations.jar" /> <path location="lib/ejb3-persistence.jar" /> @@ -413,7 +478,7 @@ <note> - <para><literal>ejb3configuration</literal> were the name used in previous versions. It still + <para>ejb3configuration were the name used in previous versions. It still works but will emit a warning telling you to use <literal>jpaconfiguration</literal> instead.</para> </note> @@ -442,20 +507,8 @@ <literal>&lt;configuration&gt;</literal> </property> </emphasis> plus the following additional attributes:</para> - - <para> - <programlistingco> - <areaspec> - <area coords="3 57" id="xcfg1"/> - - <area coords="4 57" id="xcfg2"/> - - <area coords="5 57" id="xcfg3"/> - <area coords="6 57" id="xcfg4"/> - <area coords="7 57" id="xcfg5"/> - </areaspec> - - <programlisting><![CDATA[<jdbcconfiguration + + <programlisting role="XML"><![CDATA[<jdbcconfiguration ... packagename="package.name" revengfile="hibernate.reveng.xml" @@ -464,43 +517,89 @@ detectoptmisticlock="true|false" ... -</jdbcconfiguration>]]></programlisting> - - <calloutlist> - <callout arearefs="xcfg1"> - <para><literal>packagename</literal> (optional): The default package name to use when - mappings for classes is created</para> - </callout> - - <callout arearefs="xcfg2"> - <para><literal>revengfile</literal> (optional): name of reveng.xml that allows you to - control various aspects of the reverse engineering.</para> - </callout> - - <callout arearefs="xcfg3"> - <para><literal>reversestrategy</literal> (optional): name of a class that implements - <literal>org.hibernate.cfg.reveng.ReverseEngineeringStrategy</literal>. Used for + </jdbcconfiguration>]]></programlisting> + + <table frame="topbot"> + <title>Jdbcconfiguration 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>packagename</para></entry> + + <entry><para>The default package name to use when + mappings for classes is 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> - </callout> - - <callout arearefs="xcfg4"> - <para>detectManytoMany (default:true): If true (the default) tables which are pure + 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 has exactly two foreign-keys pointing to other entity - tables and has no other columns.</para> - </callout> - <callout arearefs="xcfg5"> - <para>detectOptimisticLock (default:true): If true columns named VERSION or TIMESTAMP + 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 <literal>&lt;version&gt;</literal> or - <literal>&lt;timestamp&gt;</literal></para> - </callout> - </calloutlist> - </programlistingco> - </para> + 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> @@ -511,22 +610,24 @@ </property> </emphasis> to generate Hibernate xml mappings via <emphasis> - <property>&lt;hbm2hbmxml&gt;</property></emphasis>. The connection settings is here read from a <emphasis> + <property>&lt;hbm2hbmxml&gt;</property>.</emphasis> The connection settings is here read from a <emphasis> <property> - <literal>hibernate.properties</literal> + hibernate.properties </property> </emphasis> file but could just as well have been read from a <emphasis> - <property>hibernate.cfg.xml</property> - </emphasis>.</para> + <property>hibernate.cfg.xml</property>. + </emphasis></para> - <programlisting><![CDATA[<hibernatetool> + <programlisting role="XML"><![CDATA[<hibernatetool> <jdbcconfiguration propertyfile="etc/hibernate.properties" /> <hbm2hbmxml destdir="${build.dir}/src" /> </hibernatetool> ]]></programlisting> </section> </section> - </section><section> + </section> + + <section> <title>Exporters</title> <para>Exporters are the parts that does the actual job of converting the hibernate metamodel @@ -548,26 +649,7 @@ Remember that if a custom naming strategy is needed it is placed on the configuration element.</para> - <para> - <programlistingco> - <areaspec> - <area coords="2 55" id="ycfg1"/> - - <area coords="3 55" id="ycfg2"/> - - <area coords="4 55" id="ycfg3"/> - - <area coords="5 55" id="ycfg4"/> - - <area coords="6 55" id="ycfg5"/> - - <area coords="7 55" id="ycfg6"/> - - <area coords="8 55" id="ycfg7"/> - <area coords="8 55" id="ycfg8"/> - </areaspec> - - <programlisting><![CDATA[<hbm2ddl + <programlisting role="XML"><![CDATA[<hbm2ddl export="true|false" update="true|false" drop="true|false" @@ -576,65 +658,121 @@ delimiter=";" format="true|false" haltonerror="true|false" ->]]></programlisting> - - <calloutlist> - <callout arearefs="ycfg1"> - <para>export (default: true): Execute the generated statements against the - database</para> - </callout> - - <callout arearefs="ycfg2"> - <para>update(default: false): Try and create an update script representing the ++ + <table frame="topbot"> + <title>Hbm2ddl exporter 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>export</para></entry> + + <entry><para>Execute 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 &quot;delta&quot; 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> - </callout> - - <callout arearefs="ycfg3"> - <para>drop (default: false): Output will contain drop statements for the tables, - indices &amp; constraints</para> - </callout> - - <callout arearefs="ycfg4"> - <para>create (default: true): Output will contain create statements for the tables, - indices &amp; constraints</para> - </callout> - - <callout arearefs="ycfg5"> - <para>outputfilename (Optional): If specified the statements will be dumped to this - file.</para> - </callout> - - <callout arearefs="ycfg6"> - <para>delimiter (default: ";"): What delimiter to use to separate statements</para> - </callout> - - <callout arearefs="ycfg7"> - <para>format (default: false): Apply basic formatting to the statements.</para> - </callout> - - <callout arearefs="ycfg8"> - <para>haltonerror (default: false): Halt build process if an error occurs.</para> - </callout> - - </calloutlist> - </programlistingco> - </para> - + 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: &quot;;&quot;</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>&lt;hbm2ddl&gt;</property> - </emphasis>, which does not export to the database but simply dumps the sql to a file + <property>&lt;hbm2ddl&gt;</property>, + </emphasis> which does not export to the database but simply dumps the sql to a file named <emphasis> - <property>sql.ddl</property> - </emphasis>.</para> + <property>sql.ddl</property>. + </emphasis></para> - <programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <programlisting role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> <configuration configurationfile="hibernate.cfg.xml"/> <hbm2ddl export="false" outputfilename="sql.ddl"/> </hibernatetool>]]></programlisting> @@ -649,33 +787,57 @@ </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> - <para> - <programlistingco> - <areaspec> - <area coords="2 55" id="zcfg1"/> - - <area coords="3 55" id="zcfg2"/> - </areaspec> - - <programlisting><![CDATA[<hbm2java + <programlisting role="XML"><![CDATA[<hbm2java jdk5="true|false" ejb3="true|false" - <calloutlist> - <callout arearefs="zcfg1"> - <para>jdk (default: false): Code will contain JDK 5 constructs such as generics and - static imports</para> - </callout> - - <callout arearefs="zcfg2"> - <para>ejb3 (default: false): Code will contain EJB 3 features, e.g. using annotations - from javax.persistence and org.hibernate.annotations</para> - </callout> - </calloutlist> - </programlistingco> - </para> - + <table frame="topbot"> + <title>Hbm2java exporter 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>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> @@ -683,7 +845,7 @@ <property>&lt;hbm2java&gt;</property> </emphasis> to generate POJO's that utilize jdk5 constructs.</para> - <programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <programlisting role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> <configuration configurationfile="hibernate.cfg.xml"/> <hbm2java jdk5="true"/> </hibernatetool>]]></programlisting> @@ -699,20 +861,20 @@ <property>&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>hbm.xml</property> - </emphasis>. Note that not every possible mapping transformation is possible/implemented + <property>hbm.xml</property>. + </emphasis> Note that not every possible mapping transformation is possible/implemented (contributions welcome) so some hand editing might be necessary.</para> - <programlisting><![CDATA[<hbm2hbmxml/>]]></programlisting> + <programlisting role="XML"><![CDATA[<hbm2hbmxml/>]]></programlisting> <section> <title>Example</title> <para>Basic usage of <emphasis> - <property>&lt;hbm2hbmxml&gt;</property> - </emphasis>.</para> + <property>&lt;hbm2hbmxml&gt;</property>. + </emphasis></para> - <programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <programlisting role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> <configuration configurationfile="hibernate.cfg.xml"/> <hbm2hbmxml/> </hibernatetool>]]></programlisting> @@ -732,12 +894,10 @@ might be necessary.</para> </note> - <para> - <programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <programlisting role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> <annotationconfiguration configurationfile="hibernate.cfg.xml"/> <hbm2hbmxml/> </hibernatetool>]]></programlisting> - </para> </section> </section> @@ -747,34 +907,58 @@ <para><emphasis> <property>&lt;hbm2cfgxml&gt;</property> </emphasis> generates a <emphasis> - <property>hibernate.cfg.xml</property> - </emphasis>. Intended to be used together with a <emphasis> + <property>hibernate.cfg.xml</property>. + </emphasis> Intended to be used together with a <emphasis> <property>&lt;jdbcconfiguration&gt;</property> </emphasis> when performing reverse engineering, but it can be used with any kind of configuration. The <emphasis> <property>&lt;hbm2cfgxml&gt;</property> </emphasis> will contain the properties used and adds mapping entries for each mapped class.</para> - <para> - <programlistingco> - <areaspec> - <area coords="2 55" id="qcfg1"/> - </areaspec> - - <programlisting><![CDATA[<hbm2cfgxml + <programlisting role="XML"><![CDATA[<hbm2cfgxml ejb3="true|false" /> ]]></programlisting> - - <calloutlist> - <callout arearefs="qcfg1"> - <para>ejb3 (default: false): the generated cfg.xml will have &lt;mapping + + <table frame="topbot"> + <title>Hbm2cfgxml exporter attribute</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>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> - </callout> - </calloutlist> - </programlistingco> - </para> + mapping.</para></entry> + + <entry><para>False</para></entry> + </row> + + </tbody> + + </tgroup> + </table> + </section> <section> @@ -784,7 +968,7 @@ <property>&lt;hbm2doc&gt;</property> </emphasis> generates html documentation a'la javadoc for the database schema et.al.</para> - <programlisting><![CDATA[<hbm2doc/>]]></programlisting> + <programlisting role="XML"><![CDATA[<hbm2doc/>]]></programlisting> </section> <section> @@ -795,7 +979,7 @@ </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><![CDATA[<query + <programlisting role="XML"><![CDATA[<query destfile="filename"> <hql>[a HQL query string]</hql> </query> @@ -815,7 +999,7 @@ </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><![CDATA[<hibernatetool> + <programlisting role="XML"><![CDATA[<hibernatetool> <configuration configurationfile="hibernate.cfg.xml"/> <query>from java.lang.Object</query> </hibernatetool>]]></programlisting> @@ -823,22 +1007,21 @@ <para>Multiple queries can be executed by nested <emphasis> <property>&lt;hql&gt;</property> </emphasis> elements. In this example we also let the output be dumped to <emphasis> - <property>queryresult.txt</property> - </emphasis>. </para> + <property>queryresult.txt</property>. + </emphasis></para> <note> <title>Tip:</title> <para> Currently the dump is simply a call to toString on each element.</para> </note> - <para> - <programlisting><![CDATA[<hibernatetool> + <programlisting role="XML"><![CDATA[<hibernatetool> <configuration configurationfile="hibernate.cfg.xml"/> <query destfile="queryresult.txt"> <hql>select c.name from Customer c where c.age > 42</hql> <hql>from Cat</hql> </hibernatetool>]]></programlisting> - </para> + </section> </section> @@ -847,7 +1030,7 @@ <para>Generic exporter that can be controlled by an user provides a template or class.</para> - <programlisting><![CDATA[<hbmtemplate + <programlisting role="XML"><![CDATA[<hbmtemplate filepattern="{package-name}/{class-name}.ftl" template="somename.ftl" exporterclass="Exporter classname" @@ -859,7 +1042,7 @@ </note> <section> - <title>Exporter via <literal>&lt;hbmtemplate&gt;</literal></title> + <title>Exporter via &lt;hbmtemplate&gt;</title> <para>The following is an example of reverse engineering via <emphasis> <property>&lt;jdbcconfiguration&gt;</property> @@ -867,8 +1050,7 @@ <property>&lt;hbmtemplate&gt;</property> </emphasis>.</para> - <para> - <programlisting><![CDATA[ <hibernatetool destdir="${destdir}"> + <programlisting role="XML"><![CDATA[ <hibernatetool destdir="${destdir}"> <jdbcconfiguration configurationfile="hibernate.cfg.xml" packagename="my.model"/> @@ -883,7 +1065,7 @@ </hibernatetool> ]]></programlisting> - </para> + </section> </section> </section> @@ -915,7 +1097,7 @@ </emphasis> to the variable <emphasis> <property>$descriptors</property></emphasis>.</para> - <programlisting><![CDATA[<property key="descriptors" value="true"/>]]></programlisting> + <programlisting role="XML"><![CDATA[<property key="descriptors" value="true"/>]]></programlisting> <para>Most times using <emphasis> <property> @@ -940,7 +1122,7 @@ <property>&quot;toolclass&quot;</property> </emphasis> in the properties.</para> - <programlisting><![CDATA[<property key="hibernatetool.sometool.toolclass" value="x.y.z.NameOfToolClass"/> + <programlisting role="XML"><![CDATA[<property key="hibernatetool.sometool.toolclass" value="x.y.z.NameOfToolClass"/> ]]></programlisting> <para>Placing the above <emphasis> @@ -968,7 +1150,7 @@ <para> This example actually simulates what &lt;hbm2java&gt; actually does.</para> </note> - <programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <programlisting role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> <configuration configurationfile="etc/hibernate.cfg.xml"/> <hbmtemplate