doc.reference.en.modules.ant.xml Maven / Gradle / Ivy
<?xml version="1.0" encoding="ISO-8859-1"?>
<chapter id="ant">
<title>Ant Tools</title>
<section>
<title>Introduction</title>
<para>The hibernate-tools.jar contains the core for the Hibernate Tools.
It is used as the basis for both the Ant tasks described in this document
and the eclipse plugins both available from tools.hibernate.org The
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>
<section>
<title>The <literal><hibernatetool></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]"/>
]]></programlisting></para>
<para>This <literal><taskdef></literal> defines a Ant task called
<literal><hibernatetool></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><hibernatetool> </literal>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="5 55" id="ht3" />
<area coords="6 55" id="ht4" />
</areaspec>
<programlisting><![CDATA[<hibernatetool
destdir="defaultDestinationDirectory"
templatepath="defaultTemplatePath"
>
<classpath ...>
<property name="propertyName" value="value"/>
<propertyset ...>
(<configuration ...>|<annotationconfiguration ...>|<jdbcconfiguration ...>)
(<hbm2java>,<hbm2cfgxml>,...*)
</hibernatetool>]]></programlisting>
<calloutlist>
<callout arearefs="ht1">
<para><literal>destdir</literal> (requiredl): 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><literal>classpath</literal> (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
<property>propertyset</property> (optional): Used to set
properties to control the exporters. Mostly relevant for
providing custom properties to user defined templates.</para>
</callout>
</calloutlist>
</programlistingco></para>
</section>
<section>
<title>Hibernate Configurations</title>
<para><literal>hibernatetool</literal> supports three different
Hibernate configurations: A standard Hibernate configuration
(<literal><configuration></literal>), Annotation based
configuration (<literal><annotationconfiguratioin></literal>) and
a JDBC based configuration
(<literal><jdbcconfiguration></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>
<section>
<title>Standard Hibernate Configuration
(<configuration>)</title>
<para>A <configuration> is used to define a standard Hibernate
configuration. A standard Hibernate configuration reads the mappings
from the optional hbm.xml and the 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="6 55" id="cfg5" />
</areaspec>
<programlisting><![CDATA[<configuration
configurationfile="hibernate.cfg.xml"
propertyfile="hibernate.properties"
entityresolver="EntityResolver classname"
namingstrategy="NamingStrategy classname"
>
<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 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 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 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>
</section>
<section>
<title>Annotation based Configuration
(<annotationconfiguration>)</title>
<para>An <literal><annotationconfiguration></literal> is used
when you want to read the metamodel from EJB3/Hibernate Annotations
based POJO's. To use it remember to put the jars file needed for using
hibernate annotations in the classpath of the
<literal><taskdef></literal>.</para>
<para>The <annotationconfiguration> has the same attributes as
an <configuration> 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>Thus the minimal usage is:</para>
<para><programlisting><![CDATA[<annotationconfiguration
configurationfile="hibernate.cfg.xml"/>
]]></programlisting></para>
</section>
<section>
<title>JDBC Configuration for reverse engineering
(<jdbcconfiguration>)</title>
<para>A <jdbcconfiguration> is used to perform reverse
engineering of the database from a JDBC connection. The
<jdbcconfiguration> has the same attributes as a
<configuration> plus the following additional attributes:</para>
<para><programlisting><![CDATA[<jdbcconfiguration
...
packagename="package.name"
reversestrategy="ReverseEngineeringStrategy classname"
revengfile="hibernate.reveng.xml"
>
...
</jdbcconfiguration>]]></programlisting></para>
</section>
</section>
<section>
<title>Code Exporters</title>
<para>Code exporters is the parts that does the actual job of converting
the hibernate metamodel into various code artifacts. 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
<literal><hbmtemplate></literal> exporter.</para>
<section>
<title>Database schema exporter
(<literal><hbm2ddl></literal>)</title>
<para><hbm2ddl> 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>
<programlisting><![CDATA[<hbm2ddl
drop="true|false"
create="true|false"
export="true|false"
update="true|false"
outputfilename="filename.ddl"
delimiter=";"
format="true|false"
>]]></programlisting>
<para></para>
</section>
<section>
<title>POJO java code exporter
(<literal><hbm2java></literal>)</title>
<para><hbm2java> is a java codegenerator. Options for
controlling wether JDK 5 syntax can be used and wether the POJO should
be annotated with EJB3/Hibernate Annotations.</para>
<programlisting><![CDATA[<hbm2java
jdk5="true|false"
ejb3="true|false"
>]]></programlisting>
<para></para>
</section>
<section>
<title>Hibernate Mapping files exporter
(<literal><hbm2hbmxml></literal>)</title>
<para><hbm2hbmxml> generates a set of .hbm files. Intended to be
used together with a <jdbcconfiguration> 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>
<programlisting><![CDATA[<hbm2hbmxml/>]]></programlisting>
<para></para>
</section>
<section>
<title>Hibernate Configuration file exporter
(<literal><hbm2cfgxml></literal>)</title>
<para><hbm2cfgxml> generates a hibernate.cfg.xml. Intended to be
used together with a <jdbcconfiguration> when performing reverse
engineering, but can be used with any kind of configuration. The
<hbm2cfgxml> will contain the properties used and adds mapping
entriies for each mapped class.</para>
<programlisting><![CDATA[<hbm2cfgxml
ejb3="true|false"
/>
]]></programlisting>
<para></para>
</section>
<section>
<title>Documentation exporter
(<literal><hbm2doc></literal>)</title>
<para><hbm2doc> generates html documentation a'la javadoc for
the database schema et.al.</para>
<programlisting><![CDATA[<hbm2doc/>]]></programlisting>
<para></para>
</section>
<section id="hbmtemplate">
<title>Generic Hibernate metamodel exporter
(<literal><hbmtemplate></literal>)</title>
<para>Generic exporter that can be controlled by a user provided
template or class.</para>
<programlisting><![CDATA[<hbmtemplate
filepattern="{package-name}/{class-name}.vm"
template="somename.vm"
exporterclass="Exporter classname"
/>]]></programlisting>
<para>NOTICE: This release uses Velocity for the templates. The next
release might move to an alternative template engine.</para>
<section>
<title>Seam Exporter via
<literal><hbmtemplate></literal></title>
<para>The following is an example of reverse engineering via
<literal><jdbcconfiguration></literal> and use the
SeamExporter via the <literal><hbmtemplate></literal> to
generate a Seam application skeleton.</para>
<para><programlisting><![CDATA[ <hibernatetool destdir="${destdir}">
<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="."/>
</hibernatetool>
]]></programlisting></para>
</section>
</section>
</section>
<section>
<title>Using properties to configure Exporters</title>
<para>Exporters can be controlled by user properties. The user
properties is specificed via <literal><property></literal> or
<literal><propertyset></literal> and each exporter will have
access to them directly in the templates and via
<literal>Exporter.setProperties()</literal>.</para>
<para></para>
<section>
<title><literal><property></literal> and
<literal><propertyset></literal></title>
<para>The <property> allows you bind a string value to a key.
The value will be available in the templates via $<key>. The
following example will assign the string value "true" to the variable
<literal>$descriptors</literal></para>
<programlisting><![CDATA[<property key="descriptors" value="true"/>]]></programlisting>
<para>Most times using <literal><property></literal> is enough
for specifying the properties needed for the exporters. Still the ant
tools supports the notion of <literal><propertyset></literal>.
The functionallity of <literal><propertyset></literal> is
explained in detail in the Ant task manual.</para>
</section>
<section>
<title>Getting access to user specific classes</title>
<para>If the templates need to access some user class it is possible
by specifying a "toolclass" in the properties.</para>
<programlisting><![CDATA[<property key="sometool.toolclass" value="x.y.z.NameOfToolClass"/>
]]></programlisting>
<para>Placing the above <literal><property></literal> tag in
<literal><hibernatetool></literal> or inside any exporter will
automatically create an instance of
<literal>x.y.z.NameOfToolClass</literal> and it will be available in
the templates as <literal>$sometool</literal>. This is usefull to
delegate logic and code generation to java code instead of placing
such logic in the templates.</para>
<para></para>
</section>
</section>
</section>
</chapter>