JBoss.orgCommunity Documentation

Chapter 5. Ant Tools

5.1. Introduction
5.2. The <hibernatetool> Ant Task
5.2.1. Basic examples
5.3. Hibernate Configurations
5.3.1. Standard Hibernate Configuration (<configuration>)
5.3.2. Annotation based Configuration (<annotationconfiguration>)
5.3.3. JPA based configuration (<jpaconfiguration>)
5.3.4. JDBC Configuration for reverse engineering (<jdbcconfiguration>)
5.4. Exporters
5.4.1. Database schema exporter (<hbm2ddl>)
5.4.2. POJO java code exporter (<hbm2java>)
5.4.3. Hibernate Mapping files exporter (<hbm2hbmxml>)
5.4.4. Hibernate Configuration file exporter (<hbm2cfgxml>)
5.4.5. Documentation exporter (<hbm2doc>)
5.4.6. Query exporter (<query>)
5.4.7. Generic Hibernate metamodel exporter (<hbmtemplate>)
5.5. Using properties to configure Exporters
5.5.1. <property> and <propertyset>
5.5.2. Getting access to user specific classes

This chapter demonstrates how to use Hibernate Tools via Ant tasks.

The hibernate-tools.jar file, available from tools.hibernate.org, contains the core code for Hibernate Tools™. It is used as the basis for both the Ant tasks described in this document and the Eclipse plugins available as part of JBoss Developer Studio. The hibernate-tools.jar file is located in your Eclipse plugins directory at /plugins/org.hibernate.eclipse.x.x.x/lib/tools/hibernate-tools.jar.

This jar is 100% independent from the Eclipse platform and can thus be used independently of Eclipse.


There may be incompatibilities with respect to the hibernate3.jar bundled with the tools and your own JAR. To avoid any confusion it is recommended that you use the hibernate3.jar and hibernate-annotations.jar files bundled with the tools when you want to use the Ant tasks. Do not worry about using the JAR's from a later version of Hibernate (e.g. Hibernate 3.2) with a project using an earlier version of Hibernate (e.g. a Hibernate 3.1) since the generated output will work with previous Hibernate 3 versions.

To use the Ant tasks you need to have the hibernatetool task defined. That is done in your build.xml file by inserting the following XML (assuming the JARs are located in the lib directory):

<path id="toolslib">
 <path location="lib/hibernate-tools.jar" />
 <path location="lib/hibernate3.jar" />
 <path location="lib/freemarker.jar" />
 <path location="${jdbc.driver.jar}" />
<taskdef name="hibernatetool" 
         classpathref="toolslib" />

This <taskdef> defines an Ant task called hibernatetool 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.

Notice that to use the annotation based Configuration you must get a release.

When using the hibernatetool task you have to specify one or more of the following:

  <classpath ...>
  <property key="propertyName" value="value"/>
  <propertyset ...>
  (<configuration ...>|<annotationconfiguration ...>|
   <jpaconfiguration ...>|<jdbcconfiguration ...>)

Hibernatetool™ supports four different Hibernate configurations: A standard Hibernate configuration (<configuration>), Annotation based configuration (<annotationconfiguration>), JPA persistence based configuration (<jpaconfiguration>) and a JDBC based configuration (<jdbcconfiguration>) used when reverse engineering.

Each can be used to build a Hibernate Configuration object, from which a set of exporters can be run in order to generate various output formats.

The following sections describe what the various configurations can do, as well as listing their individual settings.

A <configuration> tag is used to define a standard Hibernate configuration. A standard Hibernate configuration reads the mappings from a cfg.xml file and/or a fileset.

  entityresolver="EntityResolver classname"
  namingstrategy="NamingStrategy classname"

A <jpaconfiguration> tag is used when you want to read the metamodel from JPA or Hibernate Annotation where you want to use the auto-scan configuration as defined in the JPA specification (part of EJB3). In other words, when you do not have a hibernate.cfg.xml, but instead have a setup where you use a persistence.xml file packaged in a JPA compliant manner.

The <jpaconfiguration> tag will try and auto-configure it self based on the available classpath, e.g. look for the META-INF/persistence.xml file.

The persistenceunit attribute can be used to select a specific persistence unit. If no persistenceunit attribute is specified it will automatically search for one, and if a unique one is found, use it. However, having multiple persistence units will result in an error.

To use a <jpaconfiguration> tag you will need to specify some additional JARs from the Hibernate EntityManager in the <taskdef> section of the hibernatetool. The following demonstrates a full setup:

<path id="ejb3toolslib">
 <path refid="jpatoolslib"/> <!-- 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" /> 
<taskdef name="hibernatetool" 
         classpathref="jpatoolslib" />

<hibernatetool destdir="${build.dir}">
 <jpaconfiguration persistenceunit="caveatemptor"/>
  <!-- it is in this classpath you put your classes dir,
   and/or jpa persistence compliant jar -->
  <path location="${build.dir}/jpa/classes" />

 <!-- list exporters here -->


A <jdbcconfiguration> tag is used to perform reverse engineering of a database from a JDBC connection.

This configuration works by reading the connection properties either from a hibernate.cfg.xml file or a hibernate.properties file with a fileset.

The <jdbcconfiguration> tag has the same attributes as a <configuration> tag, plus the following additional attributes:

  reversestrategy="ReverseEngineeringStrategy classname"

Exporters do the actual job of converting the Hibernate metamodel into various artifacts, mainly code. The following section describes the current supported set of exporters in the Hibernate Tool™ distribution. It is also possible to implement user defined exporters, which is done through the <hbmtemplate> exporter.

<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. Remember that if a custom naming strategy is needed it is defined in the configuration element.


Exporters can be controlled by user properties. These user properties are specified via a <property> or <propertyset> tag, and each exporter will have access to them directly in the templates and via Exporter.setProperties().