[Hibernate-commits] Hibernate Code SVN: r9777 - in trunk/HibernateExt/tools: doc/reference/en/modules src/java/org/hibernate/tool/ant src/java/org/hibernate/tool/hbm2x src/java/org/hibernate/tool/hbm2x/pojo src/testsupport

[<hib...@li...>]

Author: max...@jb...
Date: 2006-04-21 15:03:03 -0400 (Fri, 21 Apr 2006)
New Revision: 9777

Added:
   trunk/HibernateExt/tools/src/java/org/hibernate/tool/ant/QueryExporterTask.java
   trunk/HibernateExt/tools/src/java/org/hibernate/tool/hbm2x/QueryExporter.java
Removed:
   trunk/HibernateExt/tools/src/java/org/hibernate/tool/ant/HQLExporterTask.java
   trunk/HibernateExt/tools/src/java/org/hibernate/tool/hbm2x/HQLExporter.java
Modified:
   trunk/HibernateExt/tools/doc/reference/en/modules/ant.xml
   trunk/HibernateExt/tools/src/java/org/hibernate/tool/ant/HibernateToolTask.java
   trunk/HibernateExt/tools/src/java/org/hibernate/tool/hbm2x/pojo/ComponentPOJOClass.java
   trunk/HibernateExt/tools/src/testsupport/anttest-build.xml
Log:
HBX-648 ejb3 generation should generate the now required @Temporal for date/time's
+ revised ant docs

Modified: trunk/HibernateExt/tools/doc/reference/en/modules/ant.xml
===================================================================
--- trunk/HibernateExt/tools/doc/reference/en/modules/ant.xml	2006-04-20 21:35:09 UTC (rev 9776)
+++ trunk/HibernateExt/tools/doc/reference/en/modules/ant.xml	2006-04-21 19:03:03 UTC (rev 9777)
@@ -10,32 +10,41 @@
     and the eclipse plugins both available from tools.hibernate.org The
     hibernate-tools.jar is located in your eclipse plugins directory at
     <literallayout>/plugins/org.hibernate.eclipse.x.x.x/lib/tools/hibernate-tools.jar</literallayout>.
-    This jar is 100% independent from the eclipse platform.</para>
+    This jar is 100% independent from the eclipse platform and can thus be
+    used independently of eclipse.</para>
 
     <section>
       <title>The <literal>&lt;hibernatetool&gt;</literal> ant Task</title>
 
       <para>To use the ant tasks you ned to have the hibernatetool task
-      defined. That is done in your build.xml by inserting the following xml:
-      <programlisting><![CDATA[ <taskdef 
-     name="hibernatetool" 
-     classname="org.hibernate.tool.ant.HibernateToolTask" 
-     classpath="[location of hibernate-tools.jar, velocity.jar, 
-                 velocity-tools-generic.jar, jtidy.jar, 
-                 hibernate3.jar & jdbc drivers]"/> 
+      defined. That is done in your build.xml by inserting the following xml
+      (assuming the jars are in the <literal>lib</literal> directory):
+      <programlisting><![CDATA[<path id="toolslib">
+ <path location="lib/hibernate-tools.jar" />
+ <path location="lib/hibernate3.jar" />
+ <path location="lib/freemarker.jar" />
+ <path location="${jdbc.driver.jar}" />
+</path>
+   
+<taskdef name="hibernatetool" 
+         classname="org.hibernate.tool.ant.HibernateToolTask" 
+         classpathref="toolslib" />
 ]]></programlisting></para>
 
-      <para>This <literal>&lt;taskdef&gt;</literal> defines a Ant task called
+      <para>his <literal>&lt;taskdef&gt;</literal> defines a Ant task called
       <literal>&lt;hibernatetool&gt;</literal> which now can be used anywhere
       in your ant build.xml files. It is important to include all the
       hibernate tools dependencies as well as the jdbc driver.</para>
 
       <para>Notice that to use the annotation based Configuration you must get
       a release from <link
-      linkend="???">http://annotations.hibernate.org</link>. When using the
-      <literal>&lt;hibernatetool&gt; </literal>task you have to specify one or
-      more of the following:</para>
+      linkend="???">http://annotations.hibernate.org</link>.</para>
 
+      <para></para>
+
+      <para>When using the <literal>&lt;hibernatetool&gt; </literal>task you
+      have to specify one or more of the following:</para>
+
       <para><programlistingco>
           <areaspec>
             <area coords="2 55" id="ht1" />
@@ -44,7 +53,9 @@
 
             <area coords="5 55" id="ht3" />
 
-            <area coords="6 55" id="ht4" />
+            <area coords="7 55" id="ht4" />
+
+            <area coords="9 55" id="config" />
           </areaspec>
 
           <programlisting><![CDATA[<hibernatetool
@@ -54,8 +65,9 @@
   <classpath ...>
   <property name="propertyName" value="value"/>
   <propertyset ...>
-  (<configuration ...>|<annotationconfiguration ...>|<jdbcconfiguration ...>)
-  (<hbm2java>,<hbm2cfgxml>,...*)  
+  (<configuration ...>|<annotationconfiguration ...>|
+   <ejb3configuration ...>|<jdbcconfiguration ...>)
+  (<hbm2java>,<hbm2cfgxml>,<hbmtemplate>,...*)  
 </hibernatetool>]]></programlisting>
 
           <calloutlist>
@@ -81,32 +93,86 @@
               properties to control the exporters. Mostly relevant for
               providing custom properties to user defined templates.</para>
             </callout>
+
+            <callout arearefs="config">
+              <para>One of 4 different ways of configuring the Hibernate Meta
+              Model must be specified.</para>
+            </callout>
+
+            <callout arearefs="???">
+              <para>One or more of the exporters must be specified</para>
+            </callout>
           </calloutlist>
         </programlistingco></para>
+
+      <section>
+        <title>Basic examples</title>
+
+        <para>The following example shows the most basic setup for generating
+        pojo's via <literal>hbm2java</literal> from a normal
+        <literal>hibernate.cfg.xml.</literal> The output will be put in the
+        <literal>${build.dir}/generated</literal> directory.</para>
+
+        <para><programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated">
+ <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 hbm2dll, generates some DAO code via &lt;hbm2dao&gt; and
+        finally runs a custom code generation via &lt;hbmtemplate&gt;. This is
+        again from a normal <literal>hibernate.cfg.xml and </literal>the
+        output is still put in the <literal>${build.dir}/generated</literal>
+        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>
+
+        <para><programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated">
+ <classpath>
+  <path location="${build.dir}/classes"/>
+ </classpath>
+
+ <configuration configurationfile="hibernate.cfg.xml"/>
+ <hbm2ddl/>
+ <hbm2dao/>
+ <hbmtemplate
+  filepattern="{package-name}/I{class-name}Constants.java"
+  templatepath="${etc.dir}/customtemplates"
+  template="myconstants.vm"  
+ />
+</hibernatetool>]]></programlisting></para>
+      </section>
     </section>
 
     <section>
       <title>Hibernate Configurations</title>
 
-      <para><literal>hibernatetool</literal> supports three different
-      Hibernate configurations: A standard Hibernate configuration
+      <para><literal>hibernatetool</literal> supports four different Hibernate
+      configurations: A standard Hibernate configuration
       (<literal>&lt;configuration&gt;</literal>), Annotation based
-      configuration (<literal>&lt;annotationconfiguratioin&gt;</literal>) and
-      a JDBC based configuration
-      (<literal>&lt;jdbcconfiguration&gt;</literal>) for use when reverse
-      engineering.</para>
+      configuration (<literal>&lt;annotationconfiguration&gt;</literal>), EJB3
+      persistence based configuration
+      (<literal>&lt;ejb3configuration&gt;</literal>) and a JDBC based
+      configuration (<literal>&lt;jdbcconfiguration&gt;</literal>) 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.</para>
+      can be run to generate various output. Note: output can be anything,
+      e.g. specific files, statments execution against a database, error
+      reporting or anything else that can be done in java code.</para>
 
+      <para>The following section decribes what the the various configuration
+      can do, plus list the individual settings they have.</para>
+
       <section>
         <title>Standard Hibernate Configuration
         (&lt;configuration&gt;)</title>
 
         <para>A &lt;configuration&gt; is used to define a standard Hibernate
         configuration. A standard Hibernate configuration reads the mappings
-        from the optional hbm.xml and the fileset.</para>
+        from a cfg.xml and/or a fileset.</para>
 
         <para><programlistingco>
             <areaspec>
@@ -165,6 +231,30 @@
               </callout>
             </calloutlist>
           </programlistingco></para>
+
+        <section>
+          <title>Example</title>
+
+          <para>This example shows an example where no
+          <literal>hibernate.cfg.xml</literal> exists, and a
+          <literal>hibernate.properties</literal> + fileset is used instead.
+          Note, that Hibernate will still read any global
+          <literal>/hibernate.properties</literal> available in the classpath,
+          but the specified properties file here will override those values
+          for any non-global property.</para>
+
+          <para><programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated">
+ <configuration propertyfile="{etc.dir}/hibernate.properties">
+   <fileset dir="${src.dir}">
+   <include name="**/*.hbm.xml"/>
+   <exclude name="**/*Test.hbm.xml"/>
+  </fileset>
+ </configuration>
+
+ <!-- list exporters here -->
+
+</hibernatetool>]]></programlisting></para>
+        </section>
       </section>
 
       <section>
@@ -177,43 +267,154 @@
         hibernate annotations in the classpath of the
         <literal>&lt;taskdef&gt;</literal>.</para>
 
-        <para>The &lt;annotationconfiguration&gt; has the same attributes as
-        an &lt;configuration&gt; except that the configurationfile attribute
-        is now required as that is from where an AnnotationConfiguration gets
-        the list of classes/packages it should load.</para>
+        <para>The &lt;annotationconfiguration&gt; supports the same attributes
+        as an &lt;configuration&gt; except that the configurationfile
+        attribute is now required as that is from where an
+        <literal>AnnotationConfiguration</literal> gets the list of
+        classes/packages it should load.</para>
 
         <para>Thus the minimal usage is:</para>
 
-        <para><programlisting><![CDATA[<annotationconfiguration
+        <para><programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated">
+ <annotationconfiguration
   configurationfile="hibernate.cfg.xml"/>
+
+ <!-- list exporters here -->
+
+</hibernatetool>
 ]]></programlisting></para>
       </section>
 
       <section>
+        <title>EJB3 based configuration (&lt;ejb3configuration&gt;)</title>
+
+        <para>An &lt;ejb3configuration&gt; is used when you want to read the
+        metamodel from EJB3/Hibernate Annotation where you want to use the
+        auto-scan configuration as defined in the EJB3 spec. In other words,
+        when you do not have a <literal>hibernate.cfg.xml</literal>, but
+        instead have a setup where you use a
+        <literal>persistence.xml</literal> packaged in an EJB3 compliant
+        manner.</para>
+
+        <para>Note, in the current version there is no additional attribute
+        support on &lt;ejb3configuration&gt; like found on
+        &lt;annotationconfiguration&gt; and &lt;configuration&gt;. It will
+        simply just try and auto-configure it self based on the available
+        classpath, e.g. look for META-INF/persistence.xml.</para>
+
+        <para>To use an &lt;ejb3configuration&gt; you will need to specify
+        some additional jars from Hibernate EntityManager in the
+        &lt;taskdef&gt; of the hibernatetool. The following shows a full
+        setup:</para>
+
+        <programlisting><![CDATA[<path id="ejb3toolslib">
+ <path refid="toolslib"/> <!-- ref to previously defined toolslib -->
+ <path location="lib/hibernate-annotations.jar" />
+ <path location="lib/ejb3-persistence.jar" />
+ <path location="lib/hibernate-entitymanager.jar" />
+ <path location="lib/jboss-archive-browsing.jar" />
+ <path location="lib/javaassist.jar" /> 
+</path>
+   
+<taskdef name="hibernatetool" 
+         classname="org.hibernate.tool.ant.HibernateToolTask" 
+         classpathref="ejb3toolslib" />
+
+<hibernatetool destdir="${build.dir}">
+ <ejb3configuration />
+ <classpath>
+  <!-- it is in this classpath you put your classes dir,
+   and/or ejb3 persistence compliant jar -->
+  <path location="${build.dir}/ejb3/classes" />
+ </classpath>
+
+ <!-- list exporters here -->
+
+</hibernatetool>
+]]></programlisting>
+      </section>
+
+      <section>
         <title>JDBC Configuration for reverse engineering
         (&lt;jdbcconfiguration&gt;)</title>
 
         <para>A &lt;jdbcconfiguration&gt; is used to perform reverse
-        engineering of the database from a JDBC connection. The
-        &lt;jdbcconfiguration&gt; has the same attributes as a
+        engineering of the database from a JDBC connection.</para>
+
+        <para>This configuration works by reading the connection properties
+        from</para>
+
+        <para>The &lt;jdbcconfiguration&gt; has the same attributes as a
         &lt;configuration&gt; plus the following additional attributes:</para>
 
-        <para><programlisting><![CDATA[<jdbcconfiguration
+        <para><programlistingco>
+            <areaspec>
+              <area coords="4 57" id="cfg1" />
+
+              <area coords="5 57" id="cfg2" />
+
+              <area coords="6 57" id="cfg3" />
+
+            </areaspec>
+
+            <programlisting><![CDATA[<jdbcconfiguration
   ...
   packagename="package.name"
+  revengfile="hibernate.reveng.xml"
   reversestrategy="ReverseEngineeringStrategy classname"
-  revengfile="hibernate.reveng.xml"
 >
   ...
-</jdbcconfiguration>]]></programlisting></para>
+</jdbcconfiguration>]]></programlisting>
+
+            <calloutlist>
+              <callout arearefs="cfg1">
+                <para>packagename (optional): The default package name to use
+                when mappings for classes is created</para>
+              </callout>
+
+              <callout arearefs="cfg2">
+                <para><literal>revengfile</literal> (optional): name of
+                reveng.xml that allows you to control varios aspects of the
+                reverse engineering.</para>
+              </callout>
+
+              <callout arearefs="cfg3">
+                <para><literal>reversestrategy</literal> (optional): name of a
+                class that implements
+                <literal>org.hibernate.cfg.reveng.ReverseEngineeringStrategy</literal>.
+                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>
+            </calloutlist>
+          </programlistingco></para>
+
+        <section>
+          <title>Example</title>
+
+          <para>Here is an example of using
+          <literal>&lt;jdbcconfiguration&gt;</literal> to generate Hibernate
+          xml mappings via <literal>&lt;hbm2hbmxml&gt;</literal>. The
+          connection settings is here read from a
+          <literal>hibernate.properties</literal> file but could just as well
+          have been read from a <literal>hibernate.cfg.xml.</literal></para>
+
+          <programlisting><![CDATA[<hibernatetool>
+ <jdbcconfiguration propertyfile="etc/hibernate.properties" />
+ <hbm2hbmxml destdir="${build.dir}/src" /> 
+</hibernatetool>
+]]></programlisting>
+        </section>
       </section>
     </section>
 
     <section>
-      <title>Code Exporters</title>
+      <title>Exporters</title>
 
-      <para>Code exporters is the parts that does the actual job of converting
-      the hibernate metamodel into various code artifacts. The following
+      <para>Exporters is the parts that does 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
       Hibernate Tool distribution. It is also possible for userdefined
       exporters, that is done through the
@@ -225,19 +426,92 @@
 
         <para>&lt;hbm2ddl&gt; 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.</para>
+        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><![CDATA[<hbm2ddl
+        <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="6 55" id="cfg6" />
+
+              <area coords="7 55" id="cfg7" />
+
+              <area coords="8 55" id="cfg8" />
+            </areaspec>
+
+            <programlisting><![CDATA[<hbm2ddl
+ export="true|false"
+ update="true|false"
  drop="true|false"
  create="true|false"
- export="true|false"
- update="true|false"
  outputfilename="filename.ddl"
  delimiter=";" 
  format="true|false"
 >]]></programlisting>
 
-        <para></para>
+            <calloutlist>
+              <callout arearefs="cfg1">
+                <para>export (default: true): Execute the generated statements
+                against the database</para>
+              </callout>
+
+              <callout arearefs="cfg2">
+                <para>update(default: false): 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>
+              </callout>
+
+              <callout arearefs="cfg3">
+                <para>drop (default: false): Output will contain drop
+                statements for the tables, indices &amp; constraints</para>
+              </callout>
+
+              <callout arearefs="cfg4">
+                <para>create (default: true): Output will contain create
+                statements for the tables, indices &amp; constraints</para>
+              </callout>
+
+              <callout arearefs="cfg5">
+                <para>outputfilename (Optional): If specified the statements
+                will be dumped to this file.</para>
+              </callout>
+
+              <callout arearefs="cfg6">
+                <para>delimiter (default: ";"): What delimter to use to
+                separate statements</para>
+              </callout>
+
+              <callout arearefs="cfg7">
+                <para>format (default: false): Apply basic formatting to the
+                statements.</para>
+              </callout>
+            </calloutlist>
+          </programlistingco></para>
+
+        <section>
+          <title>Example</title>
+
+          <para>Basic example of using &lt;hbm2ddl&gt;, which does not export
+          to the database but simply dumps the sql to a file named
+          sql.ddl.</para>
+
+          <programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated">
+ <configuration configurationfile="hibernate.cfg.xml"/>
+ <hbm2ddl export="false" outputfilename="sql.ddl"/>
+</hibernatetool>]]></programlisting>
+        </section>
       </section>
 
       <section>
@@ -248,12 +522,43 @@
         controlling wether JDK 5 syntax can be used and wether the POJO should
         be annotated with EJB3/Hibernate Annotations.</para>
 
-        <programlisting><![CDATA[<hbm2java
+        <para><programlistingco>
+            <areaspec>
+              <area coords="2 55" id="cfg1" />
+
+              <area coords="3 55" id="cfg2" />
+            </areaspec>
+
+            <programlisting><![CDATA[<hbm2java
  jdk5="true|false"
  ejb3="true|false"
 >]]></programlisting>
 
-        <para></para>
+            <calloutlist>
+              <callout arearefs="cfg1">
+                <para>jdk (default: false): Code will contain JDK 5 constructs
+                such as generics and static imports</para>
+              </callout>
+
+              <callout arearefs="cfg2">
+                <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>
+
+        <section>
+          <title>Example</title>
+
+          <para>Basic example of using &lt;hbm2java&gt; to generate POJO's
+          that utilize jdk5 constructs.</para>
+
+          <programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated">
+ <configuration configurationfile="hibernate.cfg.xml"/>
+ <hbm2java jdk5="true"/>
+</hibernatetool>]]></programlisting>
+        </section>
       </section>
 
       <section>
@@ -264,12 +569,34 @@
         used together with a &lt;jdbcconfiguration&gt; when performing reverse
         engineering, but can be used with any kind of configuration. e.g. to
         convert from annotation based pojo's to hbm.xml. Note that not every
-        possible mapping transformation is possible/implemented so some hand
-        editing might be necessary.</para>
+        possible mapping transformation is possible/implemented (contributions
+        welcome) so some hand editing might be necessary.</para>
 
         <programlisting><![CDATA[<hbm2hbmxml/>]]></programlisting>
 
-        <para></para>
+        <section>
+          <title>Example</title>
+
+          <para>Basic usage of &lt;hbm2hbmxml&gt;</para>
+
+          <programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated">
+ <configuration configurationfile="hibernate.cfg.xml"/>
+ <hbm2hbmxml/>
+</hibernatetool>]]></programlisting>
+
+          <para>&lt;hbm2hbmxml&gt; is normally used with a
+          &lt;jdbcconfiguration&gt; 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
+          &lt;annotationconfiguration&gt;. Note: not all conversions is
+          implemented (contributions welcome), so some hand editing might be
+          necessary.</para>
+
+          <para><programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated">
+ <annotaitonconfiguration configurationfile="hibernate.cfg.xml"/>
+ <hbm2hbmxml/>
+</hibernatetool>]]></programlisting></para>
+        </section>
       </section>
 
       <section>
@@ -280,14 +607,26 @@
         used together with a &lt;jdbcconfiguration&gt; when performing reverse
         engineering, but can be used with any kind of configuration. The
         &lt;hbm2cfgxml&gt; will contain the properties used and adds mapping
-        entriies for each mapped class.</para>
+        entries for each mapped class.</para>
 
-        <programlisting><![CDATA[<hbm2cfgxml
+        <para><programlistingco>
+            <areaspec>
+              <area coords="2 55" id="cfg1" />
+            </areaspec>
+
+            <programlisting><![CDATA[<hbm2cfgxml
   ejb3="true|false"
 />
 ]]></programlisting>
 
-        <para></para>
+            <calloutlist>
+              <callout arearefs="cfg1">
+                <para>ejb3 (default: false): the generated cfg.xml will have
+                &lt;mapping class=".."/&gt;, opposed to &lt;mapping
+                resource="..."/&gt; for each mapping.</para>
+              </callout>
+            </calloutlist>
+          </programlistingco></para>
       </section>
 
       <section>
@@ -298,8 +637,52 @@
         the database schema et.al.</para>
 
         <programlisting><![CDATA[<hbm2doc/>]]></programlisting>
+      </section>
 
+      <section>
+        <title>Query exporter (&lt;query&gt;)</title>
+
+        <para>&lt;query&gt; is used to execute a HQL query statements and
+        optionally send the output to a file. Can be used for verifying the
+        mappings and for basic data extraction.</para>
+
+        <programlisting><![CDATA[<query
+ destfile="filename">
+ <hql>[a HQL query string]</hql>
+</query>
+]]></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 etc.</para>
+
         <para></para>
+
+        <section>
+          <title>Examples</title>
+
+          <para>Simplest usage of &lt;query&gt; 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>
+ <configuration configurationfile="hibernate.cfg.xml"/>
+ <query>from java.lang.Object</query>
+</hibernatetool>]]></programlisting>
+
+          <para>Multiple queries can be executed by nested &lt;hql&gt;
+          elements. In this example we also let the output be dumped to
+          <literal>queryresult.txt</literal>. Note that currently the dump is
+          simply a call to toString on each element.</para>
+
+          <para><programlisting><![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>
 
       <section id="hbmtemplate">
@@ -310,13 +693,14 @@
         template or class.</para>
 
         <programlisting><![CDATA[<hbmtemplate
- filepattern="{package-name}/{class-name}.vm"
- template="somename.vm"
+ filepattern="{package-name}/{class-name}.ftl"
+ template="somename.ftl"
  exporterclass="Exporter classname"
 />]]></programlisting>
 
-        <para>NOTICE: This release uses Velocity for the templates. The next
-        release might move to an alternative template engine.</para>
+        <para>NOTICE: Previous versions of the tools used Velocity. We are now
+        using Freemarker which provides us much better exception and error
+        handling.</para>
 
         <section>
           <title>Seam Exporter via
@@ -328,13 +712,17 @@
           generate a Seam application skeleton.</para>
 
           <para><programlisting><![CDATA[ <hibernatetool destdir="${destdir}">
-  <jdbcconfiguration configurationfile="hibernate.cfg.xml" packagename="x.y.z.seam.crud"/>   
+  <jdbcconfiguration 
+     configurationfile="hibernate.cfg.xml" 
+     packagename="x.y.z.seam.crud"/>   
   
   <!-- setup properties -->  
   <property key="seam_appname" value="Registration"/>
   <property key="seam_shortname" value="crud"/>
     
-  <hbmtemplate exporterclass="org.hibernate.tool.hbm2x.seam.SeamExporter" filepattern="."/>
+  <hbmtemplate 
+     exporterclass="org.hibernate.tool.hbm2x.seam.SeamExporter" 
+     filepattern="."/>
         
 </hibernatetool>
 ]]></programlisting></para>
@@ -351,8 +739,6 @@
       access to them directly in the templates and via
       <literal>Exporter.setProperties()</literal>.</para>
 
-      <para></para>
-
       <section>
         <title><literal>&lt;property&gt;</literal> and
         <literal>&lt;propertyset&gt;</literal></title>
@@ -388,7 +774,27 @@
         delegate logic and code generation to java code instead of placing
         such logic in the templates.</para>
 
-        <para></para>
+        <section>
+          <title>Example</title>
+
+          <para>Here is an example that uses &lt;hbmtemplate&gt; together with
+          &lt;property&gt; which will be available to the templates/exporter.
+          Note: This example actually simulates what &lt;hbm2java&gt; actually
+          does.</para>
+
+          <programlisting><![CDATA[<hibernatetool destdir="${build.dir}/generated">
+<configuration 
+   configurationfile="etc/hibernate.cfg.xml"/>
+ <hbmtemplate 
+   templateprefix="pojo/" 
+   template="pojo/Pojo.ftl" 
+   filepattern="{package-name}/{class-name}.java">
+  <property key="jdk5" value="true" />
+  <property key="ejb3" value="true" />
+ </hbmtemplate>
+</hibernatetool>
+]]></programlisting>
+        </section>
       </section>
     </section>
   </section>

Deleted: trunk/HibernateExt/tools/src/java/org/hibernate/tool/ant/HQLExporterTask.java
===================================================================
--- trunk/HibernateExt/tools/src/java/org/hibernate/tool/ant/HQLExporterTask.java	2006-04-20 21:35:09 UTC (rev 9776)
+++ trunk/HibernateExt/tools/src/java/org/hibernate/tool/ant/HQLExporterTask.java	2006-04-21 19:03:03 UTC (rev 9777)
@@ -1,45 +0,0 @@
-package org.hibernate.tool.ant;
-
-import org.hibernate.tool.hbm2x.Exporter;
-import org.hibernate.tool.hbm2x.HQLExporter;
-
-public class HQLExporterTask extends ExporterTask {
-
-	private String query;
-	private String filename;
-
-	public HQLExporterTask(HibernateToolTask parent) {
-		super( parent );		
-	}
-
-	protected Exporter configureExporter(Exporter exp) {
-		HQLExporter exporter = (HQLExporter) exp;
-		exporter.setQuery(query);
-		exporter.setFilename(filename);
-		super.configureExporter( exp );		
-        return exporter;
-	}
-
-	protected Exporter createExporter() {
-		HQLExporter exporter = new HQLExporter();
-		return exporter;
-	}
-
-	public void addText(String text) {
-		query = text;
-	}
-	
-	public void setDestFile(String filename) {
-		this.filename = filename;
-	}
-	 
-	public void execute() {
-		parent.log("Executing: [" + query + "]");
-		super.execute();
-	}
-	public String getName() {
-		return "hql (Executes HQL queries)";
-	}
-	
-	
-}

Modified: trunk/HibernateExt/tools/src/java/org/hibernate/tool/ant/HibernateToolTask.java
===================================================================
--- trunk/HibernateExt/tools/src/java/org/hibernate/tool/ant/HibernateToolTask.java	2006-04-20 21:35:09 UTC (rev 9776)
+++ trunk/HibernateExt/tools/src/java/org/hibernate/tool/ant/HibernateToolTask.java	2006-04-21 19:03:03 UTC (rev 9777)
@@ -114,8 +114,8 @@
 	}
 	
 	
-	public HQLExporterTask createHql() {
-		HQLExporterTask generator = new HQLExporterTask(this);
+	public QueryExporterTask createQuery() {
+		QueryExporterTask generator = new QueryExporterTask(this);
 		generators.add(generator);
 		return generator;
 	}
@@ -147,18 +147,20 @@
 		Iterator iterator = generators.iterator();
 		
 		AntClassLoader loader = getProject().createClassLoader(classPath);
+		ExporterTask generatorTask = null;
+		int count = 1;
 		try {
 			loader.setParent(this.getClass().getClassLoader() ); // if this is not set, classes from the taskdef cannot be found - which is crucial for e.g. annotations.
 			loader.setThreadContextLoader();
 			
-			int count = 1;
-			while (iterator.hasNext() ) {
-				ExporterTask generatorTask = (ExporterTask) iterator.next();
+			
+			while (iterator.hasNext() ) {				
+				generatorTask = (ExporterTask) iterator.next();
 				log(count++ + ". task: " + generatorTask.getName() );
 				generatorTask.execute();			
 			}
 		} catch (RuntimeException re) {
-			reportException(re);
+			reportException(re, count, generatorTask);
 		} 
 		finally {
 			if (loader != null) {
@@ -168,8 +170,9 @@
 		}
 	}
 
-	private void reportException(Throwable re) {
-		log("An exception occurred. To get the full stack trace run ant with -verbose", Project.MSG_ERR);
+	private void reportException(Throwable re, int count, ExporterTask generatorTask) {
+		log("An exception occurred while running exporter #" + count + ":" + generatorTask.getName(), Project.MSG_ERR);
+		log("To get the full stack trace run ant with -verbose", Project.MSG_ERR);
 		log(re.toString(), Project.MSG_ERR);
 		String ex = new String();
 		Throwable cause = re.getCause();

Copied: trunk/HibernateExt/tools/src/java/org/hibernate/tool/ant/QueryExporterTask.java (from rev 9763, trunk/HibernateExt/tools/src/java/org/hibernate/tool/ant/HQLExporterTask.java)
===================================================================
--- trunk/HibernateExt/tools/src/java/org/hibernate/tool/ant/HQLExporterTask.java	2006-04-19 00:36:18 UTC (rev 9763)
+++ trunk/HibernateExt/tools/src/java/org/hibernate/tool/ant/QueryExporterTask.java	2006-04-21 19:03:03 UTC (rev 9777)
@@ -0,0 +1,96 @@
+package org.hibernate.tool.ant;
+
+import java.util.ArrayList;
+import java.util.Iterator;
+import java.util.List;
+
+import org.apache.tools.ant.BuildException;
+import org.hibernate.tool.hbm2x.Exporter;
+import org.hibernate.tool.hbm2x.QueryExporter;
+import org.hibernate.util.StringHelper;
+
+public class QueryExporterTask extends ExporterTask {
+
+	private String query = "";
+	private String filename;
+	List queries = new ArrayList();
+
+	public QueryExporterTask(HibernateToolTask parent) {
+		super( parent );		
+	}
+
+	protected Exporter configureExporter(Exporter exp) {
+		QueryExporter exporter = (QueryExporter) exp;
+		List queryStrings = new ArrayList();
+		if(StringHelper.isNotEmpty(query)) {
+			queryStrings.add(query);
+		}
+		for (Iterator iter = queries.iterator(); iter.hasNext();) {
+			HQL hql = (HQL) iter.next();
+			if(StringHelper.isNotEmpty(hql.query)) {
+				queryStrings.add(query);
+			}
+		}
+		exporter.setQueries(queryStrings);
+		exporter.setFilename(filename);
+		super.configureExporter( exp );		
+        return exporter;
+	}
+
+	public void validateParameters() {
+		super.validateParameters();
+		if(StringHelper.isEmpty(query) && queries.isEmpty()) {
+			throw new BuildException("Need to specify at least one query.");
+		}
+		
+		for (Iterator iter = queries.iterator(); iter.hasNext();) {
+			HQL hql = (HQL) iter.next();
+			if(StringHelper.isEmpty(hql.query)) {
+				throw new BuildException("Query must not be empty");
+			}
+		}
+	}
+	protected Exporter createExporter() {
+		QueryExporter exporter = new QueryExporter();
+		return exporter;
+	}
+
+	public void addText(String text) {
+		if(StringHelper.isNotEmpty(text)) {
+		  query += trim(text);
+		}
+	}
+	
+	static private String trim(String text) {
+		return text.trim();
+	}
+
+	public static class HQL {
+		String query = "";
+		public void addText(String text) {
+			if(StringHelper.isNotEmpty(text)) {
+				query += trim(text);
+			}
+		}		
+	}
+	
+	public HQL createHql() {
+		HQL hql = new HQL();
+		queries.add(hql);
+		return hql;
+	}
+	
+	public void setDestFile(String filename) {
+		this.filename = filename;
+	}
+	 
+	public void execute() {
+		parent.log("Executing: [" + query + "]");
+		super.execute();
+	}
+	public String getName() {
+		return "query (Executes queries)";
+	}
+	
+	
+}

Deleted: trunk/HibernateExt/tools/src/java/org/hibernate/tool/hbm2x/HQLExporter.java
===================================================================
--- trunk/HibernateExt/tools/src/java/org/hibernate/tool/hbm2x/HQLExporter.java	2006-04-20 21:35:09 UTC (rev 9776)
+++ trunk/HibernateExt/tools/src/java/org/hibernate/tool/hbm2x/HQLExporter.java	2006-04-21 19:03:03 UTC (rev 9777)
@@ -1,76 +0,0 @@
-package org.hibernate.tool.hbm2x;
-
-import java.io.File;
-import java.io.FileWriter;
-import java.io.IOException;
-import java.io.PrintWriter;
-import java.util.Iterator;
-import java.util.List;
-
-import org.hibernate.SessionFactory;
-import org.hibernate.classic.Session;
-
-/** 
- * Placeholder exporter for query execution.
- * 
- **/
-public class HQLExporter extends AbstractExporter {
-
-	private String query;	
-	private String filename;
-
-	public void doStart() {
-		Session session = null;
-		SessionFactory sessionFactory = null;
-		try {		 
-			sessionFactory = getConfiguration().buildSessionFactory();
-			session = sessionFactory.openSession();
-			
-			List list = session.createQuery(getQuery()).list();
-			
-			if(getFileName()!=null) {
-				PrintWriter pw = null;
-				try {
-					File file = new File( getOutputDirectory(), getFileName() );
-					getTemplateHelper().ensureExistence( file );
-					pw = new PrintWriter( new FileWriter( file, true ) );			
-					getArtifactCollector().addFile( file, "query-output" );
-					
-					for (Iterator iter = list.iterator(); iter.hasNext();) {
-						Object element = iter.next();
-						pw.println(element);
-					}
-					
-				}
-				catch (IOException e) {
-					throw new ExporterException("Could not write query output",e);
-				} finally {
-					if(pw!=null) {
-						pw.flush();
-						pw.close();
-					}
-				}
-			}
-		} finally {
-			session.close();
-			session.getSessionFactory().close();
-		}
-	}
-
-	private String getFileName() {
-		return filename;
-	}
-
-	public void setFilename(String filename) {
-		this.filename = filename;
-	}
-	
-	private String getQuery() {
-		return query;
-	}
-
-	public void setQuery(String query) {
-		this.query = query;		
-	}
-
-}

Copied: trunk/HibernateExt/tools/src/java/org/hibernate/tool/hbm2x/QueryExporter.java (from rev 9763, trunk/HibernateExt/tools/src/java/org/hibernate/tool/hbm2x/HQLExporter.java)
===================================================================
--- trunk/HibernateExt/tools/src/java/org/hibernate/tool/hbm2x/HQLExporter.java	2006-04-19 00:36:18 UTC (rev 9763)
+++ trunk/HibernateExt/tools/src/java/org/hibernate/tool/hbm2x/QueryExporter.java	2006-04-21 19:03:03 UTC (rev 9777)
@@ -0,0 +1,84 @@
+package org.hibernate.tool.hbm2x;
+
+import java.io.File;
+import java.io.FileWriter;
+import java.io.IOException;
+import java.io.PrintWriter;
+import java.util.Iterator;
+import java.util.List;
+
+import org.hibernate.HibernateException;
+import org.hibernate.SessionFactory;
+import org.hibernate.Transaction;
+import org.hibernate.classic.Session;
+
+/** 
+ * Placeholder exporter for query execution.
+ * 
+ **/
+public class QueryExporter extends AbstractExporter {
+
+	private String filename;
+	private List queryStrings;
+
+	public void doStart() {
+		Session session = null;
+		SessionFactory sessionFactory = null;
+		Transaction transaction = null;
+		try {		 
+			sessionFactory = getConfiguration().buildSessionFactory();
+			session = sessionFactory.openSession();
+			transaction = session.beginTransaction();
+			// TODO: this is not the most efficient loop (opening/closing file)
+			for (Iterator iter = queryStrings.iterator(); iter.hasNext();) {
+				String query = (String) iter.next();
+				
+				List list = session.createQuery(query).list();
+				
+				if(getFileName()!=null) {
+					PrintWriter pw = null;
+					try {
+						File file = new File( getOutputDirectory(), getFileName() );
+						getTemplateHelper().ensureExistence( file );
+						pw = new PrintWriter( new FileWriter( file, true ) );			
+						getArtifactCollector().addFile( file, "query-output" );
+						
+						for (Iterator iter1 = list.iterator(); iter1.hasNext();) {
+							Object element = iter.next();
+							pw.println(element);
+						}
+						
+					}
+					catch (IOException e) {
+						throw new ExporterException("Could not write query output",e);
+					} finally {
+						if(pw!=null) {
+							pw.flush();
+							pw.close();
+						}
+					}
+				}
+			}
+			transaction.commit();
+		} catch(HibernateException he) {
+			if(transaction!=null) transaction.rollback();
+		} finally {			
+			session.close();
+			session.getSessionFactory().close();
+			
+		}
+	}
+
+	private String getFileName() {
+		return filename;
+	}
+
+	public void setFilename(String filename) {
+		this.filename = filename;
+	}
+	
+	public void setQueries(List queryStrings) {
+		this.queryStrings = queryStrings;		
+	}
+
+}

Modified: trunk/HibernateExt/tools/src/java/org/hibernate/tool/hbm2x/pojo/ComponentPOJOClass.java
===================================================================
--- trunk/HibernateExt/tools/src/java/org/hibernate/tool/hbm2x/pojo/ComponentPOJOClass.java	2006-04-20 21:35:09 UTC (rev 9776)
+++ trunk/HibernateExt/tools/src/java/org/hibernate/tool/hbm2x/pojo/ComponentPOJOClass.java	2006-04-21 19:03:03 UTC (rev 9777)
@@ -88,15 +88,15 @@
 	}
 
 	public String generateBasicAnnotation(Property property) {
-		return null;
+		return "";
 	}
 	
 	public String generateAnnIdGenerator() {
-		return null;
+		return "";
 	}
 
 	public String generateAnnTableUniqueConstraint() {
-		return null;
+		return "";
 	}
 	
 	public Object getDecoratedObject() {

Modified: trunk/HibernateExt/tools/src/testsupport/anttest-build.xml
===================================================================
--- trunk/HibernateExt/tools/src/testsupport/anttest-build.xml	2006-04-20 21:35:09 UTC (rev 9776)
+++ trunk/HibernateExt/tools/src/testsupport/anttest-build.xml	2006-04-21 19:03:03 UTC (rev 9777)
@@ -334,9 +334,11 @@
 		<taskdef name="hibernatetool" classname="org.hibernate.tool.ant.HibernateToolTask" classpathref="tasks.classpath" />
 		<hibernatetool destdir="${build.dir}/querytest">
 			<configuration propertyfile="../../etc/hibernate.properties" configurationfile="querytest-hibernate.cfg.xml" />
-			<hql>from java.lang.Object</hql>
-			<hql>from java.io.Serializable</hql>
-		    <hql destfile="queryresult.txt">from java.io.Serializable</hql>			
+			<query>
+				<hql>from java.lang.Object</hql>
+  			    <hql>from java.io.Serializable</hql>
+			</query>
+		    <query destfile="queryresult.txt">from java.io.Serializable</query>			
 		</hibernatetool>		
 	</target>
 </project>