Hibernate Tools Migration Guide

This page describes differences in the ant tasks, file formats and various settings/behaviors for the tools. As always, the Tools Reference Documentation contains more detailed information about the individual features.

Hibernate Tools

Old tools

This section lists the important migration differences between the old and new tools.

SchemaExport

org.hibernate.tool.hbm2ddl.SchemaExportTask is included in Hibernate3 Core and will continue to work.

But to use any new configuration features we recommend to use the new hibernatetool task

and the corresponding hbm2ddl exporter.

Here is a basic usage example:

  <hibernatetool>
   <configuration configfile="${build.dir}/hibernate.cfg.xml"/>
   <hbm2ddl/>
  </hibernatetool>

SchemaUpdate

org.hibernate.tool.hbm2ddl.SchemaUpdateTask is included in Hibernate3 Core and will continue to work.

But to use any new configuration features we recommend to use the new hibernatetool task.

and the corresponding hbm2ddl with update set to true.

Here is a basic usage example:

  <hibernatetool>
   <configuration configfile="${build.dir}/hibernate.cfg.xml"/>
   <hbm2dll update="true"/>
  </hibernatetool>

SchemaValidator

org.hibernate.tool.hbm2ddl.SchemaValidatorTask is included in Hibernate3 Core and will continue to work.

There are no replacement in this version of the tools.

hbm2java

There is no longer a separate hbm2java task (e.g. net.sf.hibernate.tool.hbm2java.Hbm2JavaTask) and even though you might succede in running it against Hibernate 3 mapping files the output will most likely be wrong or incomplete.

The correct way is to use <hibernatetool> with <hbm2java/>

Basic usage where mapping files is read from a hibernate.cfg.xml:

<hibernatetool destdir="${build.dir}/generated">
 <configuration configurationfile="hibernate.cfg.xml"/>
 <hbm2java/>
</hibernatetool>

similar usage, but this time mappings are specified via a file set:

<hibernatetool destdir="${build.dir}/generated">
 <configuration>
   <fileset dir="${src.dir}">
    <include name="**/*.hbm.xml"/>
   </fileset>
 </configuration>
 <hbm2java/>
</hibernatetool>

Some meta attributes has been changed/removed, see http://www.hibernate.org/276.html

Object vs. Primitives

Old version of hbm2java used some heuristics (which were in some cases broken) to decide if a property should be generated as a primitive (e.g. long) or an Object (e.g. java.lang.Long).

We removed the broken heuristics and now the rule is pretty simple:

If you want hbm2java to use the object version then map it to the object version. e.g. use "java.lang.Long" instead of "long".

Equals/Hashcode implementation

Earlier version of hbm2java would use API from Commons lang libraries to generate its equals and hashcode implementations. This was removed so there would be no dependency on a library that is not required for a proper POJO implementation.

Hibernate Tools 3.1beta5

FreeMarker

FreeMarker is now used for the templates.

If you have your own templates conversion is pretty straight forward. FreeMarker.org has documentation for how to convert templates from Velocity and even has a small utility tool that can handle most conversions. We converted all the built-in templates with this tool plus some very minor hand editing.

Note that we also changed some of the processing to use FreeMarker built-in features instead of doing processing tricks. e.g. it is no longer required to do two individual passes of the templates to handle import statements. Look at the built-in templates to learn about their structure and functionallity.

For discussion on why FreeMarker were chosen see this blog

reveng.xml

New features have been added to reveng.xml, but we also decided to align/clean up some of the previous format.

<key-column> instead of <column> in <primary-key>

Old:

<primary-key>
 <column name="MY_ID"/>
</primary-key>

New:

<primary-key>
 <key-column name="MY_ID"/>
</primary-key>

Reason: a column in a primary-key should not be excludable from reverse engineering. Thus the more limited <key-column> were introduced.

foreign-* on <column>

In the previous version you could define foreign-key constraints in a shorthand form directly on a column. This is no longer possible. Use an explicit <foreign-key> definition.

foreign-key name is now constraint-name

Old:

<foreign-key name="MY_CONSTRAINT" ...>
 <column-ref ...>
</foreign-key>

New:

<foreign-key constraint-name="MY_CONSTRAINT" ...>
 <column-ref ...>
</foreign-key>

Reason: constraint-name is the more proper term.